Python Generic Syntax: TypeVar, Generic, and PEP 695
Learn Python generic syntax: how TypeVar, Generic, and PEP 695 are used to write reusable, type-checked classes and functions.

Python's generic syntax lets you define functions and classes that work with any type while preserving type information for static type checkers. The core idea is to declare a type variable, then use it in signatures to describe relationships between inputs and outputs. This article covers the traditional TypeVar and Generic approach, the PEP 695 syntax introduced in Python 3.12, and the runtime behavior you should expect.
Declaring a Generic Class
The traditional way to create a generic class is to inherit from Generic[T], where T is a TypeVar. This tells type checkers that the class has a type parameter that can be substituted with a concrete type when the class is used.
from typing import TypeVar, Generic
T = TypeVar('T')
class Box(Generic[T]):
def __init__(self, item: T) -> None:
self.item = item
def get(self) -> T:
return self.itemWhen you use Box[int], the type checker knows that get() returns an int. Without the generic annotation, get() would be typed as Any, and you would lose the ability to catch type mismatches at static analysis time.
The Generic[T] base class is a marker. It makes the class subscriptable, but it does not create a separate class for each type argument. Its main purpose is to give static type checkers the information they need. At runtime, Box[int] and Box[str] are generic aliases with the same underlying class Box; no separate class is created for each type argument.
Writing Generic Functions
Generic functions use the same TypeVar mechanism. The type variable can appear in parameter types and the return type, allowing the function to express a relationship between them.
from typing import Sequence, TypeVar
T = TypeVar('T')
def first(seq: Sequence[T]) -> T:
return seq[0]Here, first accepts any sequence (list, tuple, string) and returns an element of the same type. If you call first([1, 2, 3]), the return type is inferred as int. If you call first(("a", "b")), it is inferred as str.
Using the same T declared above, type variables can also enforce that two arguments share the same type:
def pair(a: T, b: T) -> tuple[T, T]:
return (a, b)This ensures that both arguments have the same type, which is useful for functions that combine values.
Constraining Type Variables with Bounds
A bare TypeVar accepts any type. When you need to restrict the possible types, use the bound parameter. The bound specifies an upper limit; the type variable can only be substituted with that type or a subtype of it.
from typing import TypeVar
class Number:
pass
class IntNumber(Number):
pass
N = TypeVar('N', bound=Number)
def add_numbers(a: N, b: N) -> N:
# Implementation that works with Number and its subclasses
...This is useful when the generic implementation relies on methods defined in the bound class. Without the bound, the type checker would reject calls to those methods because it cannot guarantee they exist.
Bounds also work with built-in types. For example, TypeVar('T', bound=float) allows int and float but not str.
Understanding Variance and Invariance
Variance describes how generic types behave with respect to subtyping. In Python's typing system, a TypeVar can be marked as covariant, contravariant, or left invariant (the default).
- Invariant (default):
Box[int]is not a subtype ofBox[float], even thoughintis a subtype offloat. This is the safest default because it prevents accidental type mismatches when the generic type is used for both reading and writing. - Covariant (
covariant=True):Box[int]is a subtype ofBox[float]. This is suitable for types that produce values, such as an immutable container. - Contravariant (
contravariant=True):Box[float]is a subtype ofBox[int]. This is suitable for types that consume values, such as a callback.
Consider a simple producer:
T_co = TypeVar('T_co', covariant=True)
class Producer(Generic[T_co]):
def produce(self) -> T_co:
...Marking T_co as covariant lets you assign Producer[int] to a variable of type Producer[float] because int is a subtype of float. This works because the producer only returns T, never accepts it as an input.
Contravariance is the reverse: for a type that only consumes values, Box[float] would be a subtype of Box[int]. Most user-defined generics should stay invariant unless you have a clear reason to change variance. Misusing variance can lead to subtle type errors that are hard to debug.
PEP 695: The New Generic Syntax
Python 3.12 introduced a more concise syntax for generics. Instead of inheriting from Generic[T], you can declare type parameters directly in the class or function definition.
from typing import Sequence
class Box[T]:
def __init__(self, item: T) -> None:
self.item = item
def get(self) -> T:
return self.item
def first[T](seq: Sequence[T]) -> T:
return seq[0]This syntax is less verbose and removes the need to define a TypeVar separately. The type parameter T is scoped to the class or function, and it can be used in the same ways as before. PEP 695 also introduces a type statement for defining type aliases, but the generic syntax is the most visible change.
Note that this syntax requires Python 3.12 or later. If you are targeting older versions, use the typing.Generic approach. For the simple cases shown here, the two styles have the same static meaning.
Runtime Behavior: Type Hints Are Not Enforced
Generic type hints are erased at runtime. When you define class Box[T], Python does not create a distinct class for each type argument. Box[int] and Box[str] are generic aliases whose underlying class is still Box; Python does not build new subclasses for type arguments.
This means that generic syntax provides no runtime type checking. If you call box.get() and assign the result to a variable expecting a string, no error occurs at runtime; the type checker is the only tool that can catch the mismatch. This is a deliberate design choice: Python's typing system is for static analysis, not runtime enforcement.
If you need runtime validation, you must implement it separately, for example with isinstance checks or by using a library like pydantic. Generics do not replace runtime validation; they complement it by giving you early feedback during development.
Choosing Between Generics and Union Types
Generics and union types (Union[int, str] or int | str) serve different purposes. A union type says "this value can be one of a fixed set of types." A generic says "this value can be any type, but the relationship between inputs and outputs is consistent."
Use a union when the set of possible types is known and finite:
def parse(value: int | str) -> int:
...Use a generic when you want to preserve the specific type across a boundary:
def identity(value: T) -> T:
return valueIf you tried to write identity with a union, you would lose the exact type of the input. The return type would be int | str, forcing the caller to narrow it again. Generics avoid that narrowing step by carrying the type through.
A practical rule: if the function or class must work with an open set of types and the type relationship matters, use a generic. If the set of types is closed and you need to handle each case differently, use a union. Mixing both is also possible, such as def process(items: list[T]) -> T, where T itself could be a union if needed.
Generics add complexity to the signature. For a one-off script where type safety is less critical, a simpler annotation like Any or a union may be sufficient. But for library code or long-lived projects, the extra precision often pays off by catching bugs earlier and making the API self-documenting.
Try matching browser tools
All toolsSmall utilities that fit Python work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Python guides
All Python guidesPython iter(): How the Built-in Function Works
Explains Python's iter() built-in: how it creates iterators, the two-argument sentinel form, custom iterator classes, and common edge cases.
Python Pika: Queues, Exchanges, Routing Keys, and Acknowledgements
Learn how to use Python's Pika client with RabbitMQ: declare queues and exchanges, publish with routing keys, consume messages, and handle acknowledgements reliably.
Python Kafka: kafka-python vs Confluent Client
python kafka python vs confluent kafka: Compare kafka-python and Confluent Kafka Python clients: API differences, performance, feature coverage, and when to choose eac...
Python Kafka Offsets, Partitions, and Manual Commits
Learn how Kafka offsets and partitions work and how to manually commit offsets in Python consumers with kafka-python and confluent-kafka. Covers sync vs async commits, rebalances, and seeking.
More in Python
All Python guidesThe guides filed next to this one in Python, in library order.