TypeVar and Generic in Python: When and How to Use Them

Python's type annotation system has several tools that confuse developers more than almost any others: TypeVar, Generic, and ParamSpec. The confusion is understandable — they solve a specific problem that only surfaces once your code grows beyond simple concrete type annotations. This article explains exactly what that problem is, when these tools are the right solution, how variance affects the way type checkers evaluate your generics, and how PEP 695 in Python 3.12 and PEP 696 in Python 3.13 changed the game with new syntax and type parameter defaults that make the older approach feel like a workaround in comparison.

When you write def first(items: list) -> ???, you immediately run into a wall. You know the function returns whatever type of thing is in the list, but there is no way to express that relationship with a plain type annotation. You could write Any, but that defeats the purpose — you lose all the safety that type checking provides. You could write an overloaded version for every type you care about, but that is unmaintainable. TypeVar and Generic are how Python's type system solves this: they let you say "whatever type goes in, that same type comes back out," and they let type checkers like mypy and pyright enforce that contract.

The Problem They Solve

A TypeVar is a placeholder for a type that will be filled in later. It is not a type itself — it is a variable that ranges over types. The official Python documentation defines it succinctly: a TypeVar() expression creates a new type variable, and the argument to TypeVar() must be a string equal to the variable name to which it is assigned. That last rule — the redundant name string — is one of the clearest signals that the old syntax was designed as an interim solution.

Here is the canonical pre-3.12 pattern. To write a generic function that returns the first element of a sequence while preserving its type, you write:

copyfrom collections.abc import Sequence
from typing import TypeVar

T = TypeVar('T')

def first(items: Sequence[T]) -> T:
    return items[0]

When a type checker sees first([1, 2, 3]), it knows the input is Sequence[int], which means T is bound to int for that call, so the return type is inferred as int. When it sees first(['a', 'b']), T is bound to str. The same function, different type signatures per call site — that is what generics do.

The Generic base class comes into play when you need a whole class to be parameterized by a type, not just a single function. Suppose you are building a typed stack data structure. Without Generic, there is no way to say "this stack holds integers" and have the type checker enforce that pop() returns int:

copyfrom typing import TypeVar, Generic

T = TypeVar('T')

class Stack(Generic[T]):
    def __init__(self) -> None:
        self._items: list[T] = []

    def push(self, item: T) -> None:
        self._items.append(item)

    def pop(self) -> T:
        return self._items.pop()

    def peek(self) -> T:
        return self._items[-1]

With this definition, Stack[int]() creates a stack that only accepts integers. Calling .push("hello") on it produces a type error. The Generic[T] base class is the mechanism that registers T as the type parameter for the class and enables the Stack[int] subscription syntax at runtime.

You use TypeVar alone when the generic behavior belongs to a function. You add Generic[T] as a base class when the generic behavior belongs to a class — when the type parameter needs to be remembered across multiple methods. A class that inherits from Generic[T] is how you tell Python's type system that instances of that class carry a type parameter with them. The article on Python type annotations and IDE support covers many patterns where the distinction matters.

One subtlety worth understanding early: a TypeVar is invariant by default. This means that if you declare a variable as Stack[Animal], you cannot pass a Stack[Dog] where it is expected — even if Dog is a subclass of Animal. This is not a bug; it is a deliberate safety rule. The next section explains why, and when you need to change it.

Bounded Types, Constraints, and Variance

An unconstrained TypeVar accepts any type. That is useful for generic containers, but many real-world functions are not that permissive. They can work with multiple types, but not every type. Python's type system gives you two distinct tools for narrowing this range: bounds and constraints. They look similar but behave very differently, and choosing the wrong one is a common source of subtle bugs.

A bound restricts T to a type or any subtype of it. You use the bound= keyword argument:

copyfrom typing import TypeVar

class Animal:
    def speak(self) -> str: ...

class Dog(Animal):
    def fetch(self) -> None: ...

AnimalT = TypeVar('AnimalT', bound=Animal)

def make_speak(creature: AnimalT) -> AnimalT:
    creature.speak()
    return creature

# Type checker knows the return type is Dog, not just Animal
my_dog: Dog = make_speak(Dog())

The critical behavior of a bounded TypeVar is that the type checker infers the most specific type possible. When you pass a Dog, the return type is inferred as Dog, not Animal. This is what makes bounded TypeVars indispensable for factory patterns and fluent builder APIs — the caller gets back exactly what they put in, with no information lost.

