didactic 0.1.0__py3-none-any.whl

didactic/_self_describing.py

@@ -0,0 +1,206 @@
+"""Self-describing JSON via fingerprint URIs.
+
+A panproto-native form of self-describing data: an emitted JSON
+payload carries a ``$schema`` URI of the form
+``didactic://v1/<structural-fingerprint>``. A consumer that holds a
+registry of known Theories (by fingerprint) can validate an unknown
+payload by looking the URI up.
+
+This is something Pydantic structurally cannot do, because Pydantic
+has no content-addressed schema identity. didactic's structural
+fingerprint already gives every Model a stable address; this module
+just plumbs it through to JSON.
+
+Examples
+--------
+>>> import didactic.api as dx
+>>>
+>>> class User(dx.Model):
+...     id: str
+...     email: str
+>>>
+>>> u = User(id="u1", email="ada@example.org")
+>>> payload = dx.embed_schema_uri(u)
+>>> payload["$schema"].startswith("didactic://v1/")
+True
+
+See Also
+--------
+didactic.migrations._fingerprint.structural_fingerprint : the underlying address.
+"""
+
+# Cross-translation between ``FieldValue`` and ``JsonValue`` shapes
+# in the schema-URI registry layer.
+# Tracked in panproto/didactic#1.
+# pyright: reportArgumentType=false, reportReturnType=false
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from didactic.models._model import Model
+    from didactic.types._typing import JsonObject
+
+#: URI scheme prefix didactic uses for self-describing payloads.
+URI_PREFIX = "didactic://v1/"
+
+
+def schema_uri(cls: type[Model]) -> str:
+    """Return the canonical schema URI for a Model class.
+
+    Parameters
+    ----------
+    cls
+        A [Model][didactic.api.Model] subclass.
+
+    Returns
+    -------
+    str
+        ``"didactic://v1/<fingerprint>"`` where ``<fingerprint>`` is
+        the Model's structural fingerprint.
+    """
+    from didactic.migrations._fingerprint import structural_fingerprint  # noqa: PLC0415
+    from didactic.theory._theory import build_theory_spec  # noqa: PLC0415
+
+    return f"{URI_PREFIX}{structural_fingerprint(build_theory_spec(cls))}"
+
+
+def embed_schema_uri(instance: Model) -> JsonObject:
+    """Return ``instance.model_dump()`` with a ``$schema`` URI prepended.
+
+    Parameters
+    ----------
+    instance
+        A Model instance.
+
+    Returns
+    -------
+    dict
+        The dump dict, with ``"$schema"`` set to the Model's
+        canonical URI as the first key.
+
+    Notes
+    -----
+    A consumer that knows how to resolve ``didactic://v1/<fp>`` URIs
+    can fetch the Theory by fingerprint and validate the payload
+    without knowing the original Python class.
+    """
+    payload = instance.model_dump()
+    return {"$schema": schema_uri(type(instance)), **payload}
+
+
+class FingerprintRegistry:
+    """An in-memory mapping of structural fingerprint to Model class.
+
+    Use as the lookup side of a self-describing JSON pipeline:
+    register every Model your application understands, then
+    [validate_with_uri_lookup][didactic.api.validate_with_uri_lookup]
+    can resolve an unknown payload's ``$schema`` URI back to a class.
+
+    Examples
+    --------
+    >>> import didactic.api as dx
+    >>> class User(dx.Model):
+    ...     id: str
+    >>>
+    >>> reg = dx.FingerprintRegistry()
+    >>> reg.register(User)
+    >>>
+    >>> u = User(id="u1")
+    >>> payload = dx.embed_schema_uri(u)
+    >>> back = dx.validate_with_uri_lookup(payload, reg)
+    >>> back == u
+    True
+    """
+
+    __slots__ = ("_by_fingerprint",)
+
+    def __init__(self) -> None:
+        self._by_fingerprint: dict[str, type[Model]] = {}
+
+    def register[M: Model](self, cls: type[M]) -> type[M]:
+        """Register ``cls`` under its structural fingerprint."""
+        from didactic.migrations._fingerprint import (  # noqa: PLC0415
+            structural_fingerprint,
+        )
+        from didactic.theory._theory import build_theory_spec  # noqa: PLC0415
+
+        fp = structural_fingerprint(build_theory_spec(cls))
+        self._by_fingerprint[fp] = cls
+        return cls
+
+    def lookup(self, uri: str) -> type[Model] | None:
+        """Resolve a ``didactic://v1/<fp>`` URI to a registered class."""
+        if not uri.startswith(URI_PREFIX):
+            return None
+        fp = uri[len(URI_PREFIX) :]
+        return self._by_fingerprint.get(fp)
+
+    def __contains__(self, cls_or_uri: object) -> bool:
+        if isinstance(cls_or_uri, str):
+            return self.lookup(cls_or_uri) is not None
+        if isinstance(cls_or_uri, type):
+            from didactic.migrations._fingerprint import (  # noqa: PLC0415
+                structural_fingerprint,
+            )
+            from didactic.theory._theory import build_theory_spec  # noqa: PLC0415
+
+            return (
+                structural_fingerprint(build_theory_spec(cls_or_uri))
+                in self._by_fingerprint
+            )
+        return False
+
+    def __len__(self) -> int:
+        return len(self._by_fingerprint)
+
+
+def validate_with_uri_lookup(
+    payload: JsonObject,
+    registry: FingerprintRegistry,
+) -> Model:
+    """Validate ``payload`` against the Model named by its ``$schema`` URI.
+
+    Parameters
+    ----------
+    payload
+        A dict that includes a ``$schema`` key.
+    registry
+        A [FingerprintRegistry][didactic.api.FingerprintRegistry] mapping
+        URIs to Model classes.
+
+    Returns
+    -------
+    Model
+        A validated Model instance whose class came from the
+        registry.
+
+    Raises
+    ------
+    LookupError
+        If the URI is not registered.
+    KeyError
+        If the payload has no ``$schema`` key.
+    """
+    if "$schema" not in payload:
+        msg = "validate_with_uri_lookup: payload has no $schema key"
+        raise KeyError(msg)
+
+    uri = payload["$schema"]
+    cls = registry.lookup(uri)
+    if cls is None:
+        msg = f"validate_with_uri_lookup: no registered model for URI {uri!r}"
+        raise LookupError(msg)
+
+    body = {k: v for k, v in payload.items() if k != "$schema"}
+    return cls.model_validate(body)
+
+
+__all__ = [
+    "URI_PREFIX",
+    "FingerprintRegistry",
+    "embed_schema_uri",
+    "schema_uri",
+    "validate_with_uri_lookup",
+]

