python-fastapi-playbook

Python FastAPI Playbook

This is the literal procedure a frontier model follows when building or fixing FastAPI services. Follow it step by step; the order is the point. FastAPI + async is unforgiving in one specific way: code that works in a unit test (one request, no concurrency) can stall the whole process under load because a single blocking call in an async def freezes the event loop for every other request. The type checker will not catch that. Those checks are yours.

Operating loop

1. Read pyproject.toml / requirements.txt FIRST — the Pydantic major version changes everything. grep -E "pydantic" pyproject.toml requirements.txt or python -c "import pydantic; print(pydantic.VERSION)". v1 and v2 have different method names, validator decorators, and config styles (catalog below). Writing v2 idioms into a v1 project (or vice versa) produces import errors or silent no-ops. Note the package manager too: poetry.lock → poetry run, uv.lock → uv run, else python -m.
2. Find the local dialect and mirror it. Before writing a route, read two existing routers: grep -rn "APIRouter\|@router\.\|@app\." --include="*.py" .. Copy the project's router registration, response envelope, error-raising style (HTTPException vs custom handler), and dependency wiring exactly. A "cleaner" pattern that differs from the neighbors is a defect here.
3. Find the schema and dependency patterns and mirror them. Read one request model, one response model, and one Depends function. Match where validation lives (in the model, not the handler) and how sessions are acquired (yield dependency, not inline).
4. Boot the app early to catch import-time errors. Run the project's entrypoint (uvicorn app.main:app briefly, or python -c "import app.main", adjust to the real module path). FastAPI executes decorators, dependency signatures, and Pydantic model definitions at import time — a bad type annotation or a v1/v2 mismatch fails here, before any request. Do this again after your change.
5. For every path operation, decide async def vs def out loud (tree A). The choice is dictated by what the body calls, not by preference.
6. For every value crossing the HTTP boundary, put validation in a Pydantic model (tree C) — not in if checks inside the handler.
7. Run the verification recipe (below) and re-read your diff hunting for blocking calls in async def, missing await, and handlers returning ORM objects without a response_model.