Skip to main content

panproto

PyPI Python License: MIT

This package exposes panproto's Rust libraries to Python through PyO3. It does not start a subprocess or load the WebAssembly build. Python 3.13 or newer is required.

The package is pre-1.0. A minor release may change the Python API, and the package version follows the Rust workspace version.

Installation

pip install panproto

Release workflows build wheels for Linux on x86-64 and AArch64, macOS on Apple Silicon and x86-64, and Windows on x86-64. A source build requires Rust and maturin.

Quick start

Protocol.schema() returns a mutable SchemaBuilder. Builder methods update the builder and return None; call build() after all changes have been added.

import panproto

atproto = panproto.get_builtin_protocol("atproto")

old_builder = atproto.schema()
old_builder.vertex("post", "record", "app.bsky.feed.post")
old_builder.vertex("post:body", "object")
old_builder.vertex("post:body.text", "string")
old_builder.edge("post", "post:body", "record-schema")
old_builder.edge("post:body", "post:body.text", "prop", "text")
old_schema = old_builder.build()

new_builder = atproto.schema()
new_builder.vertex("post", "record", "app.bsky.feed.post")
new_builder.vertex("post:body", "object")
new_builder.vertex("post:body.content", "string")
new_builder.edge("post", "post:body", "record-schema")
new_builder.edge("post:body", "post:body.content", "prop", "content")
new_schema = new_builder.build()

report = panproto.diff_and_classify(old_schema, new_schema, atproto)
print(report.classification)
print(report.report_text())

CompatReport.classification is one of "fully-compatible", "backward-compatible", or "breaking". The object also exposes compatible, breaking_changes, non_breaking_changes, report_json(), and to_dict().

Migrations and lenses

MigrationBuilder records a source-to-target vertex map. Compile the result against its source and target schemas:

builder = panproto.MigrationBuilder()
builder.map_vertex("post", "post")
builder.map_vertex("post:body", "post:body")
migration = builder.build()

compiled = panproto.compile_migration(migration, old_schema, new_schema)

CompiledMigration.lift(instance, src_protocol, tgt_protocol=None) constructs a target instance from the mapped part of a source instance, validating the instance against the source schema under src_protocol and the result against the target schema under tgt_protocol (which defaults to src_protocol). This operation is the library's source-to-target surviving-fragment transfer. The categorical transports are separate: Delta reindexes a target instance back to the source, while a general left Kan extension computes the source-to-target Sigma transport. The vocabulary in plain terms defines both.

CompiledMigration.get(instance) and Lens.get(instance) project a source instance to a target-shaped view and return an opaque complement. Their corresponding put(view, complement) methods reconstruct a source instance.

lens, quality, proposals = panproto.auto_generate_lens(
    old_schema, new_schema, atproto
)
view, complement = lens.get(source_instance)
restored_source = lens.put(view, complement)

find_morphisms() and find_best_morphism() search for total schema morphisms. find_best_morphism() returns None when none exists. find_span() instead returns a SchemaSpan in every no-overlap case, with an empty apex representing the absence of shared structure.

The ProtolensChain.from_dsl_*() constructors retain both the structural chain and the lens-DSL compiler's value-level field transforms. Instantiating the chain installs those transforms in the compiled migration. to_json() and from_json() preserve them in the optional field_transforms member.

Tree-sitter grammar packages

The default source build enables the 11 group-core grammars: Python, JavaScript, TypeScript, Java, C#, C++, PHP, Bash, C, Go, and Rust. Optional companion wheels register other grammar groups through the panproto.grammars Python entry-point group. panproto-grammars-all contains all 261 grammars currently declared by panproto-grammars.

pip install panproto-grammars-functional

Constructing panproto.AstParserRegistry() loads metadata from installed companions. panproto._native.AstParserRegistry() constructs only the native registry. A companion whose metadata cannot be registered produces a RuntimeWarning for that grammar and does not stop the other grammars from loading.

Object ownership

PyO3 classes own Rust values directly. Several classes share immutable schemas through Rust reference counting, and Python releases those values when their wrappers are collected. There is no numeric handle API and no manual free function.

API reference

API Current behavior
parse_schema_document, parse_schema_source, parse_schema_bundle Parse schema documents or source-language definitions through the registered Rust parsers.
IoRegistry Parse and emit instances. Use len(registry) or list_protocols() to inspect the codecs in the installed build.
Theory, TheoryBuilder, create_theory, colimit_theories Construct and combine generalized algebraic theories.
Repository Open or create a filesystem-backed .panproto repository with commits, branches, tags, merge, rebase, stash, blame, bisect, data tracking, and garbage collection.
VcsRepository A separate in-memory wrapper with only add() and list_refs(). It is not a Repository subclass.
ProjectBuilder, build_project, parse_project Assemble multi-file projects.
AstParserRegistry, parse_source_file, ParseEmitLens Parse source files with the tree-sitter grammars present in the build or supplied by companion packages.
Expr, parse_expr, pretty_print_expr Parse, inspect, and evaluate the expression language through methods on Expr.

