panproto

Python bindings for panproto, a schematic version-control system that treats every supported schema language (around 50, including ATProto, OpenAPI, AsyncAPI, Avro, Protobuf, JSON Schema, and Kubernetes CRDs) as views over a single graph format.

The bindings are built with PyO3 against the Rust core directly: no WASM runtime, no subprocess, no shelling out. The full panproto surface is available from Python, including the schema/migration/lens/VCS pipelines and the tree-sitter-driven parser for 259 programming languages.

Status

panproto is pre-1.0. The 0.x series carries arbitrary breaking changes between minor versions; the panproto package version tracks the workspace version on every release. Python 3.13+ is required (the wheels are abi3 and forward-compatible across newer Python releases).

Installation

pip install panproto

Wheels are published on PyPI for Linux x86_64/aarch64, macOS arm64+x86_64, and Windows x86_64. No Rust toolchain is required to install.

Synopsis

import panproto

# Pick a built-in protocol, or define your own with `Protocol.from_theories`.
atproto = panproto.get_builtin_protocol("atproto")

# Build a schema using the fluent builder.
v1 = atproto.schema()
v1.vertex("post", "record", "app.bsky.feed.post")
v1.vertex("post:body", "object")
v1.vertex("post:body.text", "string")
v1.edge("post", "post:body", "record-schema")
v1.edge("post:body", "post:body.text", "prop", "text")
v1.constraint("post:body.text", "maxLength", "3000")
schema_v1 = v1.build()

# (build schema_v2 the same way, with the field renamed to `content` ...)

# Detect breaking changes.
report = panproto.diff_and_classify(schema_v1, schema_v2, atproto)
print(report.compatible)        # True or False
print(report.report_text())     # human-readable summary

# Auto-generate a bidirectional converter.
lens, quality, _ = panproto.auto_generate_lens(schema_v1, schema_v2, atproto)
view, complement = lens.get(instance)
restored = lens.put(view, complement)

# Version-control schemas.
repo = panproto.Repository.init("/path/to/repo")
repo.add(schema_v1)
repo.commit("initial schema", "anonymous")
repo.create_and_checkout_branch("feature")
repo.merge("feature", "anonymous")

API overview

Module / class	Purpose
`Schema`, `SchemaBuilder`	Fluent schema construction; `Schema.validate(protocol)` checks rules.
`Protocol`	Schema-language definition. `Protocol.from_theories(...)` builds one from a `Theory`.
`get_builtin_protocol(name)`	Load any of the ~50 builtin protocols by name.
`define_protocol(spec)`	Define a custom protocol from a dict.
`Theory`, `create_theory`, `TheoryBuilder`	GAT-level theory construction. `Theory.from_nickel(src)` / `from_yaml(src)` / `from_json(src)` / `from_path(p)` load theory-DSL documents; `to_yaml()` / `from_dict_yaml(s)` round-trip the flat `panproto_gat::Theory` shape (JSON pair already provided).
`diff_schemas`, `diff_and_classify`	Structural diff and breaking-change classification.
`find_best_morphism`, `find_morphisms`	Search for a total schema morphism. Returns nothing when none exists.
`find_span`, `SchemaSpan`	Search for the optimal span. Always answers: two schemas with nothing in common give an empty apex, not a failure.
`auto_generate_lens`	Generate a bidirectional `Lens` from two schemas.
`Lens`	`get(instance) -> (view, complement)`, `put(view, complement) -> instance`.
`ProtolensChain`	`from_dsl_json(src, body_vertex)` / `from_dsl_yaml` / `from_dsl_nickel` / `from_dsl_path` compile a `panproto-lens-dsl` document into a chain anchored at the named body vertex of the source schema.
`MigrationBuilder`, `compile_migration`, `compose_migrations`	Hand-rolled migration construction.
`Instance`, `IoRegistry`	Parse/emit data across the 50+ supported formats.
`Repository`	Filesystem-backed VCS: init, commit, branch, merge, log, blame, bisect, stash, tag, plus data versioning.
`AstParserRegistry`, `parse_source_file`, `ParseEmitLens`	Full-AST parsing across 259 languages via tree-sitter. `AstParserRegistry.override_grammar(name, extensions, language_ptr, node_types, ...)` swaps a registered grammar at runtime for dev-time grammar work.
`Schema.constraints_for`, `Schema.field_text`	Read every constraint on a vertex; pull the text of a tree-sitter `field('<name>', anonymous-token)` child via `schema.field_text(vid, "name")`.
`Expr`, `parse_expr`, `pretty_print_expr`	Embedded expression language.

Companion grammar packs

The published panproto wheel ships only the 11 group-core tree-sitter grammars (Python, JavaScript, TypeScript, Java, C#, C++, PHP, Bash, C, Go, Rust). Beyond that, grammars are distributed as separately-installable companion wheels, one per language group:

Wheel	Languages
`panproto-grammars-web`	HTML, CSS, JavaScript, TypeScript, TSX, JSON, Vue, Svelte, Astro, GraphQL
`panproto-grammars-systems`	C, C++, Rust, Go, Zig, D, Nim, Odin, V, Hare
`panproto-grammars-jvm`	Java, Kotlin, Scala, Groovy, Clojure
`panproto-grammars-scripting`	Python, Ruby, Lua, Bash, Perl, R, Julia, Nushell, Fish
`panproto-grammars-data`	JSON, TOML, XML, YAML, SQL, CSV, GraphQL, Protobuf
`panproto-grammars-functional`	Haskell, OCaml, Elm, Gleam, Erlang, Elixir, PureScript, F#, Clojure, Scheme, Racket
`panproto-grammars-devops`	Dockerfile, Terraform, HCL, Nix, Bash, YAML, TOML, Make, CMake
`panproto-grammars-mobile`	Swift, Kotlin, Dart, Java, Objective-C
`panproto-grammars-music`	SuperCollider, LilyPond, ABC, Csound, ChucK, Glicol, Tidal mini-notation, Strudel mini-notation
`panproto-grammars-all`	every grammar in `panproto-grammars` (259 languages)

Install whichever group you need:

pip install panproto-grammars-functional

There is nothing to import from these packages. They register a panproto.grammars entry point on installation; panproto.AstParserRegistry() walks every such entry point and threads the discovered grammar metadata into the native registry on construction. The native class is reachable as panproto._native.AstParserRegistry() for callers who want only the group-core baseline.

How it works under the hood:

Each companion is its own pyo3 cdylib depending on panproto-grammars with one group-* feature flag.
On import, the companion's grammars_metadata() returns a list of dicts containing the tree-sitter Language pointer plus byte-slice pointer/length pairs (cast to integers for transport across cdylib boundaries).
The trust boundary lives on the panproto side, in register_external_from_metadata (crates/panproto-py/src/parse.rs), which decodes the integers back into &'static references and registers a full LanguageParser. The companion's grammar bytes live in its .rodata and stay valid for the process lifetime.
A single broken grammar (e.g. an upstream node-types.json with a malformed entry) is skipped with a RuntimeWarning rather than aborting registration; mirrors the resilience of the built-in path.

Performance notes

The _native extension talks to the Rust core through PyO3's zero-copy pyclass slabs. Schemas, theories, and lenses are reference-counted Rust objects on the Python side; mutations go through dedicated builder types (SchemaBuilder, MigrationBuilder) that consume on build(), so you can't accidentally observe partial state.
Cross-thread sharing of these objects requires the GIL; for parallel work, fan out at the data layer (e.g. parallelise lens.get calls with concurrent.futures) and keep the schema/lens objects per worker.
Wheel-load cost is one-time; the import sets up the protocol registry lazily so cold-start is fast.

Contributing

Source: bindings/python. Issues and pull requests at github.com/panproto/panproto/issues.

The native extension lives at crates/panproto-py on the Rust side; bindings/python/src/panproto/__init__.py is the pure-Python re-export layer that maturin ships alongside the compiled extension.

License

Development Status
- 3 - Alpha
Intended Audience
- Developers
License
- OSI Approved :: MIT License
Programming Language
Typing
- Typed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

panproto-0.71.0-cp313-abi3-win_amd64.whl (12.9 MB view details)

Uploaded Aug 18, 2026 CPython 3.13+Windows x86-64

panproto-0.71.0-cp313-abi3-manylinux_2_28_x86_64.whl (11.7 MB view details)

Uploaded Aug 18, 2026 CPython 3.13+manylinux: glibc 2.28+ x86-64

panproto-0.71.0-cp313-abi3-manylinux_2_28_aarch64.whl (10.8 MB view details)

Uploaded Aug 18, 2026 CPython 3.13+manylinux: glibc 2.28+ ARM64

panproto-0.71.0-cp313-abi3-macosx_11_0_arm64.whl (10.8 MB view details)

Uploaded Aug 18, 2026 CPython 3.13+macOS 11.0+ ARM64

panproto-0.71.0-cp313-abi3-macosx_10_12_x86_64.whl (11.5 MB view details)

Uploaded Aug 18, 2026 CPython 3.13+macOS 10.12+ x86-64

File details

Details for the file panproto-0.71.0-cp313-abi3-win_amd64.whl.

File metadata

Download URL: panproto-0.71.0-cp313-abi3-win_amd64.whl
Upload date: Aug 18, 2026
Size: 12.9 MB
Tags: CPython 3.13+, Windows x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for panproto-0.71.0-cp313-abi3-win_amd64.whl
Algorithm	Hash digest
SHA256	`feb799679c4d1c3cd1cc40a7eac5432642043166e7a7f31af710edbbb7afc9fd`
MD5	`c357ac344e219cf1d36e41d1177a29e9`
BLAKE2b-256	`e5924690a6026aa4afb214f169b769799110c1640b8ff34bf9da596a10e6a58e`

See more details on using hashes here.

Provenance

The following attestation bundles were made for panproto-0.71.0-cp313-abi3-win_amd64.whl:

Publisher: python-wheels.yml on panproto/panproto

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: panproto-0.71.0-cp313-abi3-win_amd64.whl
- Subject digest: feb799679c4d1c3cd1cc40a7eac5432642043166e7a7f31af710edbbb7afc9fd
- Sigstore transparency entry: 2509501441
- Sigstore integration time: Aug 18, 2026
Source repository:
- Permalink: panproto/panproto@efa04235eb9aa9d718ad358b6104f69eac17881f
- Branch / Tag: refs/tags/v0.71.0
- Owner: https://github.com/panproto
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: python-wheels.yml@efa04235eb9aa9d718ad358b6104f69eac17881f
- Trigger Event: push

File details

Details for the file panproto-0.71.0-cp313-abi3-manylinux_2_28_x86_64.whl.

File metadata

Download URL: panproto-0.71.0-cp313-abi3-manylinux_2_28_x86_64.whl
Upload date: Aug 18, 2026
Size: 11.7 MB
Tags: CPython 3.13+, manylinux: glibc 2.28+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for panproto-0.71.0-cp313-abi3-manylinux_2_28_x86_64.whl
Algorithm	Hash digest
SHA256	`5dc52f8884ee7bd25e2ed05e87587b78da49040fc4f486deb43455f3a6487acc`
MD5	`e6400845529005d60de46b37f400275e`
BLAKE2b-256	`4c26b6ee1796da54136f41f0b472bb552f80bad02c6691d49108937b2437b754`

See more details on using hashes here.

Provenance

The following attestation bundles were made for panproto-0.71.0-cp313-abi3-manylinux_2_28_x86_64.whl:

Publisher: python-wheels.yml on panproto/panproto

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: panproto-0.71.0-cp313-abi3-manylinux_2_28_x86_64.whl
- Subject digest: 5dc52f8884ee7bd25e2ed05e87587b78da49040fc4f486deb43455f3a6487acc
- Sigstore transparency entry: 2509503218
- Sigstore integration time: Aug 18, 2026
Source repository:
- Permalink: panproto/panproto@efa04235eb9aa9d718ad358b6104f69eac17881f
- Branch / Tag: refs/tags/v0.71.0
- Owner: https://github.com/panproto
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: python-wheels.yml@efa04235eb9aa9d718ad358b6104f69eac17881f
- Trigger Event: push

File details

Details for the file panproto-0.71.0-cp313-abi3-manylinux_2_28_aarch64.whl.

File metadata

Download URL: panproto-0.71.0-cp313-abi3-manylinux_2_28_aarch64.whl
Upload date: Aug 18, 2026
Size: 10.8 MB
Tags: CPython 3.13+, manylinux: glibc 2.28+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for panproto-0.71.0-cp313-abi3-manylinux_2_28_aarch64.whl
Algorithm	Hash digest
SHA256	`1134edbad6c90ce0f56380f90d3ac2f86be2b04e0790fd5926ed24a627a85459`
MD5	`f7ebda7785131623e87b79a401aa9446`
BLAKE2b-256	`d9a56b9b37b41f3917f739e7ef6c417247b34e5e323e8a48eae80d98c0a810c9`

See more details on using hashes here.

Provenance

The following attestation bundles were made for panproto-0.71.0-cp313-abi3-manylinux_2_28_aarch64.whl:

Publisher: python-wheels.yml on panproto/panproto

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: panproto-0.71.0-cp313-abi3-manylinux_2_28_aarch64.whl
- Subject digest: 1134edbad6c90ce0f56380f90d3ac2f86be2b04e0790fd5926ed24a627a85459
- Sigstore transparency entry: 2509502546
- Sigstore integration time: Aug 18, 2026
Source repository:
- Permalink: panproto/panproto@efa04235eb9aa9d718ad358b6104f69eac17881f
- Branch / Tag: refs/tags/v0.71.0
- Owner: https://github.com/panproto
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: python-wheels.yml@efa04235eb9aa9d718ad358b6104f69eac17881f
- Trigger Event: push

File details

Details for the file panproto-0.71.0-cp313-abi3-macosx_11_0_arm64.whl.

File metadata

Download URL: panproto-0.71.0-cp313-abi3-macosx_11_0_arm64.whl
Upload date: Aug 18, 2026
Size: 10.8 MB
Tags: CPython 3.13+, macOS 11.0+ ARM64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for panproto-0.71.0-cp313-abi3-macosx_11_0_arm64.whl
Algorithm	Hash digest
SHA256	`42e75a5baa244297e872bd6d7ec794fbe3106d839673d64172f91e9903fca09f`
MD5	`c93e09b1c12fcac994a04d3f59bc0d50`
BLAKE2b-256	`ee757dcc76d888b4cb9d30e7af78e2a78a17f3bf995719f3637b01246fed16f9`

See more details on using hashes here.

Provenance

The following attestation bundles were made for panproto-0.71.0-cp313-abi3-macosx_11_0_arm64.whl:

Publisher: python-wheels.yml on panproto/panproto

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: panproto-0.71.0-cp313-abi3-macosx_11_0_arm64.whl
- Subject digest: 42e75a5baa244297e872bd6d7ec794fbe3106d839673d64172f91e9903fca09f
- Sigstore transparency entry: 2509502158
- Sigstore integration time: Aug 18, 2026
Source repository:
- Permalink: panproto/panproto@efa04235eb9aa9d718ad358b6104f69eac17881f
- Branch / Tag: refs/tags/v0.71.0
- Owner: https://github.com/panproto
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: python-wheels.yml@efa04235eb9aa9d718ad358b6104f69eac17881f
- Trigger Event: push

File details

Details for the file panproto-0.71.0-cp313-abi3-macosx_10_12_x86_64.whl.

File metadata

Download URL: panproto-0.71.0-cp313-abi3-macosx_10_12_x86_64.whl
Upload date: Aug 18, 2026
Size: 11.5 MB
Tags: CPython 3.13+, macOS 10.12+ x86-64
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for panproto-0.71.0-cp313-abi3-macosx_10_12_x86_64.whl
Algorithm	Hash digest
SHA256	`a56413dc9acd249400479691b4398f2625a4f8357b4263328a63f9a76cdf7696`
MD5	`8c2ea76771a12c1b7c100187b0f9bd03`
BLAKE2b-256	`3b2f99e05c95c6b4ee1a2bb502df5e0f5613d322437b2bfe315f9c96e71740ee`

See more details on using hashes here.

Provenance

The following attestation bundles were made for panproto-0.71.0-cp313-abi3-macosx_10_12_x86_64.whl:

Publisher: python-wheels.yml on panproto/panproto

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: panproto-0.71.0-cp313-abi3-macosx_10_12_x86_64.whl
- Subject digest: a56413dc9acd249400479691b4398f2625a4f8357b4263328a63f9a76cdf7696
- Sigstore transparency entry: 2509501750
- Sigstore integration time: Aug 18, 2026
Source repository:
- Permalink: panproto/panproto@efa04235eb9aa9d718ad358b6104f69eac17881f
- Branch / Tag: refs/tags/v0.71.0
- Owner: https://github.com/panproto
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: python-wheels.yml@efa04235eb9aa9d718ad358b6104f69eac17881f
- Trigger Event: push