Metadata-Version: 2.5
Name: vention-sim-grpc-py-sdk
Version: 0.1.0.dev34274290904
Summary: Generated Python gRPC clients for the Vention simulation protos
Project-URL: Homepage, https://github.com/VentionCo/simulation
Project-URL: Repository, https://github.com/VentionCo/simulation
Author: VentionCo
License: Proprietary
Keywords: client,grpc,protobuf,simulation,vention
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: grpcio<2,>=1.74.0
Requires-Dist: protobuf<7,>=6.31.1
Requires-Dist: vention-grpc-py-sdk==0.0.67
Description-Content-Type: text/markdown

# vention-sim-grpc-py-sdk

Generated Python gRPC clients for the Vention simulation protos (`physics/**` and
`vention/simulation/**` under [`proto/`](../proto)), published from this repo.

## Install

```bash
pip install vention-sim-grpc-py-sdk
```

This also installs [`vention-grpc-py-sdk`](https://pypi.org/project/vention-grpc-py-sdk/),
which ships the `vention.robots`, `vention.io_modules`, `vention.machine_motion`,
`vention.motors`, `vention.vision`, and `google.type` messages the simulation protos embed.

## Use

```python
import grpc

from vention.robots.v1.joint_trajectory_point_pb2 import JointTrajectoryPoint
from vention_sim import SIMULATION_SHA, VENTION_PROTOS_SHA, __version__
from vention_sim.simulation.v1.sim_robot_driver_commands_pb2 import StartTrajectoryRequest
from vention_sim.simulation.v4.scene.scene_management_service_pb2_grpc import SceneManagementServiceStub

channel = grpc.insecure_channel("localhost:50055")
scene = SceneManagementServiceStub(channel)
request = StartTrajectoryRequest(points=[JointTrajectoryPoint()])
print(f"built from simulation@{SIMULATION_SHA} and vention-protos@{VENTION_PROTOS_SHA}")
```

## Import root

The modules live under `vention_sim`: a proto at `vention/simulation/v1/x.proto` is
`vention_sim.simulation.v1.x_pb2`, and one at `physics/v3/x.proto` is
`vention_sim.physics.v3.x_pb2`. Only the Python import path differs from protoc's default.
The proto packages (`vention.simulation.*`, `physics.*`), file names, gRPC method paths and
`Any` type URLs are unchanged, so a `vention-grpc-py-sdk` message drops straight into a
simulation request and reflection sees the same types as every other language.

protoc would otherwise place the stubs at `vention.simulation.*`, inside the `vention`
package that `vention-grpc-py-sdk` owns. Two distributions sharing a regular package only
work while both unpack into the same `site-packages`; editable installs and any layout with
more than one root on `sys.path` lose one of them. Giving this package its own import root
removes the shared directory, so it works in every layout and never depends on how
`vention-grpc-py-sdk` is laid out.

## One package per proto source

The simulation protos import `vention-protos` files, and both packages have to coexist in
one environment. Python leaves no good way to ship two copies of the same generated module:
two distributions writing the same path overwrite each other in `site-packages`, and protobuf
registers every message in a process-global pool that rejects duplicates. So this package
ships only the simulation-owned stubs and takes the shared ones from `vention-grpc-py-sdk`,
the same way `grpcio-status` takes `google.rpc` from `googleapis-common-protos`.

The dependency is an exact pin on the `vention-grpc-py-sdk` release generated from the
`vention-protos` commit pinned in [`proto/package.json`](../proto/package.json)
(`config.protos.tag`). That package only ever patch-bumps, so its version says nothing about
compatibility; the pin is what guarantees the two stub sets agree. Upgrading one means
upgrading the other, and `pip` refuses combinations that were never generated together.

## Versions

Releases publish on every push to `main` that touches `proto/**` or `python-sdk/**`, as the
next patch after the latest release on PyPI. Pull requests touching those paths, and manual runs
of the workflow on any other branch, publish a `X.Y.Z.dev<run_id>` build (PRs get the install
command as a comment); `pip` ignores dev releases unless the version is spelled out.

`vention_sim._source` records what a wheel was built from: `SIMULATION_SHA`,
`VENTION_PROTOS_SHA`, `VENTION_GRPC_PY_SDK_VERSION`, and `__version__`.

## Contributing

Nothing in `python-sdk/src` is committed; CI regenerates it from `proto/` before publishing.
To reproduce the CI build locally:

```bash
npm ci                                   # buf comes from the proto workspace
python3 -m venv .venv && source .venv/bin/activate
python python-sdk/scripts/ci_python_package.py
```

The script exports the vendored `vention-protos` at the pinned commit (SSH access to
`VentionCo/vention-protos` required), generates the stubs with
[`buf.gen.yaml`](buf.gen.yaml), moves them under `vention_sim` and rewrites their imports
and module names to match, resolves the matching `vention-grpc-py-sdk` release from PyPI,
builds the wheel, installs it, and then checks: the SDK's `PROTOS_SHA` equals the pin, every
generated module imports, the proto package, file name and `Any` type URL of a sim message
are unchanged while its `__module__` is under `vention_sim`, a `vention-grpc-py-sdk` message
embeds into a sim request and survives serialization and pickling, and both import orders
work.

`hatch_build.py` turns the resolved SDK release into the exact dependency pin at build time.

[`publish-python-sdk.yml`](../.github/workflows/publish-python-sdk.yml) runs the same script
and uploads with the org's PyPI token.
