peritype 0.0.1__tar.gz

peritype-0.0.1/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.3
+Name: peritype
+Version: 0.0.1
+Summary: Peritype helps you explore Python types at runtime with ease.
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# Peritype
+
+Peritype helps you navigate Python types and annotations at runtime with ease.
+It provides a standard interface to inspect the mess of types, generics, `TypeVar`s, `Annotated`s, and more.
+
+## Installation
+
+```shell
+$ pip install peritype  # or use your preferred package manager
+```
+
+## Features
+
+### Simple type wrapping
+
+```python
+from peritype import wrap_type
+
+class MyClass:
+    attr: int
+
+    def __init__(self, x: int, y: str) -> None:
+        self.x = x
+        self.y = y
+
+    def my_method(self, z: float) -> bool:
+        return z > 0.0
+
+wrapped = wrap_type(MyClass)
+
+# Test if the type can match another type
+assert wrapped.match(MyClass)
+assert not wrapped.match(int)
+
+# Access attribute type hints
+hints = wrapped.attribute_hints
+assert hints['attr'].match(int)
+
+# Access the __init__ method's signature hints
+init_signature = wrapped.init.get_signature_hints()
+assert init_signature['x'].match(int)
+assert init_signature['y'].match(str)
+
+# Access method signatures
+method_wrap = wrapped.get_method_hints('my_method')
+method_signature = method_wrap.get_signature_hints()
+assert method_signature['z'].match(float)
+assert method_wrap.return_hint.match(bool)
+```
+
+### Generic type wrapping
+
+```python
+from peritype import wrap_type
+
+class GenericParent[T]:
+    def get_value(self) -> T:
+        ...
+
+class GenericChild[T, U](GenericParent[U]):
+    def get_other_value(self) -> T:
+        ...
+
+wrapped_child = wrap_type(GenericChild[int, str])
+
+# Access method signatures with resolved generics
+get_value_wrap = wrapped_child.get_method_hints('get_value')
+get_value_signature = get_value_wrap.get_signature_hints()
+assert get_value_wrap.get_return_hint().match(str)
+
+get_other_value_wrap = wrapped_child.get_method_hints('get_other_value')
+get_other_value_signature = get_other_value_wrap.get_signature_hints()
+assert get_other_value_wrap.get_return_hint().match(int)
+```
+
+### Union and `Any` handling
+
+```python
+from peritype import wrap_type
+
+int_wrap = wrap_type(int)
+# A simple type can match itself and unions including itself
+assert int_wrap.match(int)
+assert int_wrap.match(int | str)
+assert not int_wrap.match(str)
+
+union_wrap = wrap_type(int | str)
+# A union type can match any of its member types and unions including them
+assert union_wrap.match(int | str)
+assert union_wrap.match(int)
+assert union_wrap.match(str)
+assert union_wrap.match(int | float)
+assert not union_wrap.match(float)
+
+int_list_wrap = wrap_type(list[int])
+# A generic type with parameters can match the same generic with compatible parameters, including Any or Ellipsis
+assert int_list_wrap.match(list[int])
+assert int_list_wrap.match(list[int | str])
+assert int_list_wrap.match(list[Any])
+```
+
+### Type metadata, `Annotated` and more
+
+```python
+from peritype import wrap_type
+from typing import Annotated, NotRequired, TypedDict
+
+annotated_wrap = wrap_type(Annotated[int | None, "metadata"])
+
+assert annotated_wrap.nullable  # None in the union
+assert not annotated_wrap.union  # int | None is not considered a union, the None part is handled separately
+assert annotated_wrap.annotations == ("metadata",)
+
+class MyTypedDict(TypedDict, total=False):
+    x: int
+    y: NotRequired[str]
+
+typed_dict_wrap = wrap_type(MyTypedDict)
+assert not typed_dict_wrap.total
+
+attrs = typed_dict_wrap.attribute_hints
+assert attrs["x"].match(int)
+assert attrs["y"].match(str)
+assert attrs["x"].required
+assert not attrs["y"].required
+```
+
+### Function wrapping
+
+```python
+from peritype import wrap_func
+
+def my_function(a: int, b: str) -> bool:
+    return str(a) == b
+
+wrapped_func = wrap_func(my_function)
+
+# Access function signature hints
+signature_hints = wrapped_func.get_signature_hints()
+assert signature_hints['a'].match(int)
+assert signature_hints['b'].match(str)
+assert wrapped_func.get_return_hint().match(bool)
+```

peritype-0.0.1/README.md

