Python SDK reference

The Python package is panproto. It requires Python 3.13 or later and contains a native PyO3 extension.

python -m pip install panproto

Module surface

Public names are re-exported from panproto. There is no umbrella engine class. The package source lists those names in panproto.__all__, and the shipped _native.pyi file is the signature authority for the extension.

Builder contracts

Python builders mutate in place. Their mutation methods return None, except where _native.pyi declares a fluent return type.

class SchemaBuilder:
    def vertex(self, id: str, kind: str, nsid: str | None = ..., /) -> None: ...
    def edge(
        self,
        src: str,
        tgt: str,
        kind: str,
        name: str | None = ...,
    ) -> None: ...
    def constraint(self, vertex_id: str, sort: str, value: str) -> None: ...
    def build(self) -> Schema: ...

TheoryBuilder.sort, TheoryBuilder.op, and TheoryBuilder.eq return the builder and may be chained. Check _native.pyi before assuming that a builder follows either convention.

Migration direction

For a CompiledMigration whose schema mapping is (S\to T), lift(instance) accepts an (S)-instance and returns the surviving fragment as a (T)-instance. The method calls Rust’s restrict-based lift_wtype. It is neither the left Kan extension (\Sigma_F) nor precomposition (\Delta_F). get uses the same source-to-target operation and returns a complement with the view. put accepts the target view and complement and reconstructs a source instance.

Morphism search

find_span(
    src: Schema,
    tgt: Schema,
    protocol: Protocol,
    anchors: dict[str, str] | None = None,
    monic: bool = False,
    epic: bool = False,
    iso: bool = False,
) -> SchemaSpan

find_morphisms(
    src: Schema,
    tgt: Schema,
    anchors: dict[str, str] | None = None,
    monic: bool = False,
    epic: bool = False,
    iso: bool = False,
    max_results: int = 0,
) -> list[FoundMorphism]

find_span returns an empty apex when the schemas share no vertices. It requires a protocol because the induced apex is validated before it is returned. epic=True raises MigrationError for span search. Surjectivity is defined for the total-morphism functions.

find_morphisms returns total morphisms attaining the optimum. An empty list means that no total morphism exists, whereas a search failure raises MigrationError. The Python list does not carry the Rust MorphismList.truncated field, so this binding cannot report whether the engine stopped enumerating tied optima at its cap.

Grammar packs

AstParserRegistry() constructs a native registry and adds grammars advertised through installed panproto.grammars entry points. Discovery occurs when the factory is called. Importing a companion package is not required.

panproto._native.AstParserRegistry bypasses companion discovery and constructs the registry supplied by the core extension alone.

Ownership, errors, and typing

PyO3 objects follow Python reference ownership. The public stub exposes no dispose, release, or close method for schema, migration, lens, theory, repository, parser, or project objects.

PanprotoError is the common exception base. Domain subclasses include SchemaValidationError, MigrationError, LensError, CheckError, ExistenceCheckError, ExprError, GatError, IoError, VcsError, ParseError, ProjectError, and GitBridgeError.

The wheel includes py.typed and _native.pyi. Repository tests compare the stub’s public declarations with the loaded extension and check callable signatures, so generated documentation should follow the stub rather than infer signatures from Rust names.

See also

• Install the Python SDK
• Define a schema from Python
• Find a span between two schemas
• Python binding source