fastapi-prolisted

# FastAPI + SQLAlchemy (async) Pro Web-API layer guidance. Builds on the `python` module (typing, async discipline, ruff/pyright). Layering: **Router → Service → Repository**; routers stay thin (validate, delegate, shape response), business logic lives in services, data-access in repositories. ## Routers & dependency injection - Inject collaborators via `Depends(...)` — DB session, current user, settings. Don't instantiate sessions/clients inside the handler. - Declare an explicit `response_model=` and `status_code=` on every route. Never return raw ORM objects — return a Pydantic response schema (prevents lazy-load serialization surprises and leaking columns). - Keep one session per request, yielded by a dependency; commit/rollback at the edge of the unit of work, not scattered through services. - Version/prefix routers (`APIRouter(prefix=...)`); group by domain. Paginate list endpoints with a consistent envelope (ccas standardized `/pipeline/runs` pagination) and bound max page size. ## Pydantic schemas - Separate **request** (`...Create` / `...Update`) and **response** (`...Out`) models from ORM models. Use `model_config = ConfigDict(from_attributes=True)` for ORM→schema conversion. - Validate at the boundary: constrained types, field validators. Reject bad input with 422 rather than letting it reach the DB. - Don't put secrets/internal fields in response schemas. ## SQLAlchemy 2.0 async - `async with AsyncSession(...) as session:` — every query is