Rodin
47 lines
1.9 KiB
Markdown
47 lines
1.9 KiB
Markdown
# 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. |