code-review-python

Python Code Review Patterns

Stack-specific rules loaded by dh:code-reviewer when pyproject.toml or *.py files are detected.

Type Annotations

• All public function boundaries must have type annotations — parameters and return type
• Any is only acceptable with an inline comment explaining why a specific type cannot be used
• TypedDict is required for dicts that cross module boundaries; plain dict[str, ...] is only acceptable within a single function
• Optional[X] is legacy — use X | None (Python 3.10+ union syntax)
• Union[X, Y] is legacy — use X | Y
• Return type None must be explicit on functions that have no return value but have side effects
• Protocol classes are preferred over ABC for structural typing

Ruff Compliance

• Bare except: is a blocking finding — must be except ExceptionType:
• print() in library code (non-CLI, non-script) is a blocking finding (T201) — use logging instead
• Magic numbers in comparisons are a blocking finding (PLR2004) — extract to named constants
• Unused imports must be removed, not commented out
• f-strings are required for string interpolation — % and .format() are legacy
• __all__ must be defined in modules that have public API surface

ty Type Safety

• Unresolved imports indicate a missing uv add — fix the import, not the type checker
• # ty: ignore suppressions are prohibited — fix the code to satisfy ty
• ty extra-paths in pyproject.toml must stay in sync with pytest pythonpath
• TypedDict nominal incompatibility across modules means the TypedDict should be defined in a shared location, not duplicated

pytest Patterns

• Test names follow behavioral naming: test_<what>_when_<condition>_returns_<result> or test_<what>_when_<condition>_raises_<exception>
• Tests assert on observable behavior, not on implementation details (internal state, private methods)
• Integration tests hit real dependencies — mocking the thing under test is not a test
• Fixtures are preferred over test-class instance state
• assert result is not None is not a meaningful assertion — assert the actual expected value
• Tests are isolated — no shared mutable state between test functions
• Parametrize repetitive test cases with @pytest.mark.parametrize
• Each test file mirrors the module it tests: src/foo/bar.py → tests/foo/test_bar.py