From 225ddbf88df5f901bc1428cc2442ee7b8d21bded Mon Sep 17 00:00:00 2001 From: ChenYing Kuo Date: Thu, 9 May 2024 16:26:58 +0800 Subject: [PATCH] Fix markdown format in README. Signed-off-by: ChenYing Kuo --- README.md | 68 +++++++------ examples/README.md | 246 +++++++++++++++++++++++++-------------------- 2 files changed, 174 insertions(+), 140 deletions(-) diff --git a/README.md b/README.md index e7b50ec5..a2b4e2fc 100644 --- a/README.md +++ b/README.md @@ -16,76 +16,86 @@ Zenoh (pronounce _/zeno/_) unifies data in motion, data at rest and computations Check the website [zenoh.io](http://zenoh.io) and the [roadmap](https://github.com/eclipse-zenoh/roadmap) for more detailed information. ------------------------------- + # Python API This repository provides a Python binding based on the main [Zenoh implementation written in Rust](https://github.com/eclipse-zenoh/zenoh). ------------------------------- + ## How to install it The Eclipse zenoh-python library is available on [Pypi.org](https://pypi.org/project/eclipse-zenoh/). Install the latest available version using `pip`: -``` + +```bash 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). + +- `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 https://rustup.rs/) +- Have a Rust toolchain installed (instructions at [rustup.rs](https://rustup.rs/)) ### Supported Python versions and platforms zenoh-python has been tested with Python 3.7, 3.8, 3.9 and 3.10. -It relies on the [zenoh](https://github.com/eclipse-zenoh/zenoh/tree/main/zenoh) Rust API which require the full `std` library. See the list Rust supported platforms here: https://doc.rust-lang.org/nightly/rustc/platform-support.html . - +It relies on the [zenoh](https://github.com/eclipse-zenoh/zenoh/tree/main/zenoh) Rust API which require the full `std` library. See the list in [Rust Platform Support](https://doc.rust-lang.org/nightly/rustc/platform-support.html). ------------------------------- + ## How to build it -> :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active development. When you build from git, make sure you also build from git any other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.). It may happen that some changes in git are not compatible with the most recent packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in mantaining compatibility between the various git repositories in the Zenoh project. +> :warning: **WARNING** :warning: : Zenoh and its ecosystem are under active development. When you build from git, make sure you also build from git any other Zenoh repository you plan to use (e.g. binding, plugin, backend, etc.). It may happen that some changes in git are not compatible with the most recent packaged Zenoh release (e.g. deb, docker, pip). We put particular effort in mantaining compatibility between the various git repositories in the Zenoh project. Requirements: - * Python >= 3.7 - * pip >= 19.3.1 - * (Optional) A Python virtual environment (for instance [virtualenv](https://docs.python.org/3.10/tutorial/venv.html) or [miniconda](https://docs.conda.io/en/latest/miniconda.html)) - * [Rust and Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html). If you already have the Rust toolchain installed, make sure it is up-to-date with: + +- Python >= 3.7 +- pip >= 19.3.1 +- (Optional) A Python virtual environment (for instance [virtualenv](https://docs.python.org/3.10/tutorial/venv.html) or [miniconda](https://docs.conda.io/en/latest/miniconda.html)) +- [Rust and Cargo](https://doc.rust-lang.org/cargo/getting-started/installation.html). If you already have the Rust toolchain installed, make sure it is up-to-date with: ```bash - $ rustup update + rustup update ``` Steps: - * Install developments requirements: + +- Install developments requirements: + ```bash pip install -r requirements-dev.txt ``` - * 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. - ```bash - export PATH="$HOME/.local/bin:$PATH" - ``` +- 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. + + ```bash + export PATH="$HOME/.local/bin:$PATH" + ``` + +- Build and install zenoh-python: + + - With a virtual environment active: - * Build and install zenoh-python: - * With a virtual environment active: - ```bash - maturin develop --release - ``` - * Without one: - ```bash - maturin build --release - pip install ./target/wheels/ - ``` + ```bash + maturin develop --release + ``` + - Without one: + ```bash + maturin build --release + pip install ./target/wheels/ + ``` ------------------------------- -## Running the Examples -The simplest way to run some of the example is to get a Docker image of the **zenoh** network router (see https://github.com/eclipse-zenoh/zenoh#how-to-test-it) and then to run the examples on your machine. +## Running the Examples +You can install Zenoh Router first (See [the instructions](https://github.com/eclipse-zenoh/zenoh/?tab=readme-ov-file#how-to-install-it)). Then, run the zenoh-python examples following the instructions in [examples/README.md](https://github.com/eclipse-zenoh/zenoh-python/tree/main/examples#readme) diff --git a/examples/README.md b/examples/README.md index 690824b9..1edbe435 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,158 +1,182 @@ -# Zenoh Python examples +# Zenoh Python Examples -## Start instructions +## Get Started - ```bash - python3 - ``` +```bash +python3 +``` - Each example accepts the `-h` or `--help` option that provides a description of its arguments and their default values. +Each example accepts the `-h` or `--help` option that provides a description of its arguments and their default values. - If you run the tests against the zenoh router running in a Docker container, you need to add the - `-e tcp/localhost:7447` option to your examples. That's because Docker doesn't support UDP multicast - transport, and therefore the zenoh scouting and discrovery mechanism cannot work with. +If you run the tests against the zenoh router running in a Docker container, you need to add the +`-e tcp/localhost:7447` option to your examples. That's because Docker doesn't support UDP multicast +transport, and therefore the zenoh scouting and discrovery mechanism cannot work with. ## Examples description ### z_scout - Scouts for zenoh peers and routers available on the network. +Scouts for zenoh peers and routers available on the network. - Typical usage: - ```bash - python3 z_scout.py - ``` +Typical usage: + +```bash +python3 z_scout.py +``` ### z_info - Gets information about the Zenoh session. +Gets information about the Zenoh session. - Typical usage: - ```bash - python3 z_info.py - ``` +Typical usage: +```bash +python3 z_info.py +``` ### z_put - Puts a path/value into Zenoh. - The path/value will be received by all matching subscribers, for instance the [z_sub](#z_sub) - and [z_storage](#z_storage) examples. +Puts a path/value into Zenoh. +The path/value will be received by all matching subscribers, for instance the [z_sub](#z_sub) +and [z_storage](#z_storage) examples. + +Typical usage: + +```bash +python3 z_put.py +``` + +or - Typical usage: - ```bash - python3 z_put.py - ``` - or - ```bash - python3 z_put.py -k demo/example/test -v 'Hello World' - ``` +```bash +python3 z_put.py -k demo/example/test -v 'Hello World' +``` ### z_pub - Declares a resource with a path and a publisher on this resource. Then puts a value using the numerical resource id. - The path/value will be received by all matching subscribers, for instance the [z_sub](#z_sub) - and [z_storage](#z_storage) examples. +Declares a resource with a path and a publisher on this resource. Then puts a value using the numerical resource id. +The path/value will be received by all matching subscribers, for instance the [z_sub](#z_sub) +and [z_storage](#z_storage) examples. + +Typical usage: + +```bash +python3 z_pub.py +``` + +or - Typical usage: - ```bash - python3 z_pub.py - ``` - or - ```bash - python3 z_pub.py -k demo/example/test -v 'Hello World' - ``` +```bash +python3 z_pub.py -k demo/example/test -v 'Hello World' +``` ### z_sub - Creates a subscriber with a key expression. - The subscriber will be notified of each put made on any key expression matching - the subscriber's key expression, and will print this notification. +Creates a subscriber with a key expression. +The subscriber will be notified of each put made on any key expression matching +the subscriber's key expression, and will print this notification. - Typical usage: - ```bash - python3 z_sub.py - ``` - or - ```bash - python3 z_sub.py -k 'demo/**' - ``` +Typical usage: + +```bash +python3 z_sub.py +``` + +or + +```bash +python3 z_sub.py -k 'demo/**' +``` ### z_pull - Creates a pull subscriber with a selector. - The pull subscriber will receive each put made on any key expression matching - the subscriber's key expression and will pull on demand and print the received - key/value. +Creates a pull subscriber with a selector. +The pull subscriber will receive each put made on any key expression matching +the subscriber's key expression and will pull on demand and print the received +key/value. + +Typical usage: + +```bash +python3 z_pull.py +``` + +or - Typical usage: - ```bash - python3 z_pull.py - ``` - or - ```bash - python3 z_pull.py -k 'demo/**' - ``` +```bash +python3 z_pull.py -k 'demo/**' +``` ### z_get - Sends a query message for a selector. - The queryables with a matching path or selector (for instance [z_queryable](#z_queryable) and [z_storage](#z_storage)) - will receive this query and reply with paths/values that will be received by the query callback. +Sends a query message for a selector. +The queryables with a matching path or selector (for instance [z_queryable](#z_queryable) and [z_storage](#z_storage)) +will receive this query and reply with paths/values that will be received by the query callback. - Typical usage: - ```bash - python3 z_get.py - ``` - or - ```bash - python3 z_get.py -s 'demo/**' - ``` +Typical usage: + +```bash +python3 z_get.py +``` + +or + +```bash +python3 z_get.py -s 'demo/**' +``` ### z_queryable - Creates a queryable function with a key expression. - This queryable function will be triggered by each call to a get operation on zenoh - with a selector that matches the key expression, and will return a value to the querier. +Creates a queryable function with a key expression. +This queryable function will be triggered by each call to a get operation on zenoh +with a selector that matches the key expression, and will return a value to the querier. + +Typical usage: + +```bash +python3 z_queryable.py +``` + +or - Typical usage: - ```bash - python3 z_queryable.py - ``` - or - ```bash - python3 z_queryable.py -k demo/example/queryable -v 'This is the result' - ``` +```bash +python3 z_queryable.py -k demo/example/queryable -v 'This is the result' +``` ### z_storage - Trivial implementation of a storage in memory. - This examples creates a subscriber and a queryable on the same key expression. - The subscriber callback will store the received key/values in an hashmap. - The queryable callback will answer to queries with the key/values stored in the hashmap - and that match the queried selector. - - Typical usage: - ```bash - python3 z_storage.py - ``` - or - ```bash - python3 z_storage.py -k 'demo/**' - ``` +Trivial implementation of a storage in memory. +This examples creates a subscriber and a queryable on the same key expression. +The subscriber callback will store the received key/values in an hashmap. +The queryable callback will answer to queries with the key/values stored in the hashmap +and that match the queried selector. + +Typical usage: + +```bash +python3 z_storage.py +``` + +or + +```bash +python3 z_storage.py -k 'demo/**' +``` ### z_pub_thr & z_sub_thr - Pub/Sub throughput test. - This example allows to perform throughput measurements between a pubisher performing - put operations and a subscriber receiving notifications of those puts. +Pub/Sub throughput test. +This example allows to perform throughput measurements between a pubisher performing +put operations and a subscriber receiving notifications of those puts. + +Typical Subscriber usage: + +```bash +python3 z_sub_thr.py +``` - Typical Subscriber usage: - ```bash - python3 z_sub_thr.py - ``` +Typical Publisher usage: - Typical Publisher usage: - ```bash - python3 z_pub_thr.py 1024 - ``` +```bash +python3 z_pub_thr.py 1024 +```