python-types-and-apis

name	python-types-and-apis
description	Use for Python typing decisions — generics, `TypeVar`, `ParamSpec`, `TypeIs` and `TypeGuard`, `NewType`, `Protocol`, `@overload`, typed kwargs, and the shape of public function signatures.
globs	["**/pyproject.toml","**/*.py","**/*.pyi"]

Python Types and APIs

Use this when the real question is how much of the design should be expressed in type hints, protocols, and public signatures.

Working stance

• Make invalid states hard to represent before adding runtime checks.
• Keep public APIs narrower than internal helper code: precise return types, permissive argument types.
• Prefer concrete types and named protocols over open object or Any.
• Reach for generics when a single concrete type flows through the call site; otherwise stay concrete.
• Treat # type: ignore as a code smell that needs a comment naming the invariant the checker cannot see.

Decision surface

• TypeVar: a function or class needs to preserve a relationship between inputs and outputs (def first[T](xs: list[T]) -> T). Prefer PEP 695 inline syntax in Python 3.12+ for new code.
• ParamSpec: a decorator must preserve the wrapped function's signature. Pair with typing.Concatenate when the wrapper injects a prefix argument.
• TypeIs (PEP 742): a predicate is an honest equivalence — is_str(x) returning True proves x: str in the true branch and not str in the false branch.
• TypeGuard: a one-way narrowing where the false branch carries no information (e.g. is_non_empty(xs)).
• NewType: a primitive must not be confused with another primitive of the same shape (UserId = NewType("UserId", int)).
• Protocol: structural typing is the right description ("anything with .read() and .close()") and an explicit base class would over-constrain callers.
• @overload: a function takes a closed set of argument shapes and the return type depends on the shape; the implementation def stays unannotated for the union and the overloads carry the precise types.
• TypedDict or Unpack[TypedDict]: kwargs are a fixed schema that needs type-checker enforcement at the call site.

Red flags

• public functions accept or return Any without a comment naming the invariant the checker cannot express,
• a decorator wraps Callable[..., Any] and erases the wrapped signature (use ParamSpec),
• a predicate annotated -> bool is consumed by callers as a narrower (TypeIs or TypeGuard is missing),
• isinstance chains where a Protocol would express the intent,
• a NewType exists but its constructor is bypassed elsewhere in the module,
• two bool parameters in one signature (boolean blindness; use an enum or an options TypedDict),
• a cast(...) call sits next to a runtime check that would let the checker narrow on its own,
• generic parameters appear in the public signature for purely internal flexibility.

Read paramspec-and-typevars.md, typeis-vs-typeguard.md, generics-and-newtypes.md, and overloads-and-typed-kwargs.md when one of those forks becomes the main design pressure.