vention-sim-grpc-py-sdk

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

Install

pip install vention-sim-grpc-py-sdk

This also installs 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

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 (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:

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, 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: 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 runs the same script and uploads with the org's PyPI token.