typingkit 0.2.7__tar.gz → 0.2.8__tar.gz

{typingkit-0.2.7 → typingkit-0.2.8}/PKG-INFO

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

@@ -1,6 +1,6 @@
 [project]
 name = "typingkit"
-version = "0.2.7"
+version = "0.2.8"
 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,23 +8,27 @@ requires-python = ">=3.13"
 dependencies = ["numpy>=2.2"]
 
 [build-system]
-requires = ["uv_build>=0.10.9"]
+requires = ["uv_build>=0.10.11,<0.11.0"]
 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.5"]
+lint = ["ruff>=0.15.6"]
 typecheck = [
-    "basedpyright>=1.38.2",
+    "basedpyright>=1.38.3",
     "mypy[mypyc]>=1.19.1",
-    "pyrefly>=0.56.0",
+    "pyrefly>=0.57.0",
     "pyright>=1.1.408",
-    "ty>=0.0.21",
+    "ty>=0.0.23",
 ]
 
 [tool.mypy]
 enable_incomplete_feature = ["TypeForm"]
+plugins = ["typingkit.mypy_plugin"]
+
+[tool.pytest.ini_options]
+norecursedirs = ["tests/mypy_plugin"]
 
 [tool.uv]
 default-groups = "all"

{typingkit-0.2.7 → typingkit-0.2.8}/src/typingkit/core/__init__.py

