Skip to content

Python Bindings

hiroz provides Python bindings via hiroz-py, enabling Python applications to communicate with Rust and ROS 2 nodes using the same Eclipse Zenoh transport. The bindings use PyO3 for Rust-Python interop and msgspec for efficient message serialization.

Note

Python bindings provide the same pub/sub and service patterns as Rust, with Pythonic APIs. Messages are automatically serialized/deserialized between Python objects and CDR format for ROS 2 compatibility.

Installation

Pre-built wheels are available for Linux (x86_64, aarch64) and macOS (aarch64), Python 3.11+. No Rust toolchain required.

Pick a release version from the Releases page and substitute <version> below (e.g. v0.2.1).

Jazzy / Kilted / Lyrical / Rolling:

pip install https://github.com/ZettaScaleLabs/hiroz/releases/download/<version>/hiroz_msgs_py-<version>-py3-none-any.whl
pip install https://github.com/ZettaScaleLabs/hiroz/releases/download/<version>/hiroz_py-<version>-0jazzy-cp311-abi3-linux_x86_64.whl

Humble:

pip install https://github.com/ZettaScaleLabs/hiroz/releases/download/<version>/hiroz_msgs_py-<version>-py3-none-any.whl
pip install https://github.com/ZettaScaleLabs/hiroz/releases/download/<version>/hiroz_py-<version>-0humble-cp311-abi3-linux_x86_64.whl

Tip

hiroz-msgs-py (message definitions) is a dependency of hiroz-py and is installed automatically when using pip install. The explicit install above is only needed when pinning a specific version or installing from a direct URL.

Local Dry-Run (before releasing)

To verify the wheel build locally before pushing a release tag, use the build script which mirrors the CI release workflow exactly:

# Build jazzy + humble wheels into crates/hiroz-py/dist/
./scripts/build-python-wheels.nu

# Build and immediately install into crates/hiroz-py/.venv
./scripts/build-python-wheels.nu --install jazzy

# Build a single distro only
./scripts/build-python-wheels.nu jazzy

The script produces the same wheel filenames as CI (with the ‑jazzy / ‑humble distro suffix) and prints ready-to-use pip install commands for the local files.

Build from Source

For development or platforms without pre-built wheels:

Prerequisites

  • Python 3.8+
  • Rust 1.85+ — install via rustup: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
  • maturin — pip install maturin

Setup

# Create and activate virtual environment
cd crates/hiroz-py
python -m venv .venv
source .venv/bin/activate

# Install message types
pip install -e ../hiroz-msgs/python/

# Build and install hiroz-py
maturin develop

Tip

Use maturin develop --release for optimized builds when benchmarking or running in production.

Architecture

graph TD
accTitle: Python bindings architecture from Python code to Zenoh network
accDescr: Python code imports hiroz_py which calls through PyO3 into the Rust hiroz core, which uses the Zenoh transport to reach ROS 2 and Rust nodes; Python messages go through msgspec and CDR serialization.
    A[Python Code] -->|import| B[hiroz_py]
    B -->|PyO3| C[Rust hiroz]
    C -->|Zenoh| D[Network]
    D -->|Zenoh| E[ROS 2 / Rust Nodes]
    F[Python Message] -->|msgspec| G[Struct]
    G -->|serialize| H[CDR Bytes]
    H -->|deserialize| I[Rust Struct]

Quick Start

Here's a complete publisher and subscriber example from crates/hiroz-py/examples/topic_demo.py:

Publisher (Talker)

def run_talker(ctx, topic: str, count: int, interval: float):
    """Run the talker (publisher)."""
    node = ctx.create_node("talker").build()
    pub = node.create_publisher(topic, std_msgs.String)

    print(f"Talker started. Publishing to {topic}...")

    i = 0
    while count == 0 or i < count:
        message = f"Hello from Python {i}"
        msg = std_msgs.String(data=message)
        pub.publish(msg)
        print(f"PUB:{i}", flush=True)
        i += 1
        time.sleep(interval)

    print("PUB:DONE", flush=True)

Subscriber (Listener)

