flask-workflow - Claude MCP Skill

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

# Flask Workflow

## Tool Grid

| Task | Tool | Command |
|------|------|---------|
| Run dev | Flask CLI | `flask run --debug` |
| Test | pytest | `uv run pytest` |
| Lint | Ruff | `uv run ruff check .` |
| Format | Ruff | `uv run ruff format .` |
| Migrate | Flask-Migrate | `flask db upgrade` |
| Shell | Flask CLI | `flask shell` |

---

## Application Factory Pattern

All Flask applications MUST use the application factory pattern.

```python
# app/__init__.py
from flask import Flask

def create_app(config_name: str = "default") -> Flask:
    """Application factory function."""
    app = Flask(__name__)

    # Load configuration
    app.config.from_object(config[config_name])

    # Initialize extensions
    db.init_app(app)
    migrate.init_app(app, db)
    login_manager.init_app(app)

    # Register blueprints
    from app.main import main_bp
    from app.auth import auth_bp
    from app.api import api_bp

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

    # Register error handlers
    register_error_handlers(app)

    return app
```

---

## Blueprint Organization

Routes MUST be organized using Blueprints. NEVER define routes directly on the app object.

### Directory Structure

```
app/
├── __init__.py          # create_app() factory
├── extensions.py        # Extension instances
├── models/              # SQLAlchemy models
│   ├── __init__.py
│   └── user.py
├── main/                # Main blueprint
│   ├── __init__.py      # Blueprint definition
│   ├── routes.py        # Route handlers
│   └── forms.py         # WTForms (if used)
├── auth/                # Auth blueprint
│   ├── __init__.py
│   ├── routes.py
│   └── forms.py
└── api/                 # API blueprint
    ├── __init__.py
    ├── routes.py
    └── schemas.py       # Marshmallow/Pydantic schemas
```

### Blueprint Definition

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

main_bp = Blueprint("main", __name__)

from app.main import routes  # noqa: E402, F401
```

---

## Configuration

Configuration MUST be loaded from environment variables for secrets. Configuration classes SHOULD be used for different environments.

```python
# config.py
import os
from pathlib import Path

basedir = Path(__file__).parent


class Config:
    """Base configuration."""

    SECRET_KEY = os.environ.get("SECRET_KEY") or "dev-key-change-in-prod"
    SQLALCHEMY_TRACK_MODIFICATIONS = False

    @staticmethod
    def init_app(app):
        """Initialize application-specific config."""
        pass


class DevelopmentConfig(Config):
    DEBUG = True
    SQLALCHEMY_DATABASE_URI = os.environ.get("DEV_DATABASE_URL") or \
        f"sqlite:///{basedir / 'dev.db'}"


class TestingConfig(Config):
    TESTING = True
    SQLALCHEMY_DATABASE_URI = "sqlite:///:memory:"
    WTF_CSRF_ENABLED = False


class ProductionConfig(Config):
    SQLALCHEMY_DATABASE_URI = os.environ.get("DATABASE_URL")

    @staticmethod
    def init_app(app):
        # Production-specific initialization
        pass


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

---

## Extensions Pattern

Extensions MUST be instantiated in a separate module without app binding, then initialized in the factory.

```python
# app/extensions.py
from flask_sqlalchemy import SQLAlchemy
from flask_migrate import Migrate
from flask_login import LoginManager

db = SQLAlchemy()
migrate = Migrate()
login_manager = LoginManager()
login_manager.login_view = "auth.login"
```

---

## Flask-SQLAlchemy Patterns

### Model Definition

```python
# app/models/user.py
from datetime import datetime
from werkzeug.security import generate_password_hash, check_password_hash
from flask_login import UserMixin
from app.extensions import db, login_manager


class User(UserMixin, db.Model):
    __tablename__ = "users"

    id = db.Column(db.Integer, primary_key=True)
    email = db.Column(db.String(120), unique=True, nullable=False, index=True)
    password_hash = db.Column(db.String(256), nullable=False)
    created_at = db.Column(db.DateTime, default=datetime.utcnow)

    def set_password(self, password: str) -> None:
        self.password_hash = generate_password_hash(password)

    def check_password(self, password: str) -> bool:
        return check_password_hash(self.password_hash, password)


@login_manager.user_loader
def load_user(user_id: str) -> User | None:
    return db.session.get(User, int(user_id))
```

### Query Patterns

```python
# RECOMMENDED: Use db.session for queries
user = db.session.get(User, user_id)  # By primary key
users = db.session.scalars(db.select(User).filter_by(active=True)).all()

# SHOULD avoid deprecated Model.query
# user = User.query.get(user_id)  # Deprecated
```

---

## Flask-Migrate

Database migrations MUST use Flask-Migrate. NEVER modify the database schema manually.

