python

# Python Prefer typed, explicit Python with validation at boundaries, modern async I/O, and simple seams over framework-heavy indirection. ## When to Activate - Add or refactor Python modules - Choose a model type for request or domain data - Write an outbound HTTP integration - Add async handlers or background jobs - Configure pytest, typing, or packaging - Replace hidden globals with explicit dependencies - Review Python code for type and validation drift ## Typing and Modeling | Pattern | Preferred | Avoid | | --- | --- | --- | | Public functions | Full parameter and return annotations | Unannotated signatures | | Collections | `list[str]`, `dict[str, int]` | `List`, `Dict` unless compatibility requires it | | Optional values | `str | None` | Implicit `None` returns | | Need | Use | | --- | --- | | External input validation | `pydantic.BaseModel` | | Internal immutable value object | `@dataclass(frozen=True)` | | Loosely structured mapping shape | `TypedDict` | ## HTTP and Async BAD ```python import requests response = requests.get(url, timeout=30) ``` GOOD ```python import httpx async with httpx.AsyncClient(timeout=10.0) as client: response = await client.get(url) ``` | Rule | Why | | --- | --- | | Use `async` only for real I/O boundaries | Avoid fake async complexity | | Do not call blocking I/O inside async handlers | Prevent event loop stalls | | Batch concurrent I/O with `asyncio.TaskGroup` or `gather` where safe | Improve latency deterministically | ## Project Layout and DI | Section | Purpose | | --- | --- | | `[project]` | Metadata and dependencies | | `[tool.pytest.ini_options]` | Test discovery and markers | | `[tool.ruff]` or `[tool.black]` | Lint and format configuration | | `[tool.mypy]` | Type checking configuration | | Preferred | Avoid | | --- | --- | | Pass collaborators through constructors or function parameters | Global singletons hidden inside modules | | Build objects in a wiring layer | Import-time side effects creating clients | BAD ```python def create_user(data): return User(**data) ``` GOOD ```python class CreateUserInput(BaseModel): email: EmailStr name: str def create_user(data: CreateUserInput) -> User: return User(email=data.email, name=data.name) ``` ## Checklist - [ ] Public functions and methods have type hints - [ ] Boundary inputs are validated with pydantic where appropriate - [ ] `httpx` is used for outbound HTTP unless a project standard overrides it - [ ] Async code avoids blocking calls - [ ] `pyproject.toml` centralizes tool configuration - [ ] Data models use `BaseModel`, `dataclass`, or `TypedDict` intentionally - [ ] Dependencies are injected explicitly