writing-python

# Python Development `pyproject.toml` is the source of truth for the Python target, tools, scripts, and dependencies. Check it, `.python-version`, and CI before using 3.12-only syntax. Project conventions win over these defaults. ## Toolchain - uv for environments and commands (`uv run`, `uv add`); never call `pip` directly. Match the lockfile already in use. - Ruff for lint and format. Pyright for types, or `ty` only when the project has adopted it. - pytest for tests. ## Defaults - Stdlib before packages: `argparse`, `dataclasses`, `pathlib`, `json`, `urllib`, `logging`. Do not add Rich, pydantic, or dotenv only for polish. - 3.12+ typing: `X | Y`, builtin generics, PEP 695 generics and `type` aliases. Keep legacy `TypeVar` style when editing pre-3.12 modules. - `@dataclass(frozen=True, slots=True)` for small values; `TypedDict` with `NotRequired` at recurring JSON boundaries; `Protocol` owned by the consumer. Keep `dict[str, Any]` at the boundary only. - Import collection ABCs from `collections.abc`. Take `Sequence[T]` for read-only inputs. - Wrap errors with `raise DomainError(...) from exc`. Catch broad exceptions only where they become an exit code, response, log entry, or re-raise. - Async: `asyncio.TaskGroup` for sibling tasks, `asyncio.timeout` around external waits. Keep references to background tasks so their exceptions surface. - Text I/O takes an explicit `encoding`. Sort glob results when order reaches output or tests. - Libraries log through `logging`; they never print diagnostics. ## CLIs - `argparse` for small tools; Click or Typer only when the project already uses them. - `main(argv: Sequence[str] | None = None) -> int`; call `asyncio.run` only there. Expose it via `[project.scripts]` and keep `python -m pkg` working. - Config precedence: flag, env, config file, default. ## References - [testing.md](references/testing.md): read when adding or reshaping tests, or when the suite is slow. - [linting.md](references/linting.md): read when changing Ruff or type-checker config, or the lint/type-check commands. Done when the relevant build/test/lint checks pass on what you changed, or you name each check that did not run and why.