python · git:20261119.3f772fb · 2026-11-19 · sha256 c69161a1c9e49e59
python git:20261119.3f772fbA
Immutable. This exact content never changes and is served at /api/v1/blob/c69161a1c9e49e59.
---
applyTo: "**/*.py"
---
# Python Review Rules
## Construction
- `__new__` is the constructor, not `__init__`. Flag any `__init__` definition outside of `@dataclass` classes.
- Constructors must establish all invariants before returning. No partially-constructed objects.
- `@dataclass` must use `frozen=True, slots=True`.
## Encapsulation
- All instance attributes must start with `_` (protected) or `__` (private). Flag `self.name =` without underscore.
- Expose state via `@property`, not public attributes.
## Types
- `from __future__ import annotations` must be the first import in every file.
- Full type annotations on all function signatures and return types.
- Use `Protocol` for structural interfaces, `ABC` for shared implementation. Never `hasattr()`.
- Return `NotImplemented` from binary operators, never raise `NotImplementedError`.
- `cast()` must use string form: `cast("Type", val)`.
- Import abstract types from `collections.abc`, not `typing`.
## Error handling
- Validate at boundaries, trust internally. No defensive try/except in internal code.
- Never catch broad `Exception` except at CLI entry points or MCP tool handlers.
- `ValueError` for domain violations, `TypeError` for construction bypass.
## Style
- `ruff format` is the formatter (not `black`).
- Double quotes, 88-char line length.
- No backwards-compatibility shims, no `# removed` tombstones.
## Tools directory
- The OO, coupling, and suppression gates come from the pinned `punt-oo-ratchet` dev package, not an embedded implementation in `tools/`.