didactic 0.3.2__tar.gz → 0.4.1__tar.gz

{didactic-0.3.2 → didactic-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: didactic
-Version: 0.3.2
+Version: 0.4.1
 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.3.2 → didactic-0.4.1}/pyproject.toml

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

{didactic-0.3.2 → didactic-0.4.1}/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.3.2"
+__version__ = "0.4.1"
 
 #: Conventional namespace for lens utilities (`dx.lens.identity(...)`,
 #: `dx.lens.Lens`, etc.). The ``lens`` name doubles as a decorator

{didactic-0.3.2 → didactic-0.4.1}/src/didactic/codegen/_json_schema.py

@@ -1,6 +1,3 @@
-# ``annotated_metadata`` lives on ``spec.extras`` as ``Opaque`` and
-# the per-marker iteration takes the marker as an opaque value to
-# duck-type. Tracked in panproto/didactic#1.
 """JSON Schema (Draft 2020-12) generation from a Model class.
 
 The single user-facing entry point is

{didactic-0.3.2 → didactic-0.4.1}/src/didactic/fields/_derived.py

@@ -42,12 +42,6 @@ See Also
 didactic.computed : evaluated every read; not cached.
 """
 
-# Reaches into ``Model._derived_cache`` (a documented Model-internal
-# slot) from a closure attached to the @derived decorator. The
-# ``_`` prefix is conventional for "implementation detail of the
-# Model layer"; the derived-decorator integration is part of that
-# layer. Tracked in panproto/didactic#1.
-
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, cast

{didactic-0.3.2 → didactic-0.4.1}/src/didactic/fields/_unions.py

@@ -1,7 +1,3 @@
-# ``TaggedUnion.model_validate`` overrides the base class with a
-# narrower payload type; the runtime accepts the base shape too. The
-# ``Literal[...]`` discriminator extraction goes through annotation
-# walking that pyright can't follow. Tracked in panproto/didactic#1.
 """Tagged (discriminated) unions over [Model][didactic.api.Model] subclasses.
 
 Pydantic-shaped discriminated unions: declare a base class with a

{didactic-0.3.2 → didactic-0.4.1}/src/didactic/migrations/_diff.py

@@ -1,6 +1,3 @@
-# ``diff_and_classify`` returns a ``CompatReport`` whose ``.to_dict()``
-# we re-emit as ``JsonObject``; pyright's stub doesn't narrow the
-# panproto-side types tightly enough. Tracked in panproto/didactic#1.
 """Schema diff and breaking-change detection.
 
 Two thin functions over panproto's ``diff_schemas`` and

{didactic-0.3.2 → didactic-0.4.1}/src/didactic/migrations/_fingerprint.py

