panproto
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) constructs a target instance from the
mapped part of a source instance. 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
- John Cartmell, Generalised algebraic theories and contextual categories, Annals of Pure and Applied Logic 32, 209-243, 1986.
- J. Nathan Foster et al., Combinators for bidirectional tree transformations, ACM Transactions on Programming Languages and Systems 29(3), article 17, 2007.
- David I. Spivak, Functorial data migration, Information and Computation 217, 31-51, 2012.
License
1 maintainer
Metadata
1 maintainer
Release files for panproto 0.76.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| panproto-0.76.1-cp313-abi3-win_amd64.whl | CPython 3.13 | abi3 | Windows x86-64 | Details |
| panproto-0.76.1-cp313-abi3-manylinux_2_28_x86_64.whl | CPython 3.13 | abi3 | Linux glibc 2.28+ x86-64 | Details |
| panproto-0.76.1-cp313-abi3-manylinux_2_28_aarch64.whl | CPython 3.13 | abi3 | Linux glibc 2.28+ ARM64 | Details |
| panproto-0.76.1-cp313-abi3-macosx_11_0_arm64.whl | CPython 3.13 | abi3 | macOS 11.0+ ARM64 | Details |
| panproto-0.76.1-cp313-abi3-macosx_10_12_x86_64.whl | CPython 3.13 | abi3 | macOS 10.12+ x86-64 | Details |
Total release size: 60.8 MB
Release files / panproto-0.76.1-cp313-abi3-win_amd64.whl
| Download URL | panproto-0.76.1-cp313-abi3-win_amd64.whl |
|---|---|
| Size | 13.6 MB |
| Tags | CPython 3.13 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
b37b4304869eb9b47a9ca510d281dd871435b8f0100d3a5d9fd7a74391e8a9b7
|
|
BLAKE2b-256 checksum How to use checksums |
696e69999101dca6819a8a3a876b4887adf4a46ad10dc8411779da8893236e3f
|
| 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 Oct 11, 2026.
Transparency logRelease files / panproto-0.76.1-cp313-abi3-manylinux_2_28_x86_64.whl
| Download URL | panproto-0.76.1-cp313-abi3-manylinux_2_28_x86_64.whl |
|---|---|
| Size | 12.4 MB |
| Tags | CPython 3.13 Linux glibc 2.28+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
f30d7ad3e02b044cfaf71a4c8fbbf45f9bcb7ca417b2edfa4364228686bbcb08
|
|
BLAKE2b-256 checksum How to use checksums |
a578d606958b0df51f3400006acab7353dcc02b6e632ddfb004eddbf84ab2cd2
|
| 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 Oct 11, 2026.
Transparency logRelease files / panproto-0.76.1-cp313-abi3-manylinux_2_28_aarch64.whl
| Download URL | panproto-0.76.1-cp313-abi3-manylinux_2_28_aarch64.whl |
|---|---|
| Size | 11.4 MB |
| Tags | CPython 3.13 Linux glibc 2.28+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
2701dc94e6a590c5afa30bc34a12ce5532c0dc69232b8568fdc5d81e773e6c9a
|
|
BLAKE2b-256 checksum How to use checksums |
ce8c72338d494760449eea2cf56b756d5c6cefa342c7274d6c623cb62971dae9
|
| 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 Oct 11, 2026.
Transparency logRelease files / panproto-0.76.1-cp313-abi3-macosx_11_0_arm64.whl
| Download URL | panproto-0.76.1-cp313-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 11.3 MB |
| Tags | CPython 3.13 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
e8ad585c5601493482903921cb0b01b10b09dd7176d207b33bbf63bcc0a50067
|
|
BLAKE2b-256 checksum How to use checksums |
4a9a92a430b99661d1890422ebf70a1dcd89d5f8764ae637c64c46dd33d2730f
|
| 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 Oct 11, 2026.
Transparency logRelease files / panproto-0.76.1-cp313-abi3-macosx_10_12_x86_64.whl
| Download URL | panproto-0.76.1-cp313-abi3-macosx_10_12_x86_64.whl |
|---|---|
| Size | 12.2 MB |
| Tags | CPython 3.13 abi3 macOS 10.12+ x86-64 |
|
SHA-256 checksum How to use checksums |
af7899d11adddd413fac3d91df8e3a28840454d59b22c6b29714854a1febe5ef
|
|
BLAKE2b-256 checksum How to use checksums |
fba010a91756158cc2a2a2a20767fcf9f7900a00749b949375768281806e85e6
|
| 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 Oct 11, 2026.
Transparency log
