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