python-patterns/README.md

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.