Constraints, by contrast, restrict T to exactly one of a fixed set of types. The type checker will not infer anything more specific than the matching constraint. The official Python typing documentation draws a clear line between the two: a bounded TypeVar resolves to the most specific type the checker can determine, while a constrained one resolves only to whichever listed type matches — never to a subtype of it.

copyfrom typing import TypeVar

# T must be exactly str or bytes — nothing else
StrOrBytes = TypeVar('StrOrBytes', str, bytes)

def process(data: StrOrBytes) -> StrOrBytes:
    return data

result = process("hello")   # type inferred as str
result2 = process(b"world") # type inferred as bytes
# process(42)               # type error: int is not str or bytes

Understanding Variance

Variance describes how subtype relationships between concrete types carry over into generic types. It is one of the concepts that PEP 483 (opens in new window) — the theoretical foundation for Python's type hints — treats with particular rigor. There are three modes: invariant, covariant, and contravariant.

Invariant (the default) means Generic[Dog] is neither a subtype nor a supertype of Generic[Animal], even though Dog is a subtype of Animal. Mutable containers like list are invariant because allowing substitution would be unsound: if list[Dog] were a subtype of list[Animal], you could pass a list[Dog] to a function expecting list[Animal], that function could append a Cat to it, and you would have broken the caller's guarantee that the list contains only dogs. Mypy even surfaces this in its error messages, noting that List is invariant and suggesting Sequence as an alternative when you only need to read from it.

Covariant means Generic[Dog] is a subtype of Generic[Animal] when Dog is a subtype of Animal. This is safe for read-only producers. PEP 483 defines covariance as the condition where GenType[t2] is a subtype of GenType[t1] whenever t2 is a subtype of t1 — the subtype relationship flows in the same direction as the parameter relationship. Sequence[T], FrozenSet[T], and Iterator[T] in the standard library are all covariant — you can only read from them, so it is safe to substitute a more specific type. You declare this with covariant=True:

copyfrom typing import TypeVar, Generic

T_co = TypeVar('T_co', covariant=True)

class ReadOnlyBox(Generic[T_co]):
    def __init__(self, value: T_co) -> None:
        self._value = value

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

# Because T_co is covariant, ReadOnlyBox[Dog] is a subtype of ReadOnlyBox[Animal]
def describe(box: ReadOnlyBox[Animal]) -> None:
    print(box.get().speak())

describe(ReadOnlyBox(Dog()))  # accepted by the type checker

Contravariant reverses the relationship: Generic[Animal] becomes a subtype of Generic[Dog]. This applies to consumers — things that accept a type rather than produce it. The canonical example is Callable[[T], None]: a function that accepts Animal can safely be used anywhere a function accepting Dog is expected, because it can handle at least as much. You declare this with contravariant=True. The Python typing specification is precise on this point: variance is a property of a generic class, not of the type variable in isolation. The same TypeVar could behave covariantly in one class and contravariantly in another, depending on how each class uses it.

The practical rule is: use invariant (the default) for mutable containers, covariant for read-only producers, and contravariant for write-only consumers or callbacks. When you get a mypy or pyright error about variance, it is almost always telling you that you are attempting a substitution that would be unsound under those rules.

One important restriction: covariant and contravariant TypeVars are only valid for use with classes, not standalone generic functions. The typing specification is explicit on this point: variance is a property of generic types, not of generic functions in isolation. If you try to use a covariant TypeVar in a plain function signature without a wrapping class, mypy will flag it as an error.

Python 3.12 and PEP 695: The New Syntax

Python 3.12, released in October 2023, introduced PEP 695 — a redesign of how generic types and type aliases are declared. The change is substantial enough that the Python documentation characterizes the old approach as a longstanding source of developer confusion. An analysis cited in PEP 695 found that TypeVar was used in 14% of modules across 25 popular typed Python libraries, which gives a sense of how widespread the problem was.

The old approach had three concrete pain points. First, the redundant name string: T = TypeVar('T') requires you to repeat the variable name in quotes, and if you get them out of sync, behavior becomes undefined. Second, global scope pollution: type variables declared at module level appear in globals(), even though their meaning is only valid inside the generic context where they are used. Third, the need to import both TypeVar and Generic from typing, adding boilerplate that feels disproportionate to the task.

PEP 695 solves all three at once. The new syntax places type parameters directly in square brackets on the class or function definition:

copy# Python 3.12+ — no imports required for simple cases
from collections.abc import Sequence

