flask-development

Flask Development Skill

Target: Flask 3.x (Python 3.9+)

Minimal Working Example

# app.py
from flask import Flask

app = Flask(__name__)

@app.route("/")
def hello():
    return {"message": "Hello, World!"}

if __name__ == "__main__":
    app.run(debug=True)

Run: uv run flask --app app run --debug

Core Patterns

Application Factory

Always use the application factory pattern for production Flask applications:

# app/__init__.py
from flask import Flask
from app.extensions import login_manager
from config import Config


def create_app(config_class=Config):
    """Application factory function."""
    app = Flask(__name__)
    app.config.from_object(config_class)

    # Initialize extensions
    login_manager.init_app(app)

    # Register blueprints
    from app.main import bp as main_bp
    from app.auth import bp as auth_bp

    app.register_blueprint(main_bp)
    app.register_blueprint(auth_bp, url_prefix="/auth")

    # Register error handlers
    from app.errors import register_error_handlers
    register_error_handlers(app)

    return app

Key Benefits:

• Multiple app instances with different configs (testing)
• Avoids circular imports
• Extensions initialized once, bound to app later

Extensions Module

Centralizing extensions in a separate file prevents circular imports — other modules can import extensions without importing app.

# app/extensions.py
from flask_login import LoginManager

login_manager = LoginManager()
login_manager.login_view = "auth.login"
login_manager.login_message_category = "info"

Configuration

Separate configurations for different environments:

# config.py
import os
from dataclasses import dataclass
from dotenv import load_dotenv

load_dotenv()

@dataclass
class Config:
    """Base configuration."""
    SECRET_KEY = os.environ.get("SECRET_KEY", "dev-secret-key")

@dataclass
class DevelopmentConfig(Config):
    """Development configuration."""
    DEBUG = True

@dataclass
class TestingConfig(Config):
    """Testing configuration."""
    TESTING = True
    WTF_CSRF_ENABLED = False

@dataclass
class ProductionConfig(Config):
    """Production configuration."""
    DEBUG = False

config = {
    "development": DevelopmentConfig,
    "production": ProductionConfig,
    "testing": TestingConfig,
    "default": DevelopmentConfig,
}

Entry Point

# run.py
from app import create_app

app = create_app()

if __name__ == "__main__":
    app.run()

Run: flask --app run run --debug

Creating a Blueprint

Blueprints organize routes into logical groups.

# app/main/__init__.py
from flask import Blueprint

bp = Blueprint("main", __name__)

from app.main import routes  # Import routes after bp is created

# app/main/routes.py
from flask import render_template, jsonify
from app.main import bp


@bp.route("/")
def index():
    return render_template("main/index.html")


@bp.route("/api/health")
def health():
    return jsonify({"status": "ok"})

MethodViews

MethodViews map HTTP methods to class methods, which is useful when a single URL needs to handle multiple methods with distinct logic:

# app/items/views.py
from flask import render_template, redirect, url_for, request
from flask.views import MethodView

from app.items import bp


class ItemView(MethodView):
    """CRUD operations for a single item."""

    def get(self, item_id: int) -> str:
        item = get_item_or_404(item_id)
        return render_template("items/detail.html", item=item)

    def post(self) -> str:
        # Handle item creation from form
        create_item(request.form)
        return redirect(url_for("items.list"))

    def delete(self, item_id: int) -> tuple:
        delete_item(item_id)
        return "", 204


# Register the view with the blueprint
item_view = ItemView.as_view("item")
bp.add_url_rule("/items/", view_func=item_view, methods=["POST"])
bp.add_url_rule("/items/<int:item_id>", view_func=item_view, methods=["GET", "DELETE"])

Async Views

Flask 3.x has native async support. Use async views for I/O-bound operations:

import asyncio
import httpx


@bp.route("/external-data")
async def get_external_data():
    async with httpx.AsyncClient() as client:
        response = await client.get("https://api.example.com/data")
        return response.json()


@bp.route("/multiple-sources")
async def get_multiple_sources():
    async with httpx.AsyncClient() as client:
        results = await asyncio.gather(
            client.get("https://api1.example.com/data"),
            client.get("https://api2.example.com/data"),
        )
        return {"source1": results[0].json(), "source2": results[1].json()}

Context Locals (g, request, session)

from flask import g, request, session, current_app

@app.before_request
def load_user():
    user_id = session.get("user_id")
    g.user = get_user(user_id) if user_id else None

@app.route("/profile")
def profile():
    if not g.user:
        return redirect(url_for("auth.login"))
    return render_template("profile.html", user=g.user)

# Access configuration via current_app (not the app instance directly)
def send_email(to: str, subject: str, body: str):
    smtp_server = current_app.config["SMTP_SERVER"]
    # ...

CLI Commands