@@ -1,7 +1,3 @@
-# ``structural_spec`` and friends shape ``TheorySpec`` (a TypedDict)
-# back into ``JsonObject`` (``dict[str, JsonValue]``); the dict
-# invariance bites. ``_default`` narrowing on tuple inputs is
-# pyright-flagged as redundant. Tracked in panproto/didactic#1.
 """Stable fingerprints for didactic Theory specs.
 
 didactic stores migration registry entries by a fingerprint that is

{didactic-0.3.2 → didactic-0.4.1}/src/didactic/models/_config.py

@@ -46,8 +46,13 @@ class ModelConfig:
     ----------
     extra
         How to handle keyword arguments that don't match a declared
-        field. Only ``"forbid"`` is honoured currently; ``"ignore"`` and
-        ``"allow"`` raise ``NotImplementedError``.
+        field. ``"forbid"`` (default) raises ``ValidationError`` on
+        any unknown key; ``"ignore"`` silently drops unknown keys at
+        construction (the dropped values never enter the model and
+        never appear in ``model_dump()``). ``"allow"`` raises
+        ``NotImplementedError`` (it needs a storage decision for
+        unknown fields that the immutable Model contract doesn't
+        cleanly support yet).
     strict
         If ``True``, type coercion is disabled; every field's value
         must already be the declared type. Default ``True``. ``False``
@@ -75,11 +80,16 @@ class ModelConfig:
                 f"got {self.extra!r}"
             )
             raise ValueError(msg)
-        # v0.0.1 only honours `forbid`; fail loud on the unsupported settings
-        if self.extra != "forbid":
+        # ``"forbid"`` and ``"ignore"`` are honoured at construction
+        # (in ``Model.__init__``). ``"allow"`` is reserved: storing
+        # unknown values where ``model_dump`` can find them while
+        # keeping the model frozen has no settled design.
+        if self.extra == "allow":
             msg = (
-                f"ModelConfig.extra={self.extra!r} is not yet implemented; "
-                "only 'forbid' is honoured."
+                "ModelConfig.extra='allow' is not yet implemented; the "
+                "frozen-Model contract has no settled storage path for "
+                "unknown fields. Use 'ignore' to drop them silently or "
+                "'forbid' to reject them."
             )
             raise NotImplementedError(msg)
         if not self.strict:

{didactic-0.3.2 → didactic-0.4.1}/src/didactic/models/_meta.py

@@ -1,10 +1,3 @@
-# The metaclass passes resolved annotations (``type | TypeVar |
-# ForwardRef``) into ``classify`` and ``_build_field_spec``, which
-# expect the narrower ``TypeForm`` (``type | UnionType``). The
-# runtime contract handles the wider input (the metaclass also
-# accepts string forward refs and TypeVar instances), but pyright
-# can't follow the case split through the dataclass_transform
-# layer. Tracked in panproto/didactic#1.
 """The ``ModelMeta`` metaclass: class-as-Theory derivation.
 
 ``ModelMeta`` runs at class-creation time. It reads each annotated field,
@@ -32,7 +25,14 @@ from __future__ import annotations
 import annotationlib
 import contextlib
 import sys
-from typing import TYPE_CHECKING, ForwardRef, TypeVar, cast, dataclass_transform
+from typing import (
+    TYPE_CHECKING,
+    ForwardRef,
+    TypeVar,
+    cast,
+    dataclass_transform,
+    get_args,
+)
 
 from didactic.axioms._axioms import collect_class_axioms
 from didactic.fields._computed import computed_field_names
@@ -101,7 +101,27 @@ def _deferred_from_json(_: JsonValue) -> FieldValue:
     raise TypeError(msg)
 
 
-def _read_class_annotations(cls: type) -> dict[str, type | ForwardRef]:
+def _annotation_contains_typevar(annotation: object, depth: int = 0) -> bool:
+    """Return True iff ``annotation`` contains a ``TypeVar`` anywhere in its shape.
+
+    Walks parameterised generics (``list[T]``, ``tuple[T, ...]``,
+    ``dict[str, T]``, ``Embed[T]``, ``Annotated[T, ...]``, unions of
+    these) and stops at the first ``TypeVar`` leaf. Depth-bounded so
+    pathological recursive aliases don't loop forever.
+    """
+    if depth > 64:
+        return False
+    if isinstance(annotation, TypeVar):
+        return True
+    args = get_args(annotation)
+    if not args:
+        return False
+    return any(
+        a is not Ellipsis and _annotation_contains_typevar(a, depth + 1) for a in args
+    )
+
+
+def read_class_annotations(cls: type) -> dict[str, type | TypeVar | ForwardRef]:
     """Read a class's annotations through ``annotationlib``, robustly.
 
     Parameters
@@ -147,7 +167,7 @@ def _read_class_annotations(cls: type) -> dict[str, type | ForwardRef]:
     localns: dict[str, Opaque] = dict(vars(cls))
     localns.setdefault(cls.__name__, cls)
 
-    resolved: dict[str, type | ForwardRef] = {}
+    resolved: dict[str, type | TypeVar | ForwardRef] = {}
     for name, ann in raw.items():
         if isinstance(ann, str):
             try:
@@ -206,6 +226,12 @@ def _build_field_spec(
         and annotation.__forward_arg__.isupper()
     ):
         tv_name = annotation.__forward_arg__
+    elif _annotation_contains_typevar(annotation):
+        # Nested TypeVar (e.g. ``items: tuple[T, ...]`` or
+        # ``by_name: dict[str, T]``). Defer the same way as a bare
+        # TypeVar; ``Model.__class_getitem__`` substitutes through
+        # the nested shape on parameterisation.
+        tv_name = "<nested>"
     if tv_name is not None:
         from didactic.types._types import TypeTranslation  # noqa: PLC0415
 
@@ -216,11 +242,32 @@ def _build_field_spec(
             inner_kind="generic",
             from_json=_deferred_from_json,
         )
+        # If the user supplied ``f: T = dx.field(default=..., description=...)``
+        # the Field descriptor's metadata must survive on the deferred spec
+        # so a parameterised subclass can propagate the default and metadata
+        # onto its own (concrete-annotation) FieldSpec. Plain values land in
+        # ``default`` directly.
+        if isinstance(raw_default, Field):
+            return FieldSpec(
+                name=name,
+                annotation=annotation,
+                translation=deferred,
+                default=raw_default.default,
+                default_factory=raw_default.default_factory,
+                converter=raw_default.converter,
+                alias=raw_default.alias,
+                description=raw_default.description,
+                examples=raw_default.examples,
+                deprecated=raw_default.deprecated,
+                nominal=raw_default.nominal,
+                usage_mode=raw_default.usage_mode,
+                extras=dict(raw_default.extras) if raw_default.extras else {},
+            )
         return FieldSpec(
             name=name,
             annotation=annotation,
             translation=deferred,
-            default=raw_default if not isinstance(raw_default, Field) else MISSING,
+            default=raw_default,
             usage_mode="readwrite",
         )
     # Above branches return for ``TypeVar`` / ``ForwardRef`` cases; the
@@ -464,17 +511,33 @@ class ModelMeta(type):
         """
         seen: dict[str, FieldSpec] = {}
 
