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)

Parameters:

Name	Type	Description	Default
inner	ProtolensChain	An already-constructed panproto.ProtolensChain. Most callers should use the auto_generate class method or from_json rather than constructing this class directly.	required

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.

Parameters:

Name	Type	Description	Default
src_schema	Schema	The source schema.	required
tgt_schema	Schema	The target schema.	required
protocol	Protocol	The panproto protocol that both schemas conform to.	required
stringency	str | None	Optional stringency hint passed through to panproto. Use None for the default.	None

Returns:

Type	Description
DependentLens	A chain capturing the rewrites that take the source schema to the target.

Raises:

Type	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: object,
    *,
    stringency: str | None = None,
) -> DependentLens

Auto-generate using vertex-correspondence hints.

Parameters:

Name	Type	Description	Default
src_schema	Schema	Source schema.	required
tgt_schema	Schema	Target schema.	required
protocol	Protocol	The panproto protocol both schemas conform to.	required
hints	object	Vertex-correspondence hints. Their exact shape is panproto-defined.	required
stringency	str | None	Optional stringency hint. None uses panproto's default.	None

Returns:

Type	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.

Parameters:

Name	Type	Description	Default
json_text	str	A JSON string previously returned by to_json.	required

Returns:

Type	Description
DependentLens	The reconstructed chain.

Raises:

Type	Description
LensError	If json_text is not a valid serialised chain.

compose

compose(other: DependentLens) -> DependentLens

Vertically compose this chain with other.

Parameters:

Name	Type	Description	Default
other	DependentLens	Another DependentLens whose source matches this chain's target.	required

Returns:

Type	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:

Type	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.

Parameters:

Name	Type	Description	Default
schema	Schema	The concrete source schema to specialise against.	required
protocol	Protocol	The panproto protocol the schema conforms to.	required

Returns:

Type	Description
object	A panproto.Lens (treat as opaque from this side).

Raises:

Type	Description
LensError	If the chain cannot be instantiated against schema.

to_json

to_json() -> str

Serialise the chain to JSON.

Returns:

Type	Description
str	A JSON string suitable for round-tripping through from_json.

didactic.api.lens module-attribute

lens = _LensNamespace()