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: read when adding or reshaping tests, or when the suite is slow.
• linting.md: read when changing Ruff or type-checker config, or the lint/type-check commands.