Eclipse Zenoh

The Eclipse Zenoh: Zero Overhead Pub/sub, Store/Query and Compute.

Zenoh (pronounce /zeno/) unifies data in motion, data at rest and computations. It carefully blends traditional pub/sub with geo-distributed storages, queries and computations, while retaining a level of time and space efficiency that is well beyond any of the mainstream stacks.

Check the website zenoh.io and the roadmap for more detailed information.

Python API

This repository provides a Python binding based on the main Zenoh implementation written in Rust.

How to install it

The Eclipse zenoh-python library is available on Pypi.org. Install the latest available version using pip in a virtual environment:

pip install eclipse-zenoh

:warning:WARNING:warning: zenoh-python is developped in Rust. On Pypi.org we provide binary wheels for the most common platforms (Linux x86_64, i686, ARMs, MacOS universal2 and Windows amd64). But also a source distribution package for other platforms. However, for pip to be able to build this source distribution, there are some prerequisites:

• pip version 19.3.1 minimum (for full support of PEP 517). (if necessary upgrade it with command: 'sudo pip install --upgrade pip' )
• Have a Rust toolchain installed (instructions at rustup.rs)

Supported Python versions and platforms

zenoh-python has been tested with Python 3.8, 3.9, 3.10, 3.11 and 3.12

It relies on the zenoh Rust API which require the full std library. See the list in Rust Platform Support.

Enable zenoh features

To enable some compilation features of the Rust library that are disabled by default, for example shared-memory, execute the following command:

pip install eclipse-zenoh --no-binary :all: --config-settings build-args="--features=zenoh/shared-memory"

How to build it

Requirements:

• Python >= 3.8

• pip >= 19.3.1

• Rust and Cargo. If you already have the Rust toolchain installed, make sure it is up-to-date with:

  rustup update
  

Recommended: Build with Virtual Environment

Using a virtual environment is strongly recommended to avoid Python version conflicts and dependency issues.

1. Create and activate a virtual environment:

   python3 -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   

2. Install development requirements:

   pip install -r requirements-dev.txt
   

3. Build and install in development mode:

   maturin develop --release
   

4. Run examples:

   python examples/z_info.py
   

When you're done, deactivate the virtual environment:

deactivate

Alternative: Build without Virtual Environment

If you cannot use a virtual environment, follow these steps carefully:

1. Install development requirements:

   pip install -r requirements-dev.txt
   

2. Ensure your system can find the building tool maturin (installed by previous step). For example, it is placed at $HOME/.local/bin/maturin by default on Ubuntu 20.04.

   export PATH="$HOME/.local/bin:$PATH"
   

3. Build the wheel:

   maturin build --release
   

4. Install the built wheel:

   pip install ./target/wheels/*.whl --break-system-packages
   

   :warning: Important: Systems may have multiple Python installations. Ensure you use the same pip that corresponds to the python3 you intend to use for running examples. You can verify this with:

   pip --version      # Shows which Python version pip uses
   python3 --version  # Shows which Python version python3 uses
   

   If they don't match, use python3 -m pip install ./target/wheels/*.whl instead to ensure the package is installed for the correct Python version.

5. Run examples using the same Python:

   python3 examples/z_info.py
   

Building Documentation

To build the documentation locally:

1. Ensure you have zenoh-python installed (follow the build instructions above)

2. Install documentation requirements:

   pip install -r docs/requirements.txt
   

3. Build the HTML documentation:

   cd docs
   make html
   

4. Open the documentation:

   open _build/html/index.html  # macOS
   # or
   xdg-open _build/html/index.html  # Linux
   # or navigate to docs/_build/html/index.html in your browser
   

The documentation is also available online at zenoh-python.readthedocs.io.

Running the Examples

You can install Zenoh Router first (See the instructions). Then, run the zenoh-python examples following the instructions in examples/README.md