@@ -0,0 +1,143 @@
+# Peritype
+
+Peritype helps you navigate Python types and annotations at runtime with ease.
+It provides a standard interface to inspect the mess of types, generics, `TypeVar`s, `Annotated`s, and more.
+
+## Installation
+
+```shell
+$ pip install peritype  # or use your preferred package manager
+```
+
+## Features
+
+### Simple type wrapping
+
+```python
+from peritype import wrap_type
+
+class MyClass:
+    attr: int
+
+    def __init__(self, x: int, y: str) -> None:
+        self.x = x
+        self.y = y
+
+    def my_method(self, z: float) -> bool:
+        return z > 0.0
+
+wrapped = wrap_type(MyClass)
+
+# Test if the type can match another type
+assert wrapped.match(MyClass)
+assert not wrapped.match(int)
+
+# Access attribute type hints
+hints = wrapped.attribute_hints
+assert hints['attr'].match(int)
+
+# Access the __init__ method's signature hints
+init_signature = wrapped.init.get_signature_hints()
+assert init_signature['x'].match(int)
+assert init_signature['y'].match(str)
+
+# Access method signatures
+method_wrap = wrapped.get_method_hints('my_method')
+method_signature = method_wrap.get_signature_hints()
+assert method_signature['z'].match(float)
+assert method_wrap.return_hint.match(bool)
+```
+
+### Generic type wrapping
+
+```python
+from peritype import wrap_type
+
+class GenericParent[T]:
+    def get_value(self) -> T:
+        ...
+
+class GenericChild[T, U](GenericParent[U]):
+    def get_other_value(self) -> T:
+        ...
+
+wrapped_child = wrap_type(GenericChild[int, str])
+
+# Access method signatures with resolved generics
+get_value_wrap = wrapped_child.get_method_hints('get_value')
+get_value_signature = get_value_wrap.get_signature_hints()
+assert get_value_wrap.get_return_hint().match(str)
+
+get_other_value_wrap = wrapped_child.get_method_hints('get_other_value')
+get_other_value_signature = get_other_value_wrap.get_signature_hints()
+assert get_other_value_wrap.get_return_hint().match(int)
+```
+
+### Union and `Any` handling
+
+```python
+from peritype import wrap_type
+
+int_wrap = wrap_type(int)
+# A simple type can match itself and unions including itself
+assert int_wrap.match(int)
+assert int_wrap.match(int | str)
+assert not int_wrap.match(str)
+
+union_wrap = wrap_type(int | str)
+# A union type can match any of its member types and unions including them
+assert union_wrap.match(int | str)
+assert union_wrap.match(int)
+assert union_wrap.match(str)
+assert union_wrap.match(int | float)
+assert not union_wrap.match(float)
+
+int_list_wrap = wrap_type(list[int])
+# A generic type with parameters can match the same generic with compatible parameters, including Any or Ellipsis
+assert int_list_wrap.match(list[int])
+assert int_list_wrap.match(list[int | str])
+assert int_list_wrap.match(list[Any])
+```
+
+### Type metadata, `Annotated` and more
+
+```python
+from peritype import wrap_type
+from typing import Annotated, NotRequired, TypedDict
+
+annotated_wrap = wrap_type(Annotated[int | None, "metadata"])
+
+assert annotated_wrap.nullable  # None in the union
+assert not annotated_wrap.union  # int | None is not considered a union, the None part is handled separately
+assert annotated_wrap.annotations == ("metadata",)
+
+class MyTypedDict(TypedDict, total=False):
+    x: int
+    y: NotRequired[str]
+
+typed_dict_wrap = wrap_type(MyTypedDict)
+assert not typed_dict_wrap.total
+
+attrs = typed_dict_wrap.attribute_hints
+assert attrs["x"].match(int)
+assert attrs["y"].match(str)
+assert attrs["x"].required
+assert not attrs["y"].required
+```
+
+### Function wrapping
+
+```python
+from peritype import wrap_func
+
+def my_function(a: int, b: str) -> bool:
+    return str(a) == b
+
+wrapped_func = wrap_func(my_function)
+
+# Access function signature hints
+signature_hints = wrapped_func.get_signature_hints()
+assert signature_hints['a'].match(int)
+assert signature_hints['b'].match(str)
+assert wrapped_func.get_return_hint().match(bool)
+```

peritype-0.0.1/pyproject.toml

