python

Python Rules

Syntax and Typing

• For single-consumer, non-library repositories, require Python 3.12 or newer and prefer the latest stable Python release when the repository's runtime and dependencies are compatible. For public libraries, prefer the widest feasible supported range with a minimum no earlier than Python 3.11.

• Use modern type hints: str | None instead of Optional[str].

• Use built-in generics: list[T], dict[K, V] instead of List[T], Dict[K, V].

• Use Self from typing for class method return types.

• Use collections.abc for abstract types: Callable, Iterable, etc.

• Never use Protocol for model typing; use concrete model classes in type annotations.

• Model structured payloads explicitly: use TypedDict for mapping-shaped data and Pydantic BaseModel for every data-holding class, rather than arbitrary inline dictionaries, dict[str, object], dataclass, or NamedTuple.

• Use exact types or precise unions for dynamic and nested shapes; never hide their contracts behind Any or placeholder object fields in application or test annotations.

• Prefer real SDK and model types over cast(...); reserve a narrowly scoped cast for information the type system genuinely cannot express.

• Do not "fix" typing by expanding simple transformations into repetitive key-by-key copy blocks (for example, manually assigning each dict key only to satisfy pyright). Fix the source type hints (or add a precise cast/narrowing at the boundary) so the transformation can stay concise and readable.

• For persistence/update payloads (for example, upsert(...)), define a dedicated TypedDict and construct it inline at the call site. Do not add free-floating build_*/make_* helper functions whose only role is constructing a payload from another shape; the same no-free-floating-builders rule that applies to BaseModel applies here.

• When a TypedDict types a module-level constant or other shared blob (for example a CVA style config), build the value by calling the TypedDict constructor with keyword arguments (MyTypedDict(field=value, ...)) instead of assigning an annotated plain dict literal (name: MyTypedDict = {...}). Use the same for nested TypedDict rows inside lists (for example CompoundVariantRule(match={...}, class_name="...")). This keeps the type as the construction site, not only a static annotation on a dict literal.