Initial extracted documentation set

README.md

@@ -0,0 +1,71 @@
+# 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.