class Stack[T]:
    def __init__(self) -> None:
        self._items: list[T] = []

    def push(self, item: T) -> None:
        self._items.append(item)

    def pop(self) -> T:
        return self._items.pop()

def first[T](items: Sequence[T]) -> T:
    return items[0]

# Type alias — also new in 3.12
type Vector[T] = list[T]

The Python 3.12 release notes describe this as "a new, more compact and explicit way" (opens in new window) to define generic types. T, *Ts, and **P in the bracket syntax replace TypeVar, TypeVarTuple, and ParamSpec respectively, without any imports. Any class that has generic annotations in this form is automatically treated as a generic type — there is no need to inherit from Generic[T]. PEP 695 also addresses a core conceptual problem: under the old approach, the generic boilerplate obscured what a class did at its core, making type parameters harder to spot during code review.

Bounds, Constraints, and Variance in the New Syntax

Bounds and constraints translate directly into the bracket syntax using a colon:

copyfrom collections.abc import Hashable

# Bound: T must be Hashable or a subtype
def deduplicate[T: Hashable](items: list[T]) -> list[T]:
    return list(dict.fromkeys(items))

# Constraints: T must be exactly str or bytes
def encode[T: (str, bytes)](data: T) -> T:
    return data

# TypeVarTuple — variadic generics
def args_as_tuple[*Ts](*args: *Ts) -> tuple[*Ts]: ...

Variance works differently in PEP 695: rather than requiring you to declare it, type checkers infer it automatically. This is one of the most significant ergonomic improvements. Previously, developers had to reason about variance upfront and encode it into naming conventions (the community convention was T_co for covariant, T_contra for contravariant). Under PEP 695, the type checker observes how the type parameter is used — whether it appears in argument position, return position, or both — and determines variance from that. PEP 695 documents this inference as automatic: usage within a class body is the sole input the checker needs.

When to Keep the Old Syntax

The new syntax requires Python 3.12 or later. If your project needs to support Python 3.10 or 3.11, you must continue using the TypeVar and Generic imports. The two syntaxes are semantically equivalent for most purposes — class Stack[T]: and class Stack(Generic[T]): produce functionally identical behavior from the perspective of type checkers like mypy and pyright. The difference is syntactic clarity and reduced boilerplate, not functionality.

There is also one specific case where the old-style TypeVar with explicit covariant=True or contravariant=True remains the required approach even in 3.12+: when you need to override the inferred variance. If your class design requires a type parameter to behave contravariantly in a way the type checker would not infer automatically, you still create a TypeVar explicitly with contravariant=True and use it in your Generic base class. This is uncommon in practice, but it is the escape hatch.

Python 3.13 extended PEP 695 further via PEP 696, adding default values for type parameters — a feature long-requested by library authors writing complex generic APIs. The syntax places the default after an = sign in the bracket list: class Box[T = int]: means that Box() without a type argument is treated as Box[int]. As of Python 3.14 (released October 2025), the new type parameter syntax and its tooling support across mypy and pyright are considered stable and widely adopted.

tap to expand

ParamSpec: Generics for Callables

There is a third type-variable-like tool that belongs in this article: ParamSpec. Where TypeVar captures a single type, ParamSpec captures the full parameter specification of a callable — the names, types, and order of its arguments. It was introduced in PEP 612 (opens in new window) and is essential for writing typed decorators that preserve the signature of the function they wrap.

The problem ParamSpec solves is concrete. Suppose you write a logging decorator. Without ParamSpec, the only way to annotate it is with Callable[..., T] — the ellipsis means "I don't know the parameters." The type checker cannot verify that callers pass the right arguments to the wrapped function. With ParamSpec, you can thread the original parameter specification through the decorator so the type checker knows exactly what the wrapper accepts:

copyfrom typing import TypeVar, Callable, ParamSpec
import functools

P = ParamSpec('P')
R = TypeVar('R')

def log_call(func: Callable[P, R]) -> Callable[P, R]:
    @functools.wraps(func)
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        print(f"Calling {func.__name__}")
        return func(*args, **kwargs)
    return wrapper

@log_call
def add(x: int, y: int) -> int:
    return x + y

add(1, 2)       # type checker knows: two ints required
add("a", "b")   # type error: str is not int

The two attributes P.args and P.kwargs let you unpack the captured parameter specification inside the wrapper's signature. This is a specific requirement enforced by the type specification — P.args and P.kwargs must be used together, not independently.

