@eltonssouza/development-utility-kit 0.10.0

package/.claude/stacks/python/fastapi-0.115.md

@@ -0,0 +1,522 @@
+---
+stack: python/fastapi-0.115
+versions_covered: "0.115.x — 0.118.x"
+last_validated: 2026-05-28
+validated_against: "reference pack — Python 3.13 + FastAPI 0.115 + Pydantic 2.9 + SQLAlchemy 2.0"
+status: active
+pack_owner: "@elton"
+security_review: 2026-05-28
+next_review_due: 2027-05-28
+---
+
+# Python 3.13 + FastAPI 0.115+
+
+Canonical knowledge pack for FastAPI projects on Python 3.12+/3.13 + FastAPI 0.115+ (current line) + Pydantic v2 + SQLAlchemy 2.0. FastAPI's strengths show in async-first API services, MLOps endpoints, microservices, and projects where the admin/ORM/forms of Django would be dead weight. For projects that want Django's batteries-included experience (admin, forms, auth, ORM, migrations), use `python/django-5.md` instead.
+
+## 1. When to use this pack
+
+- Project declares `Primary stack: Python 3.12+ + FastAPI 0.115+` in `## Project Identity`.
+- `pyproject.toml` declares `fastapi>=0.115,<0.120` and `python_requires = ">=3.12"`.
+- Service is API-only (REST or gRPC), no admin UI, no server-rendered HTML at scale.
+- Heavy async I/O — multiple external HTTP calls, websockets, server-sent events, streaming.
+- MLOps / model-serving — Pydantic validation + automatic OpenAPI is FastAPI's home turf.
+- For full-stack monolith with admin + forms + ORM: use Django (`python/django-5.md`).
+- For batch processing without HTTP layer: use a plain Python project with `celery` or `prefect`, not FastAPI.
+
+## 2. Stack baseline (what this pack assumes)
+
+| Component | Version range | Notes |
+|---|---|---|
+| Python | 3.12 (min) / 3.13 (recommended) | 3.13 free-threaded build works with FastAPI; type hints are mandatory for the framework to function |
+| FastAPI | 0.115.x — 0.118.x | API stable; Annotated dependencies are the canonical form (0.100+) |
+| Pydantic | 2.9.x+ | Pydantic v1 unsupported as of FastAPI 0.100; do not mix |
+| Pydantic Settings | 2.5.x+ | Config via env vars, validated at startup |
+| SQLAlchemy | 2.0.x | New 2.0-style API (`select(...).where(...)`), `Mapped[...]` type annotations |
+| Async DB driver | `asyncpg` (Postgres), `aiomysql` (MySQL), `aiosqlite` (tests only) | NEVER mix sync `psycopg2` with async engine; pick one stack |
+| Migrations | Alembic 1.13+ | autogenerate is a draft, always review; never manual `Base.metadata.create_all()` in prod |
+| Build / packaging | `uv` (recommended) or `pip` + `pyproject.toml` | `uv pip sync requirements.lock` for deterministic installs |
+| ASGI server | `uvicorn[standard]` workers + `gunicorn` master | Or `granian` for lower latency in production |
+| Tests | pytest 8.x + `pytest-asyncio` + `httpx` AsyncClient + Testcontainers Postgres | NEVER SQLite if prod is Postgres |
+| Mutation | mutmut 3.x | Target ≥70% on `domain/` + `application/` |
+| Coverage | coverage.py 7.x with `branch = True` | Target ≥85% lines, ≥80% branches |
+| Static analysis | `ruff` + `mypy --strict` | Pydantic models get static checks via mypy plugin |
+| Security scan | `pip-audit` + `bandit` | 0 CVE with CVSS ≥7.0 |
+| Observability | OpenTelemetry SDK + `opentelemetry-instrumentation-fastapi` | W3C Trace Context; auto-instruments routes + DB + HTTP client |
+| Background jobs | Celery 5.x + Redis OR `arq` (async-native) | `arq` integrates with FastAPI lifespan cleanly |
+| OpenAPI docs | Auto-generated at `/docs` (Swagger UI) and `/redoc` (Redoc) | Disable in prod via `FastAPI(docs_url=None, redoc_url=None)` |
+
+## 3. Project structure (DDD-flavored FastAPI)
+
+```
+service/
+├── pyproject.toml
+├── uv.lock
+├── alembic.ini
+├── alembic/
+│   ├── env.py
+│   └── versions/
+├── env.example
+├── src/
+│   ├── domain/                       # pure Python, no FastAPI/SQLAlchemy imports
+│   │   ├── products/
+│   │   │   ├── entities.py
+│   │   │   ├── repository.py         # Protocol/ABC port
+│   │   │   └── services.py
+│   │   └── shared/
+│   ├── application/                  # use cases (1 callable each)
+│   │   ├── products/
+│   │   │   ├── create_product.py
+│   │   │   ├── list_products.py
+│   │   │   └── dto.py
+│   │   └── shared/
+│   ├── infrastructure/               # SQLAlchemy + external clients
+│   │   ├── db/
+│   │   │   ├── engine.py             # async engine + sessionmaker
+│   │   │   └── base.py               # DeclarativeBase
+│   │   ├── products/
+│   │   │   ├── models.py             # ORM (SQLAlchemy 2.0 Mapped)
+│   │   │   └── repository_impl.py
+│   │   └── http/
+│   │       └── upstream_client.py    # httpx.AsyncClient wrapper
+│   ├── api/                          # FastAPI routes + schemas
+│   │   ├── products/
+│   │   │   ├── router.py
+│   │   │   ├── schemas.py            # Pydantic req/res models
+│   │   │   └── deps.py               # Depends() factories
+│   │   └── shared/
+│   │       ├── exception_handlers.py # RFC 9457 ProblemDetail
+│   │       └── middleware.py
+│   ├── config/
+│   │   └── settings.py               # pydantic-settings BaseSettings
+│   └── main.py                       # FastAPI() instance + lifespan
+└── tests/
+    ├── unit/                         # domain + application
+    ├── integration/                  # API + DB with Testcontainers
+    └── e2e/                          # full HTTP through TestClient
+```
+
+**Rule**: `domain/` and `application/` contain **zero FastAPI and zero SQLAlchemy imports**. They are pure Python testable without any HTTP server or DB. `infrastructure/` imports SQLAlchemy. `api/` imports FastAPI. The 4 layers do not skip — `api/` never imports `infrastructure/` directly; it goes through `application/`.
+
+## 4. Code patterns
+
+### Pydantic schemas (request/response separated)
+
+```python
+# src/api/products/schemas.py
+from pydantic import BaseModel, Field, ConfigDict
+from decimal import Decimal
+from uuid import UUID
+from datetime import datetime
+
+class CreateProductRequest(BaseModel):
+    model_config = ConfigDict(extra="forbid")   # reject unknown fields
+    name: str = Field(min_length=1, max_length=120)
+    price: Decimal = Field(gt=Decimal("0"))
+    stock: int = Field(ge=0)
+
+class ProductResponse(BaseModel):
+    model_config = ConfigDict(from_attributes=True)
+    id: UUID
+    name: str
+    price: Decimal
+    stock: int
+    created_at: datetime
+```
+
+**Rule**: `extra="forbid"` on every request model — silent acceptance of unknown fields is a footgun. Response models declared explicitly (never just return ORM object dict).
+
+### Route (Annotated dependencies, FastAPI 0.115 canonical)
+
+```python
+# src/api/products/router.py
+from typing import Annotated
+from fastapi import APIRouter, Depends, status
+from src.api.products.schemas import CreateProductRequest, ProductResponse
+from src.application.products.create_product import CreateProductUseCase
+from src.api.products.deps import get_create_product_use_case
+
+router = APIRouter(prefix="/api/v1/products", tags=["products"])
+
+@router.post("", status_code=status.HTTP_201_CREATED, response_model=ProductResponse)
+async def create_product(
+    req: CreateProductRequest,
+    use_case: Annotated[CreateProductUseCase, Depends(get_create_product_use_case)],
+) -> ProductResponse:
+    product = await use_case.execute(name=req.name, price=req.price, stock=req.stock)
+    return ProductResponse.model_validate(product)
+```
+
+**Rule**: `Annotated[T, Depends(...)]` is the canonical form (FastAPI 0.95+). Routes are thin — parse, call use case, validate response. Business logic stays in `application/`.
+
+### Domain entity (no SQLAlchemy / no FastAPI)
+
+```python
+# src/domain/products/entities.py
+from dataclasses import dataclass
+from decimal import Decimal
+from uuid import UUID
+from datetime import datetime
+
+@dataclass(frozen=True)
+class Product:
+    id: UUID
+    name: str
+    price: Decimal
+    stock: int
+    created_at: datetime
+
+    def reserve(self, qty: int) -> "Product":
+        if qty <= 0:
+            raise ValueError("qty must be positive")
+        if qty > self.stock:
+            raise ValueError("insufficient stock")
+        return Product(self.id, self.name, self.price, self.stock - qty, self.created_at)
+```
+
+### Domain port + infrastructure adapter (SQLAlchemy 2.0)
+
+```python
+# src/domain/products/repository.py
+from typing import Protocol, Optional
+from uuid import UUID
+from .entities import Product
+
+class ProductRepository(Protocol):
+    async def get(self, id: UUID) -> Optional[Product]: ...
+    async def save(self, product: Product) -> None: ...
+```
+
+```python
+# src/infrastructure/products/models.py
+from sqlalchemy.orm import Mapped, mapped_column
+from sqlalchemy import String, Numeric, DateTime, func
+from datetime import datetime
+from decimal import Decimal
+from uuid import UUID, uuid4
+import sqlalchemy as sa
+from src.infrastructure.db.base import Base
+
+class ProductORM(Base):
+    __tablename__ = "products"
+    id: Mapped[UUID] = mapped_column(sa.Uuid, primary_key=True, default=uuid4)
+    name: Mapped[str] = mapped_column(String(120), index=True)
+    price: Mapped[Decimal] = mapped_column(Numeric(12, 2))
+    stock: Mapped[int] = mapped_column()
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
+```
+
+```python
+# src/infrastructure/products/repository_impl.py
+from sqlalchemy.ext.asyncio import AsyncSession
+from sqlalchemy import select
+from uuid import UUID
+from typing import Optional
+from src.domain.products.entities import Product
+from src.domain.products.repository import ProductRepository
+from src.infrastructure.products.models import ProductORM
+
+class SqlAlchemyProductRepository(ProductRepository):
+    def __init__(self, session: AsyncSession):
+        self._session = session
+
+    async def get(self, id: UUID) -> Optional[Product]:
+        row = await self._session.scalar(select(ProductORM).where(ProductORM.id == id))
+        return self._to_domain(row) if row else None
+
+    async def save(self, product: Product) -> None:
+        row = ProductORM(
+            id=product.id, name=product.name,
+            price=product.price, stock=product.stock,
+        )
+        await self._session.merge(row)
+        await self._session.commit()
+
+    @staticmethod
+    def _to_domain(row: ProductORM) -> Product:
+        return Product(
+            id=row.id, name=row.name, price=row.price,
+            stock=row.stock, created_at=row.created_at,
+        )
+```
+
+**Rule**: SQLAlchemy 2.0 style — `select(Model).where(...)` not legacy `Model.query`. `Mapped[T]` annotations for static type-check. Repository implements the domain `Protocol`.
+
+### Lifespan + dependency injection
+
+```python
+# src/main.py
+from contextlib import asynccontextmanager
+from fastapi import FastAPI
+from src.infrastructure.db.engine import engine, AsyncSessionLocal
+from src.api.products.router import router as products_router
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Startup: warm-up, health checks against DB, etc.
+    yield
+    # Shutdown: close engine cleanly
+    await engine.dispose()
+
+app = FastAPI(
+    title="Products Service",
+    lifespan=lifespan,
+    docs_url=None,                # disable in prod via settings
+    redoc_url=None,
+)
+app.include_router(products_router)
+```
+
+**Rule**: `lifespan` is the canonical startup/shutdown hook (FastAPI 0.93+). Never use deprecated `@app.on_event("startup")` — it does not support async DI correctly.
+
+## 5. Testing
+
+### Unit (pytest, no FastAPI/DB)
+
+```python
+# tests/unit/domain/products/test_product.py
+import pytest
+from decimal import Decimal
+from uuid import uuid4
+from datetime import datetime, timezone
+from src.domain.products.entities import Product
+
+def test_reserve_decreases_stock():
+    p = Product(uuid4(), "x", Decimal("9.90"), 10, datetime.now(timezone.utc))
+    p2 = p.reserve(3)
+    assert p2.stock == 7
+
+def test_reserve_refuses_excess():
+    p = Product(uuid4(), "x", Decimal("9.90"), 10, datetime.now(timezone.utc))
+    with pytest.raises(ValueError):
+        p.reserve(11)
+```
+
+### Integration (httpx AsyncClient + Testcontainers Postgres)
+
+```python
+# conftest.py
+import pytest
+import pytest_asyncio
+from testcontainers.postgres import PostgresContainer
+from httpx import ASGITransport, AsyncClient
+from src.main import app
+
+@pytest.fixture(scope="session")
+def postgres():
+    with PostgresContainer("postgres:16-alpine") as pg:
+        yield pg
+
+@pytest_asyncio.fixture
+async def client():
+    transport = ASGITransport(app=app)
+    async with AsyncClient(transport=transport, base_url="http://test") as ac:
+        yield ac
+```
+
+```python
+# tests/integration/api/products/test_create.py
+import pytest
+
+@pytest.mark.asyncio
+async def test_create_product_returns_201(client):
+    r = await client.post("/api/v1/products", json={
+        "name": "widget", "price": "9.90", "stock": 100,
+    })
+    assert r.status_code == 201
+    body = r.json()
+    assert body["name"] == "widget"
+    assert body["stock"] == 100
+```
+
+**Rule**: TestClient from FastAPI is sync — use `httpx.AsyncClient` with `ASGITransport` for async tests. `pytest-asyncio` strict mode.
+
+### Mutation (mutmut)
+
+```bash
+mutmut run --paths-to-mutate=src/domain,src/application
+mutmut results
+# Target: killed/total >= 70% on domain + application
+```
+
+## 6. Build & run commands
+
+```bash
+# Setup
+uv venv
+uv pip sync requirements.lock        # or: uv pip install -e ".[dev]"
+
+# Migrations
+alembic upgrade head
+
+# Run dev
+uvicorn src.main:app --reload --host 0.0.0.0 --port 8000
+
+# Run prod (multiple workers)
+gunicorn src.main:app -w 4 -k uvicorn.workers.UvicornWorker --bind 0.0.0.0:8000
+
+# OR with granian for lower latency
+granian --interface asgi src.main:app --workers 4 --port 8000
+
+# Lint + format
+ruff check --fix .
+ruff format .
+
+# Type check
+mypy --strict src/
+
+# Tests
+pytest                                  # all
+pytest tests/unit/                      # fast loop
+pytest --cov=src --cov-branch --cov-fail-under=85
+pytest -m "not slow"                    # skip Testcontainers
+
+# Mutation
+mutmut run --paths-to-mutate=src/domain,src/application
+
+# Security scan
+pip-audit
+bandit -ll -r src/
+
+# Migrations (always review autogenerate)
+alembic revision --autogenerate -m "add products table"
+alembic upgrade head
+alembic downgrade -1
+```
+
+## 7. Security (per ADR-007 + ADR-027 — MANDATORY section)
+
+### 7.1 Authentication & Authorization
+
+- **JWT (stateless)**: `python-jose[cryptography]` + `passlib[bcrypt]`. RS256 (asymmetric) recommended for multi-service setups; HS256 acceptable for single-service.
+- **OAuth2 + OpenID Connect**: `authlib` integrates with Auth0/Keycloak/Cognito.
+- **API keys for internal services**: `secrets.token_urlsafe(32)` + hashed storage. Never plaintext.
+- **Password hashing**: bcrypt cost 12 (passlib default), or Argon2 via `argon2-cffi` (preferred for new projects).
+- **Authorization**: dependency-based. `Depends(get_current_user)` → `Depends(require_role("admin"))` chain. Object-level checks inside the use case.
+
+### 7.2 CORS
+
+```python
+# src/main.py
+from fastapi.middleware.cors import CORSMiddleware
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["https://app.example.com"],   # NEVER ["*"] in prod
+    allow_credentials=True,
+    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+    allow_headers=["Authorization", "Content-Type"],
+)
+```
+
+### 7.3 Validation & input sanitization
+
+- **SQL injection**: SQLAlchemy 2.0 parameterizes by default. NEVER `text(f"SELECT * FROM users WHERE id = {user_input}")` — use `text("... :id").bindparams(id=user_input)`.
+- **NoSQL injection**: if using MongoDB via `motor`, use the typed query builder, not dict concatenation.
+- **Pydantic strictness**: `extra="forbid"` on all request models. Type validation is the first line of defense.
+- **File uploads**: `UploadFile.content_type` is client-supplied — always re-validate via `python-magic` server-side. Never trust the extension.
+
+### 7.4 Secrets management
+
+```python
+# src/config/settings.py
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(env_file=".env", env_file_encoding="utf-8")
+    database_url: str
+    jwt_secret_key: str
+    sentry_dsn: str | None = None
+
+settings = Settings()
+```
+
+- `.env` gitignored; `env.example` committed.
+- Cloud-native: prefer Secret Manager (AWS / GCP) over `.env` in prod. `pydantic-settings` can read from there.
+
+### 7.5 Rate limiting
+
+```python
+# pip install slowapi
+from slowapi import Limiter, _rate_limit_exceeded_handler
+from slowapi.errors import RateLimitExceeded
+from slowapi.util import get_remote_address
+
+limiter = Limiter(key_func=get_remote_address)
+app.state.limiter = limiter
+app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
+
+@router.post("/login")
+@limiter.limit("5/minute")
+async def login(request: Request, ...): ...
+```
+
+- `5/minute` on `/login`, `/signup`, `/password-reset`.
+- `100/minute` on regular authenticated GETs.
+- Behind reverse proxy: use `X-Forwarded-For` (validate the proxy is trusted!).
+
+### 7.6 OWASP Top 10 mapping
+
+| OWASP | Mitigation in FastAPI 0.115 |
+|---|---|
+| A01 Broken Access Control | `Depends(require_role(...))` per route; object-level check inside use case; default-deny pattern |
+| A02 Cryptographic Failures | Argon2/bcrypt password hashing; TLS terminated at proxy with HSTS; JWT RS256 with kid rotation |
+| A03 Injection | SQLAlchemy parameterization; Pydantic `extra="forbid"`; never `text()` with f-strings |
+| A04 Insecure Design | DDD layering enforced (`domain/` no FastAPI); use case = single async callable; ADRs document deviations |
+| A05 Security Misconfiguration | `docs_url=None, redoc_url=None` in prod; `DEBUG=False` via env split; explicit CORS allowlist |
+| A06 Vulnerable Components | `pip-audit` in CI; `renovate` for PR bumps; `bandit` for code patterns |
+| A07 Auth Failures | slowapi rate limit on auth endpoints; account lock via Redis counter; MFA via `pyotp` |
+| A08 Data Integrity | `uv pip install --require-hashes`; SBOM via `cyclonedx-py`; signed releases |
+| A09 Logging Failures | Structured JSON via `structlog`; correlation ID via `asgi-correlation-id`; **NEVER** log request body raw |
+| A10 SSRF | Allowlist outbound HTTP via centralized `httpx.AsyncClient` with explicit allowed hosts; reject `localhost`, `169.254.169.254`, private CIDRs by default |
+
+### 7.7 LGPD / GDPR / compliance specifics
+
+- **PII fields tagged**: convention `pii=True` in column comments + custom mypy check.
+- **Soft delete**: `is_deleted` + `deleted_at` columns; filter via SQLAlchemy event listener that injects `WHERE is_deleted = false`.
+- **Data subject access (Article 15)**: `GET /api/v1/me/export` returns all user data as ZIP/JSON.
+- **Erasure (Article 17)**: `DELETE /api/v1/me` redacts PII columns while preserving FKs (orders kept, customer = null).
+- **Encryption at rest**: PostgreSQL TDE (cloud-managed) or column-level via `sqlalchemy-utils` `EncryptedType`.
+
+## 8. Anti-patterns (block in code-review)
+
+| ❌ Bad | ✅ Good | Why |
+|---|---|---|
+| `def` async route that does sync I/O (e.g., `requests.get`) | `async def` + `httpx.AsyncClient` OR `def` sync route with sync I/O | Sync I/O inside `async def` blocks the event loop and kills throughput |
+| `extra="allow"` on request `BaseModel` (default `extra="ignore"`) | `extra="forbid"` explicitly | Silent acceptance of typos / unintended fields = footgun |
+| Returning ORM object directly from route | `response_model=Schema` + `Schema.model_validate(obj)` | API contract leaks data model otherwise |
+| `Base.metadata.create_all()` in `lifespan` startup | Alembic migrations, applied separately | Auto-create skips review and migration history |
+| `Session.commit()` inside a use case AND inside repository | Commit at exactly one layer (typically the use case via UnitOfWork) | Double commit / nested transactions = subtle bugs |
+| SQLite for tests when prod is Postgres | Testcontainers Postgres 16 | Subtle SQL differences cause prod-only bugs |
+| `engine = create_engine(url, echo=True)` in prod | `echo=False` in prod; `echo=True` only for local debugging | Logs every query; PII leakage; performance hit |
+| Catching `Exception:` in routes | Custom exception handlers via `app.add_exception_handler` | Hides bugs and breaks 500 telemetry |
+| Storing JWT secret in code | `pydantic_settings` from env, validated at startup | Secret in code = secret in git history |
+| Disabling `docs_url`/`redoc_url` via global if/else | Settings flag + `docs_url=settings.openapi_url` pattern | Centralized config wins |
+| Returning `dict` directly without a Pydantic response model | `response_model=...` declared explicitly | Type safety + OpenAPI schema correctness |
+
+## 9. Migration hints — FastAPI 0.95 → 0.115
+
+Breaking changes worth flagging when `migrator` agent runs FastAPI 0.95+ → 0.115:
+
+- **Pydantic v1 unsupported** (FastAPI 0.100+). All `BaseModel`/`Field`/`validator` imports must use Pydantic v2. `@validator` → `@field_validator`. `Config` class → `model_config = ConfigDict(...)`.
+- **`Annotated` dependencies are the canonical form**. `param: SomeType = Depends(...)` still works but is being phased out. Migrate to `param: Annotated[SomeType, Depends(...)]`.
+- **`lifespan` replaces `on_event`** (FastAPI 0.93+). `@app.on_event("startup")` is deprecated; use `lifespan` context manager.
+- **`response_model_exclude_unset`** behavior changed slightly when combined with `response_model_by_alias`. Test both options if you depend on aliasing.
+- **WebSocket** API gained stricter typing. If you use `WebSocket.receive_json()` patterns from <0.100, double-check.
+- **OpenAPI 3.1**: FastAPI 0.99+ emits OpenAPI 3.1 by default. Older clients may need explicit `openapi_version="3.0.0"` or use the `openapi_extra` shim.
+
+Hand off to `migrator` with: current FastAPI version, current Pydantic version, list of routes using `Depends()` without `Annotated`, list of `@app.on_event` handlers.
+
+## 10. References
+
+- [FastAPI 0.115 docs](https://fastapi.tiangolo.com/)
+- [Pydantic v2 migration guide](https://docs.pydantic.dev/latest/migration/)
+- [SQLAlchemy 2.0 docs](https://docs.sqlalchemy.org/en/20/)
+- [Alembic docs](https://alembic.sqlalchemy.org/en/latest/)
+- [pytest-asyncio docs](https://pytest-asyncio.readthedocs.io/)
+- [slowapi (rate limiting)](https://github.com/laurentS/slowapi)
+- [asgi-correlation-id](https://github.com/snok/asgi-correlation-id)
+- [OWASP REST Security Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/REST_Security_Cheat_Sheet.html)
+- ADR-007 (Senior+ gate thresholds — coverage ≥85%, mutation ≥70%)
+- ADR-026 (Generic agents + stack packs architecture)
+- ADR-027 (Pack governance — frontmatter + security mandatory + CODEOWNERS + annual review)
+- ADR-029 (Canonical pack format — this document follows it)