def run_listener(ctx, topic: str, timeout: float):
    """Run the listener (subscriber)."""
    node = ctx.create_node("listener").build()
    sub = node.create_subscriber(topic, std_msgs.String)

    print("SUB:READY", flush=True)

    start = time.time()
    received = 0

    while timeout == 0 or (time.time() - start) < timeout:
        msg = sub.recv(timeout=1.0)
        if msg is not None:
            print(f"SUB:{msg.data}", flush=True)
            received += 1

    print(f"SUB:TOTAL:{received}", flush=True)

Key Components

Component Purpose Python API
ZContextBuilder Configure hiroz environment ZContextBuilder().with_domain_id(0).build()
ZContext Manages ROS 2 connections Entry point for creating nodes
Node Logical unit of computation ctx.create_node("name").build()
Publisher Sends messages to topics node.create_publisher(topic, type)
Subscriber Receives messages from topics node.create_subscriber(topic, type)
Client Sends service requests node.create_client(service, type)
Server Handles service requests node.create_server(service, type)

Service Patterns

Examples from crates/hiroz-py/examples/service_demo.py:

Service Server

def run_server(ctx, service: str, max_requests: int):
    """Run the AddTwoInts service server."""
    node = ctx.create_node("add_two_ints_server").build()
    server = node.create_server(service, example_interfaces.AddTwoIntsRequest)

    print("SERVER:READY", flush=True)

    handled = 0
    while max_requests == 0 or handled < max_requests:
        request_id, req = server.take_request()
        result = req.a + req.b
        print(f"SERVER:{req.a}+{req.b}={result}", flush=True)

        resp = example_interfaces.AddTwoIntsResponse(sum=result)
        server.send_response(resp, request_id)
        handled += 1

    print("SERVER:DONE", flush=True)

Service Client

def run_client(ctx, service: str, a: int, b: int, timeout: float):
    """Run the AddTwoInts service client."""
    node = ctx.create_node("add_two_ints_client").build()
    client = node.create_client(service, example_interfaces.AddTwoIntsRequest)

    # Wait for service discovery
    time.sleep(1.0)

    print(f"CLIENT:REQUEST:{a}+{b}", flush=True)

    req = example_interfaces.AddTwoIntsRequest(a=a, b=b)
    try:
        resp = client.call(req, timeout=timeout)
        print(f"CLIENT:RESPONSE:{resp.sum}", flush=True)
    except RuntimeError as e:
        print(f"CLIENT:ERROR:{e}", flush=True)
        sys.exit(1)

Tip

Service servers use a pull model: take_request() blocks until a request arrives. This gives you explicit control over when to process requests.

Action Patterns

Actions extend services with long-running execution, incremental feedback, and cancellation. A goal is sent by the client, accepted or rejected by the server, executed with feedback published at each step, and finally terminated with a result.

Examples from crates/hiroz-py/examples/action_demo.py.

Defining Message Types

Actions require three message structs: Goal, Result, and Feedback. Each must have a __msgtype__ class attribute:

class CountToGoal(msgspec.Struct):
    __msgtype__: ClassVar[str] = "action_demo/msg/CountToGoal"
    target: int = 10


class CountToResult(msgspec.Struct):
    __msgtype__: ClassVar[str] = "action_demo/msg/CountToResult"
    final_count: int = 0


class CountToFeedback(msgspec.Struct):
    __msgtype__: ClassVar[str] = "action_demo/msg/CountToFeedback"
    current: int = 0

Tip

Types from hiroz_msgs_py already have __msgtype__ and a ROS 2 type hash. Inline msgspec.Struct types (as above) use a zero hash and are Python-to-Python only — they are not compatible with rmw_zenoh_cpp typed actions.

Action Server