@@ -0,0 +1,25 @@
+[project]
+name = "peritype"
+version = "0.0.1"
+description = "Peritype helps you explore Python types at runtime with ease."
+readme = "README.md"
+requires-python = ">=3.13"
+dependencies = []
+
+[build-system]
+requires = ["uv_build>=0.8.4,<0.9.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = ["ruff>=0.12.7"]
+test = ["pytest>=8.4.1", "pytest-cov>=6.2.1"]
+
+[tool.ruff]
+line-length = 120
+
+[tool.ruff.lint]
+extend-select = ["E", "W", "F", "B", "Q", "I", "N", "RUF", "UP"]
+fixable = ["ALL"]
+
+[tool.ruff.lint.per-file-ignores]
+"**/__init__.py" = ["I001"]

peritype-0.0.1/src/peritype/__init__.py

@@ -0,0 +1,12 @@
+from peritype.twrap import TWrap as TWrap
+from peritype.fwrap import FWrap as FWrap
+from peritype.wrap import wrap_type as wrap_type, wrap_func as wrap_func
+from peritype.utils import use_cache as use_cache
+
+__all__ = [
+    "FWrap",
+    "TWrap",
+    "use_cache",
+    "wrap_func",
+    "wrap_type",
+]

peritype-0.0.1/src/peritype/collections/__init__.py

@@ -0,0 +1,9 @@
+from peritype.collections.bag import TypeBag as TypeBag
+from peritype.collections.map import TypeMap as TypeMap
+from peritype.collections.tree import TypeSuperTree as TypeSuperTree
+
+__all__ = [
+    "TypeBag",
+    "TypeMap",
+    "TypeSuperTree",
+]

peritype-0.0.1/src/peritype/collections/bag.py

@@ -0,0 +1,42 @@
+from typing import Any
+
+from peritype import TWrap
+from peritype.twrap import TypeNode
+
+
+class TypeBag:
+    def __init__(self) -> None:
+        self._bag = set[TWrap[Any]]()
+        self._raw_types = dict[type[Any], set[TWrap[Any]]]()
+
+    def add(self, twrap: TWrap[Any]) -> None:
+        self._bag.add(twrap)
+
+        def _for_nodes(node: TypeNode[Any]) -> None:
+            raw_type = node.cls
+            if raw_type not in self._raw_types:
+                self._raw_types[raw_type] = set()
+            self._raw_types[raw_type].add(twrap)
+
+        if not twrap.contains_any:
+            twrap.__visit__(for_nodes=_for_nodes)
+
+    def __contains__(self, twrap: TWrap[Any]) -> bool:
+        return twrap in self._bag
+
+    def get_all(self, twrap: TWrap[Any]) -> set[TWrap[Any]]:
+        if not twrap.contains_any:
+            return {twrap} if twrap in self._bag else set()
+        candidates = set[TWrap[Any]]()
+
+        def _for_nodes(node: TypeNode[Any]) -> None:
+            raw_type = node.cls
+            if raw_type in self._raw_types:
+                candidates.update(self._raw_types[raw_type])
+
+        twrap.__visit__(for_nodes=_for_nodes)
+        result = set[TWrap[Any]]()
+        for candidate in candidates:
+            if twrap.match(candidate):
+                result.add(candidate)
+        return result

peritype-0.0.1/src/peritype/collections/map.py

@@ -0,0 +1,73 @@
+from typing import Any, Literal, overload
+
+from peritype.twrap import TWrap
+
+
+class TypeMap:
+    def __init__(self) -> None:
+        self._content: dict[TWrap[Any], set[Any]] = {}
+
+    def __contains__(self, twrap: TWrap[Any], /) -> bool:
+        return twrap in self._content
+
+    def __getitem__(self, twrap: TWrap[Any], /) -> set[Any]:
+        return self._content[twrap]
+
+    def __setitem__(self, twrap: TWrap[Any], /, value: set[Any]) -> None:
+        self._content[twrap] = value
+
+    def __delitem__(self, twrap: TWrap[Any], /) -> None:
+        del self._content[twrap]
+
+    @overload
+    def get[T](
+        self,
+        twrap: TWrap[Any],
+        /,
+        *,
+        not_none: Literal[False] = False,
+        hint: type[T] | TWrap[T],
+    ) -> set[T] | None: ...
+    @overload
+    def get[T](
+        self,
+        twrap: TWrap[Any],
+        /,
+        *,
+        not_none: Literal[True],
+        hint: type[T] | TWrap[T],
+    ) -> set[T]: ...
+    @overload
+    def get(
+        self,
+        twrap: TWrap[Any],
+        /,
+        *,
+        not_none: Literal[False] = False,
+        hint: type[Any] | TWrap[Any] | None = None,
+    ) -> set[Any] | None: ...
+    @overload
+    def get(
+        self,
+        twrap: TWrap[Any],
+        /,
+        *,
+        not_none: Literal[True],
+        hint: type[Any] | TWrap[Any] | None = None,
+    ) -> set[Any] | None: ...
+    def get(
+        self,
+        twrap: TWrap[Any],
+        /,
+        *,
+        not_none: bool = False,
+        hint: type[Any] | TWrap[Any] | None = None,
+    ) -> set[Any] | None:
+        if not_none and twrap not in self._content:
+            return set()
+        return self._content.get(twrap)
+
+    def push(self, twrap: TWrap[Any], value: Any) -> None:
+        if twrap not in self._content:
+            self._content[twrap] = set()
+        self._content[twrap].add(value)

peritype-0.0.1/src/peritype/collections/tree.py

@@ -0,0 +1,47 @@
+from typing import Any, ForwardRef, Generic, get_origin
+
+from peritype.collections import TypeMap
+from peritype.wrap import TWrap, TypeNode
+
+
+class TypeSuperTree:
+    def __init__(self) -> None:
+        self._content: TypeMap = TypeMap()
+
+    def add(self, twrap: TWrap[Any]) -> None:
+        bases = set[TWrap[Any]]()
+        self._recurse_all_bases(twrap, bases)
+        for base in bases:
+            self._add_type(base, twrap)
+            if base is not twrap:
+                self.add(base)
+
+    def __contains__(self, twrap: TWrap[Any]) -> bool:
+        return twrap in self._content
+
+    def __getitem__(self, twrap: TWrap[Any]) -> set[TWrap[Any]]:
+        return self._content[twrap]
+
+    def __delitem__(self, twrap: TWrap[Any]) -> None:
+        del self._content[twrap]
+
+    def _add_type(self, base: TWrap[Any], derived: TWrap[Any]) -> None:
+        self._content.push(base, derived)
+
+    @staticmethod
+    def _recurse_all_bases(
+        twrap: TWrap[Any],
+        seen: set[TWrap[Any]],
+    ) -> None:
+        if twrap in seen:
+            return
+        seen.add(twrap)
+
+        def _for_nodes(node: TypeNode[Any]) -> None:
+            for base in node.bases:
+                origin = get_origin(base.origin)
+                if (origin or base.origin) in (object, Generic, ForwardRef):
+                    continue
+                TypeSuperTree._recurse_all_bases(base, seen)
+
+        twrap.__visit__(for_nodes=_for_nodes)

peritype-0.0.1/src/peritype/errors.py

@@ -0,0 +1,9 @@
+from typing import Any
+
+
+class PeritypeError(Exception):
+    def __init__(self, message: str, cls: type[Any] | None = None) -> None:
+        if cls is not None:
+            message = f"{cls.__qualname__}: {message}"
+        super().__init__(message)
+        self.cls = cls

peritype-0.0.1/src/peritype/fwrap.py

@@ -0,0 +1,128 @@
+import inspect
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, get_type_hints, override
+
+from peritype.twrap import TWrap
+
+if TYPE_CHECKING:
+    from peritype.twrap import TWrap, TypeVarLookup
+
+
+class FWrap[**FuncP, FuncT]:
+    def __init__(self, func: Callable[FuncP, FuncT]) -> None:
+        if isinstance(func, FWrap):
+            raise TypeError(f"Cannot wrap {func}, already wrapped")
+        self.func = func
+        self.bound_to = getattr(self.func, "__self__", None)
+        self._signature_hints: dict[str, Any] | None = None
+        self._signature: inspect.Signature | None = None
+        self._parameters: dict[str, inspect.Parameter] | None = None
+
+    @property
+    def name(self) -> str:
+        return self.func.__name__ if hasattr(self.func, "__name__") else str(self.func)
+
+    @property
+    def parameters(self) -> dict[str, inspect.Parameter]:
+        if self._parameters is None:
+            if self._signature is None:
+                self._signature = inspect.signature(self.func)
+            self._parameters = {**self._signature.parameters}
+        return self._parameters
+
+    def param_at(self, index: int) -> inspect.Parameter:
+        all_params = [*self.parameters.values()]
+        return all_params[index]
+
+    def get_signature_hints(self, belongs_to: "TWrap[Any] | None" = None) -> "dict[str, TWrap[Any]]":
+        if self._signature_hints is None:
+            self._signature_hints = {
+                n: self._transform_annotation(c, belongs_to.type_var_lookup if belongs_to else None)
+                for n, c in get_type_hints(self.func, include_extras=True).items()
+            }
+        return self._signature_hints
+
+    def get_signature_hint(self, index: int, belongs_to: "TWrap[Any] | None" = None) -> "TWrap[Any]":
+        return self.get_signature_hints(belongs_to)[self.param_at(index).name]
+
+    def get_return_hint(self, belongs_to: "TWrap[Any] | None" = None) -> "TWrap[FuncT]":
+        return self.get_signature_hints(belongs_to)["return"]
+
+    def __call__(self, *args: FuncP.args, **kwargs: FuncP.kwargs) -> FuncT:
+        return self.func(*args, **kwargs)
+
+    @staticmethod
+    def _transform_annotation(anno: Any, lookup: "TypeVarLookup | None") -> Any:
+        from peritype import wrap_type
+
+        if lookup is not None and anno in lookup:
+            return wrap_type(lookup[anno], lookup=lookup)
+        return wrap_type(anno, lookup=lookup)
+
+    @override
+    def __str__(self) -> str:
+        return f"{self.func.__qualname__}"
+
+    @override
+    def __repr__(self) -> str:
+        return f"<Function {self}>"
+
+    @override
+    def __hash__(self) -> int:
+        return hash(self.func)
+
+    def bind(self, bound_to: "TWrap[Any]") -> "BoundFWrap[FuncP, FuncT]":
+        return BoundFWrap(self, bound_to)
+
+
+class BoundFWrap[**FWrapP, FWrapT]:
+    def __init__(self, fwrap: FWrap[FWrapP, FWrapT], bound_to: "TWrap[Any]") -> None:
+        self._fwrap = fwrap
+        self._bound_to = bound_to
+
+    @property
+    def name(self) -> str:
+        return self.inner.name
+
+    @property
+    def inner(self) -> FWrap[FWrapP, FWrapT]:
+        return self._fwrap
+
+    @property
+    def bound_to(self) -> "TWrap[Any]":
+        return self._bound_to
+
+    @property
+    def func(self) -> Callable[FWrapP, FWrapT]:
+        return self.inner.func
+
+    @property
+    def parameters(self) -> dict[str, inspect.Parameter]:
+        return self.inner.parameters
+
+    def param_at(self, index: int) -> inspect.Parameter:
+        return self.inner.param_at(index)
+
+    def get_signature_hints(self) -> dict[str, TWrap[Any]]:
+        return self._fwrap.get_signature_hints(self._bound_to)
+
+    def get_signature_hint(self, index: int) -> "TWrap[Any]":
+        return self.get_signature_hints()[self.param_at(index).name]
+
+    def get_return_hint(self) -> "TWrap[FWrapT]":
+        return self.inner.get_return_hint(self.bound_to)
+
+    def __call__(self, *args: FWrapP.args, **kwargs: FWrapP.kwargs) -> FWrapT:  # type: ignore[misc]
+        return self.inner(*args, **kwargs)
+
+    @override
+    def __str__(self) -> str:
+        return str(self.inner)
+
+    @override
+    def __repr__(self) -> str:
+        return repr(self.inner)
+
+    @override
+    def __hash__(self) -> int:
+        return hash(self.inner)

peritype-0.0.1/src/peritype/mapping.py

@@ -0,0 +1,10 @@
+from collections.abc import Iterator
+from typing import Any, Protocol, TypeVar
+
+
+class TypeVarMapping(Protocol):
+    def __getitem__(self, key: TypeVar, /) -> type[Any]: ...
+
+    def __contains__(self, key: TypeVar, /) -> bool: ...
+
+    def __iter__(self, /) -> Iterator[TypeVar]: ...

peritype-0.0.1/src/peritype/twrap.py

@@ -0,0 +1,350 @@
+from collections.abc import Callable, Iterator
+from functools import cached_property
+from types import NoneType
+from typing import TYPE_CHECKING, Any, ForwardRef, Literal, TypeVar, cast, get_type_hints, override
+
+import peritype
+from peritype.errors import PeritypeError
+
+if TYPE_CHECKING:
+    from peritype.fwrap import BoundFWrap
+
+
+class TWrapMeta:
+    def __init__(
+        self,
+        *,
+        annotated: tuple[Any],
+        required: bool,
+        total: bool,
+    ) -> None:
+        self.annotated = annotated
+        self.required = required
+        self.total = total
+
+    @cached_property
+    def _hash(self) -> int:
+        return hash((self.annotated, self.required, self.total))
+
+    @override
+    def __hash__(self) -> int:
+        return self._hash
+
+
+class TypeVarLookup:
+    def __init__(self, origins: dict[TypeVar, Any], twraps: dict[TypeVar, "TWrap[Any]"]) -> NoneType:
+        self.origin_mapping = origins
+        self.twrap_mapping = twraps
+
+    def __getitem__(self, key: TypeVar, /) -> Any:
+        if key not in self.twrap_mapping:
+            raise KeyError(key)
+        return self.origin_mapping[key]
+
+    def __contains__(self, key: TypeVar, /) -> bool:
+        return key in self.origin_mapping
+
+    def __iter__(self, /) -> Iterator[TypeVar]:
+        yield from self.origin_mapping
+
+    def __or__(self, other: "TypeVarLookup") -> "TypeVarLookup":
+        new_origins = self.origin_mapping | other.origin_mapping
+        new_twraps = self.twrap_mapping | other.twrap_mapping
+        return TypeVarLookup(new_origins, new_twraps)
+
+    def origin_items(self, /) -> Iterator[tuple[TypeVar, Any]]:
+        yield from self.origin_mapping.items()
+
+    def twrap_items(self, /) -> Iterator[tuple[TypeVar, "TWrap[Any]"]]:
+        yield from self.twrap_mapping.items()
+
+    def get_origin[DefT](self, key: TypeVar, /, default: DefT | None = None) -> Any | DefT | None:
+        if key not in self.twrap_mapping:
+            return default
+        return self.origin_mapping[key]
+
+    def get_twrap[DefT](self, key: TypeVar, /, default: DefT | None = None) -> Any | DefT | None:
+        if key not in self.twrap_mapping:
+            return default
+        return self.twrap_mapping[key]
+
+
+class TypeNode[T]:
+    def __init__(
+        self,
+        origin: Any,
+        nodes: "tuple[TWrap[Any], ...]",
+        cls: type[T],
+        vars: tuple[Any, ...],
+    ) -> None:
+        self.origin = origin
+        self.nodes = nodes
+        self.cls = cls
+        self.vars = vars
+
+    @staticmethod
+    def _format_type(v: Any) -> str:
+        if isinstance(v, type):
+            return v.__qualname__
+        if isinstance(v, TypeVar):
+            return f"~{v.__name__}"
+        if v is Ellipsis:
+            return "..."
+        if v is Literal:
+            return v.__name__
+        if isinstance(v, ForwardRef):
+            return f"'{v.__forward_arg__}'"
+        return str(v)
+
+    @cached_property
+    def _str(self) -> str:
+        if not self.vars:
+            return self._format_type(self.cls)
+        return f"{self._format_type(self.cls)}[{', '.join(map(self._format_type, self.vars))}]"
+
+    @override
+    def __str__(self) -> str:
+        return self._str
+
+    @override
+    def __repr__(self) -> str:
+        return f"<TypeNode {self._str}>"
+
+    @cached_property
+    def _hash(self) -> int:
+        return hash((self.cls, self.nodes))
+
+    @override
+    def __hash__(self) -> int:
+        return self._hash
+
+    @override
+    def __eq__(self, value: object) -> bool:
+        if not isinstance(value, TypeNode):
+            return False
+        return hash(self) == hash(value)  # pyright: ignore[reportUnknownArgumentType]
+
+    def __getitem__(self, index: int) -> "TWrap[Any]":
+        return self.nodes[index]
+
+    @cached_property
+    def base_name(self) -> str:
+        return self._format_type(self.cls)
+
+    @cached_property
+    def contains_any(self) -> bool:
+        if self.cls is Any or self.cls is Ellipsis:  # pyright: ignore[reportUnnecessaryComparison]
+            return True
+        if isinstance(self.cls, tuple) and Any in self.cls:
+            return True
+        for node in self.nodes:
+            if node.contains_any:
+                return True
+        return False
+
+    @cached_property
+    def bases(self) -> tuple["TWrap[Any]", ...]:
+        bases: list[TWrap[Any]] = []
+        if hasattr(self.cls, "__orig_bases__"):
+            origin_bases: tuple[type[Any], ...] = getattr(self.cls, "__orig_bases__", ())
+            for base in origin_bases:
+                bases.append(peritype.wrap_type(base, lookup=self.type_var_lookup))
+        elif hasattr(self.cls, "__bases__"):
+            cls_bases = getattr(self.cls, "__bases__", ())
+            for base in cls_bases:
+                bases.append(peritype.wrap_type(base, lookup=self.type_var_lookup))
+        return (*bases,)
+
+    @cached_property
+    def type_var_lookup(self) -> TypeVarLookup:
+        parameters = getattr(self.cls, "__type_params__", None) or getattr(self.cls, "__parameters__", None)
+        origin_lookup = dict(zip(parameters, self.vars, strict=True)) if parameters else {}
+        twrap_lookup = dict(zip(parameters, self.nodes, strict=True)) if parameters else {}
+        lookup = TypeVarLookup(origin_lookup, twrap_lookup)
+        base_lookup = TypeVarLookup({}, {})
+        if hasattr(self.cls, "__orig_bases__"):
+            origin_bases: tuple[type[Any], ...] = getattr(self.cls, "__orig_bases__", ())
+            for base in origin_bases:
+                base_wrap = peritype.wrap_type(base, lookup=lookup)
+                base_lookup |= base_wrap.type_var_lookup
+        return base_lookup | lookup
+
+
+class TWrap[T]:
+    def __init__(
+        self,
+        *,
+        origin: Any,
+        nodes: tuple[TypeNode[Any], ...],
+        meta: TWrapMeta,
+    ) -> None:
+        self._origin = origin
+        self._nodes = nodes
+        self._meta = meta
+        self._method_cache: dict[str, BoundFWrap[..., Any]] = {}
+
+    @cached_property
+    def _hash(self) -> int:
+        return hash(((*sorted(self._nodes, key=str),), self._meta))
+
+    @override
+    def __hash__(self) -> int:
+        return self._hash
+
+    @override
+    def __eq__(self, value: object) -> bool:
+        if not isinstance(value, TWrap):
+            return False
+        return hash(self) == hash(value)  # pyright: ignore[reportUnknownArgumentType]
+
+    @cached_property
+    def _str(self) -> str:
+        return " | ".join(str(n) for n in self._nodes)
+
+    @override
+    def __str__(self) -> str:
+        return self._str
+
+    @cached_property
+    def _repr(self) -> str:
+        return f"<Type {self}>"
+
+    @override
+    def __repr__(self) -> str:
+        return self._repr
+
+    def __visit__(self, *, for_nodes: Callable[[TypeNode[Any]], None] | None = None) -> None:
+        if for_nodes:
+            for node in self._nodes:
+                for_nodes(node)
+
+    def __getitem__(self, index: int) -> TypeNode[Any]:
+        return self.nodes[index]
+
+    @property
+    def origin(self) -> type[T]:
+        return self._origin
+
+    @property
+    def required(self) -> bool:
+        return self._meta.required
+
+    @property
+    def total(self) -> bool:
+        return self._meta.total
+
+    @cached_property
+    def annotations(self) -> tuple[Any, ...]:
+        return self._meta.annotated
+
+    @property
+    def nodes(self) -> tuple["TypeNode[Any]", ...]:
+        return self._nodes
+
+    @cached_property
+    def type_var_lookup(self) -> TypeVarLookup:
+        lookup = TypeVarLookup({}, {})
+        for node in self._nodes:
+            lookup |= node.type_var_lookup
+        return lookup
+
+    @cached_property
+    def contains_any(self) -> bool:
+        return any(node.contains_any for node in self._nodes)
+
+    @cached_property
+    def union(self) -> bool:
+        return len([n for n in self._nodes if n.cls is not NoneType]) > 1
+
+    @cached_property
+    def nullable(self) -> bool:
+        return any(n.cls is NoneType for n in self._nodes)
+
+    @cached_property
+    def attribute_hints(self) -> "dict[str, TWrap[Any]]":
+        if self.union:
+            raise TypeError("Cannot get attributes of union types")
+        attrs: dict[str, TWrap[Any]] = {}
+        for node in self._nodes:
+            if node.cls is NoneType:
+                continue
+            attrs |= self._get_recursive_attribute_hints(node.cls)
+        return attrs
+
+    def _get_recursive_attribute_hints(self, cls: type[Any]) -> "dict[str, TWrap[Any]]":
+        attr_hints: dict[str, TWrap[Any]] = {}
+        try:
+            for base in cls.__bases__:
+                attr_hints |= self._get_recursive_attribute_hints(base)
+            raw_ints: dict[str, type[Any] | TypeVar] = get_type_hints(cls, include_extras=True)
+            for attr_name, hint in raw_ints.items():
+                if isinstance(hint, TypeVar):
+                    if hint in self.type_var_lookup:
+                        attr_hints[attr_name] = peritype.wrap_type(self.type_var_lookup[hint])
+                    else:
+                        raise PeritypeError(f"TypeVar ~{hint.__name__} could not be found in lookup", cls=cls)
+                else:
+                    attr_hints[attr_name] = peritype.wrap_type(hint, lookup=self.type_var_lookup)
+        except (AttributeError, TypeError, NameError):
+            return attr_hints
+        return attr_hints
+
+    @cached_property
+    def init(self) -> "BoundFWrap[..., Any]":
+        if self.union:
+            raise TypeError("Cannot get __init__ of union types")
+        for node in self._nodes:
+            if hasattr(node.cls, "__init__"):
+                init_func = node.cls.__init__
+                fwrap = peritype.wrap_func(init_func)
+                bound_fwrap = fwrap.bind(self)
+                return bound_fwrap
+        raise TypeError("No __init__ method found in type nodes")
+
+    def get_method_hints(self, method_name: str) -> "BoundFWrap[..., Any]":
+        if self.union:
+            raise TypeError("Cannot get methods of union types")
+        if method_name in self._method_cache:
+            return self._method_cache[method_name]
+        for node in self._nodes:
+            if hasattr(node.cls, method_name):
+                method_func = getattr(node.cls, method_name)
+                fwrap = peritype.wrap_func(method_func)
+                bound_fwrap = fwrap.bind(self)
+                self._method_cache[method_name] = bound_fwrap
+                return bound_fwrap
+        raise AttributeError(f"Method '{method_name}' not found in type nodes")
+
+    def match(self, other: Any) -> bool:
+        other_wrap: TWrap[Any]
+        if isinstance(other, TWrap):
+            other_wrap = cast(TWrap[Any], other)
+        else:
+            other_wrap = peritype.wrap_type(other)
+
+        for a in self._nodes:
+            for b in other_wrap._nodes:
+                if self._nodes_intersect(a, b):
+                    return True
+        return False
+
+    @staticmethod
+    def _nodes_intersect(a: "TypeNode[Any]", b: "TypeNode[Any]") -> bool:
+        if a.origin is Any or b.origin is Any:
+            return True
+        if a.origin is Ellipsis or b.origin is Ellipsis:
+            return True
+
+        if a.cls is not b.cls:
+            return False
+
+        if not a.nodes and not b.nodes:
+            return True
+
+        if len(a.nodes) != len(b.nodes):
+            return False
+
+        for i in range(len(a.nodes)):
+            if not a.nodes[i].match(b.nodes[i]):
+                return False
+        return True

peritype-0.0.1/src/peritype/utils.py

@@ -0,0 +1,143 @@
+import collections.abc
+import contextlib
+from types import UnionType
+from typing import (
+    Annotated,
+    Any,
+    ForwardRef,
+    NotRequired,
+    ParamSpec,
+    TypeAliasType,
+    TypeVar,
+    Union,  # pyright: ignore[reportDeprecated]
+    get_args,
+    get_origin,
+)
+
+from peritype.errors import PeritypeError
+from peritype.mapping import TypeVarMapping
+from peritype.twrap import TWrapMeta
+
+
+def unpack_annotations(cls: Any, meta: TWrapMeta) -> Any:
+    if isinstance(cls, TypeAliasType):
+        return unpack_annotations(cls.__value__, meta)
+    origin = get_origin(cls)
+    if origin is Annotated:
+        cls, *annotated = get_args(cls)
+        meta.annotated = (*annotated,)
+        return unpack_annotations(cls, meta)
+    if origin is NotRequired:
+        meta.required = False
+        return unpack_annotations(get_args(cls)[0], meta)
+    meta.total = getattr(cls, "__total__", True)
+    return cls
+
+
+def unpack_union(cls: Any) -> tuple[Any, ...]:
+    origin = get_origin(cls)
+    if origin in (UnionType, Union):  # pyright: ignore[reportDeprecated]
+        return get_args(cls)
+    else:
+        return (cls,)
+
+
+def get_generics[GenT](
+    _cls: type[GenT],
+    lookup: TypeVarMapping | None,
+    raise_on_forward: bool,
+    raise_on_typevar: bool,
+) -> tuple[type[GenT], tuple[Any, ...]]:
+    if origin := get_origin(_cls):
+        type_vars: list[Any] = []
+        for arg in get_args(_cls):
+            arg: Any
+            if isinstance(arg, ForwardRef) and raise_on_forward:
+                raise PeritypeError(
+                    f"Generic parameter '{arg.__forward_arg__}' cannot be a string",
+                    cls=origin,
+                )
+            if isinstance(arg, TypeVar):
+                if lookup is not None:
+                    if arg in lookup:
+                        arg = lookup[arg]
+                    elif raise_on_typevar:
+                        raise PeritypeError(
+                            f"TypeVar ~{arg.__name__} could not be found in lookup",
+                            cls=origin,
+                        )
+                elif raise_on_typevar:
+                    raise PeritypeError(
+                        f"Generic parameter ~{arg.__name__} cannot be a TypeVar",
+                        cls=origin,
+                    )
+            if isinstance(arg, list):
+                arg = (*arg,)
+            type_vars.append(arg)
+        return origin, (*type_vars,)
+    return _cls, ()
+
+
+def use_cache(value: bool) -> None:
+    from peritype import wrap
+
+    wrap.USE_CACHE = value
+
+
+def fill_params_in(cls_: type[Any], vars: tuple[Any, ...]) -> tuple[type[Any], tuple[Any, ...]]:
+    params: tuple[Any, ...] = getattr(cls_, "__type_params__", None) or getattr(cls_, "__parameters__", None) or ()
+    if cls_ in BUILTIN_PARAM_COUNT:
+        param_count = BUILTIN_PARAM_COUNT[cls_]
+    else:
+        param_count = len(params)
+    if len(vars) >= param_count:
+        return cls_, vars
+    new_vars: list[Any] = []
+    for i in range(len(vars), param_count):
+        if i < len(params):
+            if isinstance(params[i], ParamSpec):
+                new_vars.append(...)
+            else:
+                new_vars.append(Any)
+        else:
+            new_vars.append(Any)
+    return cls_, (*vars, *new_vars)
+
+
+BUILTIN_PARAM_COUNT: dict[type[Any], int] = {
+    collections.abc.Hashable: 0,
+    collections.abc.Awaitable: 1,
+    collections.abc.Coroutine: 3,
+    collections.abc.AsyncIterable: 1,
+    collections.abc.AsyncIterator: 1,
+    collections.abc.Iterable: 1,
+    collections.abc.Iterator: 1,
+    collections.abc.Reversible: 1,
+    collections.abc.Sized: 0,
+    collections.abc.Container: 1,
+    collections.abc.Collection: 1,
+    collections.abc.Set: 1,
+    collections.abc.MutableSet: 1,
+    collections.abc.Mapping: 2,
+    collections.abc.MutableMapping: 2,
+    collections.abc.Sequence: 1,
+    collections.abc.MutableSequence: 1,
+    list: 1,
+    collections.deque: 1,
+    set: 1,
+    frozenset: 1,
+    collections.abc.MappingView: 1,
+    collections.abc.KeysView: 1,
+    collections.abc.ItemsView: 2,
+    collections.abc.ValuesView: 1,
+    contextlib.AbstractContextManager: 1,
+    contextlib.AbstractAsyncContextManager: 1,
+    dict: 2,
+    collections.defaultdict: 2,
+    collections.OrderedDict: 2,
+    collections.Counter: 1,
+    collections.ChainMap: 2,
+    collections.abc.Generator: 3,
+    collections.abc.AsyncGenerator: 2,
+    type: 1,
+}

peritype-0.0.1/src/peritype/wrap.py

@@ -0,0 +1,59 @@
+from collections.abc import Callable
+from typing import Any, cast, overload
+
+from peritype import FWrap, TWrap
+from peritype.mapping import TypeVarMapping
+from peritype.twrap import TWrapMeta, TypeNode
+from peritype.utils import fill_params_in, get_generics, unpack_annotations, unpack_union
+
+USE_CACHE = True
+_TWRAP_CACHE: dict[Any, TWrap[Any]] = {}
+_FWRAP_CACHE: dict[Any, FWrap[..., Any]] = {}
+
+
+@overload
+def wrap_type[T](
+    cls: type[T],
+    *,
+    lookup: TypeVarMapping | None = None,
+) -> TWrap[T]: ...
+@overload
+def wrap_type(
+    cls: Any,
+    *,
+    lookup: TypeVarMapping | None = None,
+) -> TWrap[Any]: ...
+def wrap_type(
+    cls: Any,
+    *,
+    lookup: TypeVarMapping | None = None,
+) -> Any:
+    if USE_CACHE and cls in _TWRAP_CACHE:
+        return _TWRAP_CACHE[cls]
+    meta = TWrapMeta(annotated=tuple[Any](), required=True, total=True)
+    unpacked: Any = unpack_annotations(cls, meta)
+    nodes = unpack_union(unpacked)
+    wrapped_nodes: list[Any] = []
+    for node in nodes:
+        if node in (None, type(None)):
+            node = type(None)
+        root, vars = get_generics(node, lookup, True, True)
+        root, vars = fill_params_in(root, vars)
+        wrapped_vars = (*(wrap_type(var) for var in vars),)
+        wrapped_node = TypeNode(node, wrapped_vars, root, vars)
+        wrapped_nodes.append(wrapped_node)
+    twrap = cast(TWrap[Any], TWrap(origin=cls, nodes=(*wrapped_nodes,), meta=meta))
+    if USE_CACHE:
+        _TWRAP_CACHE[cls] = twrap
+    return twrap
+
+
+def wrap_func[**FuncP, FuncT](
+    func: Callable[FuncP, FuncT],
+) -> FWrap[FuncP, FuncT]:
+    if USE_CACHE and func in _FWRAP_CACHE:
+        return _FWRAP_CACHE[func]
+    fwrap = FWrap(func)
+    if USE_CACHE:
+        _FWRAP_CACHE[func] = fwrap
+    return fwrap