FastAPI Standards

The FastAPI delta over standards-python, which in turn extends .claude/rules/common/. Load this only for FastAPI work — it does not apply to Python generally.

What applies immediately

• Three layers, no leakage. Router validates and calls one service; service holds business rules and no HTTP types; repository does database access and returns no HTTP responses.
• Domain exceptions, not HTTPException, in services. Map them to responses in one place with @app.exception_handler(...) registered in create_app(). Never a bare except:.
• Never block the event loop inside async def — no sync requests, sync SQLAlchemy, time.sleep, or CPU-bound loops. Offload with asyncio.to_thread.
• One AsyncSession per request from a dependency, expire_on_commit=False, transaction owned at the request boundary. Eager-load relationships with selectinload/joinedload.
• Separate request, update, and response schemas. Input must not accept server-owned fields; output must never expose password hashes, tokens, or internal auth state. Never return an ORM instance directly.
• Typed settings via pydantic-settings, validated at startup, injected with Depends — not os.getenv scattered through the codebase.

Reference files