{"id":8132,"library":"eclipse-zenoh","title":"Eclipse Zenoh Python API","description":"Eclipse Zenoh (pronounce /zeno/) is a lightweight, high-performance middleware that unifies data in motion, data at rest, and computations across diverse environments, from embedded systems to the cloud. The Python API (version 1.9.0) provides bindings to the core Rust implementation, enabling pub/sub, geo-distributed storage, queries, and computations. It maintains an active development and release cadence, with major updates often quarterly, aiming for performance and efficiency beyond mainstream stacks.","status":"active","version":"1.9.0","language":"en","source_language":"en","source_url":"https://github.com/eclipse-zenoh/zenoh-python","tags":["iot","embedded","edge-computing","pub/sub","data-flow","robotics","ros2","protocol","middleware"],"install":[{"cmd":"pip install eclipse-zenoh","lang":"bash","label":"Install stable version"}],"dependencies":[{"reason":"Zenoh-python is developed in Rust. While binary wheels are provided for common platforms, building from source requires a Rust toolchain.","package":"Rust toolchain","optional":true}],"imports":[{"symbol":"zenoh","correct":"import zenoh"},{"symbol":"Config","correct":"import zenoh\nconfig = zenoh.Config()"},{"symbol":"Session","correct":"import zenoh\nwith zenoh.open(zenoh.Config()) as session:"},{"symbol":"Publisher","correct":"publisher = session.declare_publisher(key)"},{"symbol":"Subscriber","correct":"subscriber = session.declare_subscriber(key, listener)"},{"symbol":"Sample","correct":"def listener(sample): ... print(sample.payload.to_string())"},{"symbol":"ZBytes","correct":"value_bytes = zenoh.ZBytes(b'hello')"}],"quickstart":{"code":"import zenoh\nimport time\nimport random\nimport os\n\n# Configure a Zenoh session (default configuration for local peer/client)\n# For a router or specific configuration, consider loading from a file:\n# config_file = os.environ.get('ZENOH_CONFIG_FILE', '')\n# if config_file: config = zenoh.Config.from_file(config_file)\n# else: config = zenoh.Config()\n\ndef read_temp():\n    return random.randint(15, 30)\n\nif __name__ == \"__main__\":\n    # Open a Zenoh session using a context manager for proper cleanup\n    with zenoh.open(zenoh.Config()) as session:\n        key = 'myhome/kitchen/temp'\n        # Declare a publisher on the specified key expression\n        pub = session.declare_publisher(key)\n\n        print(f\"Zenoh Publisher sending data to '{key}'...\")\n        try:\n            while True:\n                t = read_temp()\n                buf = f\"{t}\"\n                pub.put(buf)\n                print(f\"Putting Data ('{key}': '{buf}')...\")\n                time.sleep(1)\n        except KeyboardInterrupt:\n            print(\"Publisher stopped.\")\n","lang":"python","description":"This quickstart demonstrates a simple Zenoh publisher that periodically sends random temperature readings to the 'myhome/kitchen/temp' key expression. It uses a context manager to ensure the Zenoh session is properly closed. To observe the data, you would run a separate Zenoh subscriber."},"warnings":[{"fix":"Review the migration guides (e.g., v0.11 -> v1.0) on the official Zenoh documentation. Update code to use context managers for `zenoh.open()` and `declare_publisher`/`declare_subscriber`, handle payloads as `zenoh.ZBytes`, and adjust callback signatures.","message":"The API underwent significant reworks between versions 0.x and 1.x (e.g., v0.11 to v1.0), emphasizing a more 'pythonic' feel. Key changes include mandatory use of context managers for sessions/entities, the `Value` type being replaced by `ZBytes` and `Encoding`, and `drop-callback` requiring wrapping in `handlers.Callback`.","severity":"breaking","affected_versions":"< 1.0.0"},{"fix":"Ensure you have the Rust toolchain installed on your system (follow instructions at `rustup.rs`) before attempting to `pip install eclipse-zenoh`. Binary wheels are provided for common platforms, so this issue is typically encountered in less common environments or when building from source.","message":"Installing `eclipse-zenoh` via pip might fail with build errors if you are on a platform without pre-built binary wheels and do not have a Rust toolchain installed. This is because the Python API is a binding over a Rust implementation.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Always use a Python `with` statement (context manager) when opening a Zenoh session (`with zenoh.open(zenoh.Config()) as session:`) or explicitly call `session.close()` before your script exits.","message":"Failure to properly close a Zenoh session can lead to the script hanging on exit. This occurs if object finalizers are called after the library's internal Rust thread has already been killed.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Synchronize the system clocks of all participating Zenoh nodes (publishers, subscribers, routers) using a time synchronization protocol like NTP or PTP.","message":"Zenoh nodes communicating with each other can drop messages or log 'Error treating timestamp for received Data' if their system clocks drift by more than 100ms.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"For Zenoh 1.x, access the payload directly via `sample.payload`. To get string representation, use `sample.payload.to_string()`. If specific metadata is expected, ensure the publishing side includes it and check for its presence on the receiving side.","cause":"In older Zenoh Python API versions, `data_info` or `timestamp` might not always be present or valid on a received `Sample` object, leading to `NoneType` errors when accessed directly without checks. The API for `Sample` payload handling has evolved.","error":"AttributeError: 'NoneType' object has no attribute 'timestamp' (or similar on sample.data_info)"},{"fix":"Synchronize the system clocks of all machines running Zenoh applications using a Network Time Protocol (NTP) client or Precision Time Protocol (PTP).","cause":"This error indicates that the system clocks between the Zenoh publisher and subscriber/router are not synchronized, and the time difference exceeds 100 milliseconds.","error":"ERROR zenoh::net::routing::pubsub] Error treating timestamp for received Data (incoming timestamp ... exceeding delta 100ms is rejected: ...)"},{"fix":"Install the Rust toolchain by following the instructions at `https://rustup.rs/`. After installation, ensure your shell environment is updated (e.g., `source $HOME/.cargo/env`) and try `pip install eclipse-zenoh` again.","cause":"You are attempting to install `eclipse-zenoh` from a source distribution, but the Rust toolchain (including the `rustc` compiler) is not installed or not in your system's PATH.","error":"Command 'rustc' not found"}]}