typingkit 0.2.3__tar.gz → 0.2.4__tar.gz

{typingkit-0.2.3 → typingkit-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: typingkit
-Version: 0.2.3
+Version: 0.2.4
 Summary: Python strong typing suite, along with Typed NumPy: Static shape typing and runtime shape validation.
 Author: Ashrith Sagar
 Author-email: Ashrith Sagar <ashrith9sagar@gmail.com>

{typingkit-0.2.3 → typingkit-0.2.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "typingkit"
-version = "0.2.3"
+version = "0.2.4"
 description = "Python strong typing suite, along with Typed NumPy: Static shape typing and runtime shape validation."
 readme = "README.md"
 authors = [{ name = "Ashrith Sagar", email = "ashrith9sagar@gmail.com" }]

typingkit-0.2.4/src/typingkit/__init__.py

@@ -0,0 +1,5 @@
+"""
+TypingKit
+=======
+"""
+# src/typingkit/__init__.py

typingkit-0.2.4/src/typingkit/core/__init__.py

@@ -0,0 +1,17 @@
+"""
+TypingKit core
+=======
+"""
+# src/typingkit/core/__init__.py
+
+from typingkit.core.dict import TypedDict, TypedDictConfig
+from typingkit.core.generics import RuntimeGeneric
+from typingkit.core.list import TypedList, TypedListConfig
+
+__all__ = [
+    "RuntimeGeneric",
+    "TypedList",
+    "TypedListConfig",
+    "TypedDict",
+    "TypedDictConfig",
+]

{typingkit-0.2.3/src/typingkit/_typed → typingkit-0.2.4/src/typingkit/core}/_debug.py

@@ -2,7 +2,7 @@
 Debugging utilities
 =======
 """
-# src/typingkit/_typed/debug.py
+# src/typingkit/core/_debug.py
 
 from typing import Any, TypeVar, get_args, get_origin
 

typingkit-0.2.4/src/typingkit/core/dict.py

@@ -0,0 +1,152 @@
+"""
+TypedDict
+=======
+"""
+# src/typingkit/core/dict.py
+
+from collections.abc import Mapping
+from types import GenericAlias, NoneType, UnionType
+from typing import Any, Literal, Self, TypeVar, cast, get_args, get_origin
+
+from typingkit.core.generics import RuntimeGeneric, get_runtime_args
+
+## Typings
+
+Length = TypeVar("Length", bound=int, default=int)
+Key = TypeVar("Key", default=Any)
+Value = TypeVar("Value", default=Any)
+
+
+## Exceptions
+
+
+class LengthError(Exception):
+    """Raised when dict length doesn't match expected length."""
+
+
+## Runtime validation
+
+
+class TypedDictConfig:
+    VALIDATE_LENGTH: bool = True
+
+    @classmethod
+    def enable_all(cls):
+        cls.VALIDATE_LENGTH = True
+
+    @classmethod
+    def disable_all(cls):
+        cls.VALIDATE_LENGTH = False
+
+
+def _resolve_length(length: Any) -> Any:
+    # ~TypeVar
+    if isinstance(length, TypeVar):
+        # [TODO]: How should typing.NoDefault be handled?
+        length = _resolve_length(length.__default__)
+
+    origin = get_origin(length)
+
+    # Literal[A, B, ...]
+    if origin is Literal:
+        length = set(get_args(length))
+
+    # Union[A, B, ...]
+    if origin is UnionType:
+        resolved = (_resolve_length(arg) for arg in get_args(length))
+        result = set[Any]()
+        for r in resolved:
+            if isinstance(r, set):
+                result |= r
+            else:
+                result.add(r)
+        return result
+
+    return length
+
+
+def _validate_length(object: Mapping[Key, Value], length: Any) -> None:
+    if not TypedDictConfig.VALIDATE_LENGTH:
+        return None
+
+    length = _resolve_length(length)
+
+    # type[Any]
+    if length is Any:
+        return None
+
+    # type[int]; Including <subclass of int>
+    if isinstance(length, type) and issubclass(length, int):
+        return None
+
+    # Should already be disallowed statically, here we just raise a runtime error
+    if length is NoneType:
+        raise LengthError("Invalid length")
+    # [TODO]: Others
+
+    # [NOTE]: From a statical perspective, being strict,
+    # prefer Literal[~int] over ~int, although we allow it here, for now.
+
+    actual = len(object)
+    if isinstance(length, set):
+        if len(length) > 1:  # pyright: ignore[reportUnknownArgumentType]
+            for arg in length:  # pyright: ignore[reportUnknownVariableType]
+                if isinstance(arg, int):
+                    if arg == actual:
+                        break
+
+                ## [TODO]: Similar to the outer validation, so prolly can refactor through a recursive function call
+                # type[Any]
+                if arg is Any:
+                    break
+
+                # type[int]; Including <subclass of int>
+                if isinstance(arg, type) and issubclass(arg, int):
+                    break
+            else:
+                raise LengthError(
+                    f"Length mismatch: expected one of {length}, got {actual}"
+                )
+        elif len(length) == 1:  # pyright: ignore[reportUnknownArgumentType]
+            # Defer to the single case below
+            length = length.pop()  # pyright: ignore[reportUnknownVariableType]
+        else:  # len(length) == 0
+            # This case should prolly never arise? Strictly speaking, statically.
+            return None
+    # (Concrete) int
+    if isinstance(length, int):
+        # This case is just for a minimal error message, we could already handle
+        # it in the `set` case above, provided `_resolve_length` resolves it accordingly.
+        if actual != length:
+            raise LengthError(f"Length mismatch: expected {length}, got {actual}")
+
+    return None  # Fallback
+
+
+## TypedDict
+class TypedDict(RuntimeGeneric[Length, Key, Value], dict[Key, Value]):
+    @classmethod
+    def __pre_new__(cls, alias: GenericAlias, *args: Any, **kwargs: Any) -> Self:
+        # Create `dict` object
+        obj = super().__pre_new__(alias, *args, **kwargs)
+
+        ## Runtime validations
+        typeargs = get_runtime_args(alias, cls)
+        if len(typeargs) == 3:
+            (length, _, _) = typeargs
+        elif len(typeargs) == 2:
+            (length, _) = typeargs
+        elif len(typeargs) == 1:
+            (length,) = typeargs
+        else:
+            raise TypeError
+        _validate_length(obj, length)
+
+        return obj
+
+    def __len__(self) -> Length:
+        return cast(Length, super().__len__())
+
+    @property
+    def length(self) -> Length:
+        return self.__len__()

typingkit-0.2.4/src/typingkit/core/generics.py

@@ -0,0 +1,180 @@
+"""
+Generics
+=======
+"""
+# src/typingkit/core/generics.py
+
+from types import GenericAlias, get_original_bases
+from typing import (
+    Any,
+    Generic,
+    Self,
+    TypeVar,
+    TypeVarTuple,
+    Unpack,
+    cast,
+    get_args,
+    get_origin,
+)
+
+Ts = TypeVarTuple("Ts")
+
+
+class RuntimeGeneric(Generic[Unpack[Ts]]):
+    @classmethod
+    def __class_getitem__(cls, item: Any, /) -> GenericAlias:
+        # [HACK] Misuses __class_getitem__
+        # See https://docs.python.org/3/reference/datamodel.html#the-purpose-of-class-getitem
+
+        try:
+            ga = cast(GenericAlias, super().__class_getitem__(item))  # type: ignore[misc]
+        except:  # noqa: E722
+            # Fallback if superclass does not implement `__class_getitem__`
+            ga = GenericAlias(cls, item)
+        return _RuntimeGenericAlias.from_generic_alias(ga)
+
+    @classmethod
+    def __pre_new__(cls, alias: GenericAlias, *args: Any, **kwargs: Any) -> Self:
+        return cls(*args, **kwargs)
+
+
+class _RuntimeGenericAlias(GenericAlias):
+    """
+    Deferred RuntimeGeneric constructor.
+    Enables progressive type specialisation, behaving like a type-level curry.
+    """
+
+    @classmethod
+    def from_generic_alias(cls, alias: GenericAlias) -> Self:
+        origin = get_origin(alias)
+        typeargs = get_args(alias)
+        return cls(origin, typeargs)
+
+    def __getitem__(self, typeargs: Any) -> Self:
+        ga = super().__getitem__(typeargs)
+        return type(self).from_generic_alias(ga)
+
+    def __call__(self, *args: Any, **kwargs: Any) -> Any:
+        origin: type[RuntimeGeneric[Unpack[Ts]]] = get_origin(self)  # type: ignore[valid-type]
+        obj = origin.__pre_new__(self, *args, **kwargs)
+        return obj
+
+
+## Generics resolution
+
+
+def _substitute(tp: Any, mapping: dict[Any, Any]) -> Any:
+    if isinstance(tp, TypeVar):
+        return mapping.get(tp, tp)
+
+    if isinstance(tp, TypeVarTuple):
+        return mapping.get(tp, tp)
+
+    origin = get_origin(tp)
+    if origin is None:
+        return tp
+
+    args = get_args(tp)
+
+    if origin is Unpack:
+        (inner,) = args
+        value = _substitute(inner, mapping)
+
+        # If the inner resolved to a tuple (TypeVarTuple binding),
+        # return the tuple directly so the parent can expand it.
+        if isinstance(value, tuple):
+            return value  # pyright: ignore[reportUnknownVariableType]
+
+        return Unpack[value]
+
+    new_args_list = list[Any]()
+    for arg in args:
+        val = _substitute(arg, mapping)
+        if isinstance(val, tuple):
+            new_args_list.extend(val)  # pyright: ignore[reportUnknownArgumentType]
+        else:
+            new_args_list.append(val)
+    new_args = tuple(new_args_list)
+
+    try:
+        return origin[new_args]
+    except TypeError:
+        return tp
+
+
+def _build_mapping(params: tuple[Any, ...], args: tuple[Any, ...]) -> dict[Any, Any]:
+    mapping = dict[Any, Any]()
+    i: int = 0
+    j: int = 0
+
+    while i < len(params):
+        p = params[i]
+
+        if isinstance(p, TypeVarTuple):
+            # Handle tuple unpacking
+            remaining_params = len(params) - i - 1
+            remaining_args = len(args) - j
+            size = remaining_args - remaining_params
+            if size < 0:
+                raise TypeError(
+                    f"Not enough type arguments to bind TypeVarTuple {p}. "
+                    f"Expected at least {len(params)} but got {len(args)}"
+                )
+            mapping[p] = args[j : j + size]
+            j += size
+            i += 1
+            continue
+
+        if j >= len(args):
+            # No argument supplied, try default
+            default = getattr(p, "__default__", None)
+            if default is not None:
+                mapping[p] = default
+            else:
+                raise TypeError(
+                    f"Missing type argument for {p}. Expected {len(params)} args, got {len(args)}"
+                )
+        else:
+            mapping[p] = args[j]
+            j += 1
+
+        i += 1
+
+    if j < len(args):
+        # Extra arguments leftover
+        raise TypeError(
+            f"Too many type arguments. Expected {len(params)}, got {len(args)}"
+        )
+
+    return mapping
+
+
+def get_runtime_args(tp: Any, cls: type) -> tuple[Any, ...]:
+    args = get_args(tp)
+
+    parameters: tuple[Any, ...] = getattr(cls, "__parameters__", ())
+    mapping = _build_mapping(parameters, args)
+
+    current_cls = cls
+    while True:
+        orig_bases = get_original_bases(current_cls)
+        for base in orig_bases:
+            origin = get_origin(base)
+            if origin is None:
+                continue
+
+            resolved = _substitute(base, mapping)
+
+            if get_origin(resolved) is RuntimeGeneric:
+                return get_args(resolved)
+
+            parent_params = getattr(origin, "__parameters__", ())
+            parent_args = get_args(resolved)
+
+            mapping = _build_mapping(parent_params, parent_args)
+            current_cls = origin
+            break
+        else:
+            break
+
+    return args

{typingkit-0.2.3/src/typingkit/_typed → typingkit-0.2.4/src/typingkit/core}/list.py

@@ -2,7 +2,7 @@
 TypedList
 =======
 """
-# src/typingkit/_typed/list.py
+# src/typingkit/core/list.py
 
 import copy
 import numbers
@@ -10,7 +10,7 @@ from collections.abc import Iterable, Sequence
 from types import GenericAlias, NoneType, UnionType
 from typing import Any, Callable, Literal, Self, TypeVar, cast, get_args, get_origin
 
-from typingkit._typed.generics import RuntimeGeneric
+from typingkit.core.generics import RuntimeGeneric, get_runtime_args
 
 ## Typings
 
@@ -168,7 +168,7 @@ class TypedList(RuntimeGeneric[Length, Item], list[Item]):
         obj = super().__pre_new__(alias, *args, **kwargs)
 
         ## Runtime validations
-        typeargs = get_args(alias)
+        typeargs = get_runtime_args(alias, cls)
         if len(typeargs) == 2:
             length, item_type = typeargs
         elif len(typeargs) == 1:
@@ -193,11 +193,7 @@ class TypedList(RuntimeGeneric[Length, Item], list[Item]):
         return self.__len__()
 
     @classmethod
-    def full(
-        cls: "type[TypedList[Length, Item]]",
-        length: Length,
-        fill_value: Item | Callable[[int], Item],
-    ) -> "TypedList[Length, Item]":
+    def full(cls, length: Length, fill_value: Item | Callable[[int], Item]) -> Self:
         data: list[Item]
         if callable(fill_value):
             data = [cast(Item, fill_value(i)) for i in range(length)]

typingkit-0.2.4/src/typingkit/numpy/__init__.py

@@ -0,0 +1,15 @@
+"""
+Typed NumPy
+=======
+"""
+# src/typingkit/numpy/__init__.py
+
+import numpy
+
+from typingkit.numpy._typed import TypedNDArray, enforce_shapes
+
+__all__ = [
+    "numpy",
+    "TypedNDArray",
+    "enforce_shapes",
+]

typingkit-0.2.4/src/typingkit/numpy/_typed/__init__.py

@@ -0,0 +1,13 @@
+"""
+Typed NumPy core
+=======
+"""
+# src/typingkit/numpy/_typed/__init__.py
+
+from typingkit.numpy._typed.context import enforce_shapes
+from typingkit.numpy._typed.ndarray import TypedNDArray
+
+__all__ = [
+    "TypedNDArray",
+    "enforce_shapes",
+]

{typingkit-0.2.3/src/typingkit → typingkit-0.2.4/src/typingkit/numpy}/_typed/context.py

@@ -3,7 +3,7 @@ Context binding
 =======
 Manages TypeVar binding contexts for shape validation.
 """
-# src/typingkit/_typed/context.py
+# src/typingkit/numpy/_typed/context.py
 
 # pyright: reportPrivateUsage = false
 
@@ -21,7 +21,7 @@ from typing import (
     get_type_hints,
 )
 
-from typingkit._typed.ndarray import (
+from typingkit.numpy._typed.ndarray import (
     DimensionError,
     _validate_shape,
     _validate_shape_against_contexts,

{typingkit-0.2.3/src/typingkit → typingkit-0.2.4/src/typingkit/numpy}/_typed/dimexpr.py

@@ -2,7 +2,7 @@
 DimExpr
 =======
 """
-# src/typingkit/_typed/dimexpr.py
+# src/typingkit/numpy/_typed/dimexpr.py
 
 import math
 from typing import (

{typingkit-0.2.3/src/typingkit → typingkit-0.2.4/src/typingkit/numpy}/_typed/factory.py

@@ -2,7 +2,7 @@
 Shape factory for TypedNDArray
 =======
 """
-# src/typingkit/_typed/factory.py
+# src/typingkit/numpy/_typed/factory.py
 
 # pyright: reportPrivateUsage = false
 
@@ -12,7 +12,7 @@ from typing import Any, Generic, TypeVar
 import numpy as np
 import numpy.typing as npt
 
-from typingkit._typed.ndarray import TypedNDArray, _AnyShape
+from typingkit.numpy._typed.ndarray import TypedNDArray, _AnyShape
 
 _ShapeT = TypeVar("_ShapeT", bound=_AnyShape)
 _ScalarT = TypeVar("_ScalarT", bound=np.generic)

{typingkit-0.2.3/src/typingkit → typingkit-0.2.4/src/typingkit/numpy}/_typed/helpers.py

@@ -2,13 +2,13 @@
 Helpers for TypedNDArray
 =======
 """
-# src/typingkit/_typed/helpers.py
+# src/typingkit/numpy/_typed/helpers.py
 
 from typing import Literal, TypeAlias, TypeVar
 
 import numpy as np
 
-from typingkit._typed.ndarray import TypedNDArray
+from typingkit.numpy._typed.ndarray import TypedNDArray
 
 ## Helpers
 

{typingkit-0.2.3/src/typingkit → typingkit-0.2.4/src/typingkit/numpy}/_typed/ndarray.py

@@ -2,7 +2,7 @@
 NDArray
 =======
 """
-# src/typingkit/_typed/ndarray.py
+# src/typingkit/numpy/_typed/ndarray.py
 
 # pyright: reportPrivateUsage = false
 
@@ -134,7 +134,7 @@ def _validate_dtype(
 
 
 def _resolve_shape(args: _AnyShape) -> _AnyShape:
-    from typingkit._typed.dimexpr import _resolve_dim
+    from typingkit.numpy._typed.dimexpr import _resolve_dim
 
     # [TODO]: Handle TypeAliasType
     return tuple(_resolve_dim(arg) for arg in args)
@@ -199,7 +199,7 @@ def _validate_shape(expected: _AnyShape, actual: _Shape) -> None:
 
 def _validate_shape_against_contexts(shape_spec: _AnyShape, actual: _Shape) -> None:
     """Validate shape against active TypeVar contexts (class-level and method-level)."""
-    from typingkit._typed.context import (
+    from typingkit.numpy._typed.context import (
         _active_class_context,
         _method_typevar_context,
     )

typingkit-0.2.3/src/typingkit/__init__.py

@@ -1,11 +0,0 @@
-"""
-Typed NumPy
-=======
-"""
-# src/typingkit/__init__.py
-
-import numpy
-
-__all__ = [
-    "numpy",
-]

typingkit-0.2.3/src/typingkit/_typed/__init__.py

@@ -1,11 +0,0 @@
-"""
-Typed NumPy core
-=======
-"""
-# src/typingkit/_typed/__init__.py
-
-from typingkit._typed.ndarray import TypedNDArray
-
-__all__ = [
-    "TypedNDArray",
-]

typingkit-0.2.3/src/typingkit/_typed/generics.py

@@ -1,50 +0,0 @@
-"""
-Generics
-=======
-"""
-# src/typingkit/_typed/generics.py
-
-from types import GenericAlias
-from typing import Any, Generic, Self, TypeVarTuple, Unpack, cast, get_args, get_origin
-
-Ts = TypeVarTuple("Ts", default=Unpack[tuple[Any, ...]])
-
-
-class RuntimeGeneric(Generic[Unpack[Ts]]):
-    @classmethod
-    def __class_getitem__(cls, item: Any, /) -> GenericAlias:
-        # [HACK] Misuses __class_getitem__
-        # See https://docs.python.org/3/reference/datamodel.html#the-purpose-of-class-getitem
-
-        try:
-            ga = cast(GenericAlias, super().__class_getitem__(item))  # type: ignore[misc]
-        except:  # noqa: E722
-            # Fallback if superclass does not implement `__class_getitem__`
-            ga = GenericAlias(cls, item)
-        return _RuntimeGenericAlias.from_generic_alias(ga)
-
-    @classmethod
-    def __pre_new__(cls, alias: GenericAlias, *args: Any, **kwargs: Any) -> Self:
-        return cls(*args, **kwargs)
-
-
-class _RuntimeGenericAlias(GenericAlias):
-    """
-    Deferred RuntimeGeneric constructor.
-    Enables progressive type specialisation, behaving like a type-level curry.
-    """
-
-    @classmethod
-    def from_generic_alias(cls, alias: GenericAlias) -> Self:
-        origin = get_origin(alias)
-        typeargs = get_args(alias)
-        return cls(origin, typeargs)
-
-    def __getitem__(self, typeargs: Any) -> Self:
-        ga = super().__getitem__(typeargs)
-        return type(self).from_generic_alias(ga)
-
-    def __call__(self, *args: Any, **kwargs: Any) -> Any:
-        origin: type[RuntimeGeneric] = get_origin(self)
-        obj = origin.__pre_new__(self, *args, **kwargs)
-        return obj