In Python 3.12's bracket syntax, ParamSpec is written with a ** prefix:

copyfrom collections.abc import Callable
import functools

def log_call[**P, R](func: Callable[P, R]) -> Callable[P, R]:
    @functools.wraps(func)
    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
        print(f"Calling {func.__name__}")
        return func(*args, **kwargs)
    return wrapper

There is also TypeVarTuple (introduced in PEP 646 (opens in new window)), which captures a variable number of type arguments — used for functions that operate on tuples of arbitrary length and shape. In the bracket syntax it is written with a * prefix: def args_as_tuple[*Ts](*args: *Ts) -> tuple[*Ts]: .... TypeVarTuple is an advanced feature primarily useful in numerical computing frameworks and low-level library code.

Protocol: Structural Generics

Every example so far has used nominal subtyping: Dog is accepted as an Animal because it explicitly inherits from Animal. Python's type system also supports structural subtyping through Protocol, introduced in PEP 544 (opens in new window). The distinction matters here because Protocol and Generic are frequently confused, and in many situations Protocol is the right answer where developers reflexively reach for a bounded TypeVar.

A Protocol describes a structural interface — a set of methods and attributes a type must have — without requiring the type to explicitly declare that it implements the protocol. If a class has a speak() method that returns str, it satisfies a Speakable protocol, regardless of its inheritance chain. This is duck typing made statically checkable:

copyfrom typing import Protocol

class Speakable(Protocol):
    def speak(self) -> str: ...

# Works with any class that has a speak() method
# — no inheritance from Speakable required
def make_noise(creature: Speakable) -> str:
    return creature.speak()

class Dog:
    def speak(self) -> str:
        return "woof"

class Robot:
    def speak(self) -> str:
        return "beep"

make_noise(Dog())    # accepted
make_noise(Robot())  # also accepted

The key question — "should I use a bounded TypeVar or a Protocol?" — comes down to whether you need to preserve the specific type through the operation. If the function receives a Dog and must return that same Dog (not just a Speakable), use a bounded TypeVar. If the function just needs to call methods on whatever it receives and returns something else entirely, a Protocol is simpler and more flexible.

Protocols and generics can also be combined. A Protocol can inherit from Generic[T] to describe a generic structural interface — for example, an Iterator[T] protocol that describes any object with a __next__(self) -> T method. The standard library uses this pattern extensively: Iterable, Iterator, Sequence, and Mapping in collections.abc are all defined as generic protocols.

What Actually Happens at Runtime

A question that trips up nearly every developer encountering generics for the first time: does this actually enforce anything when the code runs? The short answer is no. Python's type annotations, including everything built with TypeVar, Generic, and Protocol, are not enforced by the Python interpreter at runtime. They are metadata — hints for type checkers, IDEs, and documentation tools, not runtime guards.

At runtime, T = TypeVar('T') creates an object of type TypeVar, and class Stack(Generic[T]): sets up Stack so it supports subscript syntax — that is why Stack[int] does not raise an error. But Stack[int] and Stack[str] are the same class at runtime. There is no separate specialized class generated per type argument, unlike Java or C# generics. Python uses type erasure: the type parameter is recorded in __class_getitem__ for introspection purposes, but the actual instance stores no type information about its parameter.

copyfrom typing import TypeVar, Generic

T = TypeVar('T')

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

int_box = Box[int](42)
str_box = Box[str]("hello")

# These are the same class at runtime
print(type(int_box))              # 
print(type(str_box))              # 
print(type(int_box) is type(str_box))  # True

# No runtime enforcement — this runs without error
int_box.value = "not an int"      # type error statically; fine at runtime

This design is intentional. CPython prioritizes performance and simplicity, and full reification of generic types at runtime would introduce significant overhead. The tradeoff is that your type safety net is entirely static — it exists at the point where you run a type checker like mypy or pyright, not when your program executes. This is why integrating a type checker into your CI pipeline matters: the runtime will not catch violations that the static checker would have flagged.

When Not to Use Generics

The existence of TypeVar and Generic does not mean every function or class that accepts multiple types needs them. Overusing generics is one of the clearest signs of premature type-system engineering, and it produces code that is harder to read without making it meaningfully safer.

The most common misapplication is reaching for TypeVar when Union or a direct concrete type annotation is what the code means. Consider a function that accepts either a string or a list of strings and always returns a list. Using TypeVar here is wrong — the function does not return "whatever type went in," it always returns a list, so the relationship between input and output types is not preserved:

