ai-agents python.instructions.md

Python Rules

These rules apply when you write or review Python. The dev and install target is 3.14 (.python-version, CI, requires-python = ">=3.14"). But plugin hooks and skill scripts run under the host's ambient interpreter, which may be older, so a blocking gate (scripts/validation/validate_python_syntax.py, issue #2655) requires every tracked file to parse at the hook-portability syntax floor, currently 3.10. Write to that floor: avoid syntax newer than 3.10, such as PEP 695 generics (def f[T](), 3.12+) and PEP 758 unparenthesized except A, B: (3.14). Defer to pyproject.toml, ruff config, and mypy settings over personal preference.

Typing

• Type every public function signature: parameters and return. Internal helpers with obvious types may omit annotations, but a boundary without types is a bug.
• Use built-in generics (list[str], dict[str, int], tuple[int, ...]) and X | None instead of Optional[X].
• Prefer precise types: Sequence/Mapping for read-only parameters, Protocol for structural interfaces, Literal for fixed string sets, TypedDict for structured dict payloads at a boundary.
• Run mypy in CI and treat type errors as failures. A passing type checker is part of the contract, not optional.

Idioms

• Use @dataclass(frozen=True, slots=True) for immutable value objects. Reach for Pydantic only when you need validation or serialization at a boundary; do not pay its cost for internal data.
• Prefer comprehensions and generator expressions over map/filter with lambdas. Use a generator when the result is consumed once and may be large; materialize a list only when you need to index or reuse it.
• Manage every resource with a context manager (with). Write your own with contextlib.contextmanager rather than paired open/close calls.
• Use pathlib.Path for filesystem paths, not string concatenation or os.path.
• Use structural pattern matching (match/case) for dispatch over shapes, not as a glorified if chain over equal values; a dict lookup is clearer there.