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 traditionalT = 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:
- Install community stubs: Many popular libraries provide typed companion packages on PyPI (e.g.,
types-requests,types-redis). - Generate stub files (
.pyi): Pyright allows generating stubs withpyright --createstub <package>. - 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
TypeVarto bind input types directly to output types. - Use
Generic[T]for parameterized container classes. - Use
ParamSpecto preserve complete function signatures across decorators. - Use
Protocolfor flexible, interface-based architecture decoupled from class hierarchies.