def run_server(ctx, action: str):
    node = ctx.create_node("count_to_server").build()
    server = node.create_action_server(
        action, CountToGoal, CountToResult, CountToFeedback
    )

    print("SERVER:READY", flush=True)

    while True:
        request = server.recv_goal(timeout=1.0)
        if request is None:
            continue

        goal = request.goal()
        print(f"SERVER:GOAL:{goal.target}", flush=True)
        executing = request.accept_and_execute()

        count = 0
        while count < goal.target:
            time.sleep(0.2)
            count += 1
            executing.publish_feedback(CountToFeedback(current=count))
            print(f"SERVER:FEEDBACK:{count}", flush=True)

            if executing.is_cancel_requested:
                print(f"SERVER:CANCELED:{count}", flush=True)
                executing.canceled(CountToResult(final_count=count))
                break
        else:
            print(f"SERVER:SUCCEEDED:{count}", flush=True)
            executing.succeed(CountToResult(final_count=count))

Server Lifecycle

  1. recv_goal(timeout) — blocks until a goal arrives; returns None on timeout
  2. request.goal() — deserialize the goal payload
  3. request.accept_and_execute() → ServerGoalHandle — or request.reject()
  4. handle.publish_feedback(fb) — send incremental progress
  5. handle.is_cancel_requested — poll for client cancellation
  6. handle.succeed(result) / handle.abort(result) / handle.canceled(result) — terminate

Action Client

def run_client(ctx, action: str, target: int, cancel_after: float | None):
    node = ctx.create_node("count_to_client").build()
    client = node.create_action_client(
        action, CountToGoal, CountToResult, CountToFeedback
    )

    # Give server time to advertise
    time.sleep(1.0)

    print(f"CLIENT:SEND_GOAL:{target}", flush=True)
    handle = client.send_goal(CountToGoal(target=target))

    # Schedule cancellation if requested
    if cancel_after is not None:

        def _cancel():
            time.sleep(cancel_after)
            print("CLIENT:CANCEL", flush=True)
            handle.cancel()

        threading.Thread(target=_cancel, daemon=True).start()

    # Drain feedback
    while True:
        fb = handle.recv_feedback(timeout=0.5)
        if fb is None:
            break
        print(f"CLIENT:FEEDBACK:{fb.current}", flush=True)

    result = handle.get_result(timeout=5.0)
    if result is not None:
        print(f"CLIENT:RESULT:{result.final_count}", flush=True)
    else:
        print("CLIENT:ERROR:no result", flush=True)
        sys.exit(1)

Client Lifecycle

  1. client.send_goal(goal) → ActionGoalHandle — blocks until accepted. It raises on rejection. It raises RuntimeError when no server answers. The goal query has a 10 second timeout, and an 11 second timeout applies while the call waits for the goal to be accepted. Neither covers the encoding of the goal. It never raises TimeoutError
  2. handle.recv_feedback(timeout) — receive next feedback; returns None on timeout or when the feedback channel closes
  3. handle.get_result(timeout) — block until terminal state; returns None on timeout. Without timeout it has no time limit. The first call consumes the handle, so a timeout cannot be retried: a second call always raises RuntimeError
  4. handle.cancel() — request cancellation (the server decides when to honour it)

Goal Status

GoalStatus constants mirror action_msgs/msg/GoalStatus:

Constant Value is_active() is_terminal()
ACCEPTED 1 ✓ —
EXECUTING 2 ✓ —
CANCELING 3 ✓ —
SUCCEEDED 4 — ✓
CANCELED 5 — ✓
ABORTED 6 — ✓
status = hiroz_py.GoalStatus(handle.status)
if status.is_terminal():
    print("Done:", status)

Warning

Python actions use a byte-wrapping wire format that is not compatible with rmw_zenoh_cpp typed actions. Use the Rust ZAction trait for ROS 2 interop.

Complex Messages

Python bindings support nested message types like geometry_msgs/Twist:

from hiroz_py import geometry_msgs

# Create a Twist message with nested Vector3
twist = geometry_msgs.Twist(
    linear=geometry_msgs.Vector3(x=1.0, y=0.0, z=0.0),
    angular=geometry_msgs.Vector3(x=0.0, y=0.0, z=0.5)
)

pub = node.create_publisher("/cmd_vel", geometry_msgs.Twist)
pub.publish(twist)

Context Configuration

Connect to Specific Endpoint

ctx = (
    hiroz_py.ZContextBuilder()
    .with_connect_endpoints(["tcp/192.168.1.100:7447"])
    .build()
)

