Python conventions

Write idiomatic, typed Python

Add Python that reads as pythonic, is fully type-hinted, and matches the repo's existing idioms and tooling — clear and correct, not just runnable.

Steps

1. Read the lore first. Call search_lore (Memory MCP) for the repo's Python conventions and respect its config: the Python version, pyproject.toml (dependencies, tool config), the formatter/linter (ruff / black), and the type checker (mypy / pyright). Use the project's environment manager (poetry / venv / uv) — never install globally.
2. Find a sibling module and copy its patterns — package layout, import style, error handling, how data is modelled, and how tests are organised.
3. Type everything. Add type hints on every function signature and public attribute; prefer precise types (Sequence, Mapping, Protocol, TypedDict, Literal) over bare Any. Justify any Any in a comment. Run the project's type checker and fix the cause of errors rather than # type: ignore-ing them.
4. Model data with @dataclass (frozen where it should be immutable) or Pydantic when the repo already uses it for validation at boundaries — not loose dicts of stringly-typed keys.
5. Be pythonic. Comprehensions and generators over manual loops where readable; context managers (with) for resources; pathlib over string paths; f-strings for formatting; enumerate/zip over index juggling.
6. Handle errors explicitly. Catch the narrowest exception that fits — no bare except: and no blanket except Exception that swallows. Re-raise with context (raise X from err) or handle; never silently pass. Validate external input at the boundary.
7. Test with pytest. Use fixtures and parametrize for table-style cases; cover happy path, edge cases, and error conditions; assert behaviour, not incidental detail.
8. Verify + evidence. Run the project's tests + lint + type check, record test_output via the record-evidence skill, and submit for review.

Build / Test

• Tests: pytest (or poetry run pytest); coverage via pytest --cov.
• Lint/format: ruff check . and black --check . (or the repo's configured equivalents); fix, don't suppress.
• Types: mypy . / pyright per the repo config.
• The DoD is verified by the repo's configured test/coverage commands — run them and record the output; a green run with coverage is the evidence.

Review checklist (a Python reviewer must check)

• Type hints present and precise on all signatures; no unexplained Any; type checker passes (no stray # type: ignore).
• No bare except: and no swallowing except Exception: pass; exceptions are narrowed and re-raised with context or handled deliberately.
• PEP 8 / formatter clean — ruff + black report no diff.
• Data modelled with dataclasses/Pydantic, not ad-hoc dicts; frozen where immutable.
• Resources use context managers; no leaked file handles / connections.
• Mutable default arguments avoided (def f(x: list | None = None), not = []).
• Boundary input validated before use (request bodies, env, file content).
• Tests use pytest fixtures/parametrize and cover error paths, not only the happy path.

Rules

• Match the repo's Python version, env manager, linter/formatter, and type checker exactly.
• Type hints everywhere; unknown-equivalent precision over Any; validate external input.
• No bare excepts, no swallowed exceptions — narrow and handle or re-raise with context.
• Pythonic idioms (comprehensions, context managers, pathlib) where they improve clarity.

Capture lore

This skill is one of the places durable, reusable knowledge naturally surfaces: A Python convention this repo enforces beyond the obvious — a version constraint, a typing/validation pattern, an env-manager quirk, or a lint/type-checker rule. That kind of fact is lore. Capture it via the lore-capture protocol in your brief (CLAUDE.factory.md, step 11 "Memory contribution"): call the Memory MCP suggest_lore once at the close of your work — reusable conventions, gotchas, decisions, and boundaries only, never per-ticket trivia.