didactic 0.7.2__tar.gz → 0.7.3__tar.gz

{didactic-0.7.2 → didactic-0.7.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: didactic
-Version: 0.7.2
+Version: 0.7.3
 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
@@ -15,7 +15,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
 Requires-Python: >=3.14
 Requires-Dist: annotated-types>=0.7
-Requires-Dist: panproto>=0.48.3
+Requires-Dist: panproto>=0.52.0
 Description-Content-Type: text/markdown
 
 # didactic
@@ -39,7 +39,7 @@ contribute submodules under `didactic.<name>`.
 
 ## Install
 
-didactic targets Python 3.14 and panproto 0.43+.
+didactic targets Python 3.14 and panproto 0.52+.
 
 ```sh
 pip install didactic

{didactic-0.7.2 → didactic-0.7.3}/README.md

@@ -19,7 +19,7 @@ contribute submodules under `didactic.<name>`.
 
 ## Install
 
-didactic targets Python 3.14 and panproto 0.43+.
+didactic targets Python 3.14 and panproto 0.52+.
 
 ```sh
 pip install didactic

{didactic-0.7.2 → didactic-0.7.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "didactic"
-version = "0.7.2"
+version = "0.7.3"
 description = "Pydantic-class API on top of panproto: GATs, lenses, and VCS."
 readme = "README.md"
 requires-python = ">=3.14"
@@ -22,7 +22,7 @@ classifiers = [
     "Typing :: Typed",
 ]
 dependencies = [
-    "panproto>=0.48.3",
+    "panproto>=0.52.0",
     "annotated-types>=0.7",
 ]
 

{didactic-0.7.2 → didactic-0.7.3}/src/didactic/api.py

@@ -54,6 +54,11 @@ from didactic.fields._validators import (
 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.lenses._morphisms import (
+    Correspondence,
+    best_correspondence,
+    find_correspondences,
+)
 from didactic.migrations._diff import classify_change, diff, is_breaking_change
 from didactic.migrations._migrations import (
     load_registry,
@@ -69,7 +74,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.7.1"
+__version__ = "0.7.3"
 
 #: Conventional namespace for lens utilities (`dx.lens.identity(...)`,
 #: `dx.lens.Lens`, etc.). The ``lens`` name doubles as a decorator
@@ -81,6 +86,7 @@ __all__ = [
     "Axiom",
     "Backref",
     "BaseModel",
+    "Correspondence",
     "DependentLens",
     "Embed",
     "ExtraPolicy",
@@ -103,6 +109,7 @@ __all__ = [
     "ValidationErrorEntry",
     "__version__",
     "axiom",
+    "best_correspondence",
     "classify_change",
     "codegen",
     "computed",
@@ -110,6 +117,7 @@ __all__ = [
     "diff",
     "embed_schema_uri",
     "field",
+    "find_correspondences",
     "is_breaking_change",
     "lens",
     "load_registry",

{didactic-0.7.2 → didactic-0.7.3}/src/didactic/codegen/source.py

@@ -4,8 +4,11 @@ For every tree-sitter grammar panproto bundles, didactic can:
 
 - **De-novo emit** a [Model][didactic.api.Model] class as fresh source via
   [emit_pretty][didactic.codegen.source.emit_pretty]. Walks the
-  grammar's production rules; output is syntactically valid for any
-  grammar that ships a ``grammar.json``.
+  grammar's production rules; spacing and indentation derive from
+  grammar-classified token roles. Emit round-trips are checked
+  against each grammar's upstream corpus in panproto's test suite.
+  Use [available_targets][didactic.codegen.source.available_targets]
+  to enumerate what the running build supports.
 - **Edit-pipeline emit**: parse real source, transform the schema,
   re-emit the bytes. Uses [emit][didactic.codegen.source.emit].
 - **Parse** source bytes into a panproto Schema for inspection.

{didactic-0.7.2 → didactic-0.7.3}/src/didactic/lenses/__init__.py

@@ -4,12 +4,20 @@ from didactic.lenses import _testing as testing
 from didactic.lenses._dependent_lens import DependentLens
 from didactic.lenses._lens import Iso, Lens, Mapping, identity
 from didactic.lenses._lens import lens as lens
+from didactic.lenses._morphisms import (
+    Correspondence,
+    best_correspondence,
+    find_correspondences,
+)
 
 __all__ = [
+    "Correspondence",
     "DependentLens",
     "Iso",
     "Lens",
     "Mapping",
+    "best_correspondence",
+    "find_correspondences",
     "identity",
     "lens",
     "testing",

{didactic-0.7.2 → didactic-0.7.3}/src/didactic/lenses/_dependent_lens.py

@@ -146,7 +146,7 @@ class DependentLens:
         src_schema: panproto.Schema,
         tgt_schema: panproto.Schema,
         protocol: panproto.Protocol,
-        hints: object,
+        hints: dict[str, str],
         *,
         stringency: str | None = None,
     ) -> DependentLens:
@@ -161,8 +161,10 @@ class DependentLens:
         protocol
             The panproto protocol both schemas conform to.
         hints
-            Vertex-correspondence hints. Their exact shape is
-            panproto-defined.
+            Vertex-correspondence hints mapping source-schema vertex
+            IDs to target-schema vertex IDs. A discovered
+            [Correspondence][didactic.api.Correspondence] supplies this
+            shape via its ``vertex_map``.
         stringency
             Optional stringency hint. ``None`` uses panproto's default.
 

didactic-0.7.3/src/didactic/lenses/_morphisms.py

@@ -0,0 +1,200 @@
+"""Vertex-correspondence discovery via panproto's hom search.
+
+Given two panproto Schemas, panproto can enumerate the structure-
+preserving maps (schema morphisms) between them and score each one.
+didactic wraps that search as
+[find_correspondences][didactic.api.find_correspondences] and
+[best_correspondence][didactic.api.best_correspondence], returning
+plain [Correspondence][didactic.api.Correspondence] records.
+
+The discovered ``vertex_map`` has exactly the shape that
+[DependentLens.auto_generate_with_hints][didactic.api.DependentLens.auto_generate_with_hints]
+takes as ``hints``, so the two compose into a discover-then-derive
+pipeline: search for the best correspondence, then derive a chain
+that respects it.
+
+Examples
+--------
+>>> import didactic.api as dx
+>>> import panproto
+>>>
+>>> proto = panproto.get_builtin_protocol("openapi")
+>>> # ... build src_schema and tgt_schema via proto.schema() ...
+>>>
+>>> best = dx.best_correspondence(src_schema, tgt_schema)  # doctest: +SKIP
+>>> best.vertex_map  # doctest: +SKIP
+{'post:body.text': 'post:body.content', ...}
+>>> chain = dx.DependentLens.auto_generate_with_hints(  # doctest: +SKIP
+...     src_schema,
+...     tgt_schema,
+...     proto,
+...     best.vertex_map,
+... )
+
+See Also
+--------
+didactic.lenses._dependent_lens : the hint-consuming chain derivation.
+panproto.find_morphisms : the runtime search.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import panproto
+
+
+@dataclass(frozen=True, slots=True)
+class Correspondence:
+    """One discovered schema morphism, scored.
+
+    Parameters
+    ----------
+    vertex_map
+        Mapping from source-schema vertex IDs to target-schema vertex
+        IDs. Feed directly as the ``hints`` argument of
+        [DependentLens.auto_generate_with_hints][didactic.api.DependentLens.auto_generate_with_hints].
+    quality
+        Alignment quality in ``[0.0, 1.0]``. Higher is better.
+    """
+
+    vertex_map: dict[str, str]
+    quality: float
+
+
+def find_correspondences(
+    src_schema: panproto.Schema,
+    tgt_schema: panproto.Schema,
+    *,
+    anchors: dict[str, str] | None = None,
+    monic: bool = False,
+    epic: bool = False,
+    iso: bool = False,
+    max_results: int = 0,
+    relax_edge_name_pruning: bool = False,
+) -> list[Correspondence]:
+    """Enumerate scored vertex correspondences between two schemas.
+
+    Parameters
+    ----------
+    src_schema
+        Source schema.
+    tgt_schema
+        Target schema.
+    anchors
+        Vertex pairs (source ID to target ID) the search must respect.
+        Use to pin known correspondences and let the search fill in
+        the rest.
+    monic
+        Require the morphism to be injective on vertices (no two
+        source vertices map to the same target vertex).
+    epic
+        Require the morphism to be surjective on vertices (every
+        target vertex is hit).
+    iso
+        Require a bijection. Implies ``monic`` and ``epic``.
+    max_results
+        Upper bound on the number of morphisms returned. ``0`` means
+        unbounded.
+    relax_edge_name_pruning
+        Keep kind-compatible candidate targets that share no outgoing
+        edge name with the source vertex. By default the search prunes
+        such candidates for object vertices with large candidate
+        domains, which can discard a correct pairing when every child
+        was renamed. Naturality is still enforced.
+
+    Returns
+    -------
+    list of Correspondence
+        Discovered correspondences. Empty when no structure-preserving
+        map exists under the given constraints.
+
+    Notes
+    -----
+    The schemas didactic builds from Model classes are single-vertex
+    (the structure lives in the Theory), so searching between two
+    Models degenerates to the root pairing. The search is informative
+    on multi-vertex schemas: protocol schemas built by hand and
+    schemas recovered by [didactic.codegen.source.parse][].
+    """
+    import panproto  # noqa: PLC0415
+
+    found = panproto.find_morphisms(
+        src_schema,
+        tgt_schema,
+        anchors=anchors,
+        monic=monic,
+        epic=epic,
+        iso=iso,
+        max_results=max_results,
+        relax_edge_name_pruning=relax_edge_name_pruning,
+    )
+    return [
+        Correspondence(vertex_map=m.vertex_map, quality=float(m.quality)) for m in found
+    ]
+
+
+def best_correspondence(
+    src_schema: panproto.Schema,
+    tgt_schema: panproto.Schema,
+    *,
+    anchors: dict[str, str] | None = None,
+    monic: bool = False,
+    epic: bool = False,
+    iso: bool = False,
+    relax_edge_name_pruning: bool = False,
+) -> Correspondence | None:
+    """Return the highest-quality correspondence, or ``None``.
+
+    Parameters
+    ----------
+    src_schema
+        Source schema.
+    tgt_schema
+        Target schema.
+    anchors
+        Vertex pairs (source ID to target ID) the search must respect.
+    monic
+        Require injectivity on vertices.
+    epic
+        Require surjectivity on vertices.
+    iso
+        Require a bijection. Implies ``monic`` and ``epic``.
+    relax_edge_name_pruning
+        Keep kind-compatible candidate targets that share no outgoing
+        edge name with the source vertex. See
+        [find_correspondences][didactic.api.find_correspondences].
+
+    Returns
+    -------
+    Correspondence or None
+        The best-scoring correspondence, or ``None`` when no
+        structure-preserving map exists under the given constraints.
+
+    See Also
+    --------
+    find_correspondences : the full enumeration.
+    """
+    import panproto  # noqa: PLC0415
+
+    found = panproto.find_best_morphism(
+        src_schema,
+        tgt_schema,
+        anchors=anchors,
+        monic=monic,
+        epic=epic,
+        iso=iso,
+        relax_edge_name_pruning=relax_edge_name_pruning,
+    )
+    if found is None:
+        return None
+    return Correspondence(vertex_map=found.vertex_map, quality=float(found.quality))
+
+
+__all__ = [
+    "Correspondence",
+    "best_correspondence",
+    "find_correspondences",
+]

{didactic-0.7.2 → didactic-0.7.3}/src/didactic/theory/_theory.py

@@ -34,6 +34,8 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, TypedDict, cast
 
 if TYPE_CHECKING:
+    from collections.abc import Mapping
+
     import panproto
 
     from didactic.fields._fields import FieldSpec
@@ -58,6 +60,31 @@ class TheorySpec(TypedDict):
     policies: list[dict[str, JsonValue]]
 
 
+def _spec_payload(spec: TheorySpec) -> Mapping[str, JsonValue]:
+    """Narrow a ``TheorySpec`` to the mapping shape ``create_theory`` takes.
+
+    Parameters
+    ----------
+    spec
+        A spec dict from ``build_theory_spec``.
+
+    Returns
+    -------
+    Mapping
+        The same dict, typed as ``Mapping[str, JsonValue]``.
+
+    Notes
+    -----
+    The typing spec makes a ``TypedDict`` assignable to
+    ``Mapping[str, object]`` and to no mapping with a narrower value
+    type, so handing a ``TheorySpec`` to ``panproto.create_theory``
+    (whose parameter is ``Mapping[str, JsonValue]``) needs a cast at
+    the boundary. Every ``TheorySpec`` field type is a ``JsonValue``,
+    so the cast is sound.
+    """
+    return cast("Mapping[str, JsonValue]", spec)
+
+
 # ---------------------------------------------------------------------------
 # Spec construction (no panproto runtime required)
 # ---------------------------------------------------------------------------
@@ -347,7 +374,7 @@ def build_theory(cls: type) -> panproto.Theory:
     if len(parents) <= 1:
         # single (or no) Model inheritance: the flat spec is correct
         spec = build_theory_spec(cls)
-        return panproto.create_theory(spec)
+        return panproto.create_theory(_spec_payload(spec))
 
     # multiple Model inheritance: compute the colimit of the parent
     # theories over their lowest common ancestor in the Model lineage
@@ -432,13 +459,15 @@ def _build_colimit_theory(cls: type, parents: list[type]) -> panproto.Theory:
     """
     import panproto  # noqa: PLC0415
 
-    accumulator = panproto.create_theory(build_theory_spec(parents[0]))
+    accumulator = panproto.create_theory(_spec_payload(build_theory_spec(parents[0])))
     accumulator_cls: type = parents[0]
 
     for parent in parents[1:]:
         ancestor = _lowest_common_model_ancestor([accumulator_cls, parent])
-        ancestor_theory = panproto.create_theory(build_theory_spec(ancestor))
-        next_theory = panproto.create_theory(build_theory_spec(parent))
+        ancestor_theory = panproto.create_theory(
+            _spec_payload(build_theory_spec(ancestor))
+        )
+        next_theory = panproto.create_theory(_spec_payload(build_theory_spec(parent)))
         accumulator = panproto.colimit_theories(
             accumulator, next_theory, ancestor_theory
         )
@@ -447,7 +476,7 @@ def _build_colimit_theory(cls: type, parents: list[type]) -> panproto.Theory:
     # finally fold in any cls-only fields by colimiting against the
     # immediate spec of cls; the shared ancestor is the accumulated
     # theory we just built
-    cls_theory = panproto.create_theory(build_theory_spec(cls))
+    cls_theory = panproto.create_theory(_spec_payload(build_theory_spec(cls)))
     return panproto.colimit_theories(accumulator, cls_theory, accumulator)