Disable Multicast Scouting

ctx = (
    hiroz_py.ZContextBuilder()
    .with_domain_id(0)
    .disable_multicast_scouting()
    .build()
)

Custom Namespace

node = ctx.create_node("my_node").with_namespace("/robot1").build()

QoS

create_publisher and create_subscriber take an optional qos argument. The other entity factories (create_client, create_server, create_action_client, create_action_server) have no qos argument. With no qos, an entity uses the default profile in the table below.

import hiroz_py
from hiroz_py import std_msgs

qos = hiroz_py.QosProfile(reliability="best_effort", history="keep_last", depth=5)
pub = node.create_publisher("/topic", std_msgs.String, qos=qos)

sub = node.create_subscriber("/topic", std_msgs.String, qos=hiroz_py.QosProfile.sensor_data())

Presets

After import hiroz_py, the constants hiroz_py.QOS_DEFAULT, QOS_SENSOR_DATA, QOS_PARAMETERS and QOS_SERVICES are QosProfile objects. They equal QosProfile.default(), sensor_data(), parameters() and services(). Pass a preset or a dict as the qos argument, because qos accepts both.

preset reliability durability history
default reliable volatile keep_last, depth 10
sensor_data best_effort volatile keep_last, depth 5
parameters reliable volatile keep_last, depth 1000
services reliable volatile keep_last, depth 10

All four presets use automatic liveliness. Their deadline, lifespan and liveliness lease duration are infinite.

Constructor arguments

QosProfile(...) starts from the default profile and overrides each argument you pass. Every argument is optional.

argument values note
reliability "reliable", "best_effort"
durability "volatile", "transient_local"
history "keep_last", "keep_all" "keep_last" with no depth uses depth 10
depth integer greater than 0 with no history, depth selects keep_last. With history="keep_all", depth is ignored
liveliness "automatic", "manual_by_node", "manual_by_topic"
deadline float, seconds
lifespan float, seconds
liveliness_lease_duration float, seconds

A string outside the listed values raises ValueError. With keep_last, a depth of 0 raises ValueError. A negative depth raises OverflowError when Python converts the argument, before the profile checks it. A dictionary converts depth only when it has a history key; see Dictionaries below.

A profile has read-only properties reliability, durability, history and depth. depth is 0 for keep_all. There are no properties for the other fields.

Dictionaries

qos also accepts a dict with the same keys as the constructor arguments, for example {"reliability": "best_effort", "history": "keep_last", "depth": 5}. Any other object raises TypeError.

Warning

A dictionary key that is not in the table above is ignored without an error, so a misspelled key leaves that field at its default. A depth key with no history key is also ignored in a dictionary, so {"depth": -1} keeps the default depth and raises no error. When a history key is present, the dictionary converts depth too, so {"history": "keep_last", "depth": -1} raises OverflowError. Use QosProfile(...) when you want these mistakes to fail early.

Shared Memory

Shared memory (SHM) is a property of the context. Enable it on the ZContextBuilder before you call build():

ctx = hiroz_py.ZContextBuilder().with_shm_enabled().build()
method effect
with_shm_enabled() creates an SHM pool of 10 MiB
with_shm_pool_size(size_bytes) creates an SHM pool of size_bytes
with_shm_threshold(threshold) sets the message size, in bytes, from which SHM applies. The default threshold is 512 bytes. It has an effect only after with_shm_enabled() or with_shm_pool_size()

Pool creation can fail. The failure raises HirozError.

The Python publish methods do not use the pool or the threshold. ZPublisher.publish() serialises the message to a buffer and sends it. ZPublisher.publish_raw() sends the bytes you pass. Neither method allocates from the SHM pool, so with_shm_pool_size() and with_shm_threshold() do not change how Python publishes.

Environment variables

variable read by rule
ZENOH_SHM_ALLOC_SIZE with_shm_enabled() a positive integer, in bytes, replaces the 10 MiB pool size. Any other value is ignored
ZENOH_SHM_MESSAGE_SIZE_THRESHOLD with_shm_enabled() and with_shm_pool_size() a positive power of two, in bytes, sets the threshold. Any other value is ignored without an error

