python-standards

name	python-standards
description	Python coding standards, testing patterns, and pydantic/typing conventions for the readme2demo codebase. Use when writing or reviewing any Python in src/readme2demo/ or tests/, adding a module, or before committing code changes.

Python standards for readme2demo

Python ≥3.10. Match the surrounding code; these are the invariants.

Types & models

• Type hints on every public function signature; return types included.
• Data contracts are pydantic v2 models in types.py — the single source of truth every stage serializes through. Add a field THERE first, never invent an ad-hoc dict that crosses a stage boundary. Use model_dump_json(indent=2) / model_validate_json for run-dir I/O.
• Optional[X] for nullable; default containers via Field(default_factory=...).
• New fields must be backward-compatible (defaulted) — old run dirs on disk must still load.

Purity boundary (enforced, not stylistic)

• normalize.py and every engine parse_transcript are PURE and deterministic: no LLM calls, no network, no docker, no clock/random that changes output. They are tested against fixtures. If you need an LLM, you are in the wrong module.
• LLM calls live only in ingest (planner), distill, tutorial — via llm.py.

Docstrings

• One-line summary; then WHY when non-obvious. Regression-critical functions carry the failure they defend against (search for "Regression (" in tests).
• Public functions in the pipeline path get a docstring naming their invariant.

Testing (this is where the repo's value lives)

• python -m pytest tests/ -q runs in <1s with NO docker/network/API. Keep it that way: mock llm.complete_json, feed fixture transcripts, build models inline. Anything needing real infra is marked @pytest.mark.integration.
• EVERY bug fix carries a regression test whose docstring starts """Regression (<repo> run): ...""" and describes the real failure. It must fail on the old code.
• For grounding/equivalence changes: test BOTH directions — the new-variant is accepted AND an unproven/evil command is still rejected.
• Prefer table-style asserts on the actual artifact (the rendered commands.sh, the tape text, the guide markdown), not on internal state.

Style

• stdlib > third-party; the runtime deps are deliberately few (typer, rich, pydantic, jinja2, anthropic). Don't add a dependency for something stdlib does.
• subprocess.run(..., capture_output=True, text=True, timeout=..., errors="replace") is the house pattern for shelling out; always set a timeout.
• Fail with a specific, actionable message (name the env var, the file, the fix command) — see the preflight and EngineError messages for the tone.

Before you commit

Run /ship-check. Minimum: full suite green, python -m compileall -q src/ clean, no runs/ or secrets staged.