python-guidelines

name	python-guidelines
description	Invoke BEFORE writing any Python code (CLI tools, libraries, APIs, modules, tests). Encodes the project's Python + uv + ruff + pyright + pytest architecture, plus conditional references for DB, API, and caching work.

Python Guidelines

Follow these before writing any Python code. Load the matching reference below only when that concern is in play.

Conditional references — read the file when the case applies

• Using a database? → read references/db.md (SQLAlchemy 2.0 + Alembic).
• Building/exposing an API? → read references/api.md (FastAPI).
• Adding caching? → read references/caching.md (Redis / redis-py).

Don't load a reference the task doesn't touch. A plain CLI with no DB/API/cache uses this file alone.

Stack

• Language: Python 3.12+, fully type-annotated.
• Env & deps: uv with pyproject.toml (never hand-edit requirements.txt; no bare pip install). Add deps with uv add, run with uv run.
• CLI: Typer (or Click). Libraries: expose a clean public API in __init__.py, no CLI coupling.
• Use Context7 MCP for current, version-accurate docs of every library in the stack — never rely on training data for API syntax, config, or migrations.

Architecture

• Files ≤ ~500 lines. Split when they grow past that.
• Small, single-purpose functions — one clear responsibility each; extract when a function does too much.
• src layout: src/<pkg>/, tests in tests/. Entry point via cli.py/__main__.py; pyproject.toml [project.scripts] wires the console command.
• Directory tree by purpose, not by type. No needless files, no catch-all utils.py.
• Keep I/O and side effects at the edges; core logic stays pure and importable.
• snake_case for functions/vars/modules, PascalCase for classes, UPPER_SNAKE for constants.
• Comments minimal — explain why, never what. Docstrings on public functions/classes only.

Python rules

• Type every signature (params + return). Prefer builtins list/dict/X | None over typing.List/Optional.
• Prefer @dataclass (or Pydantic when validation is needed) over ad-hoc dicts for structured data.
• pathlib.Path over os.path. f-strings over %/.format. Context managers (with) for any resource.
• Raise specific exceptions; never bare except:. Let errors surface unless you handle them meaningfully.
• Stdlib first: pathlib/itertools/functools/collections/dataclasses/json/subprocess before any dependency.
• No mutable default args. Guard entry points with if __name__ == "__main__":.

Testing (pytest)

• pytest, tests in tests/, files test_*.py, plain assert. Fixtures only when they remove real duplication.
• Test behavior at the public boundary, not internals. Parametrize (@pytest.mark.parametrize) over copy-pasted cases.
• Every non-trivial function (branch, loop, parser, money/security path) leaves one runnable check behind.

Tooling — run before done

• Lint + fix: uv run ruff check --fix .
• Format: uv run ruff format .
• Types: uv run pyright
• Tests: uv run pytest
• All must pass clean before handing off.

Laziness

• Stdlib and one-liners before custom classes or new dependencies. Never add a dep for what a few lines cover.
• No speculative abstractions (interface with one impl, factory for one product), no config for a value that never changes, no scaffolding "for later".