Python

Edit on GitHub

Highlights

The library has been fully rewritten to use only Rust. It should make no difference for users, except for a significant performance improvement.

The API has also been reworked to feel more pythonic, using notably context managers.

Context managers and background callbacks

You should close the zenoh session after use and the recommended way is through context manager:

import zenoh
with zenoh.open(zenoh.Config()) as session:
    # `session.close()` will be called at the end of the block

Session-managed objects like subscribers or queryables can also be managed using context managers:

with session.declare_subscriber("my/keyexpr") as subscriber:
    # `subscriber.undeclare()` will be called at the end of the block`

In previous version, it was necessary to keep a variable in the scope for a subscriber/queryable declared with a callback. This constraint has been lifted, and it’s now possible to declare and forget an entity with a callback; in that case, the entity will keep living in background, until the session is closed.

import zenoh
with zenoh.open(zenoh.Config()) as session:
    session.declare_subscriber("my/keyepxr", lambda s: print(s))
    sleep(10) # subscriber stays in background and its callback can be called
    # `session.close()` will be called at the end of the block, and it will undeclare the subscriber

Value is gone, long live ZBytes

Value has been split into ZBytes and Encoding. put and other operations now require a ZBytes payload, and builders accept an optional Encoding parameter.

ZBytes is a raw bytes container. It can be created directly from raw bytes/strings using ZBytes constructor. Then bytes can be retrieved using ZBytes.to_bytes or ZBytes.to_string. Sample payload is now a ZBytes instead of bytes.

  • Zenoh 0.11.x
sample = subscriber.recv()
my_string = sample.payload.decode("utf-8")
  • Zenoh 1.0.0
sample = subscriber.recv()
my_string = sample.payload.to_string()

You can look at a full set of examples in examples/z_bytes.py.

Serialization

Zenoh does provide serialization for convenience as an extension in zenoh.ext module. Serialization is implemented for a bunch of standard types like int, float, list, dict, tuple, etc. and is used through functions z_serialize/z_deserialize.

input = b"raw bytes"
payload = ZBytes(input)
output = payload.to_bytes()

zenoh.ext serialization doesn’t pretend to cover all use cases, as it is just one available choice among other serialization formats like JSON, Protobuf, CBOR, etc. In the end, Zenoh will just send and receive payload raw bytes independently of the serialization used.

NOTE: ⚠️ Serialization of bytes is not the same as passing bytes to ZBytes constructor.

Encoding

Encoding has been reworked. Zenoh does not impose any encoding requirement on the user, nor does it operate on it. It can be thought of as optional metadata, carried over by Zenoh in such a way that the end user’s application may perform different operations based on encoding.

NOTE: ⚠️ The encoding is no longer automatically deduced from the payload type.

session.put(json.dumps({"key", "value"}), encoding=Encoding.APPLICATION_JSON)

Users can also define their own encoding scheme that does not need to be based on the pre-defined variants.

encoding = Encoding("pointcloud/LAS")

Because encoding is now optional for put, Publisher can be declared with a default encoding, which will be used in every Publisher.put.

publisher = session.declare_publisher("my/keyepxr", encoding=Encoding.APPLICATION_JSON)
// default encoding from publisher `application/json`
publisher.put(json.dumps({"key", "value"}))

Handlers

The library now directly exposes Rust-backed handlers in zenoh.handlers. When no handler is provided, zenoh.handlers.DefaultHandler is used.

import zenoh.handlers
subscriber = session.declare_subscriber("my/keyexpr", zenoh.handlers.DefaultHandler())
# equivalent to `session.declare_subscriber("my/keyexpr")`# builtin handlers provides `try_recv`/`recv` methods and can be iterated sample_or_none = subscriber.handler.try_recv()
sample = subscriber.handler.recv()
for sample in subscriber.handler:
    ...
# builtin handlers methods can be accessed directly through subscriber/queryable object sample_or_none = subscriber.try_recv()
sample = subscriber.recv()
for sample in subscriber:
    ...

Callbacks can also be used as handler:

def handle_sample(sample: zenoh.Sample):
    ...
session.declare_subscriber("my/keyexpr", handle_sample)
# A drop callback can be passed using `zenoh.handlers.Callback`def stop():
    ...
session.declare_subscriber("my/keyexpr", zenoh.handlers.Callback(handle_sample, stop))

Note that for each callback handler, zenoh will in fact use a builtin handler and spawn a thread iterating the handler and calling the callback. This is needed to avoid GIL-related issues in low-level parts of zenoh, and as a result, leads to a significant performance improvement.

Next up: Java