# FastAPI Conventions

**Descriptive first, prescriptive second.** This repo captures how mature FastAPI-adjacent codebases structure web services, then distills the conventions worth following.

Use this repo for framework and service-boundary concerns that do **not** belong in a language-level Python patterns repo.

## Structure

- `patterns/` — route, dependency, schema, persistence, error, and testing conventions
- `comparison/` — where FastAPI conventions differ from broader Python patterns
- `sources/` — upstream notes, code excerpts, and rationale
- `PROCESS.md` — the repeatable extraction/refinement workflow used to build this repo

## Current source base

Primary upstreams mined so far:
- `fastapi/fastapi`
- `encode/starlette`
- `pydantic/pydantic`
- `encode/httpx`
- `fastapi-users/fastapi-users`
- `fastapi/full-stack-fastapi-template`

## Current convention set

- `patterns/routes.md`
- `patterns/dependencies.md`
- `patterns/pydantic-boundaries.md`
- `patterns/errors.md`
- `patterns/persistence.md`
- `patterns/testing.md`
- `comparison/fastapi-vs-python.md`

## Boundary rubric: does this belong in `fastapi-conventions`?

Use this repo when the rule is mainly about the HTTP or app boundary: routes, `Depends(...)`, request/response schemas, HTTP error meaning, lifespan, or ASGI-level testing.

Push it back to the sibling `python-patterns` repo when the rule would still make sense in a CLI, library, or batch job.

Quick check:
- if FastAPI or Starlette owns the behavior, this repo should lead
- if deleting the HTTP boundary leaves most of the rule intact, it is probably too generic for this repo
- if the split is awkward, prefer the higher-level doc and cross-link rather than duplicating guidance

## Core rule

Do not write convention docs from memory. First collect repeated upstream examples with `file:line` citations, then synthesize the convention.