```bash
# Initialize migrations (once)
flask db init

# Create migration after model changes
flask db migrate -m "Add user table"

# Apply migrations
flask db upgrade

# Rollback
flask db downgrade
```

---

## Flask-Login Authentication

```python
# app/auth/routes.py
from flask import render_template, redirect, url_for, flash, request
from flask_login import login_user, logout_user, login_required, current_user
from app.auth import auth_bp
from app.models.user import User


@auth_bp.route("/login", methods=["GET", "POST"])
def login():
    if current_user.is_authenticated:
        return redirect(url_for("main.index"))

    if request.method == "POST":
        user = db.session.scalar(
            db.select(User).filter_by(email=request.form["email"])
        )
        if user and user.check_password(request.form["password"]):
            login_user(user, remember=request.form.get("remember"))
            next_page = request.args.get("next")
            return redirect(next_page or url_for("main.index"))
        flash("Invalid email or password")

    return render_template("auth/login.html")


@auth_bp.route("/logout")
@login_required
def logout():
    logout_user()
    return redirect(url_for("main.index"))
```

---

## Request and Application Context

### Application Context

Use `with app.app_context():` when accessing app-bound resources outside request handling.

```python
# CLI commands, background tasks, etc.
with app.app_context():
    db.create_all()
    user = db.session.get(User, 1)
```

### Request Context

Request-specific data (g, request, session) MUST only be accessed within request context.

```python
from flask import g, request

@app.before_request
def before_request():
    g.user = current_user
    g.locale = request.accept_languages.best_match(["en", "es"])
```

---

## Error Handlers

Error handlers SHOULD be registered in the application factory.

```python
# app/errors.py
from flask import render_template, jsonify, request


def register_error_handlers(app):
    @app.errorhandler(404)
    def not_found_error(error):
        if request.path.startswith("/api/"):
            return jsonify({"error": "Not found"}), 404
        return render_template("errors/404.html"), 404

    @app.errorhandler(500)
    def internal_error(error):
        db.session.rollback()
        if request.path.startswith("/api/"):
            return jsonify({"error": "Internal server error"}), 500
        return render_template("errors/500.html"), 500
```

---

## Testing with Test Client

Tests MUST use pytest fixtures. Test configuration MUST use TestingConfig.

```python
# tests/conftest.py
import pytest
from app import create_app
from app.extensions import db


@pytest.fixture
def app():
    app = create_app("testing")

    with app.app_context():
        db.create_all()
        yield app
        db.drop_all()


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


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

```python
# tests/test_auth.py
def test_login_page(client):
    response = client.get("/auth/login")
    assert response.status_code == 200
    assert b"Login" in response.data


def test_login_success(client, user):
    response = client.post("/auth/login", data={
        "email": "test@example.com",
        "password": "password123"
    }, follow_redirects=True)
    assert response.status_code == 200
```

---

## API Routes

API blueprints SHOULD return JSON responses and use proper HTTP status codes.

```python
# app/api/routes.py
from flask import jsonify, request
from app.api import api_bp
from app.models.user import User


@api_bp.route("/users/<int:user_id>")
def get_user(user_id: int):
    user = db.session.get(User, user_id)
    if not user:
        return jsonify({"error": "User not found"}), 404
    return jsonify({
        "id": user.id,
        "email": user.email,
        "created_at": user.created_at.isoformat()
    })


@api_bp.route("/users", methods=["POST"])
def create_user():
    data = request.get_json()
    if not data or not data.get("email"):
        return jsonify({"error": "Email required"}), 400

    user = User(email=data["email"])
    user.set_password(data["password"])
    db.session.add(user)
    db.session.commit()

    return jsonify({"id": user.id}), 201
```

---

## CLI Commands

Custom CLI commands SHOULD be defined using `@app.cli.command()` or Click groups.

```python
# app/cli.py
import click
from app.extensions import db


def register_cli(app):
    @app.cli.command()
    def initdb():
        """Initialize the database."""
        db.create_all()
        click.echo("Database initialized.")

    @app.cli.command()
    @click.argument("email")
    @click.password_option()
    def create_admin(email, password):
        """Create an admin user."""
        from app.models.user import User
        user = User(email=email, is_admin=True)
        user.set_password(password)
        db.session.add(user)
        db.session.commit()
        click.echo(f"Admin {email} created.")
```

---

## Security Checklist

- [ ] SECRET_KEY MUST be set from environment in production
- [ ] CSRF protection MUST be enabled for forms
- [ ] Passwords MUST be hashed with werkzeug.security
- [ ] SQL queries MUST use parameterized statements (SQLAlchemy handles this)
- [ ] User input MUST be validated before use
- [ ] Debug mode MUST NOT be enabled in production