peritype 0.4.0__tar.gz

peritype-0.4.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.3
+Name: peritype
+Version: 0.4.0
+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.4.0/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.4.0/peritype/__init__.py

@@ -0,0 +1,4 @@
+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

peritype-0.4.0/peritype/collections/__init__.py

@@ -0,0 +1,3 @@
+from peritype.collections.bag import TypeBag as TypeBag
+from peritype.collections.map import TypeMap as TypeMap, TypeSetMap as TypeSetMap
+from peritype.collections.tree import TypeSuperTree as TypeSuperTree

peritype-0.4.0/peritype/collections/bag.py

@@ -0,0 +1,52 @@
+from typing import Any
+
+from peritype import TWrap
+
+
+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)
+        for node in twrap.nodes:
+            raw_type = node.inner_type
+            if raw_type not in self._raw_types:
+                self._raw_types[raw_type] = set()
+            self._raw_types[raw_type].add(twrap)
+
+    def __contains__(self, twrap: TWrap[Any]) -> bool:
+        return twrap in self._bag
+
+    def get_matching(self, twrap: TWrap[Any]) -> TWrap[Any] | None:
+        if twrap in self._bag:
+            return twrap
+        for node in twrap.nodes:
+            raw_type = node.inner_type
+            if raw_type in self._raw_types:
+                for wrap in self._raw_types[raw_type]:
+                    if twrap.match(wrap):
+                        return wrap
+        return None
+
+    def contains_matching(self, twrap: TWrap[Any]) -> bool:
+        return self.get_matching(twrap) is not None
+
+    def get_all(self, twrap: TWrap[Any]) -> set[TWrap[Any]]:
+        if not twrap.contains_any:
+            return {twrap} if twrap in self._bag else set()
+        result = set[TWrap[Any]]()
+        for node in twrap.nodes:
+            raw_type = node.inner_type
+            if raw_type in self._raw_types:
+                for wrap in self._raw_types[raw_type]:
+                    if twrap.match(wrap):
+                        result.add(wrap)
+        return result
+
+    def copy(self) -> "TypeBag":
+        new_bag = TypeBag()
+        new_bag._bag = self._bag.copy()
+        new_bag._raw_types = {k: v.copy() for k, v in self._raw_types.items()}
+        return new_bag

peritype-0.4.0/peritype/collections/map.py

@@ -0,0 +1,64 @@
+from collections.abc import Iterator
+from typing import Any, overload
+
+from peritype.twrap import TWrap
+
+
+class TypeMap[K, V]:
+    def __init__(self) -> None:
+        self._content: dict[TWrap[K], V] = {}
+
+    def __contains__(self, twrap: TWrap[Any], /) -> bool:
+        return twrap in self._content
+
+    def __getitem__(self, twrap: TWrap[K], /) -> V:
+        return self._content[twrap]
+
+    def __setitem__(self, twrap: TWrap[K], value: V, /) -> None:
+        self._content[twrap] = value
+
+    def __delitem__(self, twrap: TWrap[K], /) -> None:
+        del self._content[twrap]
+
+    def __len__(self) -> int:
+        return len(self._content)
+
+    def __iter__(self) -> Iterator[tuple[TWrap[K], V]]:
+        yield from self._content.items()
+
+    @overload
+    def get[D](self, twrap: TWrap[K], /, *, default: D) -> V | D: ...
+    @overload
+    def get(
+        self,
+        twrap: TWrap[K],
+        /,
+    ) -> V | None: ...
+    def get(
+        self,
+        twrap: TWrap[K],
+        /,
+        *,
+        default: Any = None,
+    ) -> Any:
+        return self._content.get(twrap, default)
+
+    def add(self, twrap: TWrap[K], value: V, /) -> None:
+        self._content[twrap] = value
+
+    def copy(self) -> "TypeMap[K, V]":
+        new_map = TypeMap[K, V]()
+        new_map._content = self._content.copy()
+        return new_map
+
+
+class TypeSetMap[K, V](TypeMap[K, set[V]]):
+    def push(self, twrap: TWrap[K], value: V, /) -> None:
+        if twrap not in self._content:
+            self._content[twrap] = set()
+        self._content[twrap].add(value)
+
+    def count(self, twrap: TWrap[K], /) -> int:
+        if twrap not in self._content:
+            return 0
+        return len(self._content[twrap])

peritype-0.4.0/peritype/collections/tree.py

@@ -0,0 +1,47 @@
+from typing import Any, ForwardRef, Generic, get_origin
+
+from peritype.collections import TypeSetMap
+from peritype.wrap import TWrap
+
+
+class TypeSuperTree:
+    def __init__(self) -> None:
+        self._content = TypeSetMap[Any, TWrap[Any]]()
+
+    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)
+
+    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)
+        for node in twrap.nodes:
+            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)
+
+    def copy(self) -> "TypeSuperTree":
+        new_tree = TypeSuperTree()
+        new_tree._content = self._content.copy()
+        return new_tree

peritype-0.4.0/peritype/errors.py

@@ -0,0 +1,21 @@
+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
+
+
+class UnresolvedForwardRefError(PeritypeError):
+    def __init__(self, name: str, cls: type[Any] | None = None) -> None:
+        super().__init__(f"Parameter {name} could not be resolved from context", cls=cls)
+        self.name = name
+
+
+class UnresolvedTypeVarError(PeritypeError):
+    def __init__(self, typevar_name: str, cls: type[Any] | None = None) -> None:
+        super().__init__(f"TypeVar {typevar_name} could not be inferred from context", cls=cls)
+        self.typevar_name = typevar_name

peritype-0.4.0/peritype/fwrap.py

@@ -0,0 +1,92 @@
+import inspect
+from collections.abc import Callable
+from functools import cached_property
+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
+
+    @property
+    def name(self) -> str:
+        return self.func.__name__ if hasattr(self.func, "__name__") else str(self.func)
+
+    @cached_property
+    def signature(self) -> inspect.Signature:
+        return inspect.signature(self.func)
+
+    @cached_property
+    def parameters(self) -> dict[str, inspect.Parameter]:
+        return {**self.signature.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, belongs_to: "TWrap[Any]") -> "BoundFWrap[FuncP, FuncT]":
+        return BoundFWrap(self.func, belongs_to)
+
+
+class BoundFWrap[**FuncP, FuncT](FWrap[FuncP, FuncT]):
+    def __init__(self, func: Callable[FuncP, FuncT], belongs_to: "TWrap[Any]") -> None:
+        super().__init__(func)
+        self._belongs_to = belongs_to
+
+    @override
+    def get_signature_hints(self, belongs_to: "TWrap[Any] | None" = None) -> "dict[str, TWrap[Any]]":
+        return super().get_signature_hints(belongs_to=belongs_to or self._belongs_to)
+
+    @override
+    def get_signature_hint(self, index: int, belongs_to: "TWrap[Any] | None" = None) -> "TWrap[Any]":
+        return super().get_signature_hint(index, belongs_to=belongs_to or self._belongs_to)
+
+    @override
+    def get_return_hint(self, belongs_to: "TWrap[Any] | None" = None) -> "TWrap[FuncT]":
+        return super().get_return_hint(belongs_to=belongs_to or self._belongs_to)

peritype-0.4.0/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.4.0/peritype/twrap.py

