Metadata-Version: 2.5
Name: vention-sim-grpc-py-sdk
Version: 0.1.0
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.68
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<build id>` build (PRs get the install
command as a comment). Once a release exists, `pip` only installs a dev build when its version
is spelled out.

`vention_sim._source` records what a wheel was built from: `SIMULATION_SHA` (the PR head for
dev builds), `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) and fails if that overwrote the sim-owned protos,
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 runs
[`check_installed_wheel.py`](scripts/check_installed_wheel.py): the wheel pins the SDK
release whose `PROTOS_SHA` equals the pin, every generated module imports, every generated
message class belongs to its `vention_sim` module and pickles, a sim message keeps its proto
package, file name, method path and `Any` type URL, and a `vention-grpc-py-sdk` message embeds
into a sim request. Both import orders are then tried in fresh interpreters.

`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.
