didactic-pydantic 0.1.0__tar.gz

didactic_pydantic-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# dev-only working notes, design drafts, scratch
+notes/
+
+# python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+
+# virtualenvs
+.venv/
+venv/
+env/
+
+# uv
+.uv/
+
+# testing / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+
+# type-checkers / linters
+.mypy_cache/
+.ruff_cache/
+.pyright/
+
+# mkdocs build output
+site/
+
+# editors
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# os
+.DS_Store
+Thumbs.db

didactic_pydantic-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: didactic-pydantic
+Version: 0.1.0
+Summary: Pydantic interop for didactic — adapters for incremental migration.
+Author-email: Aaron Steven White <aaronstevenwhite@gmail.com>
+License-Expression: MIT
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.14
+Requires-Dist: didactic
+Requires-Dist: pydantic>=2.10
+Description-Content-Type: text/markdown
+
+# didactic-pydantic
+
+Bidirectional adapter between `pydantic.BaseModel` and `dx.Model`.
+Contributes `didactic.pydantic` to the namespace package.
+
+## Install
+
+```sh
+pip install didactic-pydantic
+```
+
+The package depends on `didactic` and `pydantic>=2.10`.
+
+## from_pydantic
+
+Convert a `pydantic.BaseModel` subclass into a `dx.Model` subclass:
+
+```python
+from pydantic import BaseModel, Field
+from didactic.pydantic import from_pydantic
+
+
+class PydUser(BaseModel):
+    id: str
+    email: str = Field(description="primary contact")
+
+
+User = from_pydantic(PydUser)
+```
+
+Field annotations, defaults, factories, aliases, descriptions,
+examples, and the `deprecated` flag carry across.
+`Annotated[T, ...]` constraint metadata flows through unchanged, so
+`annotated-types` primitives (`Ge`, `Le`, ...) continue to produce
+axioms on the didactic side.
+
+Custom Pydantic validators (`@field_validator`, `@model_validator`),
+`@computed_field`, and discriminated unions are not translated; the
+[Pydantic interop guide](https://panproto.dev/didactic/guide/pydantic/)
+lists the didactic-side replacements.
+
+## to_pydantic
+
+The inverse direction:
+
+```python
+import didactic.api as dx
+from didactic.pydantic import to_pydantic
+
+
+class User(dx.Model):
+    id: str
+    email: str = dx.field(description="primary contact")
+
+
+PydUser = to_pydantic(User)
+```
+
+Use `to_pydantic` to expose a `dx.Model` to FastAPI, OpenAPI
+generators, or any other Pydantic-shaped tool. The conversion is
+cached, so repeated calls with the same input return the same
+Pydantic class.
+
+## Documentation
+
+See [Guides > Pydantic interop](https://panproto.dev/didactic/guide/pydantic/)
+for the full feature matrix and round-trip behaviour.
+
+## License
+
+MIT.

didactic_pydantic-0.1.0/README.md

@@ -0,0 +1,71 @@
+# didactic-pydantic
+
+Bidirectional adapter between `pydantic.BaseModel` and `dx.Model`.
+Contributes `didactic.pydantic` to the namespace package.
+
+## Install
+
+```sh
+pip install didactic-pydantic
+```
+
+The package depends on `didactic` and `pydantic>=2.10`.
+
+## from_pydantic
+
+Convert a `pydantic.BaseModel` subclass into a `dx.Model` subclass:
+
+```python
+from pydantic import BaseModel, Field
+from didactic.pydantic import from_pydantic
+
+
+class PydUser(BaseModel):
+    id: str
+    email: str = Field(description="primary contact")
+
+
+User = from_pydantic(PydUser)
+```
+
+Field annotations, defaults, factories, aliases, descriptions,
+examples, and the `deprecated` flag carry across.
+`Annotated[T, ...]` constraint metadata flows through unchanged, so
+`annotated-types` primitives (`Ge`, `Le`, ...) continue to produce
+axioms on the didactic side.
+
+Custom Pydantic validators (`@field_validator`, `@model_validator`),
+`@computed_field`, and discriminated unions are not translated; the
+[Pydantic interop guide](https://panproto.dev/didactic/guide/pydantic/)
+lists the didactic-side replacements.
+
+## to_pydantic
+
+The inverse direction:
+
+```python
+import didactic.api as dx
+from didactic.pydantic import to_pydantic
+
+
+class User(dx.Model):
+    id: str
+    email: str = dx.field(description="primary contact")
+
+
+PydUser = to_pydantic(User)
+```
+
+Use `to_pydantic` to expose a `dx.Model` to FastAPI, OpenAPI
+generators, or any other Pydantic-shaped tool. The conversion is
+cached, so repeated calls with the same input return the same
+Pydantic class.
+
+## Documentation
+
+See [Guides > Pydantic interop](https://panproto.dev/didactic/guide/pydantic/)
+for the full feature matrix and round-trip behaviour.
+
+## License
+
+MIT.

didactic_pydantic-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "didactic-pydantic"
+version = "0.1.0"
+description = "Pydantic interop for didactic — adapters for incremental migration."
+readme = "README.md"
+requires-python = ">=3.14"
+license = "MIT"
+authors = [
+    { name = "Aaron Steven White", email = "aaronstevenwhite@gmail.com" },
+]
+classifiers = [
+    "Development Status :: 2 - Pre-Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "didactic",
+    "pydantic>=2.10",
+]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/didactic/pydantic"]
+
+[tool.hatch.build.targets.wheel]
+only-include = ["src/didactic/pydantic"]
+sources = ["src"]

didactic_pydantic-0.1.0/src/didactic/pydantic/__init__.py

@@ -0,0 +1,54 @@
+"""didactic-pydantic: bidirectional adapter for Pydantic interop.
+
+Two complementary adapters:
+
+[from_pydantic][didactic.pydantic.from_pydantic]
+    ``BaseModel -> dx.Model``. For incremental adoption: convert one
+    Pydantic model at a time without rewriting field declarations by
+    hand.
+[to_pydantic][didactic.pydantic.to_pydantic]
+    ``dx.Model -> BaseModel``. For interop with FastAPI, OpenAPI
+    generators, and any Pydantic-shaped consumer that wants the
+    didactic model exposed as a ``BaseModel``.
+
+Notes
+-----
+The adapter is **structural**: it inspects a Pydantic v2
+``BaseModel``'s ``model_fields`` and constructs an equivalent
+[didactic.api.Model][didactic.api.Model] subclass. Per-field metadata that
+maps cleanly (default, default_factory, alias, description, examples,
+deprecated) is preserved. ``Annotated[...]`` constraint metadata
+flows through unchanged, so ``annotated-types`` primitives like
+``Ge``/``Le`` continue to produce axioms on the didactic side.
+
+Custom Pydantic validators (``@field_validator``, ``@model_validator``)
+are **not** translated; they live on the Pydantic side. If you need
+similar behaviour on the didactic side, port them to
+[didactic.api.validates][didactic.api.validates] manually.
+
+Examples
+--------
+>>> from pydantic import BaseModel, Field
+>>> from didactic.pydantic import from_pydantic
+>>>
+>>> class PydUser(BaseModel):
+...     id: str
+...     email: str = Field(description="primary contact")
+...     display_name: str = ""
+>>>
+>>> User = from_pydantic(PydUser)  # User is a dx.Model subclass
+>>> u = User(id="u1", email="a@b.c")
+>>> u.email
+'a@b.c'
+"""
+
+from didactic.pydantic._adapter import from_pydantic
+from didactic.pydantic._reverse import to_pydantic
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    "from_pydantic",
+    "to_pydantic",
+]

didactic_pydantic-0.1.0/src/didactic/pydantic/_adapter.py

@@ -0,0 +1,308 @@
+"""Pydantic v2 to didactic Model adapter.
+
+The single user-facing entry point is [from_pydantic][didactic.pydantic.from_pydantic].
+It walks a Pydantic ``BaseModel`` subclass's ``model_fields`` and produces
+an equivalent [didactic.api.Model][didactic.api.Model] subclass.
+
+Notes
+-----
+Mapping table (Pydantic FieldInfo on the left, didactic.field on the right)::
+
+    annotation                    ->  class annotation
+    default (PydanticUndefined)   ->  MISSING
+    default_factory               ->  default_factory
+    alias / validation_alias      ->  alias
+    description                   ->  description
+    examples                      ->  examples
+    metadata (Annotated)          ->  passes through verbatim
+    deprecated                    ->  deprecated
+    init_var / repr (Pydantic)    ->  ignored (no didactic equivalent)
+    json_schema_extra             ->  extras["json_schema_extra"]
+    frozen                        ->  ignored (didactic Models are always frozen)
+
+Pydantic features explicitly **not** translated:
+
+- ``@field_validator`` / ``@model_validator``: keep on the Pydantic
+  side or re-implement with [didactic.api.validates][didactic.api.validates].
+- ``@computed_field``: re-author with [didactic.api.computed][didactic.api.computed].
+- Discriminated unions: re-author with
+  [didactic.api.TaggedUnion][didactic.api.TaggedUnion].
+
+See Also
+--------
+didactic.Model : the base class produced by from_pydantic.
+"""
+
+from __future__ import annotations
+
+import inspect
+from typing import TYPE_CHECKING, Annotated, cast
+
+from pydantic_core import PydanticUndefined
+
+import didactic.api as dx
+from didactic.fields._fields import MISSING
+from didactic.models._meta import ModelMeta
+from pydantic import BaseModel
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+
+    from didactic.types._typing import FieldValue, Opaque
+    from pydantic.fields import FieldInfo
+
+
+def from_pydantic(
+    pyd_cls: type,
+    *,
+    name: str | None = None,
+) -> type[dx.Model]:
+    """Derive a [Model][didactic.api.Model] subclass from a Pydantic ``BaseModel``.
+
+    Parameters
+    ----------
+    pyd_cls
+        The Pydantic ``BaseModel`` subclass to translate.
+    name
+        Optional name for the new didactic class. Defaults to
+        ``pyd_cls.__name__``.
+
+    Returns
+    -------
+    type
+        A new [didactic.api.Model][didactic.api.Model] subclass with one field per
+        ``pyd_cls.model_fields`` entry.
+
+    Raises
+    ------
+    TypeError
+        If ``pyd_cls`` is not a Pydantic v2 ``BaseModel`` subclass.
+
+    Notes
+    -----
+    The new class lives in the same module as ``pyd_cls`` (its
+    ``__module__`` is set accordingly) so that any forward references
+    inside its annotations resolve against the same globals.
+
+    Examples
+    --------
+    >>> from pydantic import BaseModel, Field
+    >>> class PydUser(BaseModel):
+    ...     id: str
+    ...     email: str = Field(description="primary contact")
+    >>> User = from_pydantic(PydUser)
+    >>> issubclass(User, dx.Model)
+    True
+    >>> u = User(id="u1", email="a@b.c")
+    >>> u.email
+    'a@b.c'
+    """
+    if not issubclass(pyd_cls, BaseModel):
+        msg = (
+            f"from_pydantic requires a Pydantic v2 BaseModel subclass; got {pyd_cls!r}"
+        )
+        raise TypeError(msg)
+
+    target_name = name or pyd_cls.__name__
+    annotations: dict[str, type] = {}
+    namespace: dict[str, Opaque] = {}
+
+    for fname, info in pyd_cls.model_fields.items():
+        annotation = _resolve_annotation(info)
+        annotations[fname] = annotation
+
+        # we emit a dx.field(...) whenever there's any Pydantic-side metadata
+        # to carry; default, factory, alias, description, examples, deprecated,
+        # or json_schema_extra. Required fields with no metadata don't need a
+        # didactic Field descriptor.
+        if _has_metadata(info, PydanticUndefined):
+            namespace[fname] = _to_dx_field(info, PydanticUndefined)
+
+    namespace["__annotations__"] = annotations
+    if pyd_cls.__doc__:
+        namespace["__doc__"] = pyd_cls.__doc__
+    namespace["__module__"] = pyd_cls.__module__
+
+    cls = ModelMeta(target_name, (dx.Model,), namespace)
+    return cast("type[dx.Model]", cls)
+
+
+def _resolve_annotation(info: FieldInfo) -> type:
+    """Reconstruct the original ``Annotated[...]`` annotation for a Pydantic field.
+
+    Pydantic stores constraint metadata on ``info.metadata`` separately from
+    the base annotation. The didactic metaclass expects these on the
+    annotation itself (as ``Annotated[T, ...]``) so we splice them back in.
+
+    Parameters
+    ----------
+    info
+        The Pydantic ``FieldInfo`` for one field.
+
+    Returns
+    -------
+    type
+        Either the bare type or an ``Annotated[T, *metadata]`` form.
+    """
+    base = info.annotation
+    if base is None:
+        msg = "Pydantic FieldInfo has no annotation; cannot translate."
+        raise TypeError(msg)
+    metadata = tuple(info.metadata or ())
+    if not metadata:
+        return base
+    return Annotated[base, *metadata]  # type: ignore[valid-type]
+
+
+def _is_required(info: FieldInfo, undefined: Opaque) -> bool:
+    """Whether the Pydantic field has no default and no factory."""
+    has_default = info.default is not undefined
+    has_factory = info.default_factory is not None
+    return not (has_default or has_factory)
+
+
+def _has_metadata(info: FieldInfo, undefined: Opaque) -> bool:
+    """Whether the FieldInfo carries any metadata worth materialising as a Field.
+
+    Returns
+    -------
+    bool
+        ``True`` if any of: a default, a default_factory, an alias, a
+        description, examples, the deprecated flag, or json_schema_extra
+        are set.
+    """
+    return (
+        info.default is not undefined
+        or info.default_factory is not None
+        or info.alias is not None
+        or info.validation_alias is not None
+        or info.description is not None
+        or bool(info.examples)
+        or bool(info.deprecated)
+        or info.json_schema_extra is not None
+    )
+
+
+def _to_dx_field(info: FieldInfo, undefined: Opaque) -> dx.Field:
+    """Translate one ``FieldInfo`` into a [didactic.api.field][didactic.api.field] call.
+
+    Parameters
+    ----------
+    info
+        The Pydantic ``FieldInfo``.
+    undefined
+        Pydantic's ``PydanticUndefined`` sentinel; passed in so we don't
+        need to re-import it per call.
+
+    Returns
+    -------
+    Field
+        The didactic Field descriptor.
+    """
+    # Build a Field directly so each attribute is typed precisely; the
+    # `field()` overloads are tuned for human-written class bodies, not
+    # for kwargs-spreading from a heterogeneous source dict.
+    extras: Mapping[str, Opaque] | None = None
+    if info.json_schema_extra is not None and not callable(info.json_schema_extra):
+        extras = {"json_schema_extra": dict(info.json_schema_extra)}
+
+    raw_alias = info.alias if info.alias is not None else info.validation_alias
+    alias = raw_alias if isinstance(raw_alias, str) else None
+
+    examples: tuple[FieldValue, ...] = ()
+    if info.examples:
+        examples = tuple(_coerce_example(e) for e in info.examples)
+
+    return dx.Field(
+        default=info.default if info.default is not undefined else MISSING,
+        default_factory=_coerce_factory(info.default_factory),
+        alias=alias,
+        description=info.description,
+        examples=examples,
+        deprecated=bool(info.deprecated),
+        extras=extras,
+    )
+
+
+def _coerce_example(value: object) -> FieldValue:
+    """Narrow an arbitrary Pydantic example value to ``FieldValue``.
+
+    Pydantic stores examples as ``list[Any]``; didactic's ``examples``
+    tuple is typed as ``tuple[FieldValue, ...]``. We accept the value
+    structurally and let the metaclass / validation surface any real
+    mismatch at class-construction time.
+    """
+    # FieldValue is a recursive union covering all JSON-shaped scalars,
+    # tuples, frozensets, dicts, and Models. A runtime isinstance check
+    # against the union would be expensive and brittle; the contract
+    # here is "Pydantic gave us a value the user wrote as an example,
+    # so we trust it as a FieldValue".
+    if isinstance(value, (str, int, float, bool, bytes, type(None))):
+        return value
+    if isinstance(value, (tuple, list)):
+        seq = cast("tuple[FieldValue, ...] | list[FieldValue]", value)
+        return tuple(_coerce_example(v) for v in seq)
+    if isinstance(value, dict):
+        items = cast("dict[str, FieldValue]", value)
+        return {str(k): _coerce_example(v) for k, v in items.items()}
+    if isinstance(value, frozenset):
+        members = cast("frozenset[FieldValue]", value)
+        return frozenset(_coerce_example(v) for v in members)
+    msg = f"Unsupported example value of type {type(value).__name__}: {value!r}"
+    raise TypeError(msg)
+
+
+def _coerce_factory(
+    factory: object,
+) -> Callable[[], FieldValue] | None:
+    """Validate that a Pydantic ``default_factory`` is the zero-arg form.
+
+    Pydantic v2 supports a one-arg ``default_factory(validated_data)`` form
+    that didactic does not model; we only forward the zero-arg case. The
+    returned object is the same callable, narrowed by an arity check so
+    the static type ``Callable[[], FieldValue]`` is honest.
+    """
+    if factory is None:
+        return None
+    if not callable(factory):
+        msg = f"default_factory must be callable, got {factory!r}"
+        raise TypeError(msg)
+    arity = _zero_arg_arity(factory)
+    if not arity:
+        msg = (
+            "from_pydantic only supports zero-argument default_factory; "
+            f"got a callable that requires arguments: {factory!r}"
+        )
+        raise TypeError(msg)
+    # Pydantic types default_factory loosely (it returns ``Any`` and may
+    # also accept a one-arg ``validated_data`` form). The arity check
+    # above establishes the zero-arg contract didactic requires; we use
+    # ``cast`` (the standard typed-Python narrowing primitive) to expose
+    # the original callable under didactic's narrower signature without
+    # wrapping, so identity is preserved (tests compare with ``is``).
+    return cast("Callable[[], FieldValue]", factory)
+
+
+def _zero_arg_arity(func: Callable[..., object]) -> bool:
+    """Return ``True`` if ``func`` can be called with zero positional args."""
+    try:
+        sig = inspect.signature(func)
+    except TypeError, ValueError:
+        # Built-ins like ``tuple`` may not expose a signature; assume OK.
+        return True
+    for param in sig.parameters.values():
+        if param.kind in (
+            inspect.Parameter.VAR_POSITIONAL,
+            inspect.Parameter.VAR_KEYWORD,
+        ):
+            continue
+        if param.default is inspect.Parameter.empty and param.kind in (
+            inspect.Parameter.POSITIONAL_ONLY,
+            inspect.Parameter.POSITIONAL_OR_KEYWORD,
+            inspect.Parameter.KEYWORD_ONLY,
+        ):
+            return False
+    return True
+
+
+__all__ = ["_is_required", "from_pydantic"]

didactic_pydantic-0.1.0/src/didactic/pydantic/_reverse.py

@@ -0,0 +1,241 @@
+"""didactic Model to Pydantic v2 BaseModel adapter.
+
+The single user-facing entry point is
+[to_pydantic][didactic.pydantic.to_pydantic]. It walks a didactic
+[Model][didactic.api.Model] subclass's ``__field_specs__`` and produces an
+equivalent Pydantic ``BaseModel`` subclass, suitable for use with
+FastAPI, OpenAPI generators, and any other Pydantic-shaped consumer.
+
+Notes
+-----
+Mapping table (didactic FieldSpec on the left, Pydantic FieldInfo on the right)::
+
+    annotation          ->  field annotation
+    default (MISSING)   ->  PydanticUndefined  (required)
+    default             ->  default
+    default_factory     ->  default_factory
+    alias               ->  alias / validation_alias / serialization_alias
+    description         ->  description
+    examples            ->  examples
+    deprecated          ->  deprecated
+    axioms (Annotated)  ->  passes through verbatim on the annotation
+    extras              ->  json_schema_extra
+    converter           ->  ignored (Pydantic doesn't have a direct equivalent)
+    nominal             ->  ignored (Pydantic has no vertex-identity concept)
+    usage_mode          ->  ignored
+
+didactic concepts that have no clean Pydantic equivalent are dropped
+silently:
+
+- Computed fields ([didactic.api.computed][didactic.api.computed]) are dropped.
+  Re-author with ``@computed_field`` on the Pydantic side if you need
+  them.
+- Tagged unions ([didactic.api.TaggedUnion][didactic.api.TaggedUnion]) are
+  dropped. Re-author with Pydantic's discriminated unions.
+- Validators ([didactic.api.validates][didactic.api.validates]) are dropped.
+  Re-author with ``@field_validator`` / ``@model_validator``.
+
+See Also
+--------
+didactic.pydantic.from_pydantic : the inverse direction.
+didactic.Model : the input class.
+"""
+
+# Local PEP 695 type alias inside a function body and a heterogeneous
+# kwargs dict for the dynamic-pydantic-Field construction.
+# Tracked in panproto/didactic#1.
+# pyright: reportArgumentType=false, reportGeneralTypeIssues=false
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Annotated, cast
+
+import didactic.api as dx
+from didactic.fields._fields import MISSING
+from pydantic import BaseModel, Field, create_model
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from didactic.fields._fields import FieldSpec
+    from didactic.types._typing import FieldValue
+    from pydantic.fields import FieldInfo
+
+
+def to_pydantic(
+    dx_cls: type[dx.Model],
+    *,
+    name: str | None = None,
+) -> type[BaseModel]:
+    """Derive a Pydantic ``BaseModel`` subclass from a didactic Model.
+
+    Parameters
+    ----------
+    dx_cls
+        The [didactic.api.Model][didactic.api.Model] subclass to translate.
+    name
+        Optional name for the new Pydantic class. Defaults to
+        ``dx_cls.__name__``.
+
+    Returns
+    -------
+    type
+        A new Pydantic ``BaseModel`` subclass with one field per
+        ``dx_cls.__field_specs__`` entry.
+
+    Raises
+    ------
+    TypeError
+        If ``dx_cls`` is not a [didactic.api.Model][didactic.api.Model] subclass.
+
+    Notes
+    -----
+    The new class lives in the same module as ``dx_cls`` so that any
+    forward references inside its annotations resolve against the same
+    globals. Computed fields and tagged-union variants are skipped;
+    only ``readwrite`` fields are translated.
+
+    Examples
+    --------
+    >>> import didactic.api as dx
+    >>> from didactic.pydantic import to_pydantic
+    >>>
+    >>> class User(dx.Model):
+    ...     id: str
+    ...     email: str = dx.field(description="primary contact")
+    >>>
+    >>> PydUser = to_pydantic(User)
+    >>> issubclass(PydUser, BaseModel)
+    True
+    >>> u = PydUser(id="u1", email="a@b.c")
+    >>> u.email
+    'a@b.c'
+    """
+    # static type already says ``type[dx.Model]``; the runtime check
+    # catches users who bypass type-checking and hand in a non-Model.
+    if not (isinstance(dx_cls, type) and issubclass(dx_cls, dx.Model)):  # pyright: ignore[reportUnnecessaryIsInstance]
+        msg = f"to_pydantic requires a didactic.Model subclass; got {dx_cls!r}"
+        raise TypeError(msg)
+
+    target_name = name or dx_cls.__name__
+    fields: dict[str, tuple[type, FieldInfo]] = {}
+
+    for fname, spec in dx_cls.__field_specs__.items():
+        if spec.usage_mode != "readwrite":
+            # computed and materialised fields don't translate cleanly;
+            # they would need re-authoring as @computed_field on the
+            # Pydantic side
+            continue
+
+        annotation = _annotation_with_axioms(spec)
+        field_info = _to_pydantic_field(spec)
+        fields[fname] = (annotation, field_info)
+
+    # ``create_model``'s overload signature treats every keyword as a
+    # candidate for one of its named parameters (``__config__``,
+    # ``__validators__``, …) before falling through to the
+    # ``**field_definitions`` catch-all. Splatting an arbitrary
+    # ``fields`` dict therefore looks ill-typed to pyright even though
+    # the runtime contract accepts it (it is the documented pydantic
+    # idiom for dynamic model creation). The cast widens the call
+    # site to ``Callable[..., type[BaseModel]]`` so the splat checks.
+    creator = cast("Callable[..., type[BaseModel]]", create_model)
+    return creator(
+        target_name,
+        __base__=BaseModel,
+        __module__=dx_cls.__module__,
+        __doc__=dx_cls.__doc__,
+        **fields,
+    )
+
+
+def _annotation_with_axioms(spec: FieldSpec) -> type:
+    """Reconstruct an ``Annotated[T, ...]`` annotation including axiom metadata.
+
+    Parameters
+    ----------
+    spec
+        A didactic FieldSpec.
+
+    Returns
+    -------
+    type
+        Either the bare annotation, or ``Annotated[T, *axiom_metadata]``
+        when the spec carries any ``annotated-types`` constraints in
+        its ``extras["annotated_metadata"]`` list.
+
+    Notes
+    -----
+    didactic stores ``Annotated`` metadata it does not recognise in
+    ``spec.extras``; ``annotated-types`` primitives like ``Ge``/``Le``
+    are recognised and live on ``spec.axioms`` as their string-form
+    Expr equivalents. To round-trip through Pydantic we prefer the
+    original metadata where it survived, otherwise we just send the
+    bare annotation: Pydantic doesn't speak panproto-Expr predicates.
+    """
+    metadata = spec.extras.get("annotated_metadata", ())
+    if metadata:
+        return Annotated[spec.annotation, *metadata]  # type: ignore[valid-type]
+    return spec.annotation
+
+
+def _to_pydantic_field(spec: FieldSpec) -> FieldInfo:
+    """Translate one ``FieldSpec`` into a ``pydantic.Field(...)`` call.
+
+    Parameters
+    ----------
+    spec
+        The didactic FieldSpec.
+
+    Returns
+    -------
+    FieldInfo
+        A Pydantic ``FieldInfo`` produced by ``pydantic.Field(...)``.
+    """
+    # Pydantic's ``Field`` accepts a heterogeneous mix of native types
+    # (str, bool, FieldValue defaults, callables, dicts) for its many
+    # named keywords. The kwarg dict's value type is therefore the
+    # union of all those, expressed as ``FieldValue`` plus
+    # ``Callable``/``dict`` and explicitly admitted at each assignment
+    # site below.
+    type _FieldKwargValue = (
+        FieldValue | Callable[[], FieldValue] | dict[str, FieldValue]
+    )
+    kwargs: dict[str, _FieldKwargValue] = {}
+
+    if spec.default is not MISSING:
+        kwargs["default"] = cast("FieldValue", spec.default)
+    if spec.default_factory is not None:
+        kwargs["default_factory"] = spec.default_factory
+
+    if spec.alias is not None:
+        kwargs["alias"] = spec.alias
+
+    if spec.description is not None:
+        kwargs["description"] = spec.description
+    if spec.examples:
+        kwargs["examples"] = list(spec.examples)
+    if spec.deprecated:
+        kwargs["deprecated"] = True
+
+    # surface anything else through json_schema_extra; this round-trips
+    # to from_pydantic via the same key
+    extras = {
+        k: cast("FieldValue", v)
+        for k, v in spec.extras.items()
+        if k != "annotated_metadata"
+    }
+    if extras:
+        kwargs["json_schema_extra"] = extras
+
+    # Same dynamic-kwargs pattern as ``create_model``: ``Field``'s
+    # overloads enumerate named parameters (``alias``, ``description``,
+    # …) and pyright matches each kwarg against the most specific
+    # overload first, so a splatted ``dict[str, FieldValue]`` doesn't
+    # fit any overload. The cast widens to a permissive shape that
+    # matches Pydantic's runtime contract (returns a ``FieldInfo``).
+    field_factory = cast("Callable[..., FieldInfo]", Field)
+    return field_factory(**kwargs)
+
+
+__all__ = ["to_pydantic"]