From 5ef7734315e49760f082d34720605274395d8401 Mon Sep 17 00:00:00 2001 From: gabrik Date: Mon, 21 Oct 2024 11:51:29 +0000 Subject: [PATCH] deploy: b43870053306a048c131752cd294f220fabb2349 --- docs/migration_1.0/python/index.html | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/docs/migration_1.0/python/index.html b/docs/migration_1.0/python/index.html index c99b3d6b..8e522b58 100644 --- a/docs/migration_1.0/python/index.html +++ b/docs/migration_1.0/python/index.html @@ -1,6 +1,6 @@ Python · Zenoh - pub/sub, geo distributed storage, query
-

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
+
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:
@@ -12,11 +12,18 @@
     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"
+
Drop-callback has to be wrapped in handlers.Callback
In the previous 0.11.0 version, it was possible to pass a drop-callback with the main callback in a tuple for operations like Session.declare_subscriber. However, it was also possible to pass a tuple with a “receiver” (renamed “handler” in 1.0.0) as second member, and that could confuse users.
+The API has been changed and now requires the drop-callback to be wrapped in handlers.Callback.
  • Zenoh 0.11.x
def on_sample(sample: zenoh.Sample): ...
+def on_done(): ...
+session.declare_subscriber((on_sample, on_done))
+
  • Zenoh 1.0.0
def on_sample(sample: zenoh.Sample): ...
+def on_done(): ...
+session.declare_subscriber(zenoh.handlers.Callback(on_sample, on_done))
+
NOTE: ⚠️ Passing drop-callback in a tuple will no longer work as expected, as the drop callback will never be executed. To ease migration and avoid surprises, a warning will be displayed in this case.
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.