python

What this skill does

# 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