Zenoh API Reference¶

The module of the zenoh API.

See the zenoh.Zenoh class for details

Quick start examples:¶

Put a key/value into zenoh¶

>>> import zenoh
>>> z = zenoh.Zenoh({})
>>> w = z.workspace()
>>> w.put('/demo/example/hello', 'Hello World!')
>>> z.close()

Get keys/values from zenoh¶

>>> import zenoh
>>> z = zenoh.Zenoh({})
>>> w = z.workspace()
>>> for data in w.get('/demo/example/**'):
...     print('  {} : {}  (encoding: {} , timestamp: {})'.format(
...         data.path, data.value.get_content(), data.value.encoding_descr(), data.timestamp))
>>> z.close()

zenoh.init_logger()¶

Initialize the logger used by the Rust implementation of this API.

Once initialized, you can configure the logs displayed by the API using the RUST_LOG environment variable. For instance, start python with the debug logs available:

$ RUST_LOG=debug python

More details on the RUST_LOG configuration on https://docs.rs/env_logger/latest/env_logger

Zenoh¶

class zenoh.Zenoh¶

The zenoh client API.

Creates a zenoh API, establishing a zenoh-net session with discovered peers and/or routers.

Parameters:	config – The configuration of the zenoh session config – dict of str:str

close()¶: Closes the zenoh API and the associated zenoh-net session

router_pid()¶: Returns the PeerId of the zenoh router this zenoh API is connected to (if any).

workspace()¶

Creates a [Workspace] with an optional [Path] as prefix.

Parameters:	prefix (str) – an optional prefix
Returns:	a Workspace
Return type:	Workspace
Example:

>>> z = zenoh.Zenoh(zenoh.net.Config())
>>> w = z.workspace()

Workspace¶

class zenoh.Workspace¶

A Workspace to operate on zenoh.

A Workspace has an optional path prefix from which relative paths or selectors can be used.

Example:

>>> import zenoh
>>> z = zenoh.Zenoh(zenoh.net.Config())
>>> ### Create a Workspace using prefix '/demo/example'
>>> w = z.workspace('/demo/example')
>>> ### Put using a relative path: '/demo/example/' + 'hello'
>>> w.put('hello', 'Hello World!')
>>> ### Note that absolute paths and selectors can still be used:
>>> w.put('/demo/exmaple/hello2', 'Hello World!')
>>> z.close()

delete()¶

Delete a path and its value from zenoh.

The corresponding Change will be received by all matching subscribers and all matching storages. Note that the path can be absolute or relative to this Workspace.

Parameters:	path (str) – the path
Example:

>>> import zenoh
>>> z = zenoh.Zenoh(zenoh.net.Config())
>>> w = z.workspace()
>>> w.delete('/demo/exmaple/hello')
>>> z.close()

get()¶

Get a selection of path/value from zenoh.

The selection is returned as a list of Data. Note that the selector can be absolute or relative to this Workspace.

Parameters:	selector (str) – the selector
Return type:	list of Data
Example:

>>> import zenoh
>>> z = zenoh.Zenoh(zenoh.net.Config())
>>> w = z.workspace()
>>> for data in w.get('/demo/example/**'):
...     print('  {} : {}  (encoding: {} , timestamp: {})'.format(
...         data.path, data.value.get_content(), data.value.encoding_descr(), data.timestamp))
>>> z.close()

prefix¶

Returns the prefix that was used to create this Workspace (calling [Zenoh.workspace()]).

Return type:	str

put()¶

Put a path/value into zenoh.

The corresponding Change will be received by all matching subscribers and all matching storages. Note that the path can be absolute or relative to this Workspace.

The value parameter also accepts the following types that can be converted to a Value:

bytes for a Value.Raw(APP_OCTET_STREAM, bytes)
str for a Value.StringUtf8(str)
int for a Value.Integer(int)
float for a Value.Float(int)
dict of str:str for a Value.Properties(dict)
(str, bytes) for a Value.Custom(str, bytes)

Parameters:	path (str) – the path value (Value) – the value as a `Value`
Example:

>>> import zenoh
>>> z = zenoh.Zenoh(zenoh.net.Config())
>>> w = z.workspace()
>>> w.put('/demo/exmaple/hello', 'Hello World!')
>>> z.close()

register_eval()¶

Registers an evaluation function under the provided path expression.

The callback function will receive a GetRequest for each get operation called with a selector that patches the path expression. The callback implementation has to send replies via GetRequest.reply(). Note that the path expression can be absolute or relative to this Workspace.

Parameters:	path_expr (str) – the path expression callback (function(`GetRequest`)) – the eval callback
Return type:	zenoh.Eval
Example:

>>> import zenoh, time
>>> def eval_callback(get_request):
...    print(">> [Eval listener] received get with selector: {}".format(get_request.selector))
...    get_request.reply('/demo/example/eval', 'Result for get on {}'.format(get_request.selector))
>>>
>>> z = zenoh.Zenoh(zenoh.net.Config())
>>> w = z.workspace()
>>> eval = w.register_eval('/demo/example/eval', eval_callback)
>>> time.sleep(60)
>>> eval.close()
>>> z.close()

subscribe()¶

Subscribe to changes for a selection of path/value (specified via a selector) from zenoh.

The callback function will receive each Change for a path matching the selector. Note that the selector can be absolute or relative to this Workspace.

Parameters:	selector (str) – the selector callback (function(`Change`)) – the subscription callback
Return type:	zenoh.Subscriber
Example:

>>> import zenoh, time
>>> def listener(change):
...    print(">> [Subscription listener] received {:?} for {} : {} with timestamp {}"
...    .format(change.kind, change.path, '' if change.value is None else change.value.get_content(), change.timestamp))
>>>
>>> z = zenoh.Zenoh(zenoh.net.Config())
>>> w = z.workspace()
>>> sub = w.subscribe('/demo/example/**', listener)
>>> time.sleep(60)
>>> sub.close()
>>> z.close()

Subscriber¶

class zenoh.Subscriber¶

A handle returned as a result of Workspace.subscribe() method.

close()¶: Closes the subscription.

Eval¶

class zenoh.Eval¶

A handle returned as a result of Workspace.register_eval() method.

close()¶: Closes the eval.

Value¶

class zenoh.Value¶

A user value that is associated with a path in zenoh.

static Custom()¶

Creates a Value as a bytes buffer and an encoding description (free string).

Note: this is equivalent to Value.Raw(zenoh.net.encoding.APP_CUSTOM, buffer) where buffer contains the encoding description and the data.

Parameters:	encoding_descr (str) – the encoding description buffer (bytes) – the bytes buffer

static Float()¶

An Float value.

Note: this is equivalent to Value.Raw(zenoh.net.encoding.APP_FLOAT, buffer) where buffer contains the float encoded as a String

Parameters:	f (float) – the float

static Integer()¶

An Integer value.

Note: this is equivalent to Value.Raw(zenoh.net.encoding.APP_INTEGER, buffer) where buffer contains the integer encoded as a String

Parameters:	i (int) – the integer

static Json()¶

A Json value (string format).

Note: this is equivalent to Value.Raw(zenoh.net.encoding.APP_JSON, buffer) where buffer contains the Json string

Parameters:	s (str) – the Json string

static Properties()¶

A Properties value.

Note: this is equivalent to Value.Raw(zenoh.net.encoding.APP_PROPERTIES, buffer) where buffer contains the Properties encoded as a String

Parameters:	p (dict of str:str) – the properties

static Raw()¶

Creates a Value from a bytes buffer and an encoding flag. See zenoh.net.encoding for available flags.

Parameters:	encoding (int) – the encoding flag buffer (bytes) – the bytes buffer

static StringUTF8()¶

A String value.

Note: this is equivalent to Value.Raw(zenoh.net.encoding.STRING, buffer) where buffer contains the String

Parameters:	s (str) – the string

encoding¶

the encoding flag of the Value.

Type:	int

encoding_descr()¶

Returns the encoding description of the Value.

Return type:	str

get_content()¶

Returns the typed content of the value.

Return type:	depend on the encoding flag (e.g. str for a StringUtf8 Value, int for an Integer Value …)

Data¶

class zenoh.Data¶

A Data returned as a result of a zenoh.Workspace.get() operation.

It contains the path, its associated value and a timestamp which corresponds to the time at which the path/value has been put into zenoh.

path¶

Type:	str

timestamp¶

Type:	Timestamp

value¶

Type:	Value

Selector¶

class zenoh.Selector¶

A zenoh Selector is the conjunction of a path expression identifying a set of paths and some optional parts allowing to refine the set of paths and associated values.

Structure of a selector:

/s1/s2/.../sn?x>1&y<2&...&z=4(p1=v1;p2=v2;...;pn=vn)[a;b;x;y;...;z]
|           | |             | |                   |  |           |
|-- expr ---| |--- filter --| |---- properties ---|  |--fragment-|

where:

expr: is a [PathExpr].
filter: a list of predicates separated by & allowing to perform filtering on the values associated with the matching keys. Each predicate has the form “field-operator-value” value where:
- field is the name of a field in the value (is applicable and is existing. otherwise the predicate is false)
- operator is one of a comparison operators: < , > , <= , >= , = , !=
- value is the the value to compare the field’s value with
fragment: a list of fields names allowing to return a sub-part of each value. This feature only applies to structured values using a “self-describing” encoding, such as JSON or XML. It allows to select only some fields within the structure. A new structure with only the selected fields will be used in place of the original value.

NOTE: the filters and fragments are not yet supported in current zenoh version.

filter¶: the filter part of this Selector, if any (all characters after ? and before ( or [)

fragment¶: the fragment part of this Selector, if any (all characters between [ ] and after ?)

path_expr¶: the path expression part of this Selector (before ? character).

predicate¶: the predicate part of this Selector, as used in zenoh-net. I.e. all characters after ? (or an empty String if no such character).

properties¶: the properties part of this Selector (all characters between ( ) and after ?)

ChangeKind¶

class zenoh.ChangeKind¶

The kind of a Change.

DELETE = DELETE¶

PATCH = PATCH¶

PUT = PUT¶

Change¶

class zenoh.Change¶

The notification of a change occured on a path/value and reported to a subscription.

See zenoh.Workspace.subscribe().

kind¶

the kind of change (ChangeKind.PUT or ChangeKind.DELETE).

Type:	ChangeKind

path¶

the path related to this change.

Type:	str

timestamp¶

the Timestamp of the change

Type:	Timestamp

value¶

the new Value if the kind is ChangeKind.DELETE. None if the kind is ChangeKind.DELETE.

Type:	`Value` or `None`

GetRequest¶

class zenoh.GetRequest¶

A GET request received by an evaluation function (see Workspace::register_eval()).

reply()¶

Send a path/value as a reply to the requester.

Note that the value parameter also accepts the following types that can be converted to a Value:

bytes for a Value.Raw(APP_OCTET_STREAM, bytes)
str for a Value.StringUtf8(str)
int for a Value.Integer(int)
float for a Value.Float(int)
dict of str:str for a Value.Properties(dict)
(str, bytes) for a Value.Custom(str, bytes)

Parameters:	path (str) – the path value (Value) – the value as a `Value`

selector¶

The selector used by this GetRequest

Type:	Selector