Python
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
+Python
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:
@@ -10,33 +10,20 @@
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
-```¬
-
-## ZBytes, encoding, and (de)serialization
-
-### Encoding
-
-`zenoh.Value` has been split into `zenoh.ZBytes` and `zenoh.Encoding`. Put and other operations now require a `ZBytes` payload, and accept an optional `Encoding`; the encoding is no longer automatically deduced from the payload type.
-
-```python
-session.put("my/keyexpr", 42) # default encoding `zenoh/bytes`session.put("my/keyexpr", 42, encoding=zenoh.Encoding.ZENOH_INT64)
-
Publishers can be declared with a default encoding, which will be used for each put operation.
import json
-publisher = session.declare_publisher("my/keyepxr", encoding=zenoh.Encoding.APPLICATION_JSON)
-publisher.put(json.dumps({"key", "value"})) # default encoding from publisher `application/json`
-
(De)serialization
Arbitrary types can be serialized to and deserialized from ZBytes. Default (de)serializers are provided for builtin types; list/dict are no longer serialized to JSON, they use instead the builtin serializer of Zenoh, which is compatible with other Zenoh bindings.
payload = zenoh.ZBytes(42)
-assert payload.deserialize(int) == 42# `ZBytes.deserialize` accepts generic `list`/`dict` typepayload = zenoh.ZBytes([0.5, 37.1])
-assert payload.deserialize(list[float]) == [0.5, 37.1]
-
(De)serializers can be registered for custom types:
from dataclasses import dataclass
-import zenoh
-@dataclassclass RGB:
- red: int green: int blue: int@zenoh.serializerdef serialize_rgb(rgb: RGB) -> zenoh.ZBytes:
- return zenoh.ZBytes(rgb.red | (rgb.green << 8) | (rgb.blue << 16))
-@zenoh.deserializerdef deserialize_rgb(payload: zenoh.ZBytes) -> RGB:
- compact = payload.deserialize(int)
- return RGB(compact & 255, (compact >> 8) & 255, (compact >> 16) & 255)
-color = RGB(61, 67, 97)
-assert zenoh.ZBytes(color).deserialize(RGB) == color
-# types with a registered serializer can be used directly with `put`session.put("my/keyexpr", color)
+
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()
diff --git a/docs/migration_1.0/rust/index.html b/docs/migration_1.0/rust/index.html
index d1e7ae32..b67b73e4 100644
--- a/docs/migration_1.0/rust/index.html
+++ b/docs/migration_1.0/rust/index.html
@@ -1,6 +1,6 @@
Rust · Zenoh - pub/sub, geo distributed storage, query 
-Rust
Module reorganization
We reorganized the module tree, so import paths are not the same as before. The main difference is that everything should be imported via the root path zenoh::. Here are some examples, but you can look into zenoh/src/lib.rs for the complete list of changes.
// common use
+Rust
Module reorganization
We reorganized the module tree, so import paths are not the same as before. The main difference is that everything should be imported via the root path zenoh::. Here are some examples, but you can look into zenoh/src/lib.rs for the complete list of changes.
// common use
use zenoh::config::*;
use zenoh::{Config, Error, Result};
@@ -89,14 +89,16 @@
.unwrap();
// subscriber is undeclared when dropped
Going into details, a new method undeclare_on_drop(bool) – default to true, has been added to the builders, and callback(cb) is now simply a shortcut to with(cb).undeclare_on_drop(false).
-However, the normal user would rarely need to call this method directly.
Value is gone, long live ZBytes
We have replaced Value with ZBytes and Encoding , and added a number of conversion implementations such that user structs can be serialized into ZBytes, sent via Zenoh, and de-serialized from ZBytes with ease.
This is facilitated through the ZSerde struct, and implementations of the traits
-zenoh::bytes::Deserialize and zenoh::bytes::Serialize.
We provide implementations of Zenoh’s aforementioned Deserialize and Serialize traits for primitive Rust types, Rust’s Vec, the Value type exposed by Serde’s various libraries as well as an example of Protobuf ’s prost::Message type.
You can look at a full set of examples in examples/examples/z_bytes.rs.
NOTE: ⚠️ ZSerde is not the only serializer/deserializer users can make use of, nor a limitation to the types supported by Zenoh. Users are free to use whichever serializer/deserializer they wish!
- Zenoh 0.11.x
let sample = subscriber.recv_async().await.unwrap();
+However, the normal user would rarely need to call this method directly.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. The encoding is no longer automatically deduced from the payload type.
ZBytes is a raw bytes container, which can also contain non-contiguous regions of memory. It can be created directly from raw bytes/strings using ZBytes::from. The bytes can be retrieved using ZBytes::to_bytes, which returns a Cow<[u8]>, as a copy may have to be done if the underlying bytes are not contiguous.
- Zenoh 0.11.x
let sample = subscriber.recv_async().await.unwrap();
let value: Value = sample.value;
-let the_string: String = value.try_into().unwrap();
+let raw_bytes: Vec<u8> = value.try_into().unwrap();
- Zenoh 1.0.0
let sample = subscriber.recv_async().await.unwrap();
let zbytes: ZBytes = sample.payload();
-let the_string: String = zbytes.deserialize::<String>().unwrap();
-
Encoding
Encoding has been reworked.
+
let raw_bytes: Cow<[u8]> = zbytes.as_bytes();
+
You can look at a full set of examples in examples/examples/z_bytes.rs.
Serialization
Zenoh does provide serialization for convenience as an extension in the zenoh-ext crate. Serialization is implemented for a bunch of standard types like integers, floats, Vec, HashMap, etc. and is used through functions z_serialize/z_deserialize.
let input: Vec<f32> = vec![0.0, 1.5, 42.0];
+let payload: ZBytes = z_serialize(&input);
+let output: Vec<f32> = z_deserialize(&payload).unwrap();
+
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 Vec<u8> is not the same as creating a ZBytes from a Vec<u8>: the resulting ZBytes are different, and serialization doesn’t take ownership of the bytes.
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.
We have expanded our list of pre-defined encoding types from Zenoh 0.11.0 for user convenience.
@@ -115,6 +117,9 @@
.await
.unwrap();
Users can also define their own encoding scheme that does not need to be based on the pre-defined variants.
let encoding = Encoding::from("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.
let publisher = session.declare_publisher("my/keyepxr").encoding(Encoding::APPLICATION_JSON).await.unwrap();
+// default encoding from publisher `application/json`
+publisher.put(serde_json::to_vec(json!({"key", "value"})).unwrap()).await.unwrap();
Attachment
In Zenoh 0.11.x, the AttachmentBuilder was required to create an attachment.
In Zenoh 1.0.0, we have removed AttachmentBuilder, and an attachment can be created from anything that implements Into<ZBytes>
- Zenoh 0.11.x
let mut attachment = AttachmentBuilder::new();
attachment.insert("key1", "value1");