Metadata-Version: 2.4
Name: typetoolbox
Version: 0.1.0
Summary: Runtime helpers for inspecting and resolving Python generic types.
Requires-Python: >=3.12
Requires-Dist: funcie>=0.1.1
Description-Content-Type: text/markdown

# typetoolbox

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

## Installation

```bash
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 `TypeVar`s 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

```python
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]
```
