typetoolbox

typetoolbox provides runtime utilities for inspecting Python generics and resolving TypeVar bindings.

Installation

uv add typetoolbox

Core APIs

• GenericTypeMap: map TypeVar names to concrete runtime types for a generic class/alias.
• get_generic_mapping(obj_or_type): build a GenericTypeMap from a class, alias, or object instance.
• resolve_typevars(tp, mapping_source, strict=False): recursively resolve TypeVars in nested type expressions.
• find_specializations(base_generic, where=None): find subclasses that fully close a base generic.
• inspect_specializations(base_generic, include_generic=False, where=None): inspect subclasses with rich mapping metadata.
• find_specializations_by_args(base_generic, args): return exact-arg specializations.
• build_specialization_index(base_generic): map resolved arg tuples to implementations.
• try_to_map_generic_args_to_specialization(generic_type, specialization_type): map generic args onto a concrete specialization.

Example

from typing import Generic, TypeVar

from typetoolbox import GenericTypeMap, find_specializations, resolve_typevars

X = TypeVar("X")
Y = TypeVar("Y")


class Pair(Generic[X, Y]):
    pass


class IntStrPair(Pair[int, str]):
    pass


mapping = GenericTypeMap(IntStrPair)
assert resolve_typevars(dict[X, list[Y]], mapping) == dict[int, list[str]]
assert find_specializations(Pair) == [IntStrPair]