Metadata-Version: 2.4
Name: introspection-remote-proto
Version: 0.1.0
Summary: Python bindings for the `introspection dev` tunnel wire protocol (remote.proto)
Project-URL: Homepage, https://github.com/introspection-org/introspection-cli
Project-URL: Source, https://github.com/introspection-org/introspection-cli/tree/main/python/introspection-remote-proto
Author: Introspection
License: Apache-2.0
Keywords: introspection,protobuf,remote,tunnel
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: protobuf<7,>=5.29
Description-Content-Type: text/markdown

# introspection-remote-proto

Python bindings for the `introspection dev` tunnel wire protocol.

The **canonical schema** is [`crates/protocol/proto/remote.proto`](../../crates/protocol/proto/remote.proto)
in this repository — the single source of truth for the WebSocket tunnel
between the `introspection dev` CLI and the cloud-side Data Plane. The Rust CLI
codegens it via `prost` (`crates/protocol`); this package carries the generated
**Python** protobuf module so the cloud consumes exactly the same contract
instead of hand-syncing its own copy.

```python
from introspection_remote_proto import remote_pb2, SCHEMA_VERSION

frame = remote_pb2.Frame()
frame.heartbeat.SetInParent()
wire = frame.SerializeToString()
```

## Regenerating

`remote_pb2.py` is generated from the canonical `.proto` — never hand-edited.
After changing `crates/protocol/proto/remote.proto`, regenerate from this
directory:

```bash
./gen.sh
```

The script runs `protoc --python_out` against the canonical proto and writes
`src/introspection_remote_proto/remote_pb2.py`. Keep the protobuf `protoc`
version aligned with the runtime pin in `pyproject.toml` (`protobuf>=5.29,<6`);
the generated header records the version it was produced with.

## Versioning

The package version tracks the schema. `SCHEMA_VERSION` (mirroring the Rust
crate's constant) bumps only on **breaking** envelope changes; additive,
proto3-default-compatible field changes are a minor/patch release that both the
CLI and the Data Plane can adopt independently.

Published to PyPI from this repo's release workflow. The Data Plane depends on
it (`introspection-remote-proto`) and re-exports `remote_pb2` through
`introspection_common.remote`.

Releases are change-gated: the package publishes a new version only when the
schema (or this package) actually changes — it is versioned independently of
the CLI, starting at `0.1.0`, not on every CLI release.