Register custom CLI commands for management tasks:

import click
from flask import Flask


def register_cli(app: Flask):
    @app.cli.command("seed")
    @click.argument("count", default=10)
    def seed_data(count):
        """Seed the application with sample data."""
        click.echo(f"Seeding {count} records...")
        # ... create sample data
        click.echo("Done")

Run: flask --app run seed 50

Logging

import logging
from flask import Flask


def configure_logging(app: Flask):
    handler = logging.StreamHandler()
    handler.setFormatter(logging.Formatter(
        "[%(asctime)s] %(levelname)s in %(module)s: %(message)s"
    ))
    app.logger.addHandler(handler)
    app.logger.setLevel(logging.INFO)

# Use within request context
@bp.route("/action")
def some_action():
    current_app.logger.info("Action performed by user %s", g.user)
    return "ok"

Security Best Practices

from flask_wtf.csrf import CSRFProtect
from flask_limiter import Limiter
from flask_limiter.util import get_remote_address
from flask_cors import CORS
from flask_talisman import Talisman

csrf = CSRFProtect()
limiter = Limiter(key_func=get_remote_address)

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

    csrf.init_app(app)
    limiter.init_app(app)
    CORS(app, resources={r"/api/*": {"origins": app.config["ALLOWED_ORIGINS"]}})

    if not app.debug:
        Talisman(app, content_security_policy=app.config["CSP_POLICY"])

    return app

# Rate limiting on sensitive routes
@auth_bp.route("/login", methods=["POST"])
@limiter.limit("5 per minute")
def login():
    pass

Error Handling

# app/errors.py
from flask import jsonify, Flask


class APIError(Exception):
    """Base API error class."""
    status_code = 500

    def __init__(self, message: str, status_code: int = None):
        super().__init__()
        self.message = message
        if status_code is not None:
            self.status_code = status_code

    def to_dict(self) -> dict:
        return {"error": self.message}


class NotFoundError(APIError):
    status_code = 404


class ValidationError(APIError):
    status_code = 400


class AuthenticationError(APIError):
    status_code = 401


def register_error_handlers(app: Flask):
    @app.errorhandler(APIError)
    def handle_api_error(error):
        response = jsonify(error.to_dict())
        response.status_code = error.status_code
        return response

    @app.errorhandler(404)
    def handle_404(error):
        return jsonify({"error": "Resource not found"}), 404

    @app.errorhandler(500)
    def handle_500(error):
        app.logger.error(f"Server error: {error}")
        return jsonify({"error": "Internal server error"}), 500

Authentication

For authentication patterns with Flask-Login (forms, routes, protecting routes, custom decorators), see references/authentication.md.

Critical Rules

Always Do

1. Use application factory pattern — enables testing, avoids globals
2. Put extensions in separate file — prevents circular imports
3. Import routes at bottom of blueprint __init__.py — after bp is created
4. Use current_app not app — inside request context

Never Do

1. Never import app in modules that app imports — causes circular imports
2. Never store secrets in code — use environment variables
3. Never use app.run() in production — use Gunicorn
4. Never skip CSRF protection — keep Flask-WTF enabled for form submissions

Common Errors & Fixes

Circular Import Error

Error: ImportError: cannot import name 'X' from partially initialized module

Fix: Use deferred imports inside the factory function:

# WRONG
from app.models import User  # at module level in app/__init__.py

# RIGHT
def create_app():
    # ... setup ...
    from app.models import User  # inside factory

Working Outside Application Context

Error: RuntimeError: Working outside of application context

Fix: Wrap code in app.app_context():

app = create_app()
with app.app_context():
    # now current_app, g, etc. are available
    do_something()

Blueprint Not Found

Error: werkzeug.routing.BuildError: Could not build url for endpoint

Fix: Include the blueprint name prefix in url_for():

# WRONG
url_for("login")

# RIGHT
url_for("auth.login")

CSRF Token Missing

Error: Bad Request: The CSRF token is missing

Fix: Include the token in templates:

<form method="post">
    {{ form.hidden_tag() }}
    <!-- form fields -->
</form>

Testing

# tests/conftest.py
import pytest
from app import create_app
from config import TestingConfig


@pytest.fixture
def app():
    app = create_app(TestingConfig)
    yield app


@pytest.fixture
def client(app):
    return app.test_client()


@pytest.fixture
def runner(app):
    return app.test_cli_runner()

# tests/test_main.py
def test_index(client):
    response = client.get("/")
    assert response.status_code == 200

Run: uv run pytest

Deployment

Development

flask --app run run --debug

Production with Gunicorn

uv add gunicorn
uv run gunicorn -w 4 -b 0.0.0.0:8000 "run:app"

Environment Variables (.env)

SECRET_KEY=your-production-secret-key
FLASK_ENV=production