copyfrom typing import TypeVar

# Wrong: TypeVar implies input type is preserved in the output
T = TypeVar('T', str, list)
def normalize(value: T) -> T: ...   # misleads callers

# Correct: the output is always list[str], regardless of input type
def normalize(value: str | list[str]) -> list[str]:
    if isinstance(value, str):
        return [value]
    return value

Similarly, TypeVar adds no value when a function already works correctly with Any, object, or a concrete base class. If the function only calls methods defined on object — like __str__ or __repr__ — typing the parameter as object is accurate and clear. Wrapping it in a TypeVar adds complexity without adding information.

The right signal for reaching for TypeVar is a specific structural question: does the caller need to know that the output type is the same as — or directly derived from — the input type? If the answer is no, a plain annotation is almost always the better choice. Generic code is harder to read, harder to debug, and produces more opaque error messages from type checkers. The ergonomic cost is only worth paying when the type relationship is real and the caller needs to rely on it.

Deeper Solutions Worth Knowing

The patterns covered so far — TypeVar, Generic, Protocol, and ParamSpec — are what you will find in most introductions to Python generics. But the standard library and the typing specification include several additional tools that solve real problems more precisely than the general-purpose options, and they are frequently underused.

Self: The Right Tool for Method Chaining and Fluent APIs

A common pattern in object-oriented Python is the builder or fluent API, where methods return self to allow chaining. The naive approach is to annotate the return type as the class itself, but this breaks down under inheritance: if Dog inherits from Animal and overrides a method that returns Animal, callers who hold a Dog lose its specific type after calling the method.

Before Python 3.11, the workaround was a bounded TypeVar:

copyfrom typing import TypeVar

T = TypeVar('T', bound='Animal')

class Animal:
    def set_name(self: T, name: str) -> T:
        self._name = name
        return self

class Dog(Animal):
    def fetch(self) -> None: ...

# Type checker knows this is Dog, not Animal
my_dog: Dog = Dog().set_name("Rex")

Python 3.11 added Self (PEP 673), which makes this idiom far cleaner. Self always refers to the type of the current instance, whatever class that is. You no longer need a TypeVar at all:

copyfrom typing import Self

class Animal:
    def set_name(self, name: str) -> Self:
        self._name = name
        return self

class Dog(Animal):
    def fetch(self) -> None: ...

# Still returns Dog when called on a Dog instance
my_dog: Dog = Dog().set_name("Rex")
my_dog.fetch()  # no type error — Self preserved the Dog type

Self also works in @classmethod definitions, which is where the bounded-TypeVar workaround was particularly awkward. Any class that returns its own type from a constructor-like class method should use Self as the return annotation.

TypeGuard and TypeIs: Narrowing Inside Generics

Python's type narrowing — the process by which a type checker understands that after an isinstance() check, a variable has a more specific type — works automatically for built-in checks. But it does not work automatically for custom validation functions. TypeGuard (PEP 647, Python 3.10) and TypeIs (PEP 742, Python 3.13) let you annotate a function as a type guard, so the type checker applies narrowing when that function returns True.

copyfrom typing import TypeGuard

def is_list_of_str(val: list[object]) -> TypeGuard[list[str]]:
    return all(isinstance(x, str) for x in val)

def process(items: list[object]) -> None:
    if is_list_of_str(items):
        # Type checker now knows: items is list[str] here
        upper = [s.upper() for s in items]  # no error

TypeIs is a stricter variant introduced in Python 3.13: unlike TypeGuard, it is bidirectional — the type checker narrows the type in both branches, not just the True branch. When you know the check is logically exhaustive (either the value is a str or it is not), TypeIs gives the type checker more information to work with. Both are particularly useful when working with heterogeneous generic containers that need to be split by type before processing.

@overload: A Precision Alternative to TypeVar

When a function has a small, known set of input-output type relationships — not an open-ended family of types — @overload is often more precise than a TypeVar. Overloads let you declare separate signatures for each combination, so the type checker can pick the exact one that matches a given call site rather than inferring from a generic variable.

copyfrom typing import overload

@overload
def parse(value: str) -> int: ...
@overload
def parse(value: bytes) -> float: ...

def parse(value: str | bytes) -> int | float:
    if isinstance(value, str):
        return int(value)
    return float(value)

result: int = parse("42")      # type checker infers int
result2: float = parse(b"3.14") # type checker infers float

