typingkit 0.2.4__tar.gz → 0.2.6__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: typingkit
-Version: 0.2.4
+Version: 0.2.6
 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.4 → typingkit-0.2.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "typingkit"
-version = "0.2.4"
+version = "0.2.6"
 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" }]
@@ -8,20 +8,23 @@ requires-python = ">=3.13"
 dependencies = ["numpy>=2.2"]
 
 [build-system]
-requires = ["uv_build>=0.10.7"]
+requires = ["uv_build>=0.10.9"]
 build-backend = "uv_build"
 
 [dependency-groups]
 dev = ["rich>=14.3.3"]
 test = ["pytest>=9.0.2", "pytest-memray>=1.8.0"]
-lint = ["ruff>=0.15.4"]
+lint = ["ruff>=0.15.5"]
 typecheck = [
     "basedpyright>=1.38.2",
     "mypy[mypyc]>=1.19.1",
     "pyrefly>=0.55.0",
     "pyright>=1.1.408",
-    "ty>=0.0.20",
+    "ty>=0.0.21",
 ]
 
+[tool.mypy]
+enable_incomplete_feature = ["TypeForm"]
+
 [tool.uv]
 default-groups = "all"

{typingkit-0.2.4 → typingkit-0.2.6}/src/typingkit/core/__init__.py

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

typingkit-0.2.6/src/typingkit/core/_config.py

@@ -0,0 +1,26 @@
+"""
+Runtime validation configuration
+=======
+"""
+# src/typingkit/core/_config.py
+
+__all__ = [
+    "TypedCollectionConfig",
+]
+
+
+class TypedCollectionConfig:
+    """Global switches for runtime validation in TypedList and TypedDict."""
+
+    VALIDATE_LENGTH: bool = True
+    VALIDATE_ITEM: bool = True
+
+    @classmethod
+    def enable_all(cls) -> None:
+        cls.VALIDATE_LENGTH = True
+        cls.VALIDATE_ITEM = True
+
+    @classmethod
+    def disable_all(cls) -> None:
+        cls.VALIDATE_LENGTH = False
+        cls.VALIDATE_ITEM = False

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

@@ -7,9 +7,10 @@ Debugging utilities
 from typing import Any, TypeVar, get_args, get_origin
 
 from rich.tree import Tree
+from typing_extensions import TypeForm
 
 
-def diagnostic(obj: Any, pfx: str | None = None) -> Tree:
+def diagnostic(obj: object | TypeForm[Any], pfx: str | None = None) -> Tree:
     _pfx = f"[bold cyan]{pfx}[/] " if pfx else ""
     tree = Tree(
         f"{_pfx}[yellow]obj[/]=[green]{obj!r}[/], "
@@ -17,8 +18,8 @@ def diagnostic(obj: Any, pfx: str | None = None) -> Tree:
     )
     match obj:
         case tuple():
-            for x in obj:  # type: ignore
-                tree.add(diagnostic(x))
+            for x in obj:  # pyright: ignore[reportUnknownVariableType]
+                tree.add(diagnostic(x))  # pyright: ignore[reportUnknownArgumentType]
 
         case TypeVar():
             tree.add(diagnostic(obj.__bound__, "__bound__:"))

typingkit-0.2.6/src/typingkit/core/_validators.py

