didactic 0.4.0__tar.gz → 0.4.2__tar.gz

{didactic-0.4.0 → didactic-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: didactic
-Version: 0.4.0
+Version: 0.4.2
 Summary: Pydantic-class API on top of panproto: GATs, lenses, and VCS.
 Project-URL: Homepage, https://github.com/panproto/didactic
 Project-URL: Repository, https://github.com/panproto/didactic

{didactic-0.4.0 → didactic-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "didactic"
-version = "0.4.0"
+version = "0.4.2"
 description = "Pydantic-class API on top of panproto: GATs, lenses, and VCS."
 readme = "README.md"
 requires-python = ">=3.14"

{didactic-0.4.0 → didactic-0.4.2}/src/didactic/api.py

@@ -68,7 +68,7 @@ from didactic.types import _types_lib as types
 from didactic.vcs._backref import ModelPool, resolve_backrefs
 from didactic.vcs._repo import Repository
 
-__version__ = "0.4.0"
+__version__ = "0.4.2"
 
 #: Conventional namespace for lens utilities (`dx.lens.identity(...)`,
 #: `dx.lens.Lens`, etc.). The ``lens`` name doubles as a decorator

{didactic-0.4.0 → didactic-0.4.2}/src/didactic/models/_meta.py

@@ -348,6 +348,7 @@ class ModelMeta(type):
     __model_config__: ModelConfig
     __computed_fields__: tuple[str, ...]
     __class_axioms__: tuple[Axiom, ...]
+    __field_validators__: dict[str, tuple[tuple[str, str], ...]]
     __theory_cache__: panproto.Theory | None
 
     @property
@@ -397,6 +398,7 @@ class ModelMeta(type):
             cls.__model_config__ = DEFAULT_CONFIG
             cls.__computed_fields__ = ()
             cls.__class_axioms__ = ()
+            cls.__field_validators__ = {}
             return cls
 
         cls.__schema_kind__ = name
@@ -404,6 +406,7 @@ class ModelMeta(type):
         cls.__field_specs__ = ModelMeta.collect_field_specs(cls)
         cls.__computed_fields__ = computed_field_names(cls)
         cls.__class_axioms__ = collect_class_axioms(cls)
+        cls.__field_validators__ = ModelMeta.collect_field_validators(cls)
         # placeholder for the cached panproto.Theory; populated lazily
         # by the `__theory__` property the metaclass exposes below.
         cls.__theory_cache__ = None
@@ -541,6 +544,65 @@ class ModelMeta(type):
 
         return seen
 
+    @staticmethod
+    def collect_field_validators(
+        target: type,
+    ) -> dict[str, tuple[tuple[str, str], ...]]:
+        """Walk MRO and collect ``@validates``-tagged methods.
+
+        Parameters
+        ----------
+        target
+            The class to inspect.
+
+        Returns
+        -------
+        dict
+            Mapping ``field_name -> tuple of (method_name, mode)`` in
+            registration order. Methods are stored by name (not bound
+            callable) so that subclasses overriding a validator method
+            transparently take effect: ``getattr(cls, method_name)`` at
+            call time picks up the override via normal MRO.
+
+        Notes
+        -----
+        Walks ``target.__mro__`` in reverse so subclass declarations
+        override ancestor declarations. A subclass method that shadows
+        an ancestor validator *without* re-applying ``@validates``
+        unregisters that method's marker; the override is taken at face
+        value.
+        """
+        # method_name -> marker dict, populated in reverse-MRO order so
+        # the subclass entry wins. Subclass methods that shadow without
+        # the marker remove the ancestor entry.
+        markers: dict[str, dict[str, Opaque]] = {}
+        for klass in reversed(target.__mro__):
+            if not isinstance(klass, ModelMeta):
+                continue
+            for member_name, member in vars(klass).items():
+                if member_name.startswith("__"):
+                    continue
+                marker = getattr(member, "__didactic_validator__", None)
+                if marker is None:
+                    func = getattr(member, "__func__", None)
+                    if func is not None:
+                        marker = getattr(func, "__didactic_validator__", None)
+                if marker is not None:
+                    markers[member_name] = cast("dict[str, Opaque]", marker)
+                elif callable(member) and member_name in markers:
+                    # subclass shadows the ancestor validator without
+                    # re-tagging; honour the override and drop the marker
+                    del markers[member_name]
+
+        # invert to per-field tuples, preserving registration order
+        per_field: dict[str, list[tuple[str, str]]] = {}
+        for member_name, marker in markers.items():
+            field_names = cast("tuple[str, ...]", marker["fields"])
+            mode = cast("str", marker["mode"])
+            for fname in field_names:
+                per_field.setdefault(fname, []).append((member_name, mode))
+        return {fname: tuple(items) for fname, items in per_field.items()}
+
 
 __all__ = [
     "ModelMeta",

{didactic-0.4.0 → didactic-0.4.2}/src/didactic/models/_model.py

@@ -22,10 +22,13 @@ didactic.models._storage : the pluggable storage backend.
 """
 
 # ``__init__(**kwargs: FieldValue | JsonValue)`` accepts JSON-shape
-# dicts but pyright doesn't carry the union through ``_encode_field``.
+# dicts but pyright doesn't carry the union through the field
+# pipeline; the per-call ``cast("FieldValue", value)`` covers this.
 from __future__ import annotations
 
+import inspect
 import json
+from dataclasses import dataclass
 from datetime import date, datetime, time
 from decimal import Decimal
 from types import UnionType
@@ -51,7 +54,7 @@ from didactic.models._meta import ModelMeta, read_class_annotations
 from didactic.models._storage import DictStorage
 
 if TYPE_CHECKING:
-    from collections.abc import Mapping
+    from collections.abc import Callable, Mapping
 
     from didactic.axioms._axioms import Axiom
     from didactic.codegen._json_schema import JsonSchemaDoc
@@ -180,7 +183,18 @@ class Model(metaclass=ModelMeta):
                 value = default
 
             try:
-                encoded_value = _encode_field(spec, cast("FieldValue", value))
+                encoded_value = _run_field_pipeline(
+                    cls, spec, fname, cast("FieldValue", value)
+                )
+            except _ValidatorError as fail:
+                errors.append(
+                    ValidationErrorEntry(
+                        loc=(fname,),
+                        type="validator_error",
+                        msg=fail.message,
+                    )
+                )
+                continue
             except (TypeError, ValueError) as exc:
                 errors.append(
                     ValidationErrorEntry(
@@ -319,7 +333,13 @@ class Model(metaclass=ModelMeta):
                 )
                 continue
             try:
-                encoded[k] = _encode_field(specs[k], v)
+                encoded[k] = _run_field_pipeline(cls, specs[k], k, v)
+            except _ValidatorError as fail:
+                errors.append(
+                    ValidationErrorEntry(
+                        loc=(k,), type="validator_error", msg=fail.message
+                    )
+                )
             except (TypeError, ValueError) as exc:
                 errors.append(
                     ValidationErrorEntry(loc=(k,), type="type_error", msg=str(exc))
@@ -1031,15 +1051,56 @@ def _from_json_payload(
     return out
 
 
-def _encode_field(spec: FieldSpec, value: FieldValue) -> Encoded:
-    """Run the converter (if any) and the type-translation encoder.
+@dataclass(frozen=True, slots=True)
+class _ValidatorError(Exception):
+    """Internal error type carrying a ``@validates``-raised message.
+
+    Wraps the ``ValueError`` / ``TypeError`` raised by a user
+    validator so the ``__init__`` and ``with_()`` paths can route the
+    failure to a ``"validator_error"`` ``ValidationErrorEntry``
+    instead of conflating it with the encoder's ``"type_error"``.
+    """
+
+    message: str
+
+
+def _invoke_validator(cls: type, method_name: str, value: FieldValue) -> FieldValue:
+    """Invoke a ``@validates``-tagged method with class-level binding.
+
+    Both ``@classmethod`` and plain instance methods are supported.
+    Instance methods receive the class as their first argument (the
+    Model is frozen and not yet constructed when validators run, so
+    no instance ``self`` exists). ``@staticmethod`` validators are
+    called with the value alone.
+    """
+    descriptor = inspect.getattr_static(cls, method_name)
+    if isinstance(descriptor, staticmethod):
+        sm = cast("staticmethod[..., FieldValue]", descriptor)
+        return sm.__func__(value)
+    if isinstance(descriptor, classmethod):
+        cm = cast("classmethod[type, ..., FieldValue]", descriptor)
+        return cm.__func__(cls, value)
+    return cast("Callable[..., FieldValue]", descriptor)(cls, value)
+
+
+def _run_field_pipeline(
+    cls: type,
+    spec: FieldSpec,
+    fname: str,
+    value: FieldValue,
+) -> Encoded:
+    """Run converter, before-validators, encoder, after-validators.
 
     Parameters
     ----------
+    cls
+        The Model class (used to look up validators and bind them).
     spec
         The field's spec.
+    fname
+        Field name; used to find registered validators.
     value
-        The user-supplied value.
+        The raw user-supplied value (or the resolved default).
 
     Returns
     -------
@@ -1048,12 +1109,49 @@ def _encode_field(spec: FieldSpec, value: FieldValue) -> Encoded:
 
     Raises
     ------
+    _ValidatorError
+        A ``@validates`` callback raised ``ValueError`` or ``TypeError``.
     TypeError or ValueError
-        If the value cannot be encoded.
+        The encoder rejected the value (mismatched type, failed
+        ``Annotated[...]`` constraint, etc.).
     """
     if spec.converter is not None:
         value = spec.converter(value)
-    return spec.translation.encode(value)
+
+    validators: tuple[tuple[str, str], ...] = cast(
+        "ModelMeta", cls
+    ).__field_validators__.get(fname, ())
+
+    for method_name, mode in validators:
+        if mode != "before":
+            continue
+        try:
+            value = _invoke_validator(cls, method_name, value)
+        except (ValueError, TypeError) as exc:
+            raise _ValidatorError(str(exc)) from exc
+
+    encoded_value = spec.translation.encode(value)
+
+    if not any(mode == "after" for _, mode in validators):
+        return encoded_value
+
+    # ``after`` validators see the canonical decoded form, mirroring
+    # Pydantic's behaviour where the post-coercion value is what the
+    # validator inspects. Re-encode if any validator returned a
+    # different value.
+    typed: FieldValue = spec.translation.decode(encoded_value)
+    new_value = typed
+    for method_name, mode in validators:
+        if mode != "after":
+            continue
+        try:
+            new_value = _invoke_validator(cls, method_name, new_value)
+        except (ValueError, TypeError) as exc:
+            raise _ValidatorError(str(exc)) from exc
+
+    if new_value is typed:
+        return encoded_value
+    return spec.translation.encode(new_value)
 
 
 # alias for adoption ergonomics

{didactic-0.4.0 → didactic-0.4.2}/src/didactic/types/_types.py

@@ -1357,8 +1357,18 @@ def _make_list_encoder(
 ) -> Callable[[FieldValue], Encoded]:
     def enc(v: FieldValue) -> Encoded:
         # JSON-encode the encoded items; the panproto string is therefore
-        # always a valid JSON array literal.
-        assert isinstance(v, tuple)
+        # always a valid JSON array literal. Accept list as well as tuple
+        # so call sites migrating from Pydantic (which transparently
+        # coerces list to tuple for tuple-typed fields) do not have to
+        # rewrite every ``indices=[0, 1, 2]`` literal. Reject anything
+        # else with ``TypeError`` so the caller's ``ValidationError``
+        # carries the field name instead of a bare ``AssertionError``.
+        if not isinstance(v, (tuple, list)):
+            msg = (
+                f"expected tuple or list for tuple[T, ...] field, "
+                f"got {type(v).__name__}"
+            )
+            raise TypeError(msg)
         return json.dumps([inner_encode(item) for item in v])
 
     return enc
@@ -1384,7 +1394,20 @@ def _classify_frozenset(args: tuple[TypeForm, ...]) -> TypeTranslation:
     inner = classify(args[0])
 
     def enc(v: FieldValue) -> Encoded:
-        assert isinstance(v, frozenset)
+        # Accept any non-string iterable that can lawfully be coerced to
+        # ``frozenset`` (set, frozenset, list, tuple). The same reasoning
+        # as the tuple encoder applies: Pydantic coerces, callers
+        # migrating across should not have to rewrite every literal, and
+        # rejecting via ``TypeError`` keeps the failure inside
+        # ``ValidationError``.
+        if isinstance(v, (str, bytes, bytearray)) or not isinstance(
+            v, (frozenset, set, list, tuple)
+        ):
+            msg = (
+                f"expected frozenset, set, list, or tuple for frozenset[T] "
+                f"field, got {type(v).__name__}"
+            )
+            raise TypeError(msg)
         return json.dumps(sorted(inner.encode(item) for item in v))
 
     def dec(s: Encoded) -> frozenset[FieldValue]: