typingkit 0.2.2__py3-none-any.whl

typingkit/_typed/helpers.py

@@ -0,0 +1,248 @@
+"""
+Helpers for TypedNDArray
+=======
+"""
+# src/typingkit/_typed/helpers.py
+
+from typing import Literal, TypeAlias, TypeVar
+
+import numpy as np
+
+from typingkit._typed.ndarray import TypedNDArray
+
+## Helpers
+
+# Literal type aliases for small integers
+ZERO: TypeAlias = Literal[0]
+"""Literal type for the integer `0`."""
+ONE: TypeAlias = Literal[1]
+"""Literal type for the integer `1`."""
+TWO: TypeAlias = Literal[2]
+"""Literal type for the integer `2`."""
+THREE: TypeAlias = Literal[3]
+"""Literal type for the integer `3`."""
+FOUR: TypeAlias = Literal[4]
+"""Literal type for the integer `4`."""
+FIVE: TypeAlias = Literal[5]
+"""Literal type for the integer `5`."""
+SIX: TypeAlias = Literal[6]
+"""Literal type for the integer `6`."""
+SEVEN: TypeAlias = Literal[7]
+"""Literal type for the integer `7`."""
+EIGHT: TypeAlias = Literal[8]
+"""Literal type for the integer `8`."""
+NINE: TypeAlias = Literal[9]
+"""Literal type for the integer `9`."""
+TEN: TypeAlias = Literal[10]
+"""Literal type for the integer `10`."""
+
+# TypeVars
+Dim1 = TypeVar("Dim1", bound=int, default=int)
+Dim2 = TypeVar("Dim2", bound=int, default=int)
+Dim3 = TypeVar("Dim3", bound=int, default=int)
+Dim4 = TypeVar("Dim4", bound=int, default=int)
+K = TypeVar("K", bound=int, default=int)
+L = TypeVar("L", bound=int, default=int)
+M = TypeVar("M", bound=int, default=int)
+N = TypeVar("N", bound=int, default=int)
+
+# Shape type aliases
+Shape0D: TypeAlias = tuple[()]
+"""A tuple representing a 0D shape, i.e., `()`."""
+Shape1D: TypeAlias = tuple[Dim1]
+"""A tuple representing a 1D shape, i.e., `(N,)`."""
+Shape2D: TypeAlias = tuple[Dim1, Dim2]
+"""A tuple representing a 2D shape, i.e., `(M, N)`."""
+Shape3D: TypeAlias = tuple[Dim1, Dim2, Dim3]
+"""A tuple representing a 3D shape, i.e., shape `(L, M, N)`."""
+Shape4D: TypeAlias = tuple[Dim1, Dim2, Dim3, Dim4]
+"""A tuple representing a 4D shape, i.e., shape `(K, L, M, N)`."""
+ShapeND: TypeAlias = tuple[int, ...]
+"""A tuple representing a ND shape, i.e., shape `(N, ...)`."""
+
+# DType aliases
+DType = TypeVar("DType", bound=np.dtype, default=np.dtype, covariant=True)
+
+
+## Array type aliases
+
+# Arrays based on dimensionality
+Array0D: TypeAlias = TypedNDArray[Shape0D, DType]
+"""A `numpy.ndarray` of shape `()` and dtype `DType`."""
+Array1D: TypeAlias = TypedNDArray[Shape1D[Dim1], DType]
+"""A `numpy.ndarray` of shape `(N,)` and dtype `DType`."""
+Array2D: TypeAlias = TypedNDArray[Shape2D[Dim1, Dim2], DType]
+"""A `numpy.ndarray` of shape `(M, N)` and dtype `DType`."""
+Array3D: TypeAlias = TypedNDArray[Shape3D[Dim1, Dim2, Dim3], DType]
+"""A `numpy.ndarray` of shape `(L, M, N)` and dtype `DType`."""
+Array4D: TypeAlias = TypedNDArray[Shape4D[Dim1, Dim2, Dim3, Dim4], DType]
+"""A `numpy.ndarray` of shape `(K, L, M, N)` and dtype `DType`."""
+ArrayND: TypeAlias = TypedNDArray[ShapeND, DType]
+"""A `numpy.ndarray` of shape `(N, ...)` and dtype `DType`."""
+
+# 1D Arrays with specific small sizes
+Array2: TypeAlias = TypedNDArray[tuple[TWO], DType]
+"""A `numpy.ndarray` of shape `(2,)` and dtype `DType`."""
+Array3: TypeAlias = TypedNDArray[tuple[THREE], DType]
+"""A `numpy.ndarray` of shape `(3,)` and dtype `DType`."""
+Array4: TypeAlias = TypedNDArray[tuple[FOUR], DType]
+"""A `numpy.ndarray` of shape `(4,)` and dtype `DType`."""
+ArrayN: TypeAlias = TypedNDArray[tuple[N], DType]  # Same as Array1D
+"""A `numpy.ndarray` of shape `(N,)` and dtype `DType`."""
+
+# 2D Arrays with specific small sizes
+Array2x2: TypeAlias = TypedNDArray[tuple[TWO, TWO], DType]
+"""A `numpy.ndarray` of shape `(2, 2)` and dtype `DType`."""
+Array2x3: TypeAlias = TypedNDArray[tuple[TWO, THREE], DType]
+"""A `numpy.ndarray` of shape `(2, 3)` and dtype `DType`."""
+Array2x4: TypeAlias = TypedNDArray[tuple[TWO, FOUR], DType]
+"""A `numpy.ndarray` of shape `(2, 4)` and dtype `DType`."""
+Array2xN: TypeAlias = TypedNDArray[tuple[TWO, N], DType]
+"""A `numpy.ndarray` of shape `(2, N)` and dtype `DType`."""
+
+Array3x2: TypeAlias = TypedNDArray[tuple[THREE, TWO], DType]
+"""A `numpy.ndarray` of shape `(3, 2)` and dtype `DType`."""
+Array3x3: TypeAlias = TypedNDArray[tuple[THREE, THREE], DType]
+"""A `numpy.ndarray` of shape `(3, 3)` and dtype `DType`."""
+Array3x4: TypeAlias = TypedNDArray[tuple[THREE, FOUR], DType]
+"""A `numpy.ndarray` of shape `(3, 4)` with the default `dtype."""
+Array3xN: TypeAlias = TypedNDArray[tuple[THREE, N], DType]
+"""A `numpy.ndarray` of shape `(3, N)` and dtype `DType`."""
+
+Array4x2: TypeAlias = TypedNDArray[tuple[FOUR, TWO], DType]
+"""A `numpy.ndarray` of shape `(4, 2)` and dtype `DType`."""
+Array4x3: TypeAlias = TypedNDArray[tuple[FOUR, THREE], DType]
+"""A `numpy.ndarray` of shape `(4, 3)` and dtype `DType`."""
+Array4x4: TypeAlias = TypedNDArray[tuple[FOUR, FOUR], DType]
+"""A `numpy.ndarray` of shape `(4, 4)` with the default `dtype."""
+Array4xN: TypeAlias = TypedNDArray[tuple[FOUR, N], DType]
+"""A `numpy.ndarray` of shape `(4, N)` and dtype `DType`."""
+
+ArrayNx2: TypeAlias = TypedNDArray[tuple[N, TWO], DType]
+"""A `numpy.ndarray` of shape `(N, 2)` and dtype `DType`."""
+ArrayNx3: TypeAlias = TypedNDArray[tuple[N, THREE], DType]
+"""A `numpy.ndarray` of shape `(N, 3)` and dtype `DType`."""
+ArrayNx4: TypeAlias = TypedNDArray[tuple[N, FOUR], DType]
+"""A `numpy.ndarray` of shape `(N, 4)` and dtype `DType`."""
+
+# 3D Arrays with specific small sizes
+Array2x2x2: TypeAlias = TypedNDArray[tuple[TWO, TWO, TWO], DType]
+"""A `numpy.ndarray` of shape `(2, 2, 2)` and dtype `DType`."""
+Array2x2x3: TypeAlias = TypedNDArray[tuple[TWO, TWO, THREE], DType]
+"""A `numpy.ndarray` of shape `(2, 2, 3)` and dtype `DType`."""
+Array2x2x4: TypeAlias = TypedNDArray[tuple[TWO, TWO, FOUR], DType]
+"""A `numpy.ndarray` of shape `(2, 2, 4)` and dtype `DType`."""
+Array2x2xN: TypeAlias = TypedNDArray[tuple[TWO, TWO, N], DType]
+"""A `numpy.ndarray` of shape `(2, 2, N)` and dtype `DType`."""
+
+Array2x3x2: TypeAlias = TypedNDArray[tuple[TWO, THREE, TWO], DType]
+"""A `numpy.ndarray` of shape `(2, 3, 2)` and dtype `DType`."""
+Array2x3x3: TypeAlias = TypedNDArray[tuple[TWO, THREE, THREE], DType]
+"""A `numpy.ndarray` of shape `(2, 3, 3)` and dtype `DType`."""
+Array2x3x4: TypeAlias = TypedNDArray[tuple[TWO, THREE, FOUR], DType]
+"""A `numpy.ndarray` of shape `(2, 3, 4)` and dtype `DType`."""
+Array2x3xN: TypeAlias = TypedNDArray[tuple[TWO, THREE, N], DType]
+"""A `numpy.ndarray` of shape `(2, 3, N)` and dtype `DType`."""
+
+Array2x4x2: TypeAlias = TypedNDArray[tuple[TWO, FOUR, TWO], DType]
+"""A `numpy.ndarray` of shape `(2, 4, 2)` and dtype `DType`."""
+Array2x4x3: TypeAlias = TypedNDArray[tuple[TWO, FOUR, THREE], DType]
+"""A `numpy.ndarray` of shape `(2, 4, 3)` and dtype `DType`."""
+Array2x4x4: TypeAlias = TypedNDArray[tuple[TWO, FOUR, FOUR], DType]
+"""A `numpy.ndarray` of shape `(2, 4, 4)` and dtype `DType`."""
+Array2x4xN: TypeAlias = TypedNDArray[tuple[TWO, FOUR, N], DType]
+"""A `numpy.ndarray` of shape `(2, 4, N)` and dtype `DType`."""
+
+Array2xNx2: TypeAlias = TypedNDArray[tuple[TWO, N, TWO], DType]
+"""A `numpy.ndarray` of shape `(2, N, 2)` and dtype `DType`."""
+Array2xNx3: TypeAlias = TypedNDArray[tuple[TWO, N, THREE], DType]
+"""A `numpy.ndarray` of shape `(2, N, 3)` and dtype `DType`."""
+Array2xNx4: TypeAlias = TypedNDArray[tuple[TWO, N, FOUR], DType]
+"""A `numpy.ndarray` of shape `(2, N, 4)` and dtype `DType`."""
+
+Array3x2x2: TypeAlias = TypedNDArray[tuple[THREE, TWO, TWO], DType]
+"""A `numpy.ndarray` of shape `(3, 2, 2)` and dtype `DType`."""
+Array3x2x3: TypeAlias = TypedNDArray[tuple[THREE, TWO, THREE], DType]
+"""A `numpy.ndarray` of shape `(3, 2, 3)` and dtype `DType`."""
+Array3x2x4: TypeAlias = TypedNDArray[tuple[THREE, TWO, FOUR], DType]
+"""A `numpy.ndarray` of shape `(3, 2, 4)` and dtype `DType`."""
+Array3x2xN: TypeAlias = TypedNDArray[tuple[THREE, TWO, N], DType]
+"""A `numpy.ndarray` of shape `(3, 2, N)` and dtype `DType`."""
+
+Array3x3x2: TypeAlias = TypedNDArray[tuple[THREE, THREE, TWO], DType]
+"""A `numpy.ndarray` of shape `(3, 3, 2)` and dtype `DType`."""
+Array3x3x3: TypeAlias = TypedNDArray[tuple[THREE, THREE, THREE], DType]
+"""A `numpy.ndarray` of shape `(3, 3, 3)` and dtype `DType`."""
+Array3x3x4: TypeAlias = TypedNDArray[tuple[THREE, THREE, FOUR], DType]
+"""A `numpy.ndarray` of shape `(3, 3, 4)` and dtype `DType`."""
+Array3x3xN: TypeAlias = TypedNDArray[tuple[THREE, THREE, N], DType]
+"""A `numpy.ndarray` of shape `(3, 3, N)` and dtype `DType`."""
+
+Array3x4x2: TypeAlias = TypedNDArray[tuple[THREE, FOUR, TWO], DType]
+"""A `numpy.ndarray` of shape `(3, 4, 2)` and dtype `DType`."""
+Array3x4x3: TypeAlias = TypedNDArray[tuple[THREE, FOUR, THREE], DType]
+"""A `numpy.ndarray` of shape `(3, 4, 3)` and dtype `DType`."""
+Array3x4x4: TypeAlias = TypedNDArray[tuple[THREE, FOUR, FOUR], DType]
+"""A `numpy.ndarray` of shape `(3, 4, 4)` and dtype `DType`."""
+Array3x4xN: TypeAlias = TypedNDArray[tuple[THREE, FOUR, N], DType]
+"""A `numpy.ndarray` of shape `(3, 4, N)` and dtype `DType`."""
+
+Array3xNx2: TypeAlias = TypedNDArray[tuple[THREE, N, TWO], DType]
+"""A `numpy.ndarray` of shape `(3, N, 2)` and dtype `DType`."""
+Array3xNx3: TypeAlias = TypedNDArray[tuple[THREE, N, THREE], DType]
+"""A `numpy.ndarray` of shape `(3, N, 3)` and dtype `DType`."""
+Array3xNx4: TypeAlias = TypedNDArray[tuple[THREE, N, FOUR], DType]
+"""A `numpy.ndarray` of shape `(3, N, 4)` and dtype `DType`."""
+
+Array4x2x2: TypeAlias = TypedNDArray[tuple[FOUR, TWO, TWO], DType]
+"""A `numpy.ndarray` of shape `(4, 2, 2)` and dtype `DType`."""
+Array4x2x3: TypeAlias = TypedNDArray[tuple[FOUR, TWO, THREE], DType]
+"""A `numpy.ndarray` of shape `(4, 2, 3)` and dtype `DType`."""
+Array4x2x4: TypeAlias = TypedNDArray[tuple[FOUR, TWO, FOUR], DType]
+"""A `numpy.ndarray` of shape `(4, 2, 4)` and dtype `DType`."""
+Array4x2xN: TypeAlias = TypedNDArray[tuple[FOUR, TWO, N], DType]
+"""A `numpy.ndarray` of shape `(4, 2, N)` and dtype `DType`."""
+
+Array4x3x2: TypeAlias = TypedNDArray[tuple[FOUR, THREE, TWO], DType]
+"""A `numpy.ndarray` of shape `(4, 3, 2)` and dtype `DType`."""
+Array4x3x3: TypeAlias = TypedNDArray[tuple[FOUR, THREE, THREE], DType]
+"""A `numpy.ndarray` of shape `(4, 3, 3)` and dtype `DType`."""
+Array4x3x4: TypeAlias = TypedNDArray[tuple[FOUR, THREE, FOUR], DType]
+"""A `numpy.ndarray` of shape `(4, 3, 4)` and dtype `DType`."""
+Array4x3xN: TypeAlias = TypedNDArray[tuple[FOUR, THREE, N], DType]
+"""A `numpy.ndarray` of shape `(4, 3, N)` and dtype `DType`."""
+
+Array4x4x2: TypeAlias = TypedNDArray[tuple[FOUR, FOUR, TWO], DType]
+"""A `numpy.ndarray` of shape `(4, 4, 2)` and dtype `DType`."""
+Array4x4x3: TypeAlias = TypedNDArray[tuple[FOUR, FOUR, THREE], DType]
+"""A `numpy.ndarray` of shape `(4, 4, 3)` and dtype `DType`."""
+Array4x4x4: TypeAlias = TypedNDArray[tuple[FOUR, FOUR, FOUR], DType]
+"""A `numpy.ndarray` of shape `(4, 4, 4)` and dtype `DType`."""
+Array4x4xN: TypeAlias = TypedNDArray[tuple[FOUR, FOUR, N], DType]
+"""A `numpy.ndarray` of shape `(4, 4, N)` and dtype `DType`."""
+
+Array4xNx2: TypeAlias = TypedNDArray[tuple[FOUR, N, TWO], DType]
+"""A `numpy.ndarray` of shape `(4, N, 2)` and dtype `DType`."""
+Array4xNx3: TypeAlias = TypedNDArray[tuple[FOUR, N, THREE], DType]
+"""A `numpy.ndarray` of shape `(4, N, 3)` and dtype `DType`."""
+Array4xNx4: TypeAlias = TypedNDArray[tuple[FOUR, N, FOUR], DType]
+"""A `numpy.ndarray` of shape `(4, N, 4)` and dtype `DType`."""
+
+ArrayNx2x2: TypeAlias = TypedNDArray[tuple[N, TWO, TWO], DType]
+"""A `numpy.ndarray` of shape `(N, 2, 2)` and dtype `DType`."""
+ArrayNx2x3: TypeAlias = TypedNDArray[tuple[N, TWO, THREE], DType]
+"""A `numpy.ndarray` of shape `(N, 2, 3)` and dtype `DType`."""
+ArrayNx2x4: TypeAlias = TypedNDArray[tuple[N, TWO, FOUR], DType]
+"""A `numpy.ndarray` of shape `(N, 2, 4)` and dtype `DType`."""
+ArrayNx3x2: TypeAlias = TypedNDArray[tuple[N, THREE, TWO], DType]
+"""A `numpy.ndarray` of shape `(N, 3, 2)` and dtype `DType`."""
+ArrayNx3x3: TypeAlias = TypedNDArray[tuple[N, THREE, THREE], DType]
+"""A `numpy.ndarray` of shape `(N, 3, 3)` and dtype `DType`."""
+ArrayNx3x4: TypeAlias = TypedNDArray[tuple[N, THREE, FOUR], DType]
+"""A `numpy.ndarray` of shape `(N, 3, 4)` and dtype `DType`."""
+ArrayNx4x2: TypeAlias = TypedNDArray[tuple[N, FOUR, TWO], DType]
+"""A `numpy.ndarray` of shape `(N, 4, 2)` and dtype `DType`."""
+ArrayNx4x3: TypeAlias = TypedNDArray[tuple[N, FOUR, THREE], DType]
+"""A `numpy.ndarray` of shape `(N, 4, 3)` and dtype `DType`."""
+ArrayNx4x4: TypeAlias = TypedNDArray[tuple[N, FOUR, FOUR], DType]
+"""A `numpy.ndarray` of shape `(N, 4, 4)` and dtype `DType`."""