@@ -0,0 +1,105 @@
+"""
+Runtime validators
+=======
+"""
+# src/typingkit/core/_validators.py
+
+from collections.abc import Sized
+from types import NoneType, UnionType
+from typing import Any, Literal, TypeVar, get_args, get_origin
+
+__all__ = [
+    "LengthError",
+    "validate_length",
+]
+
+
+class LengthError(Exception):
+    """Raised when an object's length doesn't match the expected length."""
+
+
+# Sentinel returned by _coerce_length when a length constraint is trivially satisfied.
+_UNCONSTRAINED = object()
+
+
+def _coerce_length(length: Any) -> Any:
+    """
+    Normalise a length annotation into one of:
+      - ``_UNCONSTRAINED``  — no check needed (TypeVar with no default, Any, bare int type)
+      - ``int``             — exact required length
+      - ``frozenset[int]``  — one of several allowed lengths (from Literal / Union)
+
+    Raises ``LengthError`` for explicitly invalid annotations (e.g. ``NoneType``).
+    """
+    # Unbound TypeVar — fall back to its default, or treat as unconstrained
+    if isinstance(length, TypeVar):
+        default = getattr(length, "__default__", None)
+        if default is None or default is length:
+            return _UNCONSTRAINED
+        return _coerce_length(default)
+
+    # Any / bare int supertype — unconstrained
+    if length is Any:
+        return _UNCONSTRAINED
+    if isinstance(length, type):
+        if length is NoneType:
+            raise LengthError(f"Invalid length annotation: {length!r}")
+        if issubclass(length, int):
+            return _UNCONSTRAINED  # e.g. Length=int means "any integer length"
+
+    origin = get_origin(length)
+
+    # Literal[a, b, ...] -> frozenset of ints
+    if origin is Literal:
+        return _coerce_union_args(get_args(length))
+
+    # X | Y | Z  ->  union of coerced results
+    if origin is UnionType:
+        return _coerce_union_args(get_args(length))
+
+    # Concrete int (e.g. Literal[3] already resolved, or bare 3)
+    if isinstance(length, int):
+        return length
+
+    return _UNCONSTRAINED  # Unknown annotation shape — Skip
+
+
+def _coerce_union_args(args: tuple[Any, ...]) -> Any:
+    """Collapse a sequence of length annotations into a single ``frozenset`` or scalar."""
+    collected = set[int]()
+    for arg in args:
+        coerced = _coerce_length(arg)
+        if coerced is _UNCONSTRAINED:
+            return _UNCONSTRAINED  # Any branch being unconstrained -> whole union is
+        if isinstance(coerced, frozenset):
+            collected |= coerced
+        else:
+            collected.add(coerced)
+    return frozenset(collected) if len(collected) != 1 else next(iter(collected))  # type: ignore[arg-type]
+
+
+def validate_length(obj: Sized, length: Any) -> None:
+    """
+    Assert that ``len(obj)`` satisfies the ``length`` annotation.
+
+    ``length`` may be a concrete ``int``, a ``TypeVar``, ``Literal[...]``,
+    a ``Union`` of the above, or ``Any``.  Unconstrained annotations (bare
+    ``int`` type, unbound ``TypeVar``, ``Any``) are accepted without a check.
+    """
+    constraint = _coerce_length(length)
+    if constraint is _UNCONSTRAINED:
+        return None
+
+    actual = len(obj)
+
+    if isinstance(constraint, frozenset):
+        if actual not in constraint:
+            allowed = ", ".join(str(val) for val in sorted(constraint))  # pyright: ignore[reportUnknownArgumentType, reportUnknownVariableType]
+            raise LengthError(
+                f"Length mismatch: expected one of {{{allowed}}}, got {actual}"
+            )
+    else:
+        if actual != constraint:
+            raise LengthError(f"Length mismatch: expected {constraint}, got {actual}")
+
+    return None

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

@@ -0,0 +1,60 @@
+"""
+TypedDict
+=======
+"""
+# src/typingkit/core/dict.py
+
+from types import GenericAlias
+from typing import Any, TypeVar, cast
+
+from typingkit.core._config import TypedCollectionConfig
+from typingkit.core._validators import LengthError, validate_length
+from typingkit.core.generics import RuntimeGeneric, get_runtime_args
+
+__all__ = [
+    "TypedDict",
+    "LengthError",
+]
+
+# ── Type parameters ───────────────────────────────────────────────────────────
+
+Length = TypeVar("Length", bound=int, default=int)
+Key = TypeVar("Key", default=Any)
+Value = TypeVar("Value", default=Any)
+
+
+# ── TypedDict ─────────────────────────────────────────────────────────────────
+
+
+class TypedDict(RuntimeGeneric[Length, Key, Value], dict[Key, Value]):
+    """
+    A ``dict`` subclass whose length is enforced at runtime via the
+    ``RuntimeGeneric`` machinery.
+
+    Usage::
+
+        TypedDict[Literal[2], str, int]({"a": 1, "b": 2})   # length checked
+        TypedDict[int, str, int]({"a": 1})                  # no length constraint
+    """
+
+    # ── RuntimeGeneric hooks ──────────────────────────────────────────────────
+
+    def __runtime_generic_post_init__(self, alias: GenericAlias) -> None:
+        args = get_runtime_args(alias)
+        length: Any = args[0] if args else Length.__default__  # type: ignore[misc]
+
+        if TypedCollectionConfig.VALIDATE_LENGTH:
+            validate_length(self, length)
+
+        # Propagate into nested RuntimeGenerics — delegate to the base class
+        # which calls __runtime_generic_iter_children__ for us.
+        return super().__runtime_generic_post_init__(alias)
+
+    # ── dict API ──────────────────────────────────────────────────────────────
+
+    def __len__(self) -> Length:
+        return cast(Length, super().__len__())
+
+    @property
+    def length(self) -> Length:
+        return self.__len__()