flask-conventions

Flask Conventions

Detection

Read pyproject.toml or requirements.txt before writing any Flask code:

grep -E "flask|Flask" requirements.txt pyproject.toml

Determine the installed extensions:

Check	Meaning
flask-login present	Session-based auth — use @login_required, login_user(), logout_user()
flask-jwt-extended present	Token-based auth — use @jwt_required(), create_access_token()
marshmallow or flask-marshmallow present	JSON API validation — use Schema.load() / Schema.dump()
flask-wtf present	HTML form validation — use FlaskForm with validate_on_submit()
flask-sqlalchemy present	ORM — use db.Model, db.session
flask-migrate present	Migrations — flask db migrate, flask db upgrade

---

App factory

Define create_app() in app/__init__.py. Never instantiate Flask at module level in a way that creates side effects — the factory pattern allows multiple app instances for testing.

# app/__init__.py
from flask import Flask

from app.config import config_by_name
from app.extensions import db, login_manager, migrate


def create_app(config_name: str = "development") -> Flask:
    app = Flask(__name__)
    app.config.from_object(config_by_name[config_name])

    _init_extensions(app)
    _register_blueprints(app)
    _register_error_handlers(app)

    return app


def _init_extensions(app: Flask) -> None:
    db.init_app(app)
    migrate.init_app(app, db)
    login_manager.init_app(app)


def _register_blueprints(app: Flask) -> None:
    from app.auth.views import auth_bp
    from app.users.views import users_bp
    from app.orders.views import orders_bp

    app.register_blueprint(auth_bp)
    app.register_blueprint(users_bp)
    app.register_blueprint(orders_bp)


def _register_error_handlers(app: Flask) -> None:
    from app.errors import register_error_handlers
    register_error_handlers(app)

Initialize extensions at module level in app/extensions.py, then call .init_app(app) in the factory. This avoids circular imports.