Writing

Advanced Python Typing: TypeVar, Generic, ParamSpec, and Protocol

In Part 1: Python Type Hints Foundations, we covered primitive types, collection generics, and basic static checking. However, real-world Python architectures require more expressive type definitions: preserving relationships across inputs and outputs, wrapping higher-order functions without losing parameter signatures, and structural interfaces.

1. Preserving Relationships with TypeVar

When a function accepts a generic sequence and returns an element from it, using Any loses type information. Using TypeVar establishes a strict type dependency between parameters and return values.

[!NOTE] Python 3.12+ Syntax Update (PEP 695) Python 3.12 introduced clean generic syntax directly on function definitions: def first[T](items: list[T]) -> T: .... For compatibility with Python 3.10 and 3.11, the traditional T = TypeVar("T") syntax remains widely used and fully supported.

from collections.abc import Sequence, Iterator
from typing import TypeVar

T = TypeVar("T")


def chunk[T](data: Sequence[T], size: int) -> Iterator[Sequence[T]]:
    for i in range(0, len(data), size):
        yield data[i : i + size]

Bounding TypeVars

You can constrain a TypeVar to specific types or their subclasses using the bound keyword:

from typing import TypeVar

# Only allows float, int, or classes derived from them
NumberT = TypeVar("NumberT", bound=float | int)


def double(val: NumberT) -> NumberT:
    return val * 2

2. Generic Classes (Generic[T])

To create classes that operate over parameterized types (such as containers, repositories, or wrappers), inherit from typing.Generic:

from typing import Generic, TypeVar

T = TypeVar("T")


class Box(Generic[T]):
    def __init__(self, value: T):
        self._value = value

    def get(self) -> T:
        return self._value

    def set(self, new_val: T) -> None:
        self._value = new_val


# Inferred as Box[str]
str_box = Box("Hello")
val = str_box.get()  # Inferred as str

3. Accurate Decorator Typing with ParamSpec

Before Python 3.10, writing a decorator that returned a wrapped function often destroyed the original function's signature in IDE autocompletion, forcing developers to use Callable[..., Any].

typing.ParamSpec captures arbitrary argument specifications (positional, keyword) and transfers them to the wrapper:

from collections.abc import Callable
from functools import wraps
import time
from typing import ParamSpec, TypeVar

P = ParamSpec("P")
R = TypeVar("R")


def timed(func: Callable[P, R]) -> Callable[P, R]:
    @wraps(func)
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        start = time.perf_counter()
        result = func(*args, **kwargs)
        elapsed = time.perf_counter() - start
        print(f"{func.__name__} took {elapsed:.4f}s")
        return result

    return wrapper


@timed
def fetch_user_data(user_id: int, include_metadata: bool = False) -> dict:
    ...

# VS Code and Pyright retain exact parameters and docstrings for fetch_user_data!

4. Structural Subtyping with Protocol

By default, Python nominal typing requires inheritance: an object is only considered a subtype if it explicitly inherits from a base class.

typing.Protocol enables structural subtyping (often referred to as static duck typing). If an object matches the attributes and methods defined on a Protocol, static checkers accept it without requiring explicit inheritance.

from typing import Protocol


class Renderable(Protocol):
    def render(self) -> str: ...


class MarkdownDoc:
    def render(self) -> str:
        return "# Title\n\nContent..."


class HtmlDoc:
    def render(self) -> str:
        return "<h1>Title</h1><p>Content...</p>"


def publish(doc: Renderable) -> None:
    print(doc.render())


# Both pass type checking cleanly without inheriting from a common base!
publish(MarkdownDoc())
publish(HtmlDoc())

Practical Strategies for Untyped Libraries

When working with third-party libraries that lack complete type annotations:

  1. Install community stubs: Many popular libraries provide typed companion packages on PyPI (e.g., types-requests, types-redis).
  2. Generate stub files (.pyi): Pyright allows generating stubs with pyright --createstub <package>.
  3. Use targeted # type: ignore[rule-code]: When an untyped library causes false positives, suppress only that specific diagnostic rather than disabling checking globally.

Summary

  • Use TypeVar to bind input types directly to output types.
  • Use Generic[T] for parameterized container classes.
  • Use ParamSpec to preserve complete function signatures across decorators.
  • Use Protocol for flexible, interface-based architecture decoupled from class hierarchies.