validating 0.0.1__tar.gz → 0.0.2__tar.gz

{validating-0.0.1 → validating-0.0.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: validating
-Version: 0.0.1
+Version: 0.0.2
 Summary: Provides a lightweight `attr()` descriptor factory that adds runtime validation to dataclass fields.
 Project-URL: Documentation, https://github.com/Chitaoji/validating/blob/main/README.md
 Project-URL: Repository, https://github.com/Chitaoji/validating/
@@ -181,7 +181,11 @@ class EvenNumber:
 This project falls under the BSD 3-Clause License.
 
 ## History
+### v0.0.2
+* Fixed runtime checking for `TypedDict` and several special typing hints to avoid invalid `isinstance` paths.
+* Added runtime validation support for `typing.Unpack`-style annotations.
+* Improved forward-reference handling under `TYPE_CHECKING` imports, including deferred annotation resolution and safer fallback behavior when references are temporarily unresolved.
+* Refined the `@validate` argument-checking path for better robustness and consistency across annotated call patterns.
 
 ### v0.0.1
-
-- Initial release.
+* Initial release.

{validating-0.0.1 → validating-0.0.2}/README.md

@@ -165,7 +165,11 @@ class EvenNumber:
 This project falls under the BSD 3-Clause License.
 
 ## History
+### v0.0.2
+* Fixed runtime checking for `TypedDict` and several special typing hints to avoid invalid `isinstance` paths.
+* Added runtime validation support for `typing.Unpack`-style annotations.
+* Improved forward-reference handling under `TYPE_CHECKING` imports, including deferred annotation resolution and safer fallback behavior when references are temporarily unresolved.
+* Refined the `@validate` argument-checking path for better robustness and consistency across annotated call patterns.
 
 ### v0.0.1
-
-- Initial release.
+* Initial release.

{validating-0.0.1 → validating-0.0.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "validating"
-version = "0.0.1"
+version = "0.0.2"
 dependencies = []
 requires-python = ">=3.13"
 authors = [

{validating-0.0.1 → validating-0.0.2}/src/validating/valid_attr.py

@@ -8,12 +8,24 @@ NOTE: this module is private. All functions and objects are available in the mai
 """
 
 import sys
+from ast import (
+    Attribute,
+    If,
+    Import,
+    ImportFrom,
+    Name,
+    NodeVisitor,
+    parse,
+)
 from dataclasses import Field, field
 from functools import partialmethod
+from importlib import import_module
+from pathlib import Path
 from types import UnionType
 from typing import (
     Any,
     Callable,
+    ForwardRef,
     Literal,
     Optional,
     Union,
@@ -22,6 +34,22 @@ from typing import (
     get_type_hints,
 )
 
+try:  # pragma: no cover - Python >= 3.11
+    from typing import NotRequired, Required, Unpack
+except ImportError:  # pragma: no cover - Python < 3.11
+    from typing_extensions import NotRequired, Required, Unpack
+
+try:  # pragma: no cover - available on modern Python versions
+    from typing import is_typeddict
+except ImportError:  # pragma: no cover - compatibility fallback
+    def is_typeddict(type_hint: Any) -> bool:
+        return bool(
+            isinstance(type_hint, type)
+            and isinstance(getattr(type_hint, "__annotations__", None), dict)
+            and hasattr(type_hint, "__required_keys__")
+            and hasattr(type_hint, "__optional_keys__")
+        )
+
 __all__ = ["attr"]
 
 
@@ -536,6 +564,7 @@ def _resolve_field_type_hint(
     name: str,
     *,
     localns: dict[str, Any] | None = None,
+    include_type_checking_names: bool = False,
 ) -> type:
     if name not in cls.__annotations__:
         return Any
@@ -544,18 +573,28 @@ def _resolve_field_type_hint(
     if not isinstance(raw_type_hint, str):
         return raw_type_hint
 
+    merged_localns = localns
+    if include_type_checking_names:
+        merged_localns = _merge_localns(
+            localns,
+            _collect_type_checking_names(cls.__module__),
+        )
+
     try:
         resolved_hints = get_type_hints(
             cls,
             globalns=vars(sys.modules[cls.__module__]),
-            localns=localns,
+            localns=merged_localns,
             include_extras=True,
         )
-    except NameError as exc:
-        raise ValidatorError(
-            f"failed to resolve annotation for {cls.__name__}.{name}: {raw_type_hint!r}"
-        ) from exc
     except Exception as exc:  # pragma: no cover - exact exception depends on annotation
+        if not include_type_checking_names:
+            return _resolve_field_type_hint(
+                cls,
+                name,
+                localns=localns,
+                include_type_checking_names=True,
+            )
         raise ValidatorError(
             f"failed to resolve annotation for {cls.__name__}.{name}: {raw_type_hint!r}"
         ) from exc
@@ -595,6 +634,89 @@ def _collect_runtime_localns(
     return merged or None
 
 
+def _merge_localns(*namespaces: dict[str, Any] | None) -> dict[str, Any] | None:
+    merged: dict[str, Any] = {}
+    for namespace in namespaces:
+        if namespace:
+            merged.update(namespace)
+    return merged or None
+
+
+def _collect_type_checking_names(module_name: str) -> dict[str, Any]:
+    module = sys.modules.get(module_name)
+    if module is None:
+        return {}
+
+    module_file = getattr(module, "__file__", None)
+    if module_file is None:
+        return {}
+
+    try:
+        source = Path(module_file).read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return {}
+
+    package = getattr(module, "__package__", None)
+    return _TypeCheckingImportCollector(package).collect(source)
+
+
+class _TypeCheckingImportCollector(NodeVisitor):
+    def __init__(self, package: str | None) -> None:
+        self.package = package
+        self.names: dict[str, Any] = {}
+
+    def collect(self, source: str) -> dict[str, Any]:
+        try:
+            tree = parse(source)
+        except SyntaxError:
+            return {}
+        self.visit(tree)
+        return self.names
+
+    def visit_If(self, node: If) -> None:
+        if self._is_type_checking_guard(node.test):
+            for stmt in node.body:
+                self._consume_type_checking_stmt(stmt)
+
+        self.generic_visit(node)
+
+    @staticmethod
+    def _is_type_checking_guard(test: Any) -> bool:
+        if isinstance(test, Name):
+            return test.id == "TYPE_CHECKING"
+        if isinstance(test, Attribute):
+            return isinstance(test.value, Name) and test.value.id == "typing" and test.attr == "TYPE_CHECKING"
+        return False
+
+    def _consume_type_checking_stmt(self, stmt: Any) -> None:
+        if isinstance(stmt, Import):
+            for alias in stmt.names:
+                try:
+                    module = import_module(alias.name)
+                except Exception:
+                    continue
+                self.names[alias.asname or alias.name.split(".")[0]] = module
+            return
+
+        if not isinstance(stmt, ImportFrom) or stmt.module is None:
+            return
+
+        target_module = "." * stmt.level + stmt.module
+        try:
+            imported = import_module(target_module, self.package)
+        except Exception:
+            return
+
+        for alias in stmt.names:
+            if alias.name == "*":
+                continue
+            try:
+                symbol = getattr(imported, alias.name)
+            except AttributeError:
+                continue
+            self.names[alias.asname or alias.name] = symbol
+
+
 def isoftype(
     value: object, type_hint: type, name: str, path: str = ""
 ) -> Optional[str]:
@@ -625,8 +747,24 @@ def isoftype(
     args = get_args(type_hint)
 
     if origin is None:
-        if isinstance(value, type_hint):
+        if isinstance(type_hint, ForwardRef):
+            # Unresolved forward references may appear in dynamic annotations
+            # (e.g. ``Union[ForwardRef("MyTypedDict"), None]``). At runtime,
+            # accept these values instead of failing with a low-signal error.
             return None
+
+        newtype_super = getattr(type_hint, "__supertype__", None)
+        if newtype_super is not None:
+            return isoftype(value, newtype_super, name, path)
+
+        if is_typeddict(type_hint):
+            return _validate_typed_dict(value, type_hint, name, path)
+
+        try:
+            if isinstance(value, type_hint):
+                return None
+        except TypeError:
+            pass
         return _format_isoftype_error(
             path, f"{type_hint!r}, got {type(value)!r} instead"
         )
@@ -645,6 +783,10 @@ def isoftype(
             return None
         return _format_isoftype_error(path, f"one of {args!r}, got {value!r} instead")
 
+    if origin is Unpack:
+        (unpacked_type,) = args
+        return isoftype(value, unpacked_type, name, path)
+
     if origin is list:
         (elem_type,) = args
         if not isinstance(value, list):
@@ -713,4 +855,46 @@ def _format_isoftype_error(path: str, detail: str) -> str:
     return f"expected {detail}"
 
 
+def _validate_typed_dict(
+    value: object,
+    type_hint: Any,
+    name: str,
+    path: str,
+) -> Optional[str]:
+    if not isinstance(value, dict):
+        return _format_isoftype_error(path, f"a dict, got {type(value)!r} instead")
+
+    annotations = getattr(type_hint, "__annotations__", {})
+    required_keys = set(getattr(type_hint, "__required_keys__", set()))
+    optional_keys = set(getattr(type_hint, "__optional_keys__", set()))
+    allowed_keys = required_keys | optional_keys | set(annotations)
+
+    missing = sorted(required_keys - set(value))
+    if missing:
+        keys = ", ".join(repr(k) for k in missing)
+        return _format_isoftype_error(path, f"missing required keys: {keys}")
+
+    extra = sorted(set(value) - allowed_keys)
+    if extra:
+        keys = ", ".join(repr(k) for k in extra)
+        return _format_isoftype_error(path, f"unexpected keys: {keys}")
+
+    for key, annotated in annotations.items():
+        if key not in value:
+            continue
+        key_type = _unwrap_required_marker(annotated)
+        key_error = isoftype(value[key], key_type, name, f"{name}[{key!r}]")
+        if key_error is not None:
+            return key_error
+
+    return None
+
+
+def _unwrap_required_marker(type_hint: Any) -> Any:
+    origin = get_origin(type_hint)
+    if origin is Required or origin is NotRequired:
+        return get_args(type_hint)[0]
+    return type_hint
+
+
 class ValidatorError(RuntimeError): ...

{validating-0.0.1 → validating-0.0.2}/src/validating/valid_func.py

@@ -13,12 +13,23 @@ from functools import wraps
 from inspect import Parameter, Signature, getsourcelines, signature
 from textwrap import dedent
 from traceback import TracebackException
-from typing import Any, Callable, get_type_hints
+from typing import Any, Callable, get_args, get_origin, get_type_hints
 
-from .valid_attr import _collect_runtime_localns, _get_owner_localns, isoftype
+from .valid_attr import (
+    _collect_runtime_localns,
+    _collect_type_checking_names,
+    _get_owner_localns,
+    _merge_localns,
+    isoftype,
+)
 
 __all__ = ["validate"]
 
+try:  # pragma: no cover - Python >= 3.11
+    from typing import Unpack
+except ImportError:  # pragma: no cover - Python < 3.11
+    from typing_extensions import Unpack
+
 _VALIDATE_MARKER = "__validating_is_validate_wrapped__"
 
 
@@ -53,6 +64,7 @@ def validate[T](func: T) -> T:
         return func
 
     sig = signature(func)
+    parameters = sig.parameters
     owner_localns = _get_owner_localns()
     resolved_annotations, deferred_annotations = _resolve_signature_annotations(
         func,
@@ -69,7 +81,7 @@ def validate[T](func: T) -> T:
             deferred_annotations,
             initial_localns=owner_localns,
         )
-        _validate_bound_arguments(func, sig, bound.arguments, resolved_annotations)
+        _validate_bound_arguments(func, parameters, bound.arguments, resolved_annotations)
         try:
             return func(*args, **kwargs)
         except AssertionError as exc:
@@ -219,7 +231,15 @@ def _resolve_signature_annotations(
             include_extras=True,
         )
     except Exception:
-        type_hints = {}
+        try:
+            type_hints = get_type_hints(
+                func,
+                globalns=globalns,
+                localns=_merge_localns(localns, _collect_type_checking_names(func.__module__)),
+                include_extras=True,
+            )
+        except Exception:
+            type_hints = {}
 
     for name, param in sig.parameters.items():
         annotation = param.annotation
@@ -246,7 +266,10 @@ def _resolve_deferred_signature_annotations(
     if not deferred_annotations:
         return
 
-    localns = _collect_runtime_localns(initial_localns)
+    localns = _merge_localns(
+        _collect_runtime_localns(initial_localns),
+        _collect_type_checking_names(func.__module__),
+    )
     globalns = vars(__import__(func.__module__, fromlist=["*"]))
     try:
         type_hints = get_type_hints(
@@ -276,12 +299,12 @@ def _resolve_deferred_signature_annotations(
 
 def _validate_bound_arguments(
     func: Callable[..., Any],
-    sig: Signature,
+    parameters: dict[str, Parameter],
     arguments: dict[str, Any],
     resolved_annotations: dict[str, Any],
 ) -> None:
     for name, value in arguments.items():
-        param = sig.parameters[name]
+        param = parameters[name]
         if name not in resolved_annotations:
             continue
         annotation = resolved_annotations[name]
@@ -295,13 +318,18 @@ def _validate_bound_arguments(
                     path=f"{name}[{idx}]",
                 )
                 if mismatch_reason is not None:
-                    raise TypeError(
-                        f"invalid type for argument {name!r} of {func.__name__}: "
-                        + mismatch_reason
-                    )
+                    _raise_argument_type_error(func, name, mismatch_reason)
             continue
 
         if param.kind is Parameter.VAR_KEYWORD:
+            if get_origin(annotation) is Unpack:
+                unpacked = get_args(annotation)
+                unpacked_annotation = unpacked[0] if unpacked else annotation
+                mismatch_reason = isoftype(value, unpacked_annotation, name, path=name)
+                if mismatch_reason is not None:
+                    _raise_argument_type_error(func, name, mismatch_reason)
+                continue
+
             for key, item in value.items():
                 mismatch_reason = isoftype(
                     item,
@@ -310,15 +338,17 @@ def _validate_bound_arguments(
                     path=f"{name}[{key!r}]",
                 )
                 if mismatch_reason is not None:
-                    raise TypeError(
-                        f"invalid type for argument {name!r} of {func.__name__}: "
-                        + mismatch_reason
-                    )
+                    _raise_argument_type_error(func, name, mismatch_reason)
             continue
 
         mismatch_reason = isoftype(value, annotation, name)
         if mismatch_reason is not None:
-            raise TypeError(
-                f"invalid type for argument {name!r} of {func.__name__}: "
-                + mismatch_reason
-            )
+            _raise_argument_type_error(func, name, mismatch_reason)
+
+
+def _raise_argument_type_error(
+    func: Callable[..., Any], name: str, mismatch_reason: str
+) -> None:
+    raise TypeError(
+        f"invalid type for argument {name!r} of {func.__name__}: " + mismatch_reason
+    )

{validating-0.0.1 → validating-0.0.2}/test.py

@@ -1,6 +1,15 @@
 import unittest
+import sys
+from importlib.util import module_from_spec, spec_from_file_location
+from pathlib import Path
+from tempfile import TemporaryDirectory
 from dataclasses import dataclass
-from typing import Any, Literal
+from typing import Any, ForwardRef, Literal, TypedDict
+
+try:
+    from typing import Unpack
+except ImportError:
+    from typing_extensions import Unpack
 
 from src.validating import (
     ValidatorError,
@@ -297,6 +306,86 @@ class TestAttrWithDataclasses(unittest.TestCase):
         cfg = Config(retries=LaterType())
         self.assertIsInstance(cfg.retries, LaterType)
 
+    def test_type_checking_import_is_lazily_loaded_for_attr(self):
+        with TemporaryDirectory() as temp_dir:
+            root = Path(temp_dir)
+            (root / "lazy_models.py").write_text(
+                "class LaterType:\n"
+                "    pass\n",
+                encoding="utf-8",
+            )
+            (root / "lazy_consumer.py").write_text(
+                "from dataclasses import dataclass\n"
+                "from typing import TYPE_CHECKING\n"
+                "from src.validating import attr\n"
+                "\n"
+                "if TYPE_CHECKING:\n"
+                "    from lazy_models import LaterType\n"
+                "\n"
+                "@dataclass\n"
+                "class Config:\n"
+                "    value: 'LaterType' = attr()\n",
+                encoding="utf-8",
+            )
+
+            self.assertNotIn("lazy_models", sys.modules)
+
+            consumer_spec = spec_from_file_location("lazy_consumer", root / "lazy_consumer.py")
+            assert consumer_spec is not None and consumer_spec.loader is not None
+            consumer_module = module_from_spec(consumer_spec)
+            sys.modules["lazy_consumer"] = consumer_module
+            consumer_spec.loader.exec_module(consumer_module)
+
+            self.assertNotIn("lazy_models", sys.modules)
+
+            models_spec = spec_from_file_location("lazy_models", root / "lazy_models.py")
+            assert models_spec is not None and models_spec.loader is not None
+            models_module = module_from_spec(models_spec)
+            sys.modules["lazy_models"] = models_module
+            models_spec.loader.exec_module(models_module)
+
+            cfg = consumer_module.Config(value=models_module.LaterType())
+            self.assertIsInstance(cfg.value, models_module.LaterType)
+
+    def test_forward_string_annotation_from_type_checking_import_is_resolved_for_attr(
+        self,
+    ):
+        with TemporaryDirectory() as temp_dir:
+            root = Path(temp_dir)
+            (root / "models.py").write_text(
+                "class LaterType:\n"
+                "    pass\n",
+                encoding="utf-8",
+            )
+            (root / "consumer.py").write_text(
+                "from dataclasses import dataclass\n"
+                "from typing import TYPE_CHECKING\n"
+                "from src.validating import attr\n"
+                "\n"
+                "if TYPE_CHECKING:\n"
+                "    from models import LaterType\n"
+                "\n"
+                "@dataclass\n"
+                "class Config:\n"
+                "    value: 'LaterType' = attr()\n",
+                encoding="utf-8",
+            )
+
+            models_spec = spec_from_file_location("models", root / "models.py")
+            assert models_spec is not None and models_spec.loader is not None
+            models_module = module_from_spec(models_spec)
+            sys.modules["models"] = models_module
+            models_spec.loader.exec_module(models_module)
+
+            consumer_spec = spec_from_file_location("consumer", root / "consumer.py")
+            assert consumer_spec is not None and consumer_spec.loader is not None
+            consumer_module = module_from_spec(consumer_spec)
+            sys.modules["consumer"] = consumer_module
+            consumer_spec.loader.exec_module(consumer_module)
+
+            cfg = consumer_module.Config(value=models_module.LaterType())
+            self.assertIsInstance(cfg.value, models_module.LaterType)
+
     def test_unresolvable_string_annotation_raises_for_attr(self):
         @dataclass
         class Config:
@@ -497,6 +586,23 @@ class TestValidateFunctionDecorator(unittest.TestCase):
         with self.assertRaises(TypeError):
             collect(1, 2, key=3)
 
+    def test_validate_supports_unpack_typed_dict_for_kwargs(self):
+        class Query(TypedDict):
+            limit: int
+            cursor: str
+
+        @validate
+        def fetch(**kwargs: Unpack[Query]):
+            return kwargs
+
+        self.assertEqual(fetch(limit=1, cursor="next"), {"limit": 1, "cursor": "next"})
+        with self.assertRaises(TypeError):
+            fetch(limit="1", cursor="next")
+        with self.assertRaises(TypeError):
+            fetch(limit=1)
+        with self.assertRaises(TypeError):
+            fetch(limit=1, cursor="next", extra="x")
+
     def test_validate_resolves_string_annotations(self):
         @validate
         def add(a: "int", b: "int") -> int:
@@ -506,6 +612,17 @@ class TestValidateFunctionDecorator(unittest.TestCase):
         with self.assertRaises(TypeError):
             add("1", 2)
 
+    def test_validate_accepts_union_with_unresolved_forward_ref(self):
+        @validate
+        def set_figure(kwargs: ForwardRef("SubplotDict") | None):
+            return kwargs
+
+        self.assertEqual(
+            set_figure({"left": 0.1, "right": 0.9}),
+            {"left": 0.1, "right": 0.9},
+        )
+        self.assertIsNone(set_figure(None))
+
     def test_validate_resolves_forward_string_annotations_in_local_scope(self):
         @validate
         def build(value: "LaterType") -> "LaterType":
@@ -518,6 +635,86 @@ class TestValidateFunctionDecorator(unittest.TestCase):
         with self.assertRaises(TypeError):
             build(1)
 
+    def test_validate_type_checking_import_is_lazily_loaded(self):
+        with TemporaryDirectory() as temp_dir:
+            root = Path(temp_dir)
+            (root / "lazy_v_models.py").write_text(
+                "class LaterType:\n"
+                "    pass\n",
+                encoding="utf-8",
+            )
+            (root / "lazy_v_consumer.py").write_text(
+                "from typing import TYPE_CHECKING\n"
+                "from src.validating import validate\n"
+                "\n"
+                "if TYPE_CHECKING:\n"
+                "    from lazy_v_models import LaterType\n"
+                "\n"
+                "@validate\n"
+                "def build(value: 'LaterType') -> 'LaterType':\n"
+                "    return value\n",
+                encoding="utf-8",
+            )
+
+            self.assertNotIn("lazy_v_models", sys.modules)
+
+            consumer_spec = spec_from_file_location("lazy_v_consumer", root / "lazy_v_consumer.py")
+            assert consumer_spec is not None and consumer_spec.loader is not None
+            consumer_module = module_from_spec(consumer_spec)
+            sys.modules["lazy_v_consumer"] = consumer_module
+            consumer_spec.loader.exec_module(consumer_module)
+
+            self.assertNotIn("lazy_v_models", sys.modules)
+
+            models_spec = spec_from_file_location("lazy_v_models", root / "lazy_v_models.py")
+            assert models_spec is not None and models_spec.loader is not None
+            models_module = module_from_spec(models_spec)
+            sys.modules["lazy_v_models"] = models_module
+            models_spec.loader.exec_module(models_module)
+
+            instance = models_module.LaterType()
+            self.assertIs(consumer_module.build(instance), instance)
+            with self.assertRaises(TypeError):
+                consumer_module.build(1)
+
+    def test_validate_resolves_forward_annotation_from_type_checking_import(self):
+        with TemporaryDirectory() as temp_dir:
+            root = Path(temp_dir)
+            (root / "models.py").write_text(
+                "class LaterType:\n"
+                "    pass\n",
+                encoding="utf-8",
+            )
+            (root / "consumer.py").write_text(
+                "from typing import TYPE_CHECKING\n"
+                "from src.validating import validate\n"
+                "\n"
+                "if TYPE_CHECKING:\n"
+                "    from models import LaterType\n"
+                "\n"
+                "@validate\n"
+                "def build(value: 'LaterType') -> 'LaterType':\n"
+                "    return value\n",
+                encoding="utf-8",
+            )
+
+            models_spec = spec_from_file_location("models", root / "models.py")
+            assert models_spec is not None and models_spec.loader is not None
+            models_module = module_from_spec(models_spec)
+            sys.modules["models"] = models_module
+            models_spec.loader.exec_module(models_module)
+
+            consumer_spec = spec_from_file_location("consumer", root / "consumer.py")
+            assert consumer_spec is not None and consumer_spec.loader is not None
+            consumer_module = module_from_spec(consumer_spec)
+            sys.modules["consumer"] = consumer_module
+            consumer_spec.loader.exec_module(consumer_module)
+
+            instance = models_module.LaterType()
+            self.assertIs(consumer_module.build(instance), instance)
+            with self.assertRaises(TypeError):
+                consumer_module.build(1)
+
     def test_validate_raises_for_unresolvable_string_annotation(self):
         @validate
         def add(a: "MissingType") -> int: