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