Flask Python

Flask (Python) — Best Practices

Project Structure

project/
├── app/
│   ├── __init__.py           # Application Factory (create_app)
│   ├── config.py             # Configuration classes (Dev, Prod, Test)
│   ├── extensions.py         # Flask extensions (db, migrate, login)
│   ├── blueprints/
│   │   ├── auth/
│   │   │   ├── __init__.py   # Blueprint creation
│   │   │   ├── routes.py     # Route definitions
│   │   │   └── forms.py      # WTForms schemas
│   │   └── users/
│   │       ├── __init__.py
│   │       └── routes.py
│   ├── models/               # SQLAlchemy models
│   │   ├── __init__.py
│   │   └── user.py
│   ├── services/             # Business logic
│   │   └── user_service.py
│   └── templates/            # Jinja2 templates (if server-rendered)
├── tests/
│   ├── conftest.py           # Pytest fixtures (app, client, db)
│   ├── test_auth.py
│   └── test_users.py
├── .env                      # Local environment variables
├── requirements.txt
└── run.py                    # Entry point

Naming Conventions

Architectural Patterns

Application Factory Pattern

Use create_app(config_name) in app/__init__.py to build the Flask instance. This allows creating different app instances for development, testing, and production without global state.

def create_app(config_name="development"):
    app = Flask(__name__)
    app.config.from_object(config_map[config_name])
    register_extensions(app)
    register_blueprints(app)
    return app

Blueprints for Routing

Organize routes into Blueprints. Each feature domain gets its own Blueprint. Never define routes directly on the app instance outside of a Blueprint.

users_bp = Blueprint("users", __name__, url_prefix="/api/users")

SQLAlchemy ORM

• Define models in a dedicated models/ package, not in routes.py.
• Use backref sparingly — prefer explicit relationship definitions.
• Use Alembic (via Flask-Migrate) for all schema migrations; never hand-write DDL.
• Keep query logic in dedicated repository functions or service methods — never inline queries in route handlers.

Configuration Separation

Create a config.py with at least three classes: Config (base), DevelopmentConfig, ProductionConfig, TestingConfig. Load the correct one via environment variable or default.

Virtual Environment Rules

• Always use a virtual environment (venv or pipenv).
• Pin dependency versions in requirements.txt.
• Never commit .venv/ or __pycache__/ to version control.

Universal DateTime Governance

• Timezone-Aware Datetimes: Use datetime.now(timezone.utc) exclusively. Banned: bare datetime.now() and datetime.utcnow().
• Clock Abstraction: Create a ClockProvider class (def now() -> datetime) injected into services. Never call datetime.now() directly in business logic.
• API Format: Transmit datetimes as ISO-8601 with offset (2026-07-23T14:30:00+00:00) or Unix epoch milliseconds.

Testing Strategies

• Use pytest as the test runner (not unittest).
• Use conftest.py to define shared fixtures (app instance, test client, database session).
• Use an in-memory SQLite database for fast test runs.
• For every Blueprint, write at least one test that validates the route returns the expected status code.