typingkit/_typed/list.py

@@ -0,0 +1,206 @@
+"""
+TypedList
+=======
+"""
+# src/typingkit/_typed/list.py
+
+import copy
+import numbers
+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
+
+## Typings
+
+Length = TypeVar("Length", bound=int, default=int)
+Item = TypeVar("Item", default=Any)
+
+
+## Exceptions
+
+
+class LengthError(Exception):
+    """Raised when list length doesn't match expected length."""
+
+
+class ItemError(Exception):
+    """Raised when list item type doesn't match expected item type."""
+
+
+## Runtime validation
+
+
+class TypedListConfig:
+    VALIDATE_LENGTH: bool = True
+    VALIDATE_ITEM: bool = True
+
+    @classmethod
+    def enable_all(cls):
+        cls.VALIDATE_LENGTH = True
+        cls.VALIDATE_ITEM = True
+
+    @classmethod
+    def disable_all(cls):
+        cls.VALIDATE_LENGTH = False
+        cls.VALIDATE_ITEM = False
+
+
+def _is_assignable(value: Any, expected_type: type) -> bool:
+    if expected_type is Any:
+        return True
+    if expected_type is complex:
+        return isinstance(value, numbers.Complex)
+    if expected_type is float:
+        return isinstance(value, numbers.Real)
+    if expected_type is int:
+        return isinstance(value, numbers.Integral)
+    try:
+        origin = get_origin(expected_type)
+        if origin is not None:
+            return isinstance(value, origin)
+        return isinstance(value, expected_type)
+    except Exception:
+        return 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: Sequence[Item], length: Any) -> None:
+    if not TypedListConfig.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
+
+
+def _validate_item(object: Iterable[Item], item_type: Any) -> None:
+    if not TypedListConfig.VALIDATE_ITEM:
+        return
+
+    for index, item in enumerate(object):
+        if not _is_assignable(item, item_type):
+            raise ItemError(
+                f"Item type mismatch: expected {item_type.__name__}, got {type(item).__name__} at index {index}"
+            )
+
+
+## TypedList
+class TypedList(RuntimeGeneric[Length, Item], list[Item]):
+    @classmethod
+    def __pre_new__(cls, alias: GenericAlias, *args: Any, **kwargs: Any) -> Self:
+        # Create `list` object
+        obj = super().__pre_new__(alias, *args, **kwargs)
+
+        ## Runtime validations
+        typeargs = get_args(alias)
+        if len(typeargs) == 2:
+            length, item_type = typeargs
+        elif len(typeargs) == 1:
+            (length,) = typeargs
+            item_type = Item.__default__  # type: ignore[misc]
+            # The `item_type` default here should match the default in `Item`.
+        else:
+            raise TypeError
+        _validate_length(obj, length)
+        _validate_item(obj, item_type)
+
+        return obj
+
+    def __len__(self) -> Length:
+        return cast(Length, super().__len__())
+
+    def copy(self) -> Self:
+        return type(self)(super().copy())
+
+    @property
+    def length(self) -> Length:
+        return self.__len__()
+
+    @classmethod
+    def full(
+        cls: "type[TypedList[Length, Item]]",
+        length: Length,
+        fill_value: Item | Callable[[int], Item],
+    ) -> "TypedList[Length, Item]":
+        data: list[Item]
+        if callable(fill_value):
+            data = [cast(Item, fill_value(i)) for i in range(length)]
+        else:
+            data = [copy.deepcopy(fill_value) for _ in range(length)]
+        return cls(data)