-        # walk MRO in reverse so derived classes overwrite base entries
+        # walk MRO in reverse so derived classes overwrite base entries.
+        # For ancestor classes the FieldSpec is already finalised
+        # (defaults captured during their own construction); copy the
+        # spec verbatim. For ``target`` itself we re-run
+        # ``_build_field_spec`` because the raw default still lives on
+        # the class dict and hasn't been stripped yet. Reading
+        # ``__dict__`` for ancestor classes would surface no default,
+        # because the metaclass strips field defaults from the class
+        # dict at the end of each Model's class-creation step.
         for klass in reversed(target.__mro__):
             if not isinstance(klass, ModelMeta):
                 continue
-            anns = _read_class_annotations(klass)
-            for fname, ann in anns.items():
-                # skip private / dunder attributes
-                if fname.startswith("_"):
+            if klass is target:
+                anns = read_class_annotations(klass)
+                for fname, ann in anns.items():
+                    if fname.startswith("_"):
+                        continue
+                    raw_default = klass.__dict__.get(fname, MISSING)
+                    seen[fname] = _build_field_spec(fname, ann, raw_default)
+            else:
+                ancestor_specs = getattr(klass, "__field_specs__", None)
+                if ancestor_specs is None:
                     continue
-                raw_default = klass.__dict__.get(fname, MISSING)
-                seen[fname] = _build_field_spec(fname, ann, raw_default)
+                for fname, spec in ancestor_specs.items():
+                    if fname.startswith("_"):
+                        continue
+                    seen[fname] = spec
 
         return seen
 

{didactic-0.3.2 → didactic-0.4.1}/src/didactic/models/_model.py

@@ -28,15 +28,26 @@ from __future__ import annotations
 import json
 from datetime import date, datetime, time
 from decimal import Decimal
-from typing import TYPE_CHECKING, ClassVar, Self, cast
+from types import UnionType
+from typing import (
+    TYPE_CHECKING,
+    Annotated,
+    ClassVar,
+    Self,
+    TypeVar,
+    Union,
+    cast,
+    get_args,
+    get_origin,
+)
 from uuid import UUID
 
-from didactic.fields._fields import MissingType
+from didactic.fields._fields import MISSING, Field, MissingType
 from didactic.fields._validators import (
     ValidationError,
     ValidationErrorEntry,
 )
-from didactic.models._meta import ModelMeta
+from didactic.models._meta import ModelMeta, read_class_annotations
 from didactic.models._storage import DictStorage
 
 if TYPE_CHECKING:
