Python

Modern Python at the language level

Write, review, modernize, type, and package Python that reads like a typed, flat-control-flow, stdlib-first program whose dependencies and tooling all live in one pyproject.toml. Types are part of the design, not decoration; the stdlib is large and you reach for it before a dependency; correctness is ruff + a type checker + pytest in one gate.

Targets Python 3.12+ (floor) / 3.14 (current, released 7 Oct 2025): PEP 695 inline type parameters (class Box[T]:, type Alias = ...), asyncio.TaskGroup, and — in 3.14 — deferred annotation evaluation by default (PEP 649/749, no more from __future__ import annotations), PEP 750 template strings (t"..."), and compression.zstd. Tooling pins: uv 0.11 (project + package manager), ruff 0.15 (lint + format), mypy 1.20 --strict (or Astral's ty, still preview — default to mypy), pytest 8.

Scope — what this skill delegates

• Building a FastAPI / ASGI service (routes, Pydantic models, SQLAlchemy, uvicorn) -> fastapi. That skill owns the service shape; this one owns the language it is written in.
• A pytest suite as the primary task — fixtures, parametrize matrices, mocking, coverage, property-based testing -> testing-py (this skill keeps only the baseline: a few tests so verify.sh has something to run, then hands off).
• Language-agnostic threat modeling / authz / OWASP review -> secure-coding (this skill keeps Python-specific safety: no eval/pickle of untrusted data, subprocess without shell=True, secrets over random).
• Containerfile / CI pipeline / deploy mechanics -> deployment (this skill ships only a uv-based CI note).
• Another language -> go, typescript, rust, etc. Django ORM/models/migrations -> django.

Python typing, async language semantics, and uv packaging live here, not in a separate skill — this skill is the canonical authority for the language substrate under any Python program.

Decision rules

Apply on every Python edit:

1. Type the boundary. Every public function, method, and module-level name gets an annotation; let inference handle locals. Untyped public API defeats --strict.
2. Flat control flow. Guard-clause and return/raise early; keep the happy path unindented — arrow code hides the logic.
3. Stdlib before a dependency. pathlib, itertools, functools, dataclasses, collections cover most needs; a new dep is a maintenance liability you must justify.
4. Prefer immutability. @dataclass(frozen=True, slots=True) for value objects; mutate only where you must — shared mutable state is the bug you debug at 2am.
5. Everything passes the gate. ruff check + ruff format --check + mypy --strict + pytest — green locally via scripts/verify.sh before you call it done.

Typing

Type the boundary; run mypy --strict so untyped code and implicit Any are errors, not silent gaps. Use PEP 695 inline syntax for all new generic code — no explicit TypeVar objects:

# Good (3.12+): inline type parameter and the `type` alias statement.
def first[T](xs: list[T]) -> T:
    return xs[0]

class Box[T]: ...
type UserId = int                 # `type` statement: a real alias, lazily evaluated
# Bad (legacy): `T = TypeVar("T")` then a Generic[T] — fine in old code, don't write it new.

Core choices: Protocol (structural, no inheritance) over an ABC when you only need "has these methods"; X | None (not Optional[X]); Literal/Enum for closed value sets; Final for constants; Self for fluent returns; @overload for signature families. Narrow with isinstance, assert, or an is None guard — mypy follows the flow. In 3.14 annotations are lazy by default (PEP 649/749), so forward references resolve without from __future__ import annotations.

Full PEP 695 bounds/constraints/variance, Protocol vs ABC, TypedDict Required/NotRequired, ParamSpec/TypeVarTuple, TypeGuard/TypeIs, cast, and common --strict errors with fixes -> references/typing.md.

Data modeling

Pick the carrier by what the data is, not by habit:

from dataclasses import dataclass

@dataclass(frozen=True, slots=True)
class Point:
    x: float
    y: float
    def translated(self, dx: float, dy: float) -> "Point":
        return Point(self.x + dx, self.y + dy)   # returns a new value, never mutates

Frozen-slots dataclass when you want methods + hashability + clear types; NamedTuple when the thing genuinely is a small tuple you also unpack positionally.

Stdlib idioms

Reach into the stdlib before adding a dependency.

• pathlib for all filesystem paths: Path("data") / name, p.read_text(), p.glob("*.json"), p.with_suffix(".bak") — typed and composable, never os.path.join.
• collections: defaultdict(list), Counter(words), deque(maxlen=100) for ring buffers.
• itertools: chain, groupby, islice, batched (3.12+) instead of hand-rolled loops.
• functools: @cache / @lru_cache for pure memoization, @cached_property, partial.
• contextlib: @contextmanager, ExitStack for dynamic resource sets, suppress(FileNotFoundError).
• logging, never print in a library: print writes to a caller's stdout you do not own; logging.getLogger(__name__) lets them configure it.

Prefer comprehensions over map/filter+lambda; prefer a generator ((... for ...)) when you only iterate once. Use match for structural dispatch over a chain of isinstance:

from functools import cache
from pathlib import Path

@cache
def config_dir() -> Path:                 # computed once, memoized
    return Path.home() / ".config" / "myapp"

def area(shape: object) -> float:
    match shape:                          # structural dispatch, captures by attribute/key
        case {"kind": "circle", "r": float(r)}:
            return 3.14159 * r * r
        case _:
            raise TypeError(f"unknown shape: {shape!r}")

f-strings for formatting; note 3.14's PEP 750 t"..." template strings yield a Template (not a str) for safe custom interpolation (e.g. escaping) — use them when an f-string would inject untrusted text. Full cookbook (itertools/functools/collections recipes, match patterns, dataclass field/default_factory/__post_init__, Enum/StrEnum/IntFlag) -> references/stdlib.md.

Errors & resources

Define a small exception hierarchy rooted in one base so callers can catch broadly or narrowly; chain causes with raise ... from; never write a bare except:.

class AppError(Exception): ...
class NotFoundError(AppError): ...

def load(path: Path) -> str:
    try:
        return path.read_text()
    except FileNotFoundError as e:
        raise NotFoundError(f"missing {path}") from e   # preserves the cause chain

Use except* to handle an ExceptionGroup (what a TaskGroup raises) by member type. Prefer EAFP (try the operation, handle the failure) over LBYL race-prone pre-checks. Always release resources with with (a context manager), not manual try/finally close.