# 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.