---

name: flask description: | Flask lightweight Python framework. Covers routing, blueprints, and extensions. Use for simple Python APIs and microservices.

USE WHEN: user mentions "flask", "flask blueprints", "python microservice", asks about "flask-restful", "flask extensions", "lightweight python api", "flask-sqlalchemy", "flask-jwt", "flask middleware"

DO NOT USE FOR: Django projects - use django instead, FastAPI with type validation - use fastapi instead, async-first APIs, applications requiring built-in admin panel allowed-tools: Read, Grep, Glob, Write, Edit

Flask Core Knowledge

Full Reference: See advanced.md for Flask-SocketIO WebSocket patterns, authentication, room management, namespaces, and broadcasting from external code.

Basic Setup

from flask import Flask, jsonify, request, abort

app = Flask(__name__)

@app.route('/users', methods=['GET'])
def get_users():
    return jsonify(users)

@app.route('/users/<int:user_id>', methods=['GET'])
def get_user(user_id):
    user = find_user(user_id)
    if not user:
        abort(404)
    return jsonify(user)

@app.route('/users', methods=['POST'])
def create_user():
    data = request.get_json()
    user = create_user_in_db(data)
    return jsonify(user), 201

Blueprints

from flask import Blueprint

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

@users_bp.route('/')
def list_users():
    return jsonify(get_all_users())

# In app.py
app.register_blueprint(users_bp)

Key Extensions

Extension	Purpose
Flask-SQLAlchemy	Database ORM
Flask-Migrate	Database migrations
Flask-JWT-Extended	JWT auth
Flask-CORS	CORS support
Flask-RESTful	REST APIs

Application Factory

from flask import Flask
from flask_sqlalchemy import SQLAlchemy
from flask_cors import CORS

db = SQLAlchemy()

def create_app(config_name='production'):
    app = Flask(__name__)
    app.config.from_object(config[config_name])

    db.init_app(app)
    CORS(app, origins=app.config['CORS_ORIGINS'])

    from .routes import users_bp, health_bp
    app.register_blueprint(users_bp, url_prefix='/api/users')
    app.register_blueprint(health_bp)

    register_error_handlers(app)
    return app

Configuration

import os

class Config:
    SECRET_KEY = os.environ.get('SECRET_KEY')
    SQLALCHEMY_TRACK_MODIFICATIONS = False
    SQLALCHEMY_ENGINE_OPTIONS = {
        'pool_size': 10,
        'pool_recycle': 3600,
        'pool_pre_ping': True,
    }

class ProductionConfig(Config):
    DEBUG = False
    SQLALCHEMY_DATABASE_URI = os.environ.get('DATABASE_URL')
    SESSION_COOKIE_SECURE = True
    SESSION_COOKIE_HTTPONLY = True

Error Handling

from flask import jsonify

class APIError(Exception):
    def __init__(self, message, status_code=400):
        self.message = message
        self.status_code = status_code

def register_error_handlers(app):
    @app.errorhandler(APIError)
    def handle_api_error(error):
        return jsonify({'error': error.message}), error.status_code

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

    @app.errorhandler(500)
    def internal_error(error):
        return jsonify({'error': 'Internal server error'}), 500

Health Checks

health_bp = Blueprint('health', __name__)

@health_bp.route('/health')
def health():
    return jsonify({'status': 'healthy'})

@health_bp.route('/ready')
def ready():
    try:
        db.engine.execute('SELECT 1')
        return jsonify({'status': 'ready', 'database': 'connected'})
    except Exception as e:
        return jsonify({'status': 'not ready'}), 503

Testing

import pytest
from app import create_app, 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()

def test_create_user(client):
    response = client.post('/api/users/', json={
        'name': 'John', 'email': 'john@example.com'
    })
    assert response.status_code == 201

When NOT to Use This Skill

• Django projects - Django provides more batteries-included features
• FastAPI with type validation - FastAPI has built-in Pydantic validation
• Async-first applications - Flask is sync-based
• Built-in admin required - Django admin is more comprehensive

Anti-Patterns

Anti-Pattern	Why It's Bad	Solution
Using global app instance	Hard to test	Use application factory pattern
No error handlers	Generic 500 errors	Register error handlers
Hardcoded config values	Can't change per environment	Use app.config.from_object()
Not using blueprints	Monolithic code	Split into blueprints
Missing CORS	Frontend can't connect	Use flask-cors extension

Quick Troubleshooting

Problem	Diagnosis	Fix
"Working outside application context"	No app context	Use with app.app_context():
Static files 404	Wrong path	Check static_folder
CORS errors	Not configured	Install and configure flask-cors
Database pool exhausted	No pooling	Configure SQLALCHEMY_ENGINE_OPTIONS
Blueprint not found	Not registered	Call app.register_blueprint()

Production Checklist

• Application factory pattern
• Environment-based config
• Structured JSON logging
• Request ID tracing
• Database connection pooling
• Health/readiness endpoints
• Global error handlers
• Gunicorn with workers
• pytest fixtures for testing
• CORS properly configured

Monitoring Metrics

Metric	Target
Response time (p99)	< 200ms
Error rate (5xx)	< 0.1%
Database pool usage	< 80%

Reference Documentation

• Blueprints
• Extensions