py

name	py
description	Python development. NOT for shell scripting (use sh) or non-Python code.
when_to_use	editing .py files, writing Python; dataclasses, type hints, enums, asyncio/asyncpg, pytest, ruff, pyright, uv, FastAPI

Python

Requires the software skill's code.md for shared naming, style, and design rules. Below are Python-specific additions and deltas.

Verify before claiming

• ANY syntax or type question: run python3 -c "import ast; ast.parse(...)", uv run pyright, or ruff check — NEVER speculate or hedge.

Version

• ALWAYS target Python 3.13+, use newest language features
• type Alias = int | str (PEP 695), not TypeAlias
• type Point[T] = tuple[T, T] for generic type aliases

Type Annotations

• Builtin generics: dict[str, float], list[str], Type | None
• NEVER move imports into TYPE_CHECKING blocks — breaks runtime
• NEVER default_factory=lambda: [] — use default_factory=list; for typed collections pass the parametrized type: default_factory=dict[K, V]
• NEVER reflexively add | None — if a field is always set at construction give it a real default (x: float = 0.0), not x: float | None = None. | None is for genuine sentinels / optional deps / nullable returns only
• ALWAYS typing.Protocol for duck-typed interfaces; use abc.ABC only when runtime isinstance is required
• NEVER introduce Protocol or broad duck typing only for tests/fakes — ALWAYS type production code from production contracts
• NEVER Literal['a', 'b'] for domain values — ALWAYS use enum.Enum (or str, Enum for pydantic/TOML compat). Literal is only for narrowing external/library types you do not own.
• Compare enum members with is / is not, not == / != — enums are singletons; is makes the identity check explicit: if status is GameStatus.LOST: not if status == GameStatus.LOST:
• Forward a pass-through **kwargs as plain **kwargs: Any to a callee that owns the real typed signature — NEVER add TypedDict + Unpack just to type a passthrough; the machinery costs more than the duplication it removes

Naming

• ALWAYS name functions and methods as verbs: get_programs(), build_index(), compute_pnl()
• NEVER name a function as a noun: program_lookup, symbol_map, client_index — these read as data, not actions
• Exception: boolean predicates — is_funded(), has_positions(), can_advance()
• The verb MUST match the behavior — a finish_task() that cancels, or a get_*() that mutates, is a lie. Rename the moment name and behavior diverge.

Properties and accessor overrides

• NEVER use @property, @x.setter, or __getattr__/__setattr__ overrides — they are code smell
• They hide computation behind attribute access, break "no surprises" reads, and make grep useless
• Two legitimate exceptions:
  1. Mocking / test doubles — overriding attribute access on a stub
  2. Adapting external/library code — wrapping an API you don't own that requires property protocol
• Instead: plain method (def program_lookup(self)) or compute once and store on the dataclass field

getattr/setattr

• Legitimate ONLY when the attribute name is a code-derived value (variable, loop var, expression) unknown until runtime
• Legitimate: getattr(obj, field_name) where field_name comes from __dataclass_fields__, a loop, or an arg
• Legitimate: setattr(obj, attr, value) in a reflection loop (applying a dict of field overrides)
• Legitimate: getattr(obj, 'attr', default) when obj genuinely may lack attr (duck typing, optional mixin, app.state, enum .name fallback)
• Slop: getattr(world, 'cfg', None) when world.cfg is a declared typed field — write world.cfg
• Slop: setattr(obj, 'literal_field', value) when the field is declared — write obj.literal_field = value
• Test: if you can swap the call for .attr syntax and pyright stays quiet, it's slop

Async

• NEVER manually close async context managers (corrupts asyncpg) — ALWAYS async with
• NEVER yield individual items; ALWAYS return batches

Stack

• ALWAYS aiohttp for clients (HTTP + WS), FastAPI for servers
• ALWAYS asyncpg direct, NEVER SQLAlchemy
• ALWAYS dataclasses over Pydantic unless validation/coercion is needed

