Rodin
71 lines
2.4 KiB
Markdown
71 lines
2.4 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** — the trigger conditions
|
|
- **When NOT to use** — where the pattern causes harm
|
|
- **Preferred shapes** — examples of the intended form
|
|
- **Counterexamples** — what to avoid and why
|
|
- **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
|
|
- `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`
|
|
|
|
Why this mix works:
|
|
- CPython: API boundaries, exceptions, context managers, typing surface design
|
|
- HTTPX: package facade design, sync/async split, transport seams, error taxonomy
|
|
- pytest: fixture lifetime, parametrization, test ergonomics
|
|
- Pydantic: validation and serialization boundaries
|
|
- attrs: lightweight value-object/data-model patterns
|
|
- Click: CLI-facing exception and public-surface patterns
|
|
- SQLAlchemy: explicit persistence/session lifetime and sync-vs-async caveats
|
|
|
|
## 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`
|
|
- `smells/common-mistakes.md`
|
|
|
|
## Reviewing this repo
|
|
|
|
Recommended review order:
|
|
1. `README.md`
|
|
2. `PROCESS.md`
|
|
3. `sources/*.md` for evidence quality
|
|
4. `patterns/*.md` for synthesis quality
|
|
5. `smells/*.md` for anti-pattern coverage
|
|
|
|
Questions to ask during review:
|
|
- Is each claim grounded in repeated upstream evidence?
|
|
- Are caveats preserved instead of flattened away?
|
|
- Does the pattern stay at the Python level rather than drifting into framework guidance?
|
|
- Are citations specific enough to be re-checked quickly?
|
|
|
|
## Extraction rule
|
|
|
|
Do not write pattern docs from memory. First collect repeated source examples with `file:line` citations, then synthesize the rule. |