Rodin
77 lines
3.2 KiB
Markdown
77 lines
3.2 KiB
Markdown
# Python Patterns
|
|
|
|
**Prescriptive.** Follow these when writing Python code.
|
|
|
|
This repo captures reusable Python patterns extracted from mature upstream codebases, then turns them into concise guidance with citations.
|
|
|
|
A good pattern doc here includes:
|
|
- **Why** — the reasoning, not just the rule
|
|
- **When to use / not use** — where the pattern helps or causes harm
|
|
- **Source citations** — verified `file:line` anchors from real codebases
|
|
|
|
These docs should be derived from what strong Python codebases actually do, not from generic style-blog advice.
|
|
|
|
## Structure
|
|
|
|
- `patterns/` — what to do
|
|
- `comparison/` — where framework or library choices bend the generic Python guidance
|
|
- `smells/` — what to avoid
|
|
- `sources/` — extracted source-study notes and upstream references
|
|
- `PROCESS.md` — the repeatable extraction/refinement workflow used to build this repo
|
|
|
|
## Current source base
|
|
|
|
Primary upstreams mined so far:
|
|
- `python/cpython`
|
|
- `encode/httpx`
|
|
- `pytest-dev/pytest`
|
|
- `pydantic/pydantic`
|
|
- `python-attrs/attrs`
|
|
- `pallets/click`
|
|
- `sqlalchemy/sqlalchemy`
|
|
|
|
## Current pattern set
|
|
|
|
- `patterns/module-design.md`
|
|
- `patterns/typing.md`
|
|
- `patterns/error-handling.md`
|
|
- `patterns/async-boundaries.md`
|
|
- `patterns/testing.md`
|
|
- `patterns/data-models.md`
|
|
- `comparison/pydantic-vs-python.md`
|
|
- `smells/common-mistakes.md`
|
|
|
|
## Boundary rubric: does this belong in `python-patterns`?
|
|
|
|
Use this rubric both when writing docs here and when deciding where a real code example belongs.
|
|
|
|
Put the guidance here when most of the rule is about:
|
|
- module and package structure
|
|
- API shape that would still make sense in a library, CLI, worker, or batch job
|
|
- internal data modeling and state boundaries
|
|
- exception design independent of HTTP or framework behavior
|
|
- typing, protocols, sync/async design, and test structure that do not depend on a web framework
|
|
|
|
Push the guidance out to a framework repo when most of the rule is about:
|
|
- request or response handling owned by FastAPI
|
|
- dependency injection through framework signatures
|
|
- HTTP exception translation, status codes, or response envelopes
|
|
- OpenAPI-facing schema behavior as part of a service contract
|
|
- app lifespan and other framework-owned resource wiring
|
|
|
|
Tie-break:
|
|
- if the guidance could reasonably live in multiple places and a clean split would make it harder for someone writing code to find, prefer the **higher-level abstraction** and cross-link to the narrower guidance instead of over-optimizing repo purity
|
|
|
|
### How to handle sloppy mixed examples
|
|
|
|
Real code often mixes Python and framework concerns in the same file, function, or even line. Do **not** classify by file path alone.
|
|
|
|
Instead:
|
|
- extract the **Python-level rule** from the mixed example and keep only that part here
|
|
- move or link the **framework-owned rule** to the framework repo
|
|
- if one line expresses both concerns, write down which part is reusable without FastAPI and which part depends on FastAPI being present
|
|
- when in doubt, prefer a narrower Python rule plus a comparison note instead of smuggling framework behavior into the base pattern
|
|
|
|
## Extraction rule
|
|
|
|
Do not write pattern docs from memory. First collect repeated source examples with `file:line` citations, then synthesize the rule. |