Lens, Iso, Mapping¶

didactic.api.Lens ¶

General bidirectional transform with a complement.

Subclass and override forward returning (b, complement), and backward taking (b, complement) and returning a. Round-trip laws (panproto's check_get_put and check_put_get):

GetPut: backward(*forward(a)) == a
PutGet: forward(backward(b, c)) == (b, c)

Notes

The pure-Python implementation does not enforce the laws; they are tested with hypothesis or verified through panproto once the runtime hookup lands.

See Also

didactic.Iso : the lossless special case (complement is unit). didactic.Mapping : one-way variant.

forward ¶

forward(a: A) -> tuple[B, C]

Project a to (b, complement). Subclasses override.

backward ¶

backward(b: B, complement: C) -> A

Reconstruct a from (b, complement). Subclasses override.

didactic.api.Iso ¶

Bases: Mapping[A, B]

Two-way bijection between A and B with no information loss.

Subclass and override forward and backward. Round-trip laws are:

backward(forward(a)) == a
forward(backward(b)) == b

didactic verifies these in tests via didactic.api.testing.verify_iso; runtime verification on every forward call is opt-in.

See Also

didactic.Lens : the general lossy lens with a complement.

backward ¶

backward(b: B) -> A

Map b back to its source. Subclasses override.

inverse ¶

inverse() -> Iso[B, A]

Return an Iso that swaps forward and backward.

didactic.api.Mapping ¶

One-way transformation from A to B.

Subclass and override forward. Cannot be composed in reverse and has no inverse.

Notes

Mappings are pure Python in v0.0.2; the panproto-side Lens representation lands later.

See Also

didactic.Iso : a Mapping with a verified inverse. didactic.Lens : a Mapping with a complement.

forward ¶

forward(a: A) -> B

Map a forward to its target.

Subclasses must override. The default raises NotImplementedError so misuse is loud.

didactic.api.DependentLens ¶

DependentLens(inner: ProtolensChain)

A schema-independent lens family.

Wraps a panproto.ProtolensChain. The wrapper carries the underlying chain and exposes the operations that are useful from didactic-shaped code:

construction via auto_generate or auto_generate_with_hints
composition (>> or compose)
fusion of all steps into one (fuse)
JSON round-trip (to_json and from_json)
instantiation against a concrete schema (instantiate)

PARAMETER	DESCRIPTION
`inner`	An already-constructed `panproto.ProtolensChain`. Most callers should use the auto_generate class method or from_json rather than constructing this class directly. TYPE: `ProtolensChain`

Notes

Equality compares the JSON-serialised form of the underlying chain; structurally identical chains are equal even if they were constructed by different code paths.

auto_generate `classmethod` ¶

auto_generate(
    src_schema: Schema,
    tgt_schema: Schema,
    protocol: Protocol,
    *,
    stringency: str | None = None,
) -> DependentLens

Auto-generate a chain between two schemas under protocol.

PARAMETER	DESCRIPTION
`src_schema`	The source schema. TYPE: `Schema`
`tgt_schema`	The target schema. TYPE: `Schema`
`protocol`	The panproto protocol that both schemas conform to. TYPE: `Protocol`
`stringency`	Optional stringency hint passed through to panproto. Use `None` for the default. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`DependentLens`	A chain capturing the rewrites that take the source schema to the target.

RAISES	DESCRIPTION
`LensError`	If panproto cannot derive a chain between the two schemas under the given protocol.

auto_generate_with_hints `classmethod` ¶

auto_generate_with_hints(
    src_schema: Schema,
    tgt_schema: Schema,
    protocol: Protocol,
    hints: dict[str, str],
    *,
    stringency: str | None = None,
) -> DependentLens

Auto-generate using vertex-correspondence hints.

PARAMETER	DESCRIPTION
`src_schema`	Source schema. TYPE: `Schema`
`tgt_schema`	Target schema. TYPE: `Schema`
`protocol`	The panproto protocol both schemas conform to. TYPE: `Protocol`
`hints`	Vertex-correspondence hints mapping source-schema vertex IDs to target-schema vertex IDs. A discovered Correspondence supplies this shape via its `vertex_map`. TYPE: `dict[str, str]`
`stringency`	Optional stringency hint. `None` uses panproto's default. TYPE: `str \| None` DEFAULT: `None`

RETURNS	DESCRIPTION
`DependentLens`	A chain that respects the given hints.

from_json `classmethod` ¶

from_json(json_text: str) -> DependentLens

Reconstruct a chain from its JSON form.

PARAMETER	DESCRIPTION
`json_text`	A JSON string previously returned by to_json. TYPE: `str`

RETURNS	DESCRIPTION
`DependentLens`	The reconstructed chain.

RAISES	DESCRIPTION
`LensError`	If `json_text` is not a valid serialised chain.

from_dsl_json `classmethod` ¶

from_dsl_json(
    source: str, body_vertex: str
) -> DependentLens

Compile a panproto-lens-dsl JSON document into a chain.

PARAMETER	DESCRIPTION
`source`	The JSON surface of `panproto-lens-dsl`: a top-level document with `id` / `description` / `steps` (and optional `constraints` / `hints` / `preferences`). TYPE: `str`
`body_vertex`	Entry vertex of the source schema the chain is being authored against. The DSL compiler uses it to anchor the per-step protolens construction. TYPE: `str`

RETURNS	DESCRIPTION
`DependentLens`	The compiled chain.

RAISES	DESCRIPTION
`LensError`	If `source` is not a valid lens-DSL document.

from_dsl_yaml `classmethod` ¶

from_dsl_yaml(
    source: str, body_vertex: str
) -> DependentLens

Compile a panproto-lens-dsl YAML document into a chain.

PARAMETER	DESCRIPTION
`source`	The YAML surface of `panproto-lens-dsl`. TYPE: `str`
`body_vertex`	Entry vertex of the source schema; see from_dsl_json. TYPE: `str`

RETURNS	DESCRIPTION
`DependentLens`	The compiled chain.

RAISES	DESCRIPTION
`LensError`	If `source` is not a valid lens-DSL document.

from_dsl_nickel `classmethod` ¶

from_dsl_nickel(
    source: str, body_vertex: str
) -> DependentLens

Compile a panproto-lens-dsl Nickel document into a chain.

PARAMETER	DESCRIPTION
`source`	The Nickel surface of `panproto-lens-dsl`. TYPE: `str`
`body_vertex`	Entry vertex of the source schema; see from_dsl_json. TYPE: `str`

RETURNS	DESCRIPTION
`DependentLens`	The compiled chain.

RAISES	DESCRIPTION
`LensError`	If `source` is not a valid lens-DSL document.

from_dsl_path `classmethod` ¶

from_dsl_path(path: str, body_vertex: str) -> DependentLens

Compile a panproto-lens-dsl document loaded from path.

Dispatches on the file extension: .ncl is parsed as Nickel, .json as JSON, .yaml / .yml as YAML.

PARAMETER	DESCRIPTION
`path`	Filesystem path to a lens-DSL document. TYPE: `str`
`body_vertex`	Entry vertex of the source schema; see from_dsl_json. TYPE: `str`

RETURNS	DESCRIPTION
`DependentLens`	The compiled chain.

RAISES	DESCRIPTION
`LensError`	If the file is missing or its contents are not a valid lens-DSL document.

compose ¶

compose(other: DependentLens) -> DependentLens

Vertically compose this chain with other.

PARAMETER	DESCRIPTION
`other`	Another DependentLens whose source matches this chain's target. TYPE: `DependentLens`

RETURNS	DESCRIPTION
`DependentLens`	The composed chain.

Notes

Composition is associative; identity is the empty chain.

fuse ¶

fuse() -> object

Fuse all steps into a single protolens.

RETURNS	DESCRIPTION
`object`	A panproto-side fused protolens. The exact return type is panproto-defined; treat it as opaque.

instantiate ¶

instantiate(schema: Schema, protocol: Protocol) -> object

Instantiate against a concrete schema to produce a panproto.Lens.

PARAMETER	DESCRIPTION
`schema`	The concrete source schema to specialise against. TYPE: `Schema`
`protocol`	The panproto protocol the schema conforms to. TYPE: `Protocol`

RETURNS	DESCRIPTION
`object`	A `panproto.Lens` (treat as opaque from this side).

RAISES	DESCRIPTION
`LensError`	If the chain cannot be instantiated against `schema`.

to_json ¶

to_json() -> str

Serialise the chain to JSON.

RETURNS	DESCRIPTION
`str`	A JSON string suitable for round-tripping through from_json.

didactic.api.lens `module-attribute` ¶

lens = _LensNamespace()

didactic.api.Correspondence `dataclass` ¶

Correspondence(vertex_map: dict[str, str], quality: float)

One discovered schema morphism, scored.

PARAMETER	DESCRIPTION
`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. TYPE: `dict[str, str]`
`quality`	Alignment quality in `[0.0, 1.0]`. Higher is better. TYPE: `float`

didactic.api.find_correspondences ¶

find_correspondences(
    src_schema: Schema,
    tgt_schema: 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.

PARAMETER	DESCRIPTION
`src_schema`	Source schema. TYPE: `Schema`
`tgt_schema`	Target schema. TYPE: `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. TYPE: `dict[str, str] \| None` DEFAULT: `None`
`monic`	Require the morphism to be injective on vertices (no two source vertices map to the same target vertex). TYPE: `bool` DEFAULT: `False`
`epic`	Require the morphism to be surjective on vertices (every target vertex is hit). TYPE: `bool` DEFAULT: `False`
`iso`	Require a bijection. Implies `monic` and `epic`. TYPE: `bool` DEFAULT: `False`
`max_results`	Upper bound on the number of morphisms returned. `0` means unbounded. TYPE: `int` DEFAULT: `0`
`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. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`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.

didactic.api.best_correspondence ¶

best_correspondence(
    src_schema: Schema,
    tgt_schema: 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.

PARAMETER	DESCRIPTION
`src_schema`	Source schema. TYPE: `Schema`
`tgt_schema`	Target schema. TYPE: `Schema`
`anchors`	Vertex pairs (source ID to target ID) the search must respect. TYPE: `dict[str, str] \| None` DEFAULT: `None`
`monic`	Require injectivity on vertices. TYPE: `bool` DEFAULT: `False`
`epic`	Require surjectivity on vertices. TYPE: `bool` DEFAULT: `False`
`iso`	Require a bijection. Implies `monic` and `epic`. TYPE: `bool` DEFAULT: `False`
`relax_edge_name_pruning`	Keep kind-compatible candidate targets that share no outgoing edge name with the source vertex. See find_correspondences. TYPE: `bool` DEFAULT: `False`

RETURNS	DESCRIPTION
`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.

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

Lens, Iso, Mapping¶

didactic.api.Lens ¶

forward ¶

backward ¶

didactic.api.Iso ¶

backward ¶

inverse ¶

didactic.api.Mapping ¶

forward ¶

didactic.api.DependentLens ¶

auto_generate classmethod ¶

auto_generate_with_hints classmethod ¶

from_json classmethod ¶

from_dsl_json classmethod ¶

from_dsl_yaml classmethod ¶

from_dsl_nickel classmethod ¶

from_dsl_path classmethod ¶

compose ¶

fuse ¶

instantiate ¶

to_json ¶

didactic.api.lens module-attribute ¶

didactic.api.Correspondence dataclass ¶

didactic.api.find_correspondences ¶

didactic.api.best_correspondence ¶

auto_generate `classmethod` ¶

auto_generate_with_hints `classmethod` ¶

from_json `classmethod` ¶

from_dsl_json `classmethod` ¶

from_dsl_yaml `classmethod` ¶

from_dsl_nickel `classmethod` ¶

from_dsl_path `classmethod` ¶

didactic.api.lens `module-attribute` ¶

didactic.api.Correspondence `dataclass` ¶