Repository reads accept full commit IDs, HEAD, branches, tags, and unique commit-ID prefixes of at least four hexadecimal characters. Prefix lookup is read-only and reports malformed, absent, ambiguous, and non-commit matches.

The type stub at src/panproto/_native.pyi gives the complete public signatures.

Repository.add_data(path, key=None, *, schema_id=None, skip_verify=False) normally validates against the staged schema, or HEAD when no schema is staged. Pass the full object ID of a persisted schema to bind one data set to that exact schema without changing HEAD or the staged schema. The committed data set retains the selected ID, and malformed, missing, or non-schema object IDs are rejected.

Development

Build the extension and run the Python test suite from this directory:

maturin develop
python -m pytest

A development build requires Rust, Python 3.13 or newer, and maturin.

Further reading

License

MIT

Metadata

Release files for panproto 0.77.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Built distributions (wheels)

Table of built distributions (wheels) for panproto 0.77.0
File Actions
panproto-0.77.0-cp313-abi3-win_amd64.whl CPython 3.13 abi3 Windows x86-64 Details for panproto-0.77.0-cp313-abi3-win_amd64.whl
panproto-0.77.0-cp313-abi3-manylinux_2_28_x86_64.whl CPython 3.13 abi3 Linux glibc 2.28+ x86-64 Details for panproto-0.77.0-cp313-abi3-manylinux_2_28_x86_64.whl
panproto-0.77.0-cp313-abi3-manylinux_2_28_aarch64.whl CPython 3.13 abi3 Linux glibc 2.28+ ARM64 Details for panproto-0.77.0-cp313-abi3-manylinux_2_28_aarch64.whl
panproto-0.77.0-cp313-abi3-macosx_11_0_arm64.whl CPython 3.13 abi3 macOS 11.0+ ARM64 Details for panproto-0.77.0-cp313-abi3-macosx_11_0_arm64.whl
panproto-0.77.0-cp313-abi3-macosx_10_12_x86_64.whl CPython 3.13 abi3 macOS 10.12+ x86-64 Details for panproto-0.77.0-cp313-abi3-macosx_10_12_x86_64.whl

Total release size: 76.5 MB

Release files / panproto-0.77.0-cp313-abi3-win_amd64.whl

Download URL panproto-0.77.0-cp313-abi3-win_amd64.whl
Size 17.0 MB
Tags CPython 3.13 Windows x86-64 abi3
SHA-256 checksum
How to use checksums
fd358a48e39434bc89209e844f8c88145507748d82e967f8353ad798729b65a4
BLAKE2b-256 checksum
How to use checksums
80c06af48555190ebca870defa4fcf248ece0be252f907b40888ff8bb0f8afe2
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / panproto-0.77.0-cp313-abi3-manylinux_2_28_x86_64.whl

Download URL panproto-0.77.0-cp313-abi3-manylinux_2_28_x86_64.whl
Size 15.7 MB
Tags CPython 3.13 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
e426a35028a12c4273981c6659d18f7e6325279e230edfbb30cba17850a0094b
BLAKE2b-256 checksum
How to use checksums
55bafd0a3defff38e39f20d1f091d11407d3c1ddc9613300c895caac344fc403
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / panproto-0.77.0-cp313-abi3-manylinux_2_28_aarch64.whl

Download URL panproto-0.77.0-cp313-abi3-manylinux_2_28_aarch64.whl
Size 14.3 MB
Tags CPython 3.13 Linux glibc 2.28+ ARM64 abi3
SHA-256 checksum
How to use checksums
c563de47e0bd4b49e503e5c8f09455a4ff94139c9f0c02a8baa1818906713d53
BLAKE2b-256 checksum
How to use checksums
02cc959c3779d439b709e34dbb057af458cac2a4161fa2f12ce67e31aa4af369
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / panproto-0.77.0-cp313-abi3-macosx_11_0_arm64.whl

Download URL panproto-0.77.0-cp313-abi3-macosx_11_0_arm64.whl
Size 14.2 MB
Tags CPython 3.13 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
45ab5cda636144b0c124117738f4135bba0f10920c00e38a9b1600324f79fac2
BLAKE2b-256 checksum
How to use checksums
a59e88adb42514b7ecf20e8ae9a82126d40e3b7f1827b4ec8a5ce837b18d1012
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Release files / panproto-0.77.0-cp313-abi3-macosx_10_12_x86_64.whl

Download URL panproto-0.77.0-cp313-abi3-macosx_10_12_x86_64.whl
Size 15.3 MB
Tags CPython 3.13 abi3 macOS 10.12+ x86-64
SHA-256 checksum
How to use checksums
bfc80576e493adc034f7fc76d3b82f702390f1d9200bc2322e5afd44f7c9f6f8
BLAKE2b-256 checksum
How to use checksums
575b0943f23938d05a13e96808162c0cf6561d89c327f9b2244e7530551d2ccf
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

Security for panproto 0.77.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

All 5 files in this release have been uploaded with provenance metadata.

Select from 5 files

Attestation for panproto-0.77.0-cp313-abi3-win_amd64.whl

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 11, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.77.0 This release

5 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page