@@ -90,6 +101,42 @@ class Model(metaclass=ModelMeta):
     __computed_fields__: ClassVar[frozenset[str]] = frozenset()
     __class_axioms__: ClassVar[tuple[Axiom, ...]] = ()
 
+    def __class_getitem__(cls, params: object) -> type[Model]:
+        """Auto-parameterise a generic Model on subscript.
+
+        ``Range[int]`` returns a concrete subclass of ``Range`` whose
+        ``T``-typed fields use ``int``. The synthesised class is
+        cached per ``cls`` and per type-arg tuple, so repeated
+        subscripts return the same class object (and that class's
+        ``Theory`` is built once).
+
+        Falls back to typing's machinery when ``cls`` declares no
+        ``TypeVar`` field annotations to substitute (the subscript
+        becomes a structural ``_GenericAlias`` for type checkers
+        only, no runtime synthesis).
+
+        Parameters
+        ----------
+        params
+            A type or a tuple of types matching the class's
+            ``__parameters__`` arity.
+
+        Returns
+        -------
+        type
+            A synthesised concrete subclass when at least one field
+            annotation can be substituted; otherwise the upstream
+            ``_GenericAlias``.
+
+        Notes
+        -----
+        Only bare ``TypeVar`` annotations are substituted. Annotations
+        that contain a ``TypeVar`` nested inside a generic shape
+        (e.g. ``items: tuple[T, ...]``) stay unsubstituted and
+        surface the existing ``TypeVar``-encode error.
+        """
+        return _parameterise(cls, params)
+
     def __init__(self, **kwargs: FieldValue | JsonValue) -> None:
         """Construct a Model from keyword arguments.
 
@@ -153,9 +200,15 @@ class Model(metaclass=ModelMeta):
         from didactic.fields._derived import derived_field_names  # noqa: PLC0415
 
         derived_names = derived_field_names(cls)
+        # ``extra="ignore"`` silently drops unknown kwargs at construction.
+        # ``with_()`` stays strict regardless: an unknown kwarg there is
+        # always a programming error (see ``Model.with_``).
+        ignore_extra = cls.__model_config__.extra == "ignore"
         for k in kwargs:
             if k in specs or k in computed_names or k in derived_names:
                 continue
+            if ignore_extra:
+                continue
             errors.append(
                 ValidationErrorEntry(
                     loc=(k,),
@@ -681,7 +734,225 @@ class Model(metaclass=ModelMeta):
 # ---------------------------------------------------------------------------
 
 
-def _to_json_safe(value: FieldValue | JsonValue) -> JsonValue:  # noqa: PLR0911
+def _parameterise(cls: type[Model], params: object) -> type[Model]:
+    """Synthesise (or fetch from cache) a concrete subclass of a generic ``cls``.
+
+    Implementation of ``Model.__class_getitem__``; lifted to a
+    module-level function so the static-type narrowing of ``params``
+    isn't trapped behind a class scope's restricted self/cls vocabulary.
+    """
+    params_tuple: tuple[object, ...] = (
+        cast("tuple[object, ...]", params) if isinstance(params, tuple) else (params,)
+    )
+
+    typevars: tuple[TypeVar, ...] = cast(
+        "tuple[TypeVar, ...]", getattr(cls, "__parameters__", ())
+    )
+    if not typevars or len(typevars) != len(params_tuple):
+        return _fallback_subscript(cls, params_tuple)
+
+    cache: dict[tuple[object, ...], type[Model]] | None = cls.__dict__.get(
+        "__parameterised_cache__"
+    )
+    if cache is None:
+        cache = {}
+        # ``setattr`` rather than direct assignment so the metaclass's
+        # frozen-class guard doesn't fire on this private bookkeeping
+        # attribute (it's not in ``__field_specs__``).
+        cls.__parameterised_cache__ = cache  # type: ignore[attr-defined]
+    cached = cache.get(params_tuple)
+    if cached is not None:
+        return cached
+
+    substitution: dict[TypeVar, object] = dict(zip(typevars, params_tuple, strict=True))
+    base_anns = read_class_annotations(cls)
+    new_anns: dict[str, object] = {}
+    for fname, ann in base_anns.items():
+        substituted = _substitute_typevars(ann, substitution)
+        if substituted is not ann:
+            new_anns[fname] = substituted
+    if not new_anns:
+        return _fallback_subscript(cls, params_tuple)
+
+    arg_names = ", ".join(getattr(p, "__name__", str(p)) for p in params_tuple)
+    new_name = f"{cls.__name__}[{arg_names}]"
+    namespace: dict[str, object] = {
+        "__annotations__": new_anns,
+        "__module__": cls.__module__,
+        "__qualname__": new_name,
+    }
+    # Propagate every parent FieldSpec's default and metadata onto the
+    # synthesised class so the metaclass's MRO walk sees them as
+    # own-class defaults. Without this stamp, the substituted-annotation
+    # re-build sees raw_default=MISSING for the synth class and treats
+    # the field as required.
+    parent_specs: dict[str, FieldSpec] = getattr(cls, "__field_specs__", {})
+    for fname in new_anns:
+        spec = parent_specs.get(fname)
+        if spec is None:
+            continue
+        descriptor = _field_descriptor_from_spec(spec)
+        # MISSING is the sentinel meaning "no default and no metadata
+        # to propagate"; the field stays required on the synthesised
+        # class. Any other value (including ``None``) IS the default.
+        if descriptor is not MISSING:
+            namespace[fname] = descriptor
+    new_cls = cast("type[Model]", type(new_name, (cls,), namespace))
+    cache[params_tuple] = new_cls
+    return new_cls
+
+
+def _substitute_typevars(
+    annotation: object, substitution: dict[TypeVar, object]
+) -> object:
+    """Substitute ``TypeVar`` leaves in ``annotation`` against ``substitution``.
+
+    Walks through nested generic shapes and returns a new annotation
+    with every ``TypeVar`` replaced by its concrete type. Returns the
+    original ``annotation`` object when no substitution applies, so
+    callers can use identity comparison to detect changes.
+
+    Handled shapes:
+
+    - bare ``TypeVar`` -> the substitution target.
+    - parameterised generic (``list[T]``, ``tuple[T, U]``,
+      ``tuple[T, ...]``, ``dict[str, T]``, ``frozenset[T]``,
+      ``Embed[T]``, ``Ref[T]``, ``Annotated[T, ...]``, etc.) -> the
+      origin re-subscripted with substituted args.
+    - union (``T | int``, ``Union[T, str]``) -> a new union with each
+      arm substituted.
+    - non-generic types and ``ForwardRef`` -> returned as-is.
+
+    Recursion bottoms out at non-substitutable leaves (real types,
+    forward references, primitive literals).
+    """
+    # bare TypeVar leaf
+    if isinstance(annotation, TypeVar):
+        return substitution.get(annotation, annotation)
+
+    args = get_args(annotation)
+    if not args:
+        return annotation
+
+    new_args = tuple(_substitute_typevars(a, substitution) for a in args)
+    if new_args == args:
+        return annotation
+
+    origin = get_origin(annotation)
+    # PEP 604 / typing union: rebuild via ``typing.Union[(...)]`` which
+    # accepts a tuple of arms and produces the appropriate union form.
+    # Ruff prefers ``X | Y``, but that can't be expressed for a runtime
+    # tuple of arms; ``noqa: UP007`` keeps the dynamic form.
+    if origin in {Union, UnionType}:
+        return Union[new_args]  # noqa: UP007
+    # ``Annotated[T, *meta]`` keeps its metadata tuple. Pyright's
+    # static check on ``Annotated[<dynamic-tuple>]`` requires the args
+    # to be statically known. Route through ``typing._SpecialForm``'s
+    # subscript via the standard ``[...]`` syntax wrapped in ``cast``
+    # to a plain subscriptable; the runtime construction works because
+    # ``obj[a, b, c]`` is sugar for ``obj.__getitem__((a, b, c))``.
+    if origin is Annotated:
+        meta = args[1:]
+        new_base = new_args[0]
+        if new_base is args[0]:
+            return annotation
+        # ``Annotated`` is a ``typing._SpecialForm`` whose ``__getitem__``
+        # accepts a tuple ``(base, *meta)``. The subscript syntax compiles
+        # to that call exactly; pyright doesn't model the special form, so
+        # cast to a subscriptable proxy.
+        annotated_subscript: object = Annotated
+        return cast("object", annotated_subscript[(new_base, *meta)])  # type: ignore[index]
+    # Generic alias: re-subscript the origin with the new args.
+    # ``tuple[T, ...]`` keeps the Ellipsis sentinel verbatim because
+    # ``Ellipsis`` is not a TypeVar (substitution returns it unchanged).
+    if origin is None:
+        return annotation
+    if not new_args:
+        return annotation
+    try:
+        return origin[new_args[0]] if len(new_args) == 1 else origin[new_args]
+    except TypeError:
+        return annotation
+
+
+def _field_descriptor_from_spec(spec: FieldSpec) -> object:
+    """Reconstruct a ``Field`` descriptor (or bare default) from a ``FieldSpec``.
+
+    Used by ``_parameterise`` to propagate a generic-parent's defaults
+    and metadata onto the synthesised concrete subclass. Returns the
+    sentinel ``MISSING`` when the parent spec carried neither a
+    default nor any metadata that needs to round-trip through
+    ``Field``: in that case the field stays required on the
+    synthesised class, matching the parent's behaviour. Otherwise
+    returns either the bare default value (for plain ``f: T = 0``)
+    or a fully-populated ``Field`` descriptor (for any spec carrying
+    metadata beyond a default).
+    """
+    has_default = spec.default is not MISSING
+    has_factory = spec.default_factory is not None
+    has_metadata = bool(
+        spec.alias
+        or spec.description
+        or spec.examples
+        or spec.deprecated
+        or spec.nominal
+        or spec.converter
+        or spec.usage_mode != "readwrite"
+        or spec.extras
+    )
+    if not (has_default or has_factory or has_metadata):
+        return MISSING
+    if has_default and not has_metadata and not has_factory:
+        return spec.default
+    return Field(
+        default=spec.default,
+        default_factory=spec.default_factory,
+        converter=spec.converter,
+        alias=spec.alias,
+        description=spec.description,
+        examples=spec.examples,
+        deprecated=spec.deprecated,
+        nominal=spec.nominal,
+        usage_mode=spec.usage_mode,
+        extras=dict(spec.extras) if spec.extras else None,
+    )
+
+
+def _fallback_subscript(cls: type[Model], params: object) -> type[Model]:
+    """Defer a non-synthesisable ``cls[params]`` to typing's machinery.
+
+    When ``cls`` declares no ``Generic[...]`` parameters, or when
+    ``params`` doesn't substitute any of its TypeVar field
+    annotations, the subscript falls through here. ``Generic`` (if
+    present in the MRO) returns a ``_GenericAlias`` for the static
+    type checker; otherwise typing raises ``TypeError``.
+    """
+    # Walk the MRO past ``Model`` itself to find an ancestor's
+    # ``__class_getitem__`` (typically ``Generic.__class_getitem__``
+    # when the user wrote ``class Foo(dx.Model, Generic[T]): ...``).
+    # If no ancestor defines it, raise the same error typing would
+    # have raised for a non-generic class.
+    for base in cls.__mro__:
+        if base is Model:
+            continue
+        descriptor = base.__dict__.get("__class_getitem__")
+        if descriptor is None:
+            continue
+        # The descriptor is a classmethod (Generic), classmethod_descriptor
+        # (object), or function. ``__get__(None, cls)`` rebinds it to
+        # ``cls`` so the call invokes ``base.__class_getitem__(cls, params)``
+        # with ``cls`` as the receiver, matching the lookup ``cls[params]``
+        # would have produced if ``Model`` were not in the MRO.
+        rebound = descriptor.__get__(None, cls)
+        return cast("type[Model]", rebound(params))
+    msg = (
+        f"{cls.__name__!r} does not declare any ``Generic[...]`` "
+        "type parameters; subscripting is not supported."
+    )
+    raise TypeError(msg)
+
+
+def _to_json_safe(value: FieldValue | JsonValue) -> JsonValue:
     """Recursively coerce a decoded value into a JSON-encodable form.
 
     Parameters

{didactic-0.3.2 → didactic-0.4.1}/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]: