panproto 0.2.0__tar.gz

panproto-0.2.0/.gitignore

@@ -0,0 +1,42 @@
+# Rust
+target/
+Cargo.lock
+
+# WASM
+pkg/
+*.wasm
+
+# Python
+__pycache__/
+*.pyc
+*.pyo
+.venv/
+*.egg-info/
+
+# Node
+node_modules/
+dist/
+package-lock.json
+
+# Coverage
+coverage/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.*
+
+# Claude
+.claude/
+
+# Notes
+notes/

panproto-0.2.0/PKG-INFO

@@ -0,0 +1,54 @@
+Metadata-Version: 2.4
+Name: panproto
+Version: 0.2.0
+Summary: Universal schema migration engine (Python SDK)
+Project-URL: Homepage, https://github.com/panproto/panproto
+Project-URL: Repository, https://github.com/panproto/panproto
+Project-URL: Documentation, https://panproto.github.io
+Author-email: Aaron Steven White <aaron.steven.white@gmail.com>
+License-Expression: MIT
+Keywords: gat,lens,migration,schema,wasm
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.13
+Requires-Dist: msgpack>=1.1.0
+Requires-Dist: wasmtime>=29.0.0
+Provides-Extra: dev
+Requires-Dist: pyright>=1.1; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# panproto — Python SDK
+
+Universal schema migration engine for Python 3.13+.
+
+## Installation
+
+```bash
+pip install panproto
+```
+
+## Quick Start
+
+```python
+from panproto import Panproto
+
+with Panproto.load() as pp:
+    atproto = pp.protocol("atproto")
+    schema = (
+        atproto.schema()
+        .vertex("post", "record", {"nsid": "app.bsky.feed.post"})
+        .vertex("post:body", "object")
+        .edge("post", "post:body", "record-schema")
+        .build()
+    )
+```
+
+## License
+
+MIT

panproto-0.2.0/README.md

@@ -0,0 +1,29 @@
+# panproto — Python SDK
+
+Universal schema migration engine for Python 3.13+.
+
+## Installation
+
+```bash
+pip install panproto
+```
+
+## Quick Start
+
+```python
+from panproto import Panproto
+
+with Panproto.load() as pp:
+    atproto = pp.protocol("atproto")
+    schema = (
+        atproto.schema()
+        .vertex("post", "record", {"nsid": "app.bsky.feed.post"})
+        .vertex("post:body", "object")
+        .edge("post", "post:body", "record-schema")
+        .build()
+    )
+```
+
+## License
+
+MIT

panproto-0.2.0/pyproject.toml

@@ -0,0 +1,75 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "panproto"
+version = "0.2.0"
+description = "Universal schema migration engine (Python SDK)"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.13"
+authors = [
+    { name = "Aaron Steven White", email = "aaron.steven.white@gmail.com" },
+]
+keywords = ["schema", "migration", "gat", "lens", "wasm"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = [
+    "wasmtime>=29.0.0",
+    "msgpack>=1.1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "ruff>=0.5",
+    "pyright>=1.1",
+]
+
+[project.urls]
+Homepage = "https://github.com/panproto/panproto"
+Repository = "https://github.com/panproto/panproto"
+Documentation = "https://panproto.github.io"
+
+[tool.hatch.build.targets.sdist]
+include = ["src/panproto"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/panproto"]
+
+[tool.pyright]
+pythonVersion = "3.13"
+pythonPlatform = "All"
+typeCheckingMode = "strict"
+reportMissingTypeStubs = false
+
+[tool.ruff]
+target-version = "py313"
+line-length = 99
+
+[tool.ruff.lint]
+select = [
+    "E", "F", "W",     # pyflakes + pycodestyle
+    "I",                # isort
+    "N",                # pep8-naming
+    "UP",               # pyupgrade
+    "B",                # bugbear
+    "A",                # builtins
+    "C4",               # comprehensions
+    "SIM",              # simplify
+    "TCH",              # type-checking imports
+    "RUF",              # ruff-specific
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["panproto"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

panproto-0.2.0/src/panproto/__init__.py

@@ -0,0 +1,148 @@
+"""panproto — Universal schema migration engine for Python.
+
+Provides a type-safe, WASM-backed runtime for defining protocols,
+building schemas, compiling bidirectional migrations, and diffing
+schema versions across ATProto, SQL, Protobuf, GraphQL, and
+JSON Schema.
+"""
+
+from __future__ import annotations
+
+from panproto._errors import (
+    ExistenceCheckError,
+    MigrationError,
+    PanprotoError,
+    SchemaValidationError,
+    WasmError,
+)
+from panproto._lens import (
+    AddField,
+    CoerceType,
+    Combinator,
+    Compose,
+    HoistField,
+    RemoveField,
+    RenameField,
+    WrapInObject,
+    add_field,
+    coerce_type,
+    combinator_to_wire,
+    compose,
+    hoist_field,
+    pipeline,
+    remove_field,
+    rename_field,
+    wrap_in_object,
+)
+from panproto._migration import (
+    CompiledMigration,
+    MigrationBuilder,
+    check_existence,
+    compose_migrations,
+)
+from panproto._panproto import Panproto
+from panproto._protocol import (
+    ATPROTO_SPEC,
+    BUILTIN_PROTOCOLS,
+    GRAPHQL_SPEC,
+    JSON_SCHEMA_SPEC,
+    PROTOBUF_SPEC,
+    SQL_SPEC,
+    Protocol,
+    define_protocol,
+)
+from panproto._schema import BuiltSchema, SchemaBuilder
+from panproto._types import (
+    Compatibility,
+    Constraint,
+    DiffReport,
+    Edge,
+    EdgeOptions,
+    # Re-export all TypedDicts + type aliases users need
+    EdgeRule,
+    ExistenceError,
+    ExistenceErrorKind,
+    ExistenceReport,
+    GetResult,
+    HyperEdge,
+    JsonValue,
+    LiftResult,
+    MigrationSpec,
+    ProtocolSpec,
+    SchemaChange,
+    SchemaChangeKind,
+    SchemaData,
+    Vertex,
+    VertexOptions,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ATPROTO_SPEC",
+    "BUILTIN_PROTOCOLS",
+    "GRAPHQL_SPEC",
+    "JSON_SCHEMA_SPEC",
+    "PROTOBUF_SPEC",
+    "SQL_SPEC",
+    "AddField",
+    "BuiltSchema",
+    "CoerceType",
+    "Combinator",
+    "Compatibility",
+    "CompiledMigration",
+    "Compose",
+    "Constraint",
+    "DiffReport",
+    "Edge",
+    "EdgeOptions",
+    # Types
+    "EdgeRule",
+    "ExistenceCheckError",
+    "ExistenceError",
+    "ExistenceErrorKind",
+    "ExistenceReport",
+    "GetResult",
+    "HoistField",
+    "HyperEdge",
+    "JsonValue",
+    "LiftResult",
+    # Migration
+    "MigrationBuilder",
+    "MigrationError",
+    "MigrationSpec",
+    # Main
+    "Panproto",
+    # Errors
+    "PanprotoError",
+    # Protocol
+    "Protocol",
+    "ProtocolSpec",
+    "RemoveField",
+    # Lens
+    "RenameField",
+    # Schema
+    "SchemaBuilder",
+    "SchemaChange",
+    "SchemaChangeKind",
+    "SchemaData",
+    "SchemaValidationError",
+    "Vertex",
+    "VertexOptions",
+    "WasmError",
+    "WrapInObject",
+    # Version
+    "__version__",
+    "add_field",
+    "check_existence",
+    "coerce_type",
+    "combinator_to_wire",
+    "compose",
+    "compose_migrations",
+    "define_protocol",
+    "hoist_field",
+    "pipeline",
+    "remove_field",
+    "rename_field",
+    "wrap_in_object",
+]

panproto-0.2.0/src/panproto/_errors.py

@@ -0,0 +1,127 @@
+"""Error hierarchy for the panproto Python SDK.
+
+All exceptions inherit from :class:`PanprotoError`.  The hierarchy mirrors
+the TypeScript SDK:
+
+.. code-block:: text
+
+    PanprotoError
+    ├── WasmError
+    ├── SchemaValidationError
+    ├── MigrationError
+    └── ExistenceCheckError
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+if TYPE_CHECKING:
+    from panproto._types import ExistenceReport
+
+__all__ = [
+    "ExistenceCheckError",
+    "MigrationError",
+    "PanprotoError",
+    "SchemaValidationError",
+    "WasmError",
+]
+
+
+class PanprotoError(Exception):
+    """Base exception for all panproto errors.
+
+    Parameters
+    ----------
+    message : str
+        Human-readable error description.
+    """
+
+    __slots__ = ("message",)
+
+    def __init__(self, message: str) -> None:
+        super().__init__(message)
+        self.message: str = message
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.message!r})"
+
+
+@final
+class WasmError(PanprotoError):
+    """Raised when an error occurs at the WASM boundary.
+
+    This covers both errors returned by WASM entry-points and failures
+    in the host-side MessagePack encode/decode path.
+
+    Parameters
+    ----------
+    message : str
+        Human-readable description of the WASM error.
+    """
+
+    __slots__ = ()
+
+
+@final
+class SchemaValidationError(PanprotoError):
+    """Raised when schema construction or validation fails.
+
+    Parameters
+    ----------
+    message : str
+        Human-readable summary of the validation failure.
+    errors : tuple[str, ...]
+        Individual validation error messages returned by the WASM validator.
+    """
+
+    __slots__ = ("errors",)
+
+    def __init__(self, message: str, errors: tuple[str, ...]) -> None:
+        super().__init__(message)
+        self.errors: tuple[str, ...] = errors
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({self.message!r}, errors={self.errors!r})"
+
+
+@final
+class MigrationError(PanprotoError):
+    """Raised when migration compilation or composition fails.
+
+    Parameters
+    ----------
+    message : str
+        Human-readable description of the migration error.
+    """
+
+    __slots__ = ()
+
+
+@final
+class ExistenceCheckError(PanprotoError):
+    """Raised when existence checking finds constraint violations.
+
+    The attached :attr:`report` contains the full structured report,
+    including individual :class:`~panproto._types.ExistenceError` entries.
+
+    Parameters
+    ----------
+    message : str
+        Human-readable summary.
+    report : ExistenceReport
+        The full existence report returned by the WASM checker.
+    """
+
+    __slots__ = ("report",)
+
+    def __init__(self, message: str, report: ExistenceReport) -> None:
+        super().__init__(message)
+        self.report: ExistenceReport = report
+
+    def __repr__(self) -> str:
+        return (
+            f"{type(self).__name__}({self.message!r}, "
+            f"valid={self.report['valid']!r}, "
+            f"errors={self.report['errors']!r})"
+        )