@@ -0,0 +1,413 @@
+import inspect
+from collections.abc import Iterator
+from functools import cached_property
+from types import NoneType
+from typing import TYPE_CHECKING, Any, ForwardRef, Generic, Literal, TypeVar, cast, get_origin, get_type_hints, override
+
+import peritype
+from peritype.errors import UnresolvedTypeVarError
+
+if TYPE_CHECKING:
+    from peritype.fwrap import BoundFWrap, FWrap
+
+
+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,
+        generic_params: "tuple[TWrap[Any], ...]",
+        inner_type: type[T],
+        origin_params: tuple[Any, ...],
+    ) -> None:
+        self._origin = origin
+        self._generic_params = generic_params
+        self._inner_type = inner_type
+        self._origin_params = origin_params
+
+    @property
+    def origin(self) -> Any:
+        return self._origin
+
+    @property
+    def generic_params(self) -> "tuple[TWrap[Any], ...]":
+        return self._generic_params
+
+    @property
+    def inner_type(self) -> type[T]:
+        return self._inner_type
+
+    @property
+    def origin_params(self) -> tuple[Any, ...]:
+        return self._origin_params
+
+    @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._origin_params:
+            return self._format_type(self._inner_type)
+        return f"{self._format_type(self._inner_type)}[{', '.join(map(self._format_type, self._origin_params))}]"
+
+    @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._inner_type, self._generic_params))
+
+    @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._generic_params[index]
+
+    @cached_property
+    def base_name(self) -> str:
+        return self._format_type(self._inner_type)
+
+    @cached_property
+    def contains_any(self) -> bool:
+        if self._inner_type is Any or self._inner_type is Ellipsis:  # pyright: ignore[reportUnnecessaryComparison]
+            return True
+        if isinstance(self._inner_type, tuple) and Any in self._inner_type:
+            return True
+        for node in self._generic_params:
+            if node.contains_any:
+                return True
+        return False
+
+    @cached_property
+    def bases(self) -> tuple["TWrap[Any]", ...]:
+        bases: list[TWrap[Any]] = []
+        if hasattr(self._inner_type, "__orig_bases__"):
+            origin_bases: tuple[type[Any], ...] = getattr(self._inner_type, "__orig_bases__", ())
+            for base in origin_bases:
+                if (base_origin := get_origin(base)) and base_origin is Generic:
+                    continue
+                bases.append(peritype.wrap_type(base, lookup=self.type_var_lookup))
+        elif hasattr(self._inner_type, "__bases__"):
+            cls_bases = getattr(self._inner_type, "__bases__", ())
+            for base in cls_bases:
+                if (base_origin := get_origin(base)) and base_origin is Generic:
+                    continue
+                bases.append(peritype.wrap_type(base, lookup=self.type_var_lookup))
+        return (*bases,)
+
+    @cached_property
+    def type_var_lookup(self) -> TypeVarLookup:
+        parameters = getattr(self._inner_type, "__type_params__", None) or getattr(
+            self._inner_type, "__parameters__", None
+        )
+        origin_lookup = dict(zip(parameters, self._origin_params, strict=True)) if parameters else {}
+        twrap_lookup = dict(zip(parameters, self._generic_params, strict=True)) if parameters else {}
+        lookup = TypeVarLookup(origin_lookup, twrap_lookup)
+        base_lookup = TypeVarLookup({}, {})
+        if hasattr(self._inner_type, "__orig_bases__"):
+            origin_bases: tuple[type[Any], ...] = getattr(self._inner_type, "__orig_bases__", ())
+            for base in origin_bases:
+                if (base_origin := get_origin(base)) and base_origin is Generic:
+                    continue
+                base_wrap = peritype.wrap_type(base, lookup=lookup)
+                base_lookup |= base_wrap.type_var_lookup
+        return base_lookup | lookup
+
+    @cached_property
+    def attribute_hints(self) -> "dict[str, TWrap[Any]]":
+        if self._inner_type is NoneType:
+            return {}
+        return self._get_recursive_attribute_hints(self._inner_type)
+
+    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 UnresolvedTypeVarError(hint.__name__, 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) -> "FWrap[..., Any]":
+        if not hasattr(self._inner_type, "__init__"):
+            raise TypeError("No __init__ method found in type nodes")
+        init_func = self._inner_type.__init__
+        return peritype.wrap_func(init_func)
+
+    @cached_property
+    def signature(self) -> inspect.Signature:
+        return self.init.signature
+
+    @cached_property
+    def parameters(self) -> dict[str, inspect.Parameter]:
+        return {**self.signature.parameters}
+
+    def instantiate(self, /, *args: Any, **kwargs: Any) -> T:
+        return self._inner_type(*args, **kwargs)
+
+    def get_method(self, method_name: str) -> "FWrap[..., Any]":
+        if not hasattr(self._inner_type, method_name):
+            raise AttributeError(f"Method '{method_name}' not found")
+        method_func = getattr(self._inner_type, method_name)
+        return peritype.wrap_func(method_func)
+
+    def match(self, other: "TWrap[Any]") -> bool:
+        for other_node in other.nodes:
+            if self._nodes_intersect(other_node):
+                return True
+        return False
+
+    def _nodes_intersect(self, b: "TypeNode[Any]") -> bool:
+        if self._origin is Any or b._origin is Any:
+            return True
+        if self._origin is Ellipsis or b._origin is Ellipsis:
+            return True
+
+        if self._inner_type is not b._inner_type:
+            return False
+
+        if not self._generic_params and not b._generic_params:
+            return True
+
+        if len(self._generic_params) != len(b._generic_params):
+            return False
+
+        for i in range(len(self._generic_params)):
+            if not self._generic_params[i].match(b._generic_params[i]):
+                return False
+        return True
+
+
+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 __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.inner_type is not NoneType]) > 1
+
+    @cached_property
+    def nullable(self) -> bool:
+        return any(n.inner_type 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")
+        return self._nodes[0].attribute_hints
+
+    @cached_property
+    def init(self) -> "BoundFWrap[..., Any]":
+        if self.union:
+            raise TypeError("Cannot get __init__ of union types")
+        return self._nodes[0].init.bind(self)
+
+    @cached_property
+    def signature(self) -> inspect.Signature:
+        if self.union:
+            raise TypeError("Cannot get signature of union types")
+        return inspect.signature(self._nodes[0].inner_type)
+
+    @cached_property
+    def parameters(self) -> dict[str, inspect.Parameter]:
+        return {**self.signature.parameters}
+
+    @cached_property
+    def inner_type(self) -> Any:
+        if self.union:
+            raise TypeError("Cannot get inner type of union types")
+        return self._nodes[0].inner_type
+
+    @cached_property
+    def generic_params(self) -> "tuple[TWrap[Any], ...]":
+        if self.union:
+            raise TypeError("Cannot get generic params of union types")
+        return self._nodes[0].generic_params
+
+    def instantiate(self, /, *args: Any, **kwargs: Any) -> T:
+        if self.union:
+            raise TypeError("Cannot instantiate union types")
+        return self._nodes[0].instantiate(*args, **kwargs)
+
+    def get_method(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]
+        return self._nodes[0].get_method(method_name).bind(self)
+
+    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:
+            if a.match(other_wrap):
+                return True
+        return False

peritype-0.4.0/peritype/utils.py

@@ -0,0 +1,163 @@
+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 UnresolvedForwardRefError, UnresolvedTypeVarError
+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],
+    *,
+    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
+            match arg:
+                case TypeVar() if raise_on_typevar:
+                    raise UnresolvedTypeVarError(arg.__name__, cls=origin)
+                case ForwardRef() if raise_on_forward:
+                    raise UnresolvedForwardRefError(arg.__forward_arg__, cls=origin)
+                case list():
+                    arg = (*arg,)
+                case _:
+                    pass
+            type_vars.append(arg)
+        return origin, (*type_vars,)
+    return _cls, ()
+
+
+def specialize_type(
+    cls: Any,
+    lookup: TypeVarMapping,
+    *,
+    raise_on_forward: bool = True,
+    raise_on_typevar: bool = True,
+) -> Any:
+    origin = get_origin(cls)
+    if origin is None:
+        return cls
+    args = get_args(cls)
+    if not args:
+        return cls
+    new_args: list[Any] = []
+    specialized = False
+    for arg in args:
+        match arg:
+            case TypeVar() if arg in lookup:
+                new_args.append(lookup[arg])
+                specialized = True
+            case TypeVar() if raise_on_typevar:
+                raise UnresolvedTypeVarError(arg.__name__, cls=origin)
+            case ForwardRef() if raise_on_forward:
+                raise UnresolvedForwardRefError(arg.__forward_arg__, cls=origin)
+            case _:
+                new_args.append(arg)
+    vars = tuple(new_args)
+    if not specialized:
+        return cls
+    return origin[vars]
+
+
+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.4.0/peritype/wrap.py

@@ -0,0 +1,68 @@
+import weakref
+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,
+    specialize_type,
+    unpack_annotations,
+    unpack_union,
+)
+
+USE_CACHE = True
+_TWRAP_CACHE: weakref.WeakValueDictionary[Any, TWrap[Any]] = weakref.WeakValueDictionary()
+_FWRAP_CACHE: weakref.WeakValueDictionary[Any, FWrap[..., Any]] = weakref.WeakValueDictionary()
+
+
+@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 lookup is not None:
+        cls = specialize_type(cls, lookup, raise_on_forward=True, raise_on_typevar=True)
+    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, raise_on_forward=True, raise_on_typevar=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

peritype-0.4.0/pyproject.toml

@@ -0,0 +1,29 @@
+[project]
+name = "peritype"
+version = "0.4.0"
+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.9.23,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+package = "peritype"
+module-root = ""
+
+[dependency-groups]
+dev = ["ruff>=0.14.11"]
+test = ["pytest>=9.0.2", "pytest-cov>=7.0.0"]
+
+[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"]