The advantage over a constrained TypeVar here is that @overload can express asymmetric relationships: the input type being str does not mean the output type is str. A constrained TypeVar always returns the same type it received. Use @overload when the input-to-output mapping is discrete and known upfront.

NewType: Nominal Distinctiveness Without Full Generics

NewType creates a distinct named type that is a subtype of an existing type, without the overhead of defining a full class or a generic. At runtime it is a no-op — the value is still just the original type. But the type checker treats the new type as distinct, catching accidental interchangeability between logically different values that happen to share the same underlying type:

copyfrom typing import NewType

UserId = NewType('UserId', int)
OrderId = NewType('OrderId', int)

def get_order(user_id: UserId, order_id: OrderId) -> None: ...

uid = UserId(42)
oid = OrderId(99)

get_order(uid, oid)   # correct
get_order(oid, uid)   # type error: OrderId is not UserId

NewType fills a gap that generics do not: it gives you type safety for values that are semantically distinct but structurally identical. Without it, a function expecting a UserId will silently accept any int. It is particularly useful in domain-driven designs where the same primitive type (string, integer, UUID) appears in many different semantic roles.

Never and NoReturn: Exhaustiveness in Generic Dispatch

Never (added to typing in Python 3.11) and its function-level counterpart NoReturn represent the bottom type — a value of type Never can never exist. This sounds abstract, but it has a concrete use in generic code: exhaustive pattern matching. When you write a function that dispatches on a union type and want the type checker to guarantee you have handled every case, a Never-typed fallback is the standard pattern:

copyfrom typing import Never

# Python 3.12+ type alias syntax
class Circle:
    radius: float

class Rectangle:
    width: float
    height: float

class Triangle:
    base: float
    height: float

type Shape = Circle | Rectangle | Triangle

def assert_never(x: Never) -> Never:
    raise AssertionError(f"Unhandled case: {x!r}")

def area(shape: Shape) -> float:
    match shape:
        case Circle():    return 3.14159 * shape.radius ** 2
        case Rectangle(): return shape.width * shape.height
        # If Triangle is added to Shape but not handled here,
        # the type checker flags assert_never(shape) as an error
        case _:           assert_never(shape)

This is a more rigorous approach than leaving the fallback as a generic raise ValueError. The type checker uses Never to verify at analysis time that the union is fully covered — you find out about a missing case when you run mypy, not when the code executes in production.

Multiple TypeVars in One Generic Class

A generic class is not limited to a single type parameter. When a class needs to track two or more independent types — a key and a value, for example — you declare multiple TypeVars and pass them all to Generic. The ordering in the Generic[K, V] base determines the order of the type arguments when the class is subscripted:

copyfrom typing import TypeVar, Generic

K = TypeVar('K')
V = TypeVar('V')

class Pair(Generic[K, V]):
    def __init__(self, key: K, value: V) -> None:
        self.key = key
        self.value = value

    def swap(self) -> "Pair[V, K]":
        return Pair(self.value, self.key)

# Python 3.12+ equivalent — no imports needed
class Pair[K, V]:
    def __init__(self, key: K, value: V) -> None:
        self.key = key
        self.value = value

    def swap(self) -> "Pair[V, K]":
        return Pair(self.value, self.key)

p: Pair[str, int] = Pair("age", 30)
swapped: Pair[int, str] = p.swap()

Each TypeVar must be distinct — passing the same one twice (Generic[T, T]) is invalid and will produce both a runtime error and a type checker error. In the bracket syntax, the same rule applies: class Pair[T, T]: is a SyntaxError.

Generics and Dataclasses

Python's @dataclass decorator works with generic classes. You combine Generic[T] (or the bracket syntax) with @dataclass to get auto-generated __init__, __repr__, and comparison methods that are all type-aware. This is one of the cleanest patterns for typed data containers:

copyfrom dataclasses import dataclass
from typing import TypeVar, Generic, Optional

T = TypeVar('T')

@dataclass
class Result(Generic[T]):
    value: Optional[T] = None
    error: Optional[str] = None

    @property
    def ok(self) -> bool:
        return self.error is None

# Python 3.12+ equivalent
@dataclass
class Result[T]:
    value: T | None = None
    error: str | None = None

    @property
    def ok(self) -> bool:
        return self.error is None

success: Result[int] = Result(value=42)
failure: Result[int] = Result(error="not found")