with_shm_pool_size() does not read ZENOH_SHM_ALLOC_SIZE. A later call to with_shm_threshold() replaces a threshold that came from the environment.

Buffer Group

create_subscriber has a buffer_group argument. It decides whether the subscriber joins the CPU buffer group of rmw_zenoh. A buffer-aware ROS 2 Lyrical publisher sends a message with an unbounded uint8[] or char[] field to the members of this group on a separate key. The ROS 2 Interoperability chapter explains the mechanism.

sub = node.create_subscriber("/chatter", std_msgs.String, buffer_group="off")
value the subscriber joins
"auto" (default) on every topic. The Python bindings have no message schema to inspect, so "auto" does the same as "cpu"
"cpu" on every topic
"off" never

A subscriber never joins in two cases, under every value: it uses transient_local durability, or its key format is not the one of rmw_zenoh.

A value outside the table raises ValueError. A value that is not a string raises TypeError. The argument works for queue subscribers and for callback subscribers.

Publishers, service clients, service servers and action clients and servers have no buffer_group argument in Python. The Python node builder has no node-level default for it either, so each create_subscriber call chooses its own value.

Errors

hiroz-py defines four exception classes. All of them are attributes of hiroz_py.

class base raised by hiroz-py
HirozError Exception yes
TimeoutError HirozError yes
SerializationError HirozError never
TypeMismatchError HirozError never

hiroz_py.TimeoutError is not the built-in TimeoutError. Catch it as hiroz_py.TimeoutError.

Every service client query has a configured timeout of 10 seconds. The timeout argument of call is a separate, outer timeout that wraps the whole call, including the creation of the query. Its default is one hour. The call raises hiroz_py.TimeoutError when the outer timeout ends. The call raises RuntimeError when the query completes without a reply, for example when no server matches or when the 10 second query timeout ends. The two timeouts do not start at the same moment, so a timeout near 10 seconds can produce either error. Neither timeout covers the conversion of the request or the response, so neither is a limit on the elapsed time of the whole method.

A negative, NaN, infinite or overflowing timeout is not supported. An overflowing timeout is a value too large for a Duration. It does not raise a normal exception: the binding panics and Python raises pyo3_runtime.PanicException, which derives from BaseException, so except Exception does not catch it. Every timeout argument that is a float behaves this way.

What raises what

situation result
the outer timeout of ZClient.call ends hiroz_py.TimeoutError
the query of ZClient.call completes with no reply, for example when no server matches or the 10 second query timeout ends RuntimeError
a server answers a ZClient.call after its query has ended RuntimeError. The late reply is dropped
ZClient.call(...) fails for any other reason, for example the server disappears RuntimeError
ZSubscriber.recv(timeout=t) gets no message in time returns None
ZActionClient.send_goal(...) gets no answer from a server RuntimeError. The goal query has a 10 second timeout, and an 11 second timeout applies while the call waits for the goal to be accepted
ZServer.take_request() or send_response(...) fails in the core RuntimeError
an action client or server cannot be created, an action call fails in the core, you finish a goal twice, or you call recv on a callback subscriber RuntimeError
a context, node, publisher, subscriber, service client or service server cannot be created, or a publish or receive fails in the core HirozError
a QoS string, a depth of 0 with keep_last, or a buffer_group value is invalid ValueError
a negative depth passed to QosProfile(...), or in a dictionary that has a history key OverflowError, raised by the conversion of depth. A dictionary without history does not convert depth
a message field holds an integer outside the range of its type OverflowError, raised when the message is converted
a message object lacks a field that its type defines AttributeError, raised when the message is converted
a message class has no __msgtype__, or qos has the wrong type TypeError
the request class passed to create_client or create_server has no __hash__ string TypeError
the request class passed to create_client or create_server has a malformed __hash__ ValueError

In the code that converts Python messages to and from CDR, invalid values raise ValueError, TypeError, OverflowError or AttributeError. They do not raise SerializationError or TypeMismatchError.

