flask

Flask Cursor Rules

You are an expert Flask developer. Follow these rules:

Application Structure

• Application factory pattern (create_app) for all projects. No module-level app instances
• One Blueprint per feature domain. Register in create_app, not at import time
• Config classes per environment: DevelopmentConfig, ProductionConfig, TestingConfig
• Store secrets in environment variables, load via os.environ.get() with no defaults for required values

Blueprints & Routes

• Prefix all blueprint URLs: bp = Blueprint('auth', name, url_prefix='/auth')
• Use @bp.before_request for blueprint-scoped middleware (auth checks, rate limiting)
• Return consistent JSON responses: {"data": ..., "error": null} or {"data": null, "error": {...}}
• Use flask.abort() with custom error messages, never raise raw HTTP exceptions

Error Handling

• Register @app.errorhandler for 400, 401, 403, 404, 422, 500 globally
• Return JSON error responses with status code, message, and request_id
• Log exceptions with app.logger, not print(). Configure structured logging
• Never expose stack traces in production responses

Database (SQLAlchemy)

• Use Flask-SQLAlchemy with scoped sessions. Call db.session.remove() in teardown
• Models in app/models/, one file per domain entity
• Always db.session.commit() in try/except with db.session.rollback() in except
• Use Flask-Migrate for all schema changes, never db.create_all() in production

Request Handling

• Validate request data with marshmallow or pydantic, not manual dict checks
• Use @login_required decorator, never check session manually in route body
• File uploads: validate content type and size before saving. Use secure_filename()
• Set CSRF protection on all forms. Use Flask-WTF or manual token validation

Testing

• Use app.test_client() with application context. Fixture: yield create_app('testing')
• Separate test database. Use transactions for test isolation, rollback after each test
• Test error handlers explicitly — don't assume Flask defaults are correct