didactic/api.py

@@ -0,0 +1,126 @@
+"""Aggregator module for the didactic API.
+
+`didactic` lets you author class-based, declarative data models the way
+[Pydantic][pydantic] does, while the underlying values are
+[panproto][panproto] [Theory][panproto.Theory] and
+[Schema][panproto.Schema] instances rather than ad hoc Python objects with
+bolt-on validation. The selling point is everything you get *for free*
+once your data is panproto-native: lenses, dependent optics, theory
+colimits, schema migrations as data, vertex-level VCS, and cross-language
+semantic export.
+
+[pydantic]: https://docs.pydantic.dev/
+[panproto]: https://github.com/panproto/panproto
+
+Notes
+-----
+The conventional alias for this module is ``dx``::
+
+    import didactic.api as dx
+
+
+    class User(dx.Model):
+        id: str
+        email: str
+
+The ``didactic`` namespace itself is a PEP 420 implicit namespace
+package; the four distributions (``didactic`` / ``didactic-pydantic`` /
+``didactic-settings`` / ``didactic-fastapi``) each contribute a
+sub-package (``didactic.api``, ``didactic.pydantic``,
+``didactic.settings``, ``didactic.fastapi``) without an
+``__init__.py`` at the namespace root. This lets static type checkers
+resolve cross-distribution imports without a ``pkgutil`` workaround.
+"""
+
+from didactic import codegen
+from didactic._self_describing import (
+    FingerprintRegistry,
+    embed_schema_uri,
+    schema_uri,
+    validate_with_uri_lookup,
+)
+from didactic.axioms._axioms import Axiom, axiom
+from didactic.fields._computed import computed
+from didactic.fields._derived import derived
+from didactic.fields._fields import Field, FieldSpec, field
+from didactic.fields._refs import Backref, Embed, Ref
+from didactic.fields._unions import TaggedUnion
+from didactic.fields._validators import (
+    ValidationError,
+    ValidationErrorEntry,
+    validates,
+)
+from didactic.lenses import _testing as testing
+from didactic.lenses._dependent_lens import DependentLens
+from didactic.lenses._lens import Iso, Lens, Mapping, lens
+from didactic.migrations._diff import classify_change, diff, is_breaking_change
+from didactic.migrations._migrations import (
+    load_registry,
+    migrate,
+    register_migration,
+    save_registry,
+)
+from didactic.migrations._synthesis import SynthesisResult, synthesise_migration
+from didactic.models._config import DEFAULT_CONFIG, ExtraPolicy, ModelConfig
+from didactic.models._model import BaseModel, Model
+from didactic.models._root import RootModel, TypeAdapter
+from didactic.types import _types_lib as types
+from didactic.vcs._backref import ModelPool, resolve_backrefs
+from didactic.vcs._repo import Repository
+
+__version__ = "0.1.0"
+
+#: Conventional namespace for lens utilities (`dx.lens.identity(...)`,
+#: `dx.lens.Lens`, etc.). The ``lens`` name doubles as a decorator
+#: (``@dx.lens(A, B)``) and as a module-style namespace. The attributes
+#: are bound by ``_LensNamespace.__init__`` in :mod:`didactic.lenses._lens`.
+
+
+__all__ = [
+    "DEFAULT_CONFIG",
+    "Axiom",
+    "Backref",
+    "BaseModel",
+    "DependentLens",
+    "Embed",
+    "ExtraPolicy",
+    "Field",
+    "FieldSpec",
+    "FingerprintRegistry",
+    "Iso",
+    "Lens",
+    "Mapping",
+    "Model",
+    "ModelConfig",
+    "ModelPool",
+    "Ref",
+    "Repository",
+    "RootModel",
+    "SynthesisResult",
+    "TaggedUnion",
+    "TypeAdapter",
+    "ValidationError",
+    "ValidationErrorEntry",
+    "__version__",
+    "axiom",
+    "classify_change",
+    "codegen",
+    "computed",
+    "derived",
+    "diff",
+    "embed_schema_uri",
+    "field",
+    "is_breaking_change",
+    "lens",
+    "load_registry",
+    "migrate",
+    "register_migration",
+    "resolve_backrefs",
+    "save_registry",
+    "schema_uri",
+    "synthesise_migration",
+    "testing",
+    "types",
+    "validate_with_uri_lookup",
+    "validates",
+]