This pattern is particularly valuable in API response handling, where the payload type varies but the envelope structure is fixed. The type checker tracks the T through both the constructor and any property or method that references it.

TypeAlias vs. the type Statement

Before Python 3.12, generic type aliases required TypeAlias from typing to tell the type checker that an assignment was a type alias rather than a regular variable. Without it, type checkers sometimes misinterpreted the assignment:

copyfrom typing import TypeVar, TypeAlias

T = TypeVar('T')

# Pre-3.12: explicit TypeAlias annotation
Vector: TypeAlias = list[T]
Matrix: TypeAlias = list[list[T]]

# Python 3.12+: the type statement (PEP 695)
type Vector[T] = list[T]
type Matrix[T] = list[list[T]]

The type statement introduced by PEP 695 is the modern replacement. It eliminates the need for the TypeAlias import, supports the bracket syntax for generic parameters, and uses lazy evaluation — the right-hand side is not evaluated until the alias is used, which avoids circular reference issues. TypeAlias has been deprecated since Python 3.12 in favor of the type statement.

Debugging Generics with reveal_type()

When a generic expression produces an unexpected type checker error, reveal_type() is the diagnostic tool. It is not a runtime function — it is a directive that type checkers recognize. When mypy or pyright encounters reveal_type(expr), it prints the inferred type of the expression at analysis time. This is indispensable for understanding how a type checker resolves generic type parameters:

copyfrom typing import TypeVar
from collections.abc import Sequence

T = TypeVar('T')

def first(items: Sequence[T]) -> T:
    return items[0]

result = first([1, 2, 3])
reveal_type(result)  # mypy output: "Revealed type is 'builtins.int'"

result2 = first(["a", "b"])
reveal_type(result2)  # mypy output: "Revealed type is 'builtins.str'"

Use reveal_type() liberally when debugging complex generic signatures. It shows exactly what the type checker infers at each step, which makes it straightforward to identify where a type parameter is being resolved differently than you expected. Python 3.11 added reveal_type() as a built-in that also works at runtime (printing to stderr), but its primary value remains as a static analysis tool.

How mypy and pyright Differ on Generics

While mypy and pyright both implement the Python typing specification, they are independently developed and occasionally diverge on edge cases in generic type checking. The differences that surface in practice tend to involve variance inference, type narrowing within generic contexts, and how aggressively each tool infers type parameters from usage. Pyright, developed by Microsoft and used in Pylance (the VS Code Python extension), tends to implement new PEPs faster and is generally stricter about variance violations. Mypy, the original Python type checker, has broader community adoption and is often more permissive in ambiguous cases. When writing generic libraries intended for broad consumption, running both checkers during development is the most reliable approach to ensuring your type annotations are specification-compliant rather than accidentally dependent on one tool's interpretation.

Key Takeaways

1. Use TypeVar for generic functions, Generic[T] for generic classes (pre-3.12): A standalone TypeVar is sufficient when the generic behavior belongs entirely to one function. When a class needs to carry a type parameter across multiple methods, inherit from Generic[T]. In Python 3.12+, both patterns collapse into the bracket syntax — def f[T](...) and class C[T]:.
2. Bounded TypeVars preserve specificity; constrained ones do not: Use bound=SomeClass when you want the return type to stay as specific as possible (the return type of make_speak(Dog()) is Dog, not Animal). Use positional constraints like TypeVar('T', str, bytes) when you need to accept exactly a fixed set of types and no subtypes of them matter.
3. Default variance is invariant — change it only when you have a reason: Mutable containers should stay invariant. Read-only producers (things that only return T) can be declared covariant. Consumers and callbacks (things that only accept T) can be contravariant. In Python 3.12+, you rarely need to declare variance at all — type checkers infer it.
4. Do not mix old and new syntax within the same class: PEP 695 is explicit that combining bracket-style type parameters with a traditional Generic[T] base on the same class produces a runtime error. Mixing is fine across separate classes in the same file — just not within a single definition.
5. PEP 695 is the modern standard for projects on Python 3.12+: The bracket syntax removes redundant name strings, eliminates global scope pollution, and makes variance inference automatic. The two approaches are semantically equivalent for most purposes, so migration is safe. If you are targeting older Python versions, the old syntax remains fully supported and is not deprecated.
6. Covariant and contravariant TypeVars cannot be used in plain functions: The typing specification is clear that variance is a property of a generic class, not of a generic function. Placing a covariant=True TypeVar in a function signature that is not part of a class will produce errors from both mypy and pyright.
7. Use ParamSpec when wrapping callables: TypeVar alone cannot capture the full parameter list of a function. ParamSpec (or **P in bracket syntax) is the correct tool for typed decorators and higher-order functions that need to preserve the wrapped function's complete signature.
8. Consider Protocol before writing a bounded TypeVar: If your function only needs to call certain methods on its argument and does not need to return the exact same type it received, a Protocol is often simpler and more flexible than a bounded TypeVar. Protocols describe structural interfaces rather than requiring explicit inheritance.
9. Type annotations are not enforced at runtime: Python uses type erasure. Stack[int] and Stack[str] are the same class at runtime. Violations that mypy or pyright would catch will not raise errors when your program executes — which is why running a type checker in CI matters.
10. A TypeVar used in only one position in a signature accomplishes nothing: If T appears in a parameter but not in the return type or any other parameter, it is functionally equivalent to object or Any. Use a concrete type annotation instead. Mypy will flag this pattern directly.
11. Use Self instead of a bounded TypeVar for fluent APIs and method chaining: Self (Python 3.11, PEP 673) always resolves to the type of the current instance and works correctly under inheritance without any TypeVar declaration. It also applies cleanly to @classmethod constructors that return instances of the class.
12. Use TypeGuard or TypeIs when custom validation functions need to narrow types: Standard isinstance() narrowing is automatic, but type checkers cannot narrow based on arbitrary validation logic. Annotating such functions with TypeGuard[T] or TypeIs[T] tells the checker the type is narrowed inside the guarded branch. TypeIs (Python 3.13) is bidirectional and stricter.
13. Use @overload when the input-to-output mapping is discrete and asymmetric: A constrained TypeVar always returns the type it received. @overload lets you declare that str input yields int output and bytes input yields float output — relationships a TypeVar cannot express.
14. Use NewType for nominal distinctiveness without a full class: When the same underlying type (such as int or str) appears in multiple semantically distinct roles, NewType prevents silent substitution between them at zero runtime cost. The values remain the original type at runtime; only the type checker sees the distinction.
15. Use Never to enforce exhaustive dispatch in generic union handling: Annotating a fallback function's parameter as Never makes the type checker verify that all members of a union are handled. If a new variant is added and the handler is not updated, the checker flags the gap at analysis time rather than at runtime.

Generic programming in Python has traveled a long road from the early PEP 484 boilerplate through the cleaner PEP 695 syntax. The core idea has not changed: when you want a function or class to operate over a family of types while preserving type information through each operation, TypeVar and Generic — or their modern equivalents — are the correct tools. But the type system also includes precision instruments — Self, TypeGuard, @overload, NewType, Never — that each solve a narrower problem more cleanly than a general-purpose TypeVar would. Choosing between them is the skill: understanding not just what each tool does, but which one matches the actual shape of the problem. For more on Python's type system and related concepts, explore the full library of Python tutorials (opens in new window) on PythonCodeCrack.

Frequently Asked Questions

Sources

• PEP 544 — Protocols: Structural Subtyping (Static Duck Typing) (opens in new window), Python Enhancement Proposals
• PEP 695 — Type Parameter Syntax (opens in new window), Python Enhancement Proposals
• PEP 696 — Type Defaults for Type Parameters (opens in new window), Python Enhancement Proposals
• PEP 612 — Parameter Specification Variables (opens in new window), Python Enhancement Proposals
• PEP 646 — Variadic Generics (opens in new window), Python Enhancement Proposals
• PEP 484 — Type Hints (opens in new window), Python Enhancement Proposals
• PEP 483 — The Theory of Type Hints (opens in new window), Python Enhancement Proposals
• typing — Support for type hints (opens in new window), Python 3 Documentation
• What's New In Python 3.12 (opens in new window), Python 3 Documentation
• What's New In Python 3.13 (opens in new window), Python 3 Documentation
• Generics — Python Typing Specification (opens in new window), typing.python.org
• Python 3.12 Preview: Static Typing Improvements (opens in new window), Real Python
• PEP 673 — Self Type (opens in new window), Python Enhancement Proposals
• PEP 647 — User-Defined Type Guards (opens in new window), Python Enhancement Proposals
• PEP 742 — Narrowing Types with TypeIs (opens in new window), Python Enhancement Proposals
• typing.Never — Python 3 Documentation (opens in new window)
• typing.NewType — Python 3 Documentation (opens in new window)