Named Data Structures

• ALWAYS dataclass/NamedTuple over bare tuples for return types (except trivial/test code)
• ALWAYS @dataclass(frozen=True) by default for value/data types — immutability prevents aliasing bugs, makes instances hashable, and catches accidental mutation at runtime. Drop frozen only for types that are deliberately mutated in place (accumulators, stateful objects like World/Client)
• PREFER frozen=True, slots=True together — slots adds faster attribute access + lower memory; the cost is only modest construction/hash overhead (reads are free)
• ALWAYS @dataclass(frozen=True) over a heterogeneous tuple used as a dict/map key — positional key[2] or key[:4] access is a smell; name the fields
• A wider frozen key projects to a narrower one via a named accessor (order_key), NEVER by slicing key[:4]
• NEVER kw_only=True / InitVar to dodge dataclass field-ordering — if every caller passes a value the default is dead, so make the field required
• NEVER use tuple as a generic collection just because the values are not mutated — ALWAYS use list for ordinary sequences; reserve tuple for dict/set keys, deliberate immutability boundaries, varargs/returns where positional shape is the point, or small fixed heterogeneous records when a dataclass would be overkill.

Datetime

• datetime.fromtimestamp(ts, tz=timezone.utc) not utcfromtimestamp

Logging

• ALWAYS log = logging.getLogger(__name__) — variable ALWAYS named log

Imports

• NEVER alias a module import unless the name genuinely collides: import json_utils not import json_utils as ju
• When aliasing a symbol import, use the source module as prefix: from heapq import merge as heapq_merge

Style

• Exception variables: NEVER e — use ex, exc, err
• Use async with asynccontextmanager for resource cleanup, never bare try/finally for pools/connections
• Python-specific short vars: ts, ms for time
• NEVER sys.path modification — ALWAYS set PYTHONPATH or install the package
• NEVER global keyword except trivial scripts or signal handlers — ALWAYS pass state explicitly
• NEVER multi-assign tuples: a, b, c = x, y, z — one per line
• Emptiness by truthiness: if not xs / if xs, NEVER len(xs) == 0 / len(xs) > 0 (works for any __len__/__bool__ type)
• NEVER rewrite an expression into an equivalent form for its own sake (Field(None) → Field(default=None), adding/removing a redundant # noqa) — keep diffs to real changes
• For small fixed sequences used only by a for loop, prefer comma iteration: for x in A, B: not for x in [A, B] or for x in (A, B)

Package Structure

• NEVER create __init__.py unless it contains actual code

Build

• uv for packages, pyright for types
• pre-commit: ruff format + lint, end-of-file-fixer, trailing-whitespace
• make check: ruff lint + format check (canonical CQ target)
• make right: pyright only (not in pre-commit)
• except T, V: (no parens) is VALID on Python 3.14 (PEP 758), a SyntaxError only on <3.14. ruff 0.15.17 ruff-format strips the parens from except (T, V): — fine on 3.14; if the code must also run on <3.14, guard with except (T, V): # fmt: skip

Testing

• ALWAYS python -m pytest not pytest directly (package discovery)
• Set PYTHONPATH once at Makefile top, not per target
• Testcontainers: centralize in conftest.py
• ALWAYS build properly shaped test doubles (Mock / MagicMock with explicit attrs or a small fake class); NEVER make production code tolerate incomplete fakes
• NEVER monkeypatch module globals (module.fn = stub) for a test seam — ALWAYS inject the dep as a param (get_cfg_fn: Callable[...] | None = None) defaulting to the module fn (get_cfg_fn or get_cfg)
• ALWAYS relax pyright for test paths when strict test typing is impractical (exclude tests from strict source check or use a separate relaxed test config); NEVER weaken production annotations for fake convenience

Subprocesses

• start_new_session=True on create_subprocess_exec (prevents Ctrl-C leak)
• Kill process groups: os.killpg(os.getpgid(proc.pid), signal.SIGKILL)