didactic/axioms/__init__.py

@@ -0,0 +1,11 @@
+"""Class-level axioms and their construction-time enforcement."""
+
+from didactic.axioms._axiom_enforcement import check_class_axioms
+from didactic.axioms._axioms import Axiom, axiom, collect_class_axioms
+
+__all__ = [
+    "Axiom",
+    "axiom",
+    "check_class_axioms",
+    "collect_class_axioms",
+]

didactic/axioms/_axiom_enforcement.py

@@ -0,0 +1,236 @@
+"""Axiom enforcement: parse axiom strings into predicates run at construction.
+
+Each ``__axioms__`` entry is parsed into a panproto ``Expr`` AST via
+``panproto.parse_expr``, then evaluated against a Model instance's
+field values during construction. Failures raise
+[didactic.api.ValidationError][didactic.api.ValidationError] with the axiom's
+message.
+
+The evaluator walks the panproto Expr ``to_dict()`` form, which is a
+tagged union of ``{"Builtin": ...}``, ``{"Var": ...}``, ``{"Lit": ...}``,
+and a small set of other variants.
+
+See Also
+--------
+didactic.axioms._axioms : the Axiom record type and ``__axioms__`` collection.
+panproto.parse_expr : the underlying parser.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from didactic.axioms._axioms import Axiom
+    from didactic.types._typing import FieldValue, JsonValue
+
+
+# A panproto Expr ``to_dict()`` AST node is one of any JsonValue-shaped
+# payload — at the leaves of dispatch we narrow with ``match`` /
+# ``isinstance``. Using ``JsonValue`` (rather than the narrower
+# "single-key dict envelope" shape) lets list-positional accesses like
+# ``args[0]`` inside ``Builtin`` typecheck without a per-element
+# ``isinstance`` chain.
+type ExprNode = JsonValue
+# The evaluator returns a Python value whose runtime type depends on
+# the expression: a literal evaluates to a scalar, a variable lookup
+# returns whatever ``env`` holds, an arithmetic op returns the result
+# of Python's operator protocol over those leaves. The union is
+# constructed from the documented ``FieldValue`` set (everything that
+# can sit in an environment binding); callers narrow per use site
+# (e.g. the predicate wrapper ``_predicate`` casts the result to
+# ``bool``).
+type EvalResult = FieldValue
+
+
+def parse_axiom_predicate(axiom: Axiom):  # type: ignore[no-untyped-def]
+    """Parse an axiom expression into a callable predicate.
+
+    Parameters
+    ----------
+    axiom
+        An [Axiom][didactic.api.Axiom] instance whose ``expr`` is the
+        Haskell-style surface syntax accepted by
+        ``panproto.parse_expr``.
+
+    Returns
+    -------
+    Callable[[dict[str, FieldValue]], bool]
+        A predicate that takes a ``{field_name: value}`` environment
+        and returns whether the axiom holds.
+
+    Raises
+    ------
+    panproto.ExprError
+        If the axiom cannot be parsed.
+
+    Notes
+    -----
+    The parser is invoked once per ``Axiom``; cache the result if you
+    plan to evaluate the same axiom many times.
+    """
+    import panproto  # noqa: PLC0415
+
+    expr = panproto.parse_expr(axiom.expr)
+    # ``Expr.to_dict()`` returns ``dict[str, object]`` (the panproto
+    # binding doesn't declare a tighter type because the leaf values
+    # are dynamic). Cast to the ``JsonValue`` shape ``_evaluate``
+    # expects; the runtime contract guarantees JSON-shaped leaves.
+    ast = cast("JsonValue", expr.to_dict())
+
+    def _predicate(env: dict[str, FieldValue]) -> bool:
+        return bool(_evaluate(ast, env))
+
+    return _predicate
+
+
+def _evaluate(node: ExprNode, env: dict[str, FieldValue]) -> EvalResult:
+    """Walk a panproto Expr ``to_dict`` AST and evaluate against ``env``.
+
+    The function handles the common subset that shows up in axiom
+    expressions: variable lookup, literals, comparison operators,
+    boolean connectives, and arithmetic. Unrecognised node shapes
+    raise ``NotImplementedError``.
+
+    Pattern-matched on the panproto Expr shape: each variant is
+    a single-key dict whose value has a known structure. The match
+    statements narrow the dynamic ``ExprNode`` shape into the typed
+    sub-shapes the helpers consume.
+    """
+    match node:
+        case {"Var": str(name)}:
+            if name not in env:
+                msg = f"axiom references unbound variable {name!r}"
+                raise NameError(msg)
+            return env[name]
+        case {"Lit": dict(lit)}:
+            return _evaluate_literal(lit)
+        case {"Builtin": [str(op), list(args)]}:
+            return _evaluate_builtin(op, args, env)
+        case {"App": [dict(func), arg]}:
+            # general App: rare in axioms; treat as a builtin family if
+            # head is a Var pointing at a known function name
+            if "Var" in func and isinstance(func["Var"], str):
+                return _evaluate_builtin(func["Var"], [arg], env)
+            msg = f"App nodes with non-Var heads are not supported: {func!r}"
+            raise NotImplementedError(msg)
+        case _:
+            msg = f"unsupported Expr node shape: {node!r}"
+            raise NotImplementedError(msg)
+
+
+def _evaluate_literal(lit: ExprNode) -> EvalResult:
+    """Evaluate a panproto literal node."""
+    match lit:
+        case {"Int": int(v) | str(v)}:
+            return int(v)
+        case {"Float": float(v) | int(v) | str(v)}:
+            return float(v)
+        case {"Str": str(v)}:
+            return v
+        case {"Bool": bool(v)}:
+            return v
+        case {"Char": str(v)}:
+            return v
+        case _:
+            msg = f"unsupported Literal: {lit!r}"
+            raise NotImplementedError(msg)
+
+
+def _evaluate_builtin(
+    op: str,
+    args: Sequence[ExprNode],
+    env: dict[str, FieldValue],
+) -> EvalResult:
+    """Evaluate a panproto builtin operator.
+
+    All comparison and arithmetic operators rely on Python's
+    duck-typed operator protocols; the values come from
+    ``_evaluate``'s ``EvalResult`` (an alias for ``object``) and the
+    runtime contract is that an axiom expression's leaf values are
+    comparable with the relevant operators. ``# type: ignore`` markers
+    sit at each operator site because pyright cannot prove that
+    arbitrary ``object`` values support ``<``/``+``/etc.
+    """
+    # comparison and equality (panproto uses Gte/Lte/Neq variants)
+    if op == "Eq":
+        a, b = (_evaluate(args[0], env), _evaluate(args[1], env))
+        return a == b
+    if op in ("Ne", "Neq"):
+        return _evaluate(args[0], env) != _evaluate(args[1], env)
+    if op == "Lt":
+        return _evaluate(args[0], env) < _evaluate(args[1], env)  # type: ignore[operator]
+    if op in ("Le", "Lte"):
+        return _evaluate(args[0], env) <= _evaluate(args[1], env)  # type: ignore[operator]
+    if op == "Gt":
+        return _evaluate(args[0], env) > _evaluate(args[1], env)  # type: ignore[operator]
+    if op in ("Ge", "Gte"):
+        return _evaluate(args[0], env) >= _evaluate(args[1], env)  # type: ignore[operator]
+
+    # boolean connectives
+    if op == "And":
+        return all(bool(_evaluate(a, env)) for a in args)
+    if op == "Or":
+        return any(bool(_evaluate(a, env)) for a in args)
+    if op == "Not":
+        return not bool(_evaluate(args[0], env))
+
+    # arithmetic
+    if op == "Add":
+        return _evaluate(args[0], env) + _evaluate(args[1], env)  # type: ignore[operator]
+    if op == "Sub":
+        return _evaluate(args[0], env) - _evaluate(args[1], env)  # type: ignore[operator]
+    if op == "Mul":
+        return _evaluate(args[0], env) * _evaluate(args[1], env)  # type: ignore[operator]
+    if op == "Div":
+        return _evaluate(args[0], env) / _evaluate(args[1], env)  # type: ignore[operator]
+    if op == "Mod":
+        return _evaluate(args[0], env) % _evaluate(args[1], env)  # type: ignore[operator]
+    if op == "Neg":
+        return -_evaluate(args[0], env)  # type: ignore[operator]
+
+    # length-style helpers (axioms about collection sizes are common)
+    if op == "Len":
+        return len(_evaluate(args[0], env))  # type: ignore[arg-type]
+
+    msg = f"axiom evaluator does not yet implement Builtin {op!r}"
+    raise NotImplementedError(msg)
+
+
+def check_class_axioms(cls: type, env: dict[str, FieldValue]) -> list[str]:
+    """Run every collected axiom on ``cls`` against ``env``.
+
+    Parameters
+    ----------
+    cls
+        A [Model][didactic.api.Model] subclass with ``__class_axioms__``.
+    env
+        The field-name to value mapping.
+
+    Returns
+    -------
+    list of str
+        Failure messages, one per axiom that does not hold. Empty
+        when every axiom holds.
+    """
+    failures: list[str] = []
+    axioms: tuple[Axiom, ...] = getattr(cls, "__class_axioms__", ())
+    for ax in axioms:
+        try:
+            predicate = parse_axiom_predicate(ax)
+            ok = predicate(env)
+        except (NameError, NotImplementedError) as exc:
+            failures.append(f"axiom {ax.expr!r}: cannot evaluate ({exc})")
+            continue
+        if not ok:
+            msg = ax.message or f"axiom failed: {ax.expr}"
+            failures.append(msg)
+    return failures
+
+
+__all__ = [
+    "check_class_axioms",
+    "parse_axiom_predicate",
+]