General purpose ensure

Author: Tinche

src/cattrs/__init__.py

@@ -11,20 +11,21 @@
     StructureHandlerNotFoundError,
 )
 from .gen import override
-from .v import transform_error
+from .v import ensure, transform_error
 
 __all__ = [
-    "structure",
-    "unstructure",
+    "ensure",
     "get_structure_hook",
     "get_unstructure_hook",
+    "global_converter",
     "register_structure_hook_func",
     "register_structure_hook",
     "register_unstructure_hook_func",
     "register_unstructure_hook",
     "structure_attrs_fromdict",
     "structure_attrs_fromtuple",
-    "global_converter",
+    "structure",
+    "unstructure",
     "BaseConverter",
     "Converter",
     "AttributeValidationNote",

src/cattrs/v/__init__.py

@@ -1,8 +1,8 @@
 """Cattrs validation."""
 
-from typing import Any, Callable, List, Union
+from typing import Annotated, Any, Callable, List, TypeVar, Union, overload
 
-from attrs import frozen
+from attrs import NOTHING, frozen
 
 from .._compat import ExceptionGroup
 from ..errors import (
@@ -146,3 +146,26 @@ def transform_error(
     else:
         errors.append(f"{format_exception(exc, None)} @ {path}")
     return errors
+
+
+T = TypeVar("T")
+E = TypeVar("E")
+
+
+@overload
+def ensure(
+    type: type[list[T]], *validators: Callable[[list[T]], Any], elems: type[E]
+) -> type[list[E]]: ...
+
+
+@overload
+def ensure(type: type[T], *validators: Callable[[T], Any]) -> type[T]: ...
+
+
+def ensure(type: Any, *validators: Any, elems: Any = NOTHING) -> Any:
+    if elems is not NOTHING:
+        # These are lists.
+        if not validators:
+            return type[elems]
+        return Annotated[type, VAnnotation(validators)]
+    return Annotated[type, VAnnotation(validators)]

src/cattrs/v/_hooks.py

@@ -0,0 +1,62 @@
+"""Hooks and hook factories for validation."""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from .._compat import Annotated, ExceptionGroup, is_annotated
+from ..dispatch import StructureHook
+from . import VAnnotation
+
+if TYPE_CHECKING:
+    from ..converters import BaseConverter
+
+
+def get_validator_annotation(type: Any) -> tuple[VAnnotation, Any] | None:
+    if is_annotated(type):
+        args = type.__metadata__
+        for arg in args:
+            if isinstance(arg, VAnnotation):
+                new_args = tuple(a for a in args[1:] if a is not arg)
+                if new_args:
+                    return Annotated(type.__origin__, *new_args)  # type: ignore
+                return arg, type.__origin__
+    return None
+
+
+def is_validated(type: Any) -> bool:
+    """The predicate for validated annotations."""
+    return get_validator_annotation(type) is not None
+
+
+def validator_factory(type: Any, converter: BaseConverter) -> StructureHook:
+    res = get_validator_annotation(type)
+    assert res is not None
+    val_annotation, type = res
+
+    base_hook = converter.get_structure_hook(type)
+
+    if converter.detailed_validation:
+
+        def validating_hook(val: Any, _: Any) -> Any:
+            res = base_hook(val, type)
+            errors = []
+            for validator in val_annotation.validators:
+                try:
+                    if validator(res) is False:
+                        raise ValueError(f"Validation failed for {res}")
+                except Exception as exc:
+                    errors.append(exc)
+            if errors:
+                raise ExceptionGroup("Value validation failed", errors)
+            return res
+
+    else:
+
+        def validating_hook(val: Any, _: Any) -> Any:
+            res = base_hook(val, type)
+            for validator in val_annotation.validators:
+                if validator(res) is False:
+                    raise ValueError(f"Validation failed for {res}")
+            return res
+
+    return validating_hook

tests/test_converter_typing.yml

@@ -0,0 +1,9 @@
+- case: sequence_structuring
+  main: |
+    from typing import Sequence
+    from cattrs import Converter
+
+    c = Converter()
+
+    # Maybe one day!
+    c.structure([], Sequence[int])  # E: Only concrete class can be given where "type[Sequence[int]]" is expected  [type-abstract]

tests/v/test_ensure.py

@@ -0,0 +1,76 @@
+"""Tests for `cattrs.v.ensure`."""
+import sys
+from typing import List, MutableSequence, Sequence
+
+from pytest import fixture, mark, raises
+
+from cattrs import BaseConverter
+from cattrs._compat import ExceptionGroup
+from cattrs.v import ensure
+from cattrs.v._hooks import is_validated, validator_factory
+
+
+@fixture
+def valconv(converter) -> BaseConverter:
+    converter.register_structure_hook_factory(is_validated)(validator_factory)
+    return converter
+
+
+def test_ensured_ints(valconv: BaseConverter):
+    """Validation for primitives works."""
+    assert valconv.structure("5", ensure(int, lambda i: i > 0))
+
+    with raises(Exception) as exc:
+        valconv.structure("-5", ensure(int, lambda i: i > 0))
+
+    if valconv.detailed_validation:
+        assert isinstance(exc.value, ExceptionGroup)
+        assert isinstance(exc.value.exceptions[0], ValueError)
+    else:
+        assert isinstance(exc.value, ValueError)
+
+
+def test_ensured_lists(valconv: BaseConverter):
+    """Validation for lists works."""
+    assert valconv.structure([1, 2], ensure(list[int], lambda lst: len(lst) > 0))
+
+    with raises(Exception) as exc:
+        valconv.structure([], ensure(list[int], lambda lst: len(lst) > 0))
+
+    if valconv.detailed_validation:
+        assert isinstance(exc.value, ExceptionGroup)
+        assert isinstance(exc.value.exceptions[0], ValueError)
+    else:
+        assert isinstance(exc.value, ValueError)
+
+
+@mark.parametrize("type", [List, Sequence, MutableSequence])
+def test_ensured_list_elements(valconv: BaseConverter, type):
+    """Validation for list elements works."""
+    assert valconv.structure([1, 2], ensure(type, elems=ensure(int, lambda i: i > 0)))
+
+    with raises(Exception) as exc:
+        valconv.structure([1, -2], ensure(type, elems=ensure(int, lambda i: i > 0)))
+
+    if valconv.detailed_validation:
+        assert isinstance(exc.value, ExceptionGroup)
+        assert isinstance(exc.value.exceptions[0], ExceptionGroup)
+        assert isinstance(exc.value.exceptions[0].exceptions[0], ValueError)
+    else:
+        assert isinstance(exc.value, ValueError)
+
+
+@mark.skipif(sys.version_info[:2] < (3, 10), reason="Not supported on older Pythons")
+def test_ensured_list(valconv: BaseConverter):
+    """Ensure works for builtin lists."""
+    assert valconv.structure([1, 2], ensure(list, elems=ensure(int, lambda i: i > 0)))
+
+    with raises(Exception) as exc:
+        valconv.structure([1, -2], ensure(list, elems=ensure(int, lambda i: i > 0)))
+
+    if valconv.detailed_validation:
+        assert isinstance(exc.value, ExceptionGroup)
+        assert isinstance(exc.value.exceptions[0], ExceptionGroup)
+        assert isinstance(exc.value.exceptions[0].exceptions[0], ValueError)
+    else:
+        assert isinstance(exc.value, ValueError)

tests/v/test_ensure_typing.yml

@@ -0,0 +1,49 @@
+- case: int_validation
+  main: |
+    from cattrs import v, Converter, ensure
+
+    c = Converter()
+
+    reveal_type(c.structure("5", ensure(int)))  # N: Revealed type is "builtins.int"
+
+    reveal_type(c.structure("5", ensure(int, lambda i: i > 5)))  # N: Revealed type is "builtins.int"
+
+    reveal_type(c.structure("5", ensure(int, v.greater_than(5))))  # N: Revealed type is "builtins.int"
+
+    c.structure("5", ensure(int, lambda i: len(i) > 5))  # E: Argument 1 to "len" has incompatible type "int"; expected "Sized"  [arg-type]
+- case: list_validation
+  main: |
+    from typing import List
+
+    from cattrs import v, Converter, ensure
+
+    c = Converter()
+
+    reveal_type(c.structure([], ensure(List[int])))  # N: Revealed type is "builtins.list[builtins.int]"
+
+    reveal_type(c.structure([], ensure(List[int], lambda lst: len(lst) > 0)))  # N: Revealed type is "builtins.list[builtins.int]"
+
+    reveal_type(c.structure([], ensure(List[int], v.len_between(1, 5))))  # N: Revealed type is "builtins.list[builtins.int]"
+- case: list_and_int_validation
+  main: |
+    from typing import List
+
+    from cattrs import Converter, ensure
+
+    c = Converter()
+
+    reveal_type(c.structure([], ensure(List, elems=ensure(int))))  # N: Revealed type is "builtins.list[builtins.int]"
+    reveal_type(c.structure([], ensure(List, elems=ensure(int, lambda i: i > 5))))  # N: Revealed type is "builtins.list[builtins.int]"
+
+    # Quite unfortunate this doesn't work.
+    c.structure([], List[ensure(int), lambda i: i > 5])  # E: Type expected within [...]  [misc]  # E: The type "type[list[Any]]" is not generic and not indexable  [misc]
+- case: sequence_and_int_validation
+  main: |
+    from typing import Sequence
+
+    from cattrs import Converter, ensure
+
+    c = Converter()
+
+    # This doesn't work because of no TypeForm.
+    c.structure([], ensure(Sequence, elems=ensure(int)))  # E: Argument 1 to "ensure" has incompatible type "type[Sequence[Any]]"; expected "type[list[Never]]"  [arg-type]