backend-python-fastapi

Files (3)

• SKILL.md
• FASTAPI_PROJECT_PATTERNS.md · references/
• PYTHON_313_FEATURES.md · references/

SKILL.md (first lines)

# Backend Python (FastAPI) -- Production Playbook

FastAPI, Pydantic v2 and async SQLAlchemy 2.x services. Django -> `backend-python-django` if installed (it is a catalog skill); schema DDL and migration operations -> `postgres-schema-migrations` (integrate the resulting contract with FastAPI dependencies here). Read the project's interpreter pin, manifest and lockfile before choosing version-specific features.

## Execution playbook

### Step 1 -- Structure
- Follow the repository's existing structure; introduce a layer only for a present responsibility that needs it.
- Modern Python features: verify availability against the project's pinned version. Read `references/PYTHON_313_FEATURES.md` before enabling a free-threaded build, or the experimental JIT -- each has a footgun (thread-unsafe C extensions, no production recommendation yet) that a one-line summary here would hide.

### Step 2 -- FastAPI, Pydantic v2 and dependency injection
- App factory (`create_app()` with a `lifespan` for the DB pool and cache connections), Pydantic v2 request/response schemas, typed settings and the `get_db` / service dependency chain: read `references/FASTAPI_PROJECT_PATTERNS.md` when you build them.
- Settings fail fast: `pydantic-settings` with `SecretStr` secrets, a `field_validator` rejecting a JWT secret under 32 characters, and `get_settings()` called in the `lifespan` or at import so bad config crashes at startup, not at the first request.

### Step 3 -- Database with SQLAlchemy 2.0 async and Alembic
- `mapped_column` style models, `create_async_engine` + `async_sessionmaker(expire_on_commit=False)`, one session per request.
- Alembic: `alembic init -t async`, configure `env.py` for async, `--autogenerate`, and review every autogenerated migration before applying.
- Repository layer only when data access must vary independently or be swapped in tests; a small service can query directly.

### Step 4 -- Authentication, background tasks and errors
- OAuth2 + JWT: `jwt.decode` with the configured algorithm (never a hardcoded one), `options={"require": ["exp", "sub"]}`, `audience=` plus `verify_aud` only when an audience is configured. Catch `jwt.InvalidTokenError` and answer 401 -- never an unhandled `KeyError`/500 on a bad or incomplete token.
- `BackgroundTasks` for lightweight fire-and-forget (email, audit log); Celery or ARQ with a broker for reliable, retryable, long-running work. Add `X-Request-ID` to every response for tracing.
- Errors: a domain exception hierarchy (`NotFoundError` 404, `ConflictError` 409, `ForbiddenError` 403) behind one registered `exception_handler` returning RFC 9457 Problem Details; see the handler in `references/FASTAPI_PROJECT_PATTERNS.md` when writing it, failure taxonomy in `error-handling`.

### Step 5 -- Testing and deployment
- `pytest` + `pytest-asyncio` (mode=auto); `httpx.AsyncClient` with `ASGITransport` against the app; `testcontainers` for real PostgreSQL (no SQLite substitution); fixtures run app factory -> client -> test database with rollback per test.
- Profile with `py-spy` (CPU) and `memray` (memory); benchmark with `locust` or `k6`.
- Multi-worker production: `uvicorn --workers` or behind `gunicorn`; handle SIGTERM and drain in-flight requests.

## Common pitfalls
- Sync database drivers in async FastAPI (blocks the event loop); one SQLAlchemy session shared across requests (use the per-request factory).
- Alembic migrations not run against a real PostgreSQL before deploy; SQLite in tests (misses constraint and type differences).

## Reference files
Load these from `references/` only when the task needs the deeper detail:
- **[`references/FASTAPI_PROJECT_PATTERNS.md`](references/FASTAPI_PROJECT_PATTERNS.md)** -- read when building the app factory, dependency-injection graph, Pydantic v2 schemas/typed settings, or async/background-task patterns in full.
- **[`references/PYTHON_313_FEATURES.md`](references/PYTHON_313_FEATURES.md)** -- consult before enabling free-threaded (no-GIL) mode, the JIT compiler, or other 3.13+ language features for a specific workload.

## Official documentation

<!-- FRESHNESS: Always verify against official docs. Links may change. -->

- **FastAPI**: https://fastapi.tiangolo.com/ | release notes: https://fastapi.tiangolo.com/release-notes/
- **Pydantic v2**: https://docs.pydantic.dev/latest/
- **SQLAlchemy 2.x (async)**: https://docs.sqlalchemy.org/en/20/ | https://docs.sqlalchemy.org/en/20/orm/extensions/asyncio.html
- **Alembic**: https://alembic.sqlalchemy.org/
- **uvicorn**: https://www.uvicorn.org/ | **granian** (Rust ASGI server): https://github.com/emmett-framework/granian
- **Python status / release schedule**: https://devguide.python.org/versions/ | What's New: https://docs.python.org/3/whatsnew/
- **uv (package manager)**: https://docs.astral.sh/uv/
- **pytest**: https://docs.pytest.org/ | **pytest-asyncio**: https://pytest-asyncio.readthedocs.io/
- **testcontainers-python**: https://testcontainers-python.readthedocs.io/

From rafaelob/aiLine, Apache-2.0.

More from rafaelob/aiLine