ZServer.send_response(response, request_id) needs the request_id dictionary that take_request() returned. Pass it unchanged. A dictionary without an sn or gid key raises KeyError. A gid that does not hold 16 bytes raises ValueError.

import hiroz_py

try:
    resp = client.call(req, timeout=2.0)
except hiroz_py.TimeoutError:
    print("no response in 2 s")
except RuntimeError as e:
    print("call failed:", e)

Performance: Zero-Copy Large Payloads

When working with large byte arrays (sensor data, images, point clouds), hiroz-py minimizes memory copies using a zero-copy optimization for uint8[] and byte[] fields.

ZBufView

When a subscriber receives a message, hiroz exposes byte array fields as a ZBufView — a zero-copy view into the received network buffer. ZBufView implements Python's buffer protocol:

msg = sub.recv(timeout=1.0)
# msg.data is a ZBufView — no copy has occurred

# Zero-copy access via buffer protocol
mv = memoryview(msg.data)
header = mv[:8]  # Slice without copying the entire payload

# Only copies when explicitly converted
data = bytes(msg.data)

Echo Without Copying

For relay and echo patterns, pass ZBufView fields directly to a new message. The derive macro detects ZBufView and extracts the inner buffer via reference counting — no data copy occurs:

# Receive and re-publish — zero-copy for byte array fields
msg = sub.recv(timeout=1.0)
echo = std_msgs.ByteMultiArray(data=msg.data)  # No copy!
pub.publish(echo)

ZBufView API

Method Description
len(view) Number of bytes
bool(view) True if not empty
view[i] Single byte access
view[start:stop] Slice (returns bytes)
memoryview(view) Zero-copy buffer protocol access
bytes(view) Convert to bytes (copies)
view.is_zero_copy Whether the view avoids internal copying

Tip

For best performance with large payloads, avoid calling bytes() on ZBufView fields. Use memoryview() for read access, or pass the ZBufView directly when re-publishing.

How It Works

The optimization operates at three layers:

  1. Deserialization bypass: When the Python subscriber receives a message, hiroz stores the raw network buffer (ZBuf) in a thread-local. During CDR deserialization, byte array fields create sub-views into this buffer instead of copying (ZSlice::subslice()).

  2. Buffer protocol: ZBufView wraps the ZBuf and exposes its bytes to Python via __getbuffer__/__releasebuffer__. For contiguous buffers (the common case), this is a direct pointer — no copy at all.

  3. Pass-through re-publish: The FromPyMessage derive macro recognizes ZBufView inputs and extracts the inner ZBuf via clone(), which only increments a reference count on the underlying memory.

ROS 2 Interoperability

Python nodes interoperate with ROS 2 C++ nodes via the shared Zenoh transport. See the dedicated ROS 2 Interoperability chapter for setup instructions.

Running Tests

# Python unit tests
cd crates/hiroz-py
source .venv/bin/activate
python -m pytest tests/ -v

# Python-Rust interop tests
cargo test --features python-interop -p hiroz-tests --test python_interop -- --test-threads=1

Troubleshooting

Import errors when using hiroz_py

This error occurs when the package hasn't been built or installed correctly. Solution: Rebuild and install the package:

cd crates/hiroz-py
source .venv/bin/activate
pip install -e ../hiroz-msgs/python/
maturin develop
Message type not found

This error occurs when trying to use a message type that isn't supported by the Python bindings. Solution: Use a class from hiroz_msgs_py. A class that only defines __msgtype__ passes create_publisher and create_subscriber, but publish raises ValueError and recv raises TypeError when the type is not in the generated registry. hiroz_py.list_registered_types() returns the registered message type names.

Ensure you are passing a message class object (e.g., std_msgs.String), not a string.

recv() always returns None

This happens when no messages arrive within the timeout period. Solution:

  • Check the topic name matches exactly (including leading /)
  • Verify the publisher is running and connected to the same Zenoh network
  • Increase the timeout value
  • Use --nocapture with pytest to see debug output: python -m pytest tests/ -v --capture=no

Resources

Start with the pub/sub example to understand the basics, then explore services for request-response patterns.