Python Generic Type Parameters

Advanced

Python lets you make functions, classes, and type aliases generic by putting a type parameter list after their name. This gives one definition a type parameter such as T that can represent different types.

A generic function

Put a type parameter in square brackets immediately after the function name. The parameter can then be used in the function annotations.

1
2
3
4
5

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

print(first([10, 20, 30]))
print(first(["Ada", "Grace"]))

A generic class

A class can declare a type parameter in the same position. The parameter is then available in annotations inside the class body.

1
2
3
4
5
6
7
8
9

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

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

print(Box(42).get())
print(Box("ready").get())

A generic type alias

The type statement from the previous lesson can also have type parameters.

1
2
3
4

type Pair[T] = tuple[T, T]

point: Pair[int] = (3, 4)
print(point)

Use more than one type parameter

Separate type parameters with commas when a result relates more than one type.

1
2
3
4
5

def pair[T, U](left: T, right: U) -> tuple[T, U]:
    return left, right

print(pair(7, "seven"))
print(pair("name", True))

Type parameters have their own scope

A type parameter belongs to the generic function, class, or alias that declares it. It is not automatically a name in the surrounding module scope.

1
2
3
4
5
6
7
8

def identity[T](value: T) -> T:
    return value

print(identity.__type_params__[0].__name__)
try:
    print(T)
except NameError:
    print("T is not a module-level name")

A type parameter can have a bound

A type variable can have a bound after a colon. The bound describes the types a type checker may allow for that parameter.

1
2
3
4
5
6
7

def echo_int[T: int](value: T) -> T:
    return value

parameter = echo_int.__type_params__[0]
print(parameter.__name__)
print(parameter.__bound__.__name__)
print(echo_int(7))

Python 3.13+ also supports type-parameter defaults

A type parameter may have a default expression after =. This affects type-parameter substitution for type-checking, and the default is available from the type-parameter object.

1
2
3
4
5
6

def make_value[T = int](value: T) -> T:
    return value

parameter = make_value.__type_params__[0]
print(parameter.__default__.__name__)
print(make_value(42))

The other type-parameter kinds

Python also provides TypeVarTuple with a leading * and ParamSpec with a leading **. These support generic APIs involving a variable number of types or a callable’s parameter list. They are useful, but their practical typing patterns are more advanced than the single-type-parameter examples in this lesson.

1
2
3
4

type Record[*Ts] = tuple[*Ts]

record: Record[int, str, float] = (7, "Ada", 3.14)
print(record)

1
2
3
4
5
6
7
8
9

from collections.abc import Callable

type Handler[**P, R] = Callable[P, R]

def name_length(name: str) -> int:
    return len(name)

handler: Handler[[str], int] = name_length
print(handler("Ada"))

Key idea

A type parameter list makes a function, class, or type alias generic. Start with a simple T when one type varies, add more parameters when types have different roles, and move to TypeVarTuple or ParamSpec only when the API genuinely needs their more advanced relationships.