python

# Python **Readability counts. Explicit is better than implicit. If your code needs a comment to explain its control flow, restructure it.** Python 3.14+ is the baseline. Use modern syntax unconditionally — no backward compatibility with older Python versions unless the project explicitly requires it. ## References - **[`${CLAUDE_SKILL_DIR}/references/typing.md`]** — Type annotation patterns, generics, overloads, TypeVar, variance: full annotation examples, generic class patterns, Protocol implementation, TypeVar usage - **[`${CLAUDE_SKILL_DIR}/references/packaging.md`]** — Project layout, pyproject.toml, uv, dependency management: pyproject.toml templates, uv workflows, src layout, dependency groups, build backends - **[`${CLAUDE_SKILL_DIR}/references/modules.md`]** — Module system, imports, namespace packages, `__init__.py`: import resolution order, circular import fixes, lazy imports, namespace packages - **[`${CLAUDE_SKILL_DIR}/references/concurrency.md`]** — asyncio, TaskGroup, cancellation, timeouts, threading interop: TaskGroup error handling, timeout scopes, cancellation semantics, to_thread, eager task factory ## Naming - **Variables, functions, methods** — snake_case: `user_name`, `fetch_data` - **Classes, type aliases** — PascalCase: `UserService`, `HttpClient` - **Constants** — UPPER_SNAKE_CASE: `MAX_RETRIES`, `API_BASE_URL` - **Modules, packages** — snake_case, short: `user_store`, `auth` - **Private attributes/methods** — `_` prefix: `_internal_cache`, `_validate()` - **Name-mangled attributes** — `__` prefix: `__secret` (rarely needed) - **Type variables** — PascalCase, short: `T`, `KT`, `VT`, `ResponseT` - **Protocols** — PascalCase, `-able`/`-ible` suffix: `Renderable`, `Serializable` - **Descriptive names.** `user_count` not `n`. Short names (`i`, `x`) only in tiny scopes (comprehensions, simple lambdas). - **No redundant context.** `car.make` not `car.car_make`. - **Boolean names:** `is_`/`has_`/`can_`/`should_` prefix: `is_valid`, `has_access`. - **Dunder methods are reserved for the data model.** Never invent custom dunder names. - **Avoid single-character names** outside loop indices, comprehension variables, and well-established conventions (`f` for file, `e` for exception, `k`/`v` for key/value). ## Type Annotations Python 3.14+ uses modern annotation syntax natively. No `from __future__ import annotations` needed — all annotations are evaluated lazily by default. ### Core Rules - **Annotate all public API boundaries** — function signatures, class attributes, module-level variables. Internal code often needs fewer annotations; types flow from context. - **Use built-in generics:** `list[str]`, `dict[str, int]`, `tuple[int, ...]`, `set[float]`. Never import `List`, `Dict`, `Tuple`, `Set` from `typing`. - **Union with `|`:** `str | None`, `int | float`. Never `Optional[X]` or `Union[X, Y]`. - **`type` statement for aliases:** `type Vector = list[float]`. Not `TypeAlias` annotation. - **`None` return:** annotate `-> None` on functions that return nothing. Omit return type only on `__init__`. - **Avoid `Any`** — it disables type checking. Use `object` when you mean "any type but still type-safe." Use `Any` only at true interop boundaries with untyped code. ### Generics - **`type` parameter syntax (3.12+):** `class Stack[T]:` and `def first[T](items: list[T]) -> T:` instead of `TypeVar` declarations. - **Constrained type parameters:** `def process[T: (str, bytes)](data: T) -> T:` for a finite set of allowed types. - **Bounded type parameters:** `def sort[T: Comparable](items: list[T]) -> list[T]:` for upper-bound constraints. - **Variance is inferred** from usage in 3.12+ generics. No manual `covariant`/`contravariant` flags needed. ### Protocols (Structural Typing) - **Prefer protocols over ABCs** when you don't control the implementing types or when structural compatibility is sufficient. - **`@runtime_checkable`** only when you need `isinstance()` checks — it adds overhead and only validates method presence, not signatures. - **Keep protocols small** — one to three methods. A protocol with many methods is a sign you need an ABC or a concrete base class. ```python from typing import Protocol, runtime_checkable @runtime_checkable class Renderable(Protocol): def render(self) -> str: ... ``` ### Callable Types - **`collections.abc.Callable`** for callable annotations: `Callable[[int, str], bool]`. - **`ParamSpec`** for decorators that preserve signatures: `def decorator[**P, R](fn: Callable[P, R]) -> Callable[P, R]:`. - **Use `Protocol`** for complex callable signatures with keyword arguments or overloads. ### TypeGuard and TypeIs - **`TypeIs`** (3.13+) for narrowing that refines the input type: `def is_str_list(val: list[object]) -> TypeIs[list[str]]:`. - **`TypeGuard`** for narrowing where the output type is unrelated to input: `def is_valid_config(data: object) -> TypeGuard[Config]:`. See `${CLAUDE_SKILL_DIR}/references/typing.md` for full annotation patterns, generics, overloads, and variance. ## Data Classes and Structured Data ### dataclasses - **Use `@dataclass` for data containers** — classes that primarily hold data with minimal behavior. - **`frozen=True`** for immutable data: `@dataclass(frozen=True)`. Default to frozen unless mutation is required. - **`slots=True`** for memory efficiency and attribute safety: `@dataclass(slots=True, frozen=True)`. - **`kw_only=True`** when constructors have more than 3 fields — prevents positional argument ordering bugs. - **`field(default_factory=list)`** for mutable defaults. Never use mutable default arguments. - **Post-init processing:** `__post_init__` for derived fields and validation. ```python @dataclass(frozen=True, slots=True, kw_only=True) class User: name: str email: str roles: list[str] = field(default_factory=list) ``` ### When NOT to Use dataclasses - **Simple value containers** with 1-2 fields: use `NamedTuple` or plain tuples. - **Config/settings with validation:** use Pydantic or attrs with validators. - **Persistence/ORM models:** use the ORM's model base class. ### NamedTuple - **Use `class` syntax** over functional form: `class Point(NamedTuple): x: float; y: float`. - NamedTuples are immutable and iterable — useful as dict keys and in destructuring. ## Enums - **Use `enum.Enum`** for categorical constants. Never use bare strings or ints as pseudo-enums. - **`enum.StrEnum`** when the enum must interoperate with string APIs (JSON, config keys). - **`enum.IntEnum`** only when integer interop is mandatory (legacy protocols). Prefer `Enum` otherwise. - **`@enum.unique`** to prevent duplicate values. - **Access by value:** `Color(1)`. Access by name: `Color["RED"]`. Iteration: `for c in Color:`. - **Never subclass enums with members.** Enums with members are final. ```python from enum import StrEnum, unique @unique class Status(StrEnum): ACTIVE = "active" INACTIVE = "inactive" SUSPENDED = "suspended" ``` ## Pattern Matching `match`/`case` (3.10+) is the preferred dispatch mechanism for structural patterns. - **Use match for structural dispatch** — matching on type, shape, or destructured values. Don't use match as a substitute for simple `if`/`elif` chains on a single value. - **Always include a wildcard `case _:` arm** unless the match is provably exhaustive. - **Guard clauses** with `if`: `case Point(x, y) if x > 0:`. - **Use `|` for alternatives:** `case "quit" | "exit" | "q":`. - **Capture with walrus:** `case {"error": str() as msg}:` captures while matching type. - **Class patterns** require `__match_args__` or keyword patterns: `case Point(x=0, y=y):`. ```python match command: case {"action": "move", "direction": str() as direction}: move(direction) case {"action": "attack", "target": str() as target}: attack(target) case _: raise ValueError(f"Unknown command: {command}") ``` ## Functions - **Early return.** Guard clauses first, happy path flat. Reduce nesting. - **One function, one job.** If the name contains "and", split it. - **Type-annotate all parameters and return types** on public functions. - **Default arguments:** immutable values only. Use `None` + conditional for mutable defaults: `def f(items: list[int] | None = None):` then `items = items or []` in body. Never `def f(items: list[int] = []):`. - **`*` to force keyword-only arguments** after positional params: `def connect(host: str, *, port: int = 443):`. - **`/` to force positional-only** for parameters that callers shouldn't name: `def sqrt(x: float, /) -> float:`. - **Prefer returning values** over mutating arguments. Functions should be referentially transparent when possible. - **`None` means absent, not error.** Return `T | None` for optional results. Raise exceptions for errors. ## Decorators - **Preserve signatures** with `functools.wraps`: ```python def retry[**P, R](fn: Callable[P, R]) -> Callable[P, R]: @functools.wraps(fn) def wrapper(*args: P.args, **kwargs: P.kwargs) -> R: ... return wrapper ``` - **Decorator order matters.** Decorators apply bottom-up. `@staticmethod` and `@classmethod` must be outermost (topmost in source). - **Parametric decorators** return a decorator: `@retry(attempts=3)` means `retry` returns the actual decorator function. - **Don't over-abstract with decorators.** If the decorator hides important control flow (error handling, transaction management), make it explicit instead. ## Context Managers - **`contextlib.contextmanager`** for simple resource management: ```python @contextmanager def managed_connection(url: str) -> Iterator[Connection]: conn = Connection(url) try: yield conn finally: conn.close() ``` - **Class-based context managers** when state management is complex — implement `__enter__` and `__exit__`. - **`contextlib.suppress(ExceptionType)`** instead of empty `except: pass`. - **`contextlib.closing(thing)`** for objects with `.close()` but no `__exit__`. - **`contextlib.asynccontextmanager`** for async resource management. - **Always use `with`** for files, locks, database connections, and any resource that needs deterministic cleanup. ## Generators and Iterators - **Generators for lazy sequences.** Use `yield` to produce values on demand instead of building full lists in memory. - **Generator expressions** over list comprehensions when the result is iterated only once: `sum(x * x for x in range(1000))`. - **`yield from`** to delegate to sub-generators — preserves `.send()`, `.throw()`, `.close()` protocol. - **`itertools`** for composition: `chain`, `islice`, `groupby`, `batched` (3.12+), `pairwise` (3.10+). - **Annotate generators:** `def gen() -> Iterator[int]:` for simple generators, `Generator[YieldType, SendType, ReturnType]` when using `.send()`. - **Never exhaust a generator twice.** Generators are single-pass. If you need multiple passes, materialize to a list or use `itertools.tee`. ## Comprehensions - **List/dict/set comprehensions** for simple transforms: `[x.name for x in users if x.active]`. - **One level of nesting maximum.** Two nested `for` clauses are the absolute limit. Beyond that, extract to a function. - **Don't use comprehensions for side effects.** `[print(x) for x in items]` is wrong — use a `for` loop. - **Walrus operator in comprehensions** for compute-once-filter-and-use: `[y for x in data if (y := transform(x)) is not None]`. - **Dict comprehensions** for key transformations: `{k.lower(): v for k, v in headers.items()}`. ## Exception Handling