@@ -4,14 +4,20 @@ TypingKit core
 """
 # src/typingkit/core/__init__.py
 
-from typingkit.core._config import TypedCollectionConfig
+from typingkit.core._options import (
+    RuntimeOptions,
+    reset_global_default_runtime_options,
+    set_global_default_runtime_options,
+)
 from typingkit.core.dict import TypedDict
 from typingkit.core.generics import RuntimeGeneric
 from typingkit.core.list import TypedList
 
 __all__ = [
     "RuntimeGeneric",
+    "RuntimeOptions",
+    "set_global_default_runtime_options",
+    "reset_global_default_runtime_options",
     "TypedList",
     "TypedDict",
-    "TypedCollectionConfig",
 ]

typingkit-0.2.8/src/typingkit/core/_options.py

@@ -0,0 +1,195 @@
+"""
+RuntimeOptions
+==============
+
+Per-class, inheritable, optionally context-scoped configuration for
+``RuntimeGeneric`` subclasses.
+
+Public API
+----------
+RuntimeOptions          – base frozen-dataclass config attached to a class
+RuntimeOptionsProxy     – ContextVar-backed scoped override (context manager)
+
+Attaching options to a class
+-----------------------------
+Pass an ``options=`` keyword to the class statement — handled by
+``RuntimeGeneric.__init_subclass__``::
+
+    class MyClass(RuntimeGeneric[A, B],
+                    options=ListOptions(validate_a=False)):
+        ...
+
+Options are inherited through the MRO; a subclass that does not pass
+``options=`` inherits its nearest parent's options unchanged.
+
+Subclassing RuntimeOptions
+--------------------------
+Add domain-specific flags by subclassing::
+
+    @dataclass(frozen=True)
+    class MyClassRuntimeOptions(RuntimeOptions):
+        validate_a: bool = True
+        validate_b: bool = True
+
+Temporary overrides
+--------------------
+Use ``RuntimeOptions.scoped(...)`` as a context manager::
+
+    with RuntimeOptions.scoped(validate=False):
+        MyClass[Literal[3], Literal[4]](...)
+
+Scoped options take precedence over class-level options for any
+``__runtime_generic_post_init__`` call made within the ``with`` block,
+across all ``RuntimeGeneric`` subclasses.  The override is thread- and
+async-safe (backed by a ``ContextVar``).
+"""
+# src/typingkit/core/_options.py
+
+from __future__ import annotations
+
+from contextvars import ContextVar
+from dataclasses import dataclass, replace
+from typing import Any
+
+__all__ = [
+    "RuntimeOptions",
+]
+
+# ── Scoped override ───────────────────────────────────────────────────────────
+
+_scoped_options: ContextVar[RuntimeOptions | None] = ContextVar(
+    "_scoped_options", default=None
+)
+
+
+# ── Options dataclass ─────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class RuntimeOptions:
+    """
+    Immutable per-class configuration for ``RuntimeGeneric``.
+
+    Fields
+    ------
+    validate : bool
+        Master switch.  When ``False``, ``__runtime_generic_post_init__`` is
+        skipped entirely — equivalent to plain ``Generic`` behaviour.  Takes
+        effect both at the alias-call level (``_RuntimeGenericAlias.__call__``)
+        and inside the post-init guard, so subclasses never see the call.
+
+    propagate : bool
+        Whether to walk ``__runtime_generic_iter_children__`` and propagate
+        resolved types into child ``RuntimeGeneric`` instances.  Setting this
+        to ``False`` validates `self` but stops at the boundary — useful when
+        children manage their own lifecycle (e.g. lazy containers).
+    """
+
+    validate: bool = True
+    propagate: bool = True
+
+    # ── Merging ───────────────────────────────────────────────────────────────
+
+    def merged(self, **overrides: Any) -> RuntimeOptions:
+        """Return a new options object with `overrides` applied."""
+        return replace(self, **overrides)
+
+    # ── Scoped context manager ────────────────────────────────────────────────
+
+    @staticmethod
+    def scoped(**overrides: Any) -> _RuntimeOptionsScopedCtx:
+        """
+        Context manager for temporary option overrides.
+
+        Merges `overrides` into the currently-active scoped options (or the
+        sentinel ``RuntimeOptions()`` if none is active), so nested scopes
+        compose correctly::
+
+            with RuntimeOptions.scoped(validate=False):
+                with RuntimeOptions.scoped(propagate=False):
+                    ...  # both validate=False and propagate=False
+        """
+        return _RuntimeOptionsScopedCtx(overrides)
+
+    # ── Internal resolution ───────────────────────────────────────────────────
+
+    @staticmethod
+    def resolve(class_options: RuntimeOptions) -> RuntimeOptions:
+        """
+        Return the effective options for a call, merging scoped overrides.
+
+        Scoped options (from ``RuntimeOptions.scoped(...)``) always win over
+        class-level options.  Only the fields present in *class_options*'s
+        type are considered from the scoped override, so domain-specific
+        fields on a subclass are not accidentally clobbered.
+        """
+        # Global default acts as a master override — if it disables validation,
+        # nothing can re-enable it except explicitly passing scoped().
+        effective = class_options
+        if not global_default_runtime_options.validate and effective.validate:
+            effective = replace(effective, validate=False)
+        if not global_default_runtime_options.propagate and effective.validate:
+            effective = replace(effective, propagate=False)
+
+        scoped = _scoped_options.get()
+        if scoped is None:
+            return effective
+
+        # Apply only the base RuntimeOptions fields from the scoped override;
+        # domain-specific fields on class_options are preserved.
+        base_fields = {"validate", "propagate"}
+        overrides: dict[str, Any] = {}
+        for field in base_fields:
+            scoped_val = getattr(scoped, field, None)
+            effective_val = getattr(effective, field, None)
+            if scoped_val is not None and scoped_val != effective_val:
+                overrides[field] = scoped_val
+        if not overrides:
+            return effective
+        return replace(effective, **overrides)
+
+
+# ── Context manager implementation ────────────────────────────────────────────
+
+
+class _RuntimeOptionsScopedCtx:
+    """Returned by ``RuntimeOptions.scoped()``; not part of the public API."""
+
+    __slots__ = ("_overrides", "_token")
+
+    def __init__(self, overrides: dict[str, Any]) -> None:
+        self._overrides = overrides
+        self._token = None
+
+    def __enter__(self) -> RuntimeOptions:
+        current = _scoped_options.get() or RuntimeOptions()
+        merged = replace(current, **self._overrides)
+        self._token = _scoped_options.set(merged)  # type: ignore[assignment]
+        return merged
+
+    def __exit__(self, *_: Any) -> None:
+        if self._token is not None:
+            _scoped_options.reset(self._token)
+            self._token = None
+
+    # Support async with as well
+    async def __aenter__(self) -> RuntimeOptions:
+        return self.__enter__()
+
+    async def __aexit__(self, *args: Any) -> None:
+        self.__exit__(*args)
+
+
+# ── Global default ────────────────────────────────────────────────────────────
+
+global_default_runtime_options: RuntimeOptions = RuntimeOptions()
+
+
+def set_global_default_runtime_options(options: RuntimeOptions) -> None:
+    global global_default_runtime_options
+    global_default_runtime_options = options
+
+
+def reset_global_default_runtime_options() -> None:
+    global global_default_runtime_options
+    global_default_runtime_options = RuntimeOptions()

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

@@ -0,0 +1,72 @@
+"""
+TypedDict
+=======
+A dict subclass with runtime length enforcement.
+"""
+# src/typingkit/core/dict.py
+
+from dataclasses import dataclass
+from types import GenericAlias
+from typing import Any, TypeVar, cast
+
+from typingkit.core._options import RuntimeOptions
+from typingkit.core._validators import LengthError, validate_length
+from typingkit.core.generics import RuntimeGeneric, get_runtime_args, mapping_from_alias
+
+__all__ = [
+    "TypedDict",
+    "TypedDictOptions",
+    "LengthError",
+]
+
+Length = TypeVar("Length", bound=int, default=int)
+Key = TypeVar("Key", default=Any)
+Value = TypeVar("Value", default=Any)
+
+
+@dataclass(frozen=True)
+class TypedDictOptions(RuntimeOptions):
+    validate_length: bool = True
+
+
+_DEFAULT_DICT_OPTIONS = TypedDictOptions()
+
+
+class TypedDict(
+    RuntimeGeneric[Length, Key, Value],
+    dict[Key, Value],
+    options=_DEFAULT_DICT_OPTIONS,
+):
+    """
+    A ``dict`` subclass with optional runtime length enforcement.
+
+    Usage::
+
+        TypedDict[Literal[2], str, int]({"a": 1, "b": 2})  # length checked
+        TypedDict[int, str, int]({"a": 1})                 # unconstrained length
+    """
+
+    def __runtime_generic_validate__(self, alias: GenericAlias) -> None:
+        # get_runtime_args always returns a full-length tuple (defaults filled).
+        # Safe to unpack directly against the class's parameter list.
+        length, _key, _value = get_runtime_args(alias)
+
+        opts = self.__class__._runtime_options_
+        # Narrow to TypedDictOptions for the domain-specific flag.
+        # Falls back gracefully if a subclass switched to a plain RuntimeOptions.
+        if isinstance(opts, TypedDictOptions) and opts.validate_length:
+            validate_length(self, length)
+
+        # Propagate resolved types into child RuntimeGeneric instances.
+        # We call this here (rather than relying on the base post_init) because
+        # we've already resolved the mapping above — avoids a second build.
+        self.__runtime_generic_propagate_children__(
+            mapping_from_alias(alias, type(self))
+        )
+
+    def __len__(self) -> Length:
+        return cast(Length, super().__len__())
+
+    @property
+    def length(self) -> Length:
+        return self.__len__()