TypeVar

typing.TypeVar is a class used to instantiate type variables for generic type hinting in Python. It acts as a placeholder for a specific, yet-to-be-determined type that must remain consistent across multiple evaluations within a given static typing scope, such as a function signature or a generic class definition.

from typing import TypeVar

T = TypeVar('T')

Signature and Parameters

The TypeVar constructor accepts a mandatory name and several optional arguments to restrict type resolution and define variance.

TypeVar(name, *constraints, bound=None, covariant=False, contravariant=False, infer_variance=False)

name (str) A string literal that must exactly match the name of the variable to which the TypeVar is assigned. This is required by the Python runtime for introspection, __name__ resolution, and pickling.

*constraints (type) Positional arguments that restrict the type variable to a discrete, closed set of allowed types. When constraints are provided, the static type checker forces the resolved type to be exactly one of the specified types, not a subclass.

# Can only resolve to exactly `str` or exactly `bytes`
AnyStr = TypeVar('AnyStr', str, bytes) 

bound (type) A keyword argument that establishes an upper bound for the type variable. The resolved type must be the specified bounding type or a subclass of that bounding type. Unlike *constraints, bound allows for continuous subtype resolution.

class Shape: pass


# Can resolve to Shape or any subclass of Shape
TShape = TypeVar('TShape', bound=Shape) 

covariant (bool) A keyword argument that marks the type variable as covariant. Covariance indicates that a generic type Generic[T] preserves the subtyping relationship of its type arguments. If Derived is a subtype of Base, then Generic[Derived] is recognized as a subtype of Generic[Base].

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

contravariant (bool) A keyword argument that marks the type variable as contravariant. Contravariance reverses the subtyping relationship. If Derived is a subtype of Base, then Generic[Base] is recognized as a subtype of Generic[Derived].

T_contra = TypeVar('T_contra', contravariant=True)

infer_variance (bool) Introduced in Python 3.12, this keyword argument instructs static type checkers (like Mypy or Pyright) to automatically infer the variance (invariant, covariant, or contravariant) based on how the type variable is structurally utilized within a generic class.

T_infer = TypeVar('T_infer', infer_variance=True)

Python 3.12+ Type Parameter Syntax (PEP 695)

As of Python 3.12, explicit instantiation of TypeVar via the typing module is largely superseded by the native type parameter syntax. This syntax automatically creates the underlying TypeVar objects at runtime and implicitly handles variance inference.

# Implicit TypeVar 'T'
def process[T](item: T) -> T: ...


# Implicit TypeVar 'T' with a bound
class Container[T: Shape]: ...


# Implicit TypeVar 'T' with constraints
def concatenate[T: (str, bytes)](a: T, b: T) -> T: ...

Master Python with Deep Grasping Methodology!

Learn More