0
# Eclipse Zenoh Python API
1

2
Eclipse Zenoh is a high-performance networking library that provides Python bindings for the Zenoh protocol, a cutting-edge pub/sub, store/query and compute framework designed for zero-overhead communication. It enables Python developers to build distributed applications with unified data-in-motion, data-at-rest, and computational capabilities that blend traditional publish-subscribe patterns with geo-distributed storage, queries, and computations while maintaining exceptional time and space efficiency.
3

4
## Package Information
5

6
- **Package Name**: eclipse-zenoh
7
- **Language**: Python
8
- **Installation**: `pip install eclipse-zenoh`
9
- **Version**: 1.5.1
10
- **Platform Support**: Linux, macOS, Windows
11
- **Python Version**: 3.8+
12

13
## Core Imports
14

15
```python
16
import zenoh
17
```
18

19
For specific functionality:
20

21
```python
22
from zenoh import Config, Session, Priority, CongestionControl
23
```
24

25
For extensions (serialization and advanced features):
26

27
```python
28
import zenoh.ext
29
from zenoh.ext import z_serialize, z_deserialize
30
```
31

32
For handlers:
33

34
```python
35
from zenoh.handlers import DefaultHandler, FifoChannel, RingChannel, Callback
36
```
37

38
## Basic Usage
39

40
```python
41
import zenoh
42

43
# Create and open a session
44
config = zenoh.Config()
45
session = zenoh.open(config)
46

47
# Publisher pattern
48
publisher = session.declare_publisher("demo/example")
49
publisher.put("Hello, Zenoh!")
50

51
# Subscriber pattern
52
def listener(sample):
53
    print(f"Received: {sample.payload.to_string()} on {sample.key_expr}")
54

55
subscriber = session.declare_subscriber("demo/example", listener)
56

57
# Query pattern
58
replies = session.get("demo/**")
59
for reply in replies:
60
    if reply.ok:
61
        print(f"Got: {reply.ok.payload.to_string()}")
62

63
# Cleanup
64
publisher.undeclare()
65
subscriber.undeclare()
66
session.close()
67
```
68

69
## Architecture
70

71
Zenoh's architecture is built around several key concepts:
72

73
- **Session**: Central communication hub that manages all operations
74
- **Key Expressions**: Hierarchical addressing scheme for resources (e.g., "sensors/temperature/room1")
75
- **Data Flow Patterns**: Publisher/Subscriber for streaming, Query/Queryable for request-response
76
- **Zero-copy Data**: Efficient `ZBytes` container for high-performance data handling
77
- **Quality of Service**: Fine-grained control over priority, congestion control, and reliability
78
- **Handlers**: Flexible callback system supporting Rust channels and Python callbacks
79

80
The Python API provides bindings to a high-performance Rust implementation, ensuring excellent performance while maintaining Python's ease of use.
81

82
## Capabilities
83

84
### Session Management
85

86
Core session lifecycle including configuration, connection establishment, and discovery operations.
87

88
```python { .api }
89
def open(config: Config) -> Session: ...
90
def scout(what: WhatAmIMatcher = None, **kwargs) -> Scout: ...
91

92
class Config:
93
    def __init__(self): ...
94
    @staticmethod
95
    def from_file(path: str) -> Config: ...
96
    @staticmethod
97
    def from_json5(config: str) -> Config: ...
98

99
class Session:
100
    def close(self) -> None: ...
101
    def declare_publisher(self, key_expr, **kwargs) -> Publisher: ...
102
    def declare_subscriber(self, key_expr, handler=None, **kwargs) -> Subscriber: ...
103
    def declare_queryable(self, key_expr, handler, **kwargs) -> Queryable: ...
104
    def declare_querier(self, key_expr, **kwargs) -> Querier: ...
105
    def get(self, selector, **kwargs): ...
106
    def put(self, key_expr, payload, **kwargs): ...
107
    def delete(self, key_expr, **kwargs): ...
108
```
109

110
[Session Management](./session-management.md)
111

112
### Publisher/Subscriber Pattern
113

114
Real-time data streaming with publish/subscribe messaging patterns.
115

116
```python { .api }
117
class Publisher:
118
    key_expr: KeyExpr
119
    encoding: Encoding
120
    congestion_control: CongestionControl
121
    priority: Priority
122
    def put(self, payload, **kwargs) -> None: ...
123
    def delete(self, **kwargs) -> None: ...
124
    def undeclare(self) -> None: ...
125
    def declare_matching_listener(self, handler) -> MatchingListener: ...
126

127
class Subscriber:
128
    key_expr: KeyExpr
129
    handler: Handler
130
    def undeclare(self) -> None: ...
131
    def try_recv(self): ...
132
    def recv(self): ...
133
    def __iter__(self): ...
134

135
class Sample:
136
    key_expr: KeyExpr
137
    payload: ZBytes
138
    encoding: Encoding
139
    kind: SampleKind
140
    timestamp: Timestamp
141
```
142

143
[Publisher/Subscriber](./pubsub.md)
144

145
### Query/Queryable Pattern
146

147
Request-response messaging for querying distributed data and services.
148

149
```python { .api }
150
def get(self, selector: str, **kwargs): ...
151

152
class Query:
153
    selector: Selector
154
    key_expr: KeyExpr
155
    parameters: Parameters
156
    def reply(self, payload, **kwargs) -> None: ...
157
    def reply_err(self, payload, **kwargs) -> None: ...
158
    def reply_del(self, **kwargs) -> None: ...
159

160
class Reply:
161
    ok: Sample
162
    err: ReplyError
163

164
class Queryable:
165
    def undeclare(self) -> None: ...
166
    def try_recv(self): ...
167
    def recv(self): ...
168

169
class Querier:
170
    def get(self, **kwargs): ...
171
    def undeclare(self) -> None: ...
172
```
173

174
[Query/Queryable](./query.md)
175

176
### Data Types
177

178
Core data structures for efficient data handling and type safety.
179

180
```python { .api }
181
class ZBytes:
182
    def __init__(self, data): ...
183
    def to_bytes(self) -> bytes: ...
184
    def to_string(self) -> str: ...
185

186
class Encoding:
187
    def __init__(self, encoding_type: str): ...
188
    def with_schema(self, schema: str) -> Encoding: ...
189

190
class KeyExpr:
191
    def __init__(self, key: str): ...
192
    def intersects(self, other: KeyExpr) -> bool: ...
193

194
class Selector:
195
    key_expr: KeyExpr
196
    parameters: Parameters
197

198
class Parameters:
199
    def get(self, key: str): ...
200
    def insert(self, key: str, value: str): ...
201
```
202

203
[Data Types](./data-types.md)
204

205
### Handler System
206

207
Flexible handler system for processing asynchronous data streams with channels and callbacks.
208

209
```python { .api }
210
from zenoh.handlers import DefaultHandler, FifoChannel, RingChannel, Callback
211

212
class FifoChannel:
213
    def __init__(self, capacity: int): ...
214
    def try_recv(self): ...
215
    def recv(self): ...
216

217
class Callback:
218
    def __init__(self, callback: callable, drop: callable = None): ...
219
```
220

221
[Handler System](./handlers.md)
222

223
### Advanced Features
224

225
Liveliness detection, matching listeners, and advanced networking features.
226

227
```python { .api }
228
class Liveliness:
229
    def declare_token(self, key_expr) -> LivelinessToken: ...
230
    def declare_subscriber(self, key_expr, handler) -> Subscriber: ...
231

232
class MatchingStatus:
233
    matching: bool
234

235
class MatchingListener:
236
    def undeclare(self) -> None: ...
237
```
238

239
[Advanced Features](./advanced.md)
240

241
### Extensions
242

243
Serialization utilities and advanced publisher/subscriber features with additional reliability and caching.
244

245
```python { .api }
246
from zenoh.ext import z_serialize, z_deserialize
247
from zenoh.ext import AdvancedPublisher, AdvancedSubscriber
248

249
def z_serialize(obj) -> ZBytes: ...
250
def z_deserialize(target_type, data: ZBytes): ...
251
```
252

253
[Extensions](./extensions.md)
254

255
## Quality of Service
256

257
```python { .api }
258
class Priority:
259
    REAL_TIME = ...
260
    INTERACTIVE_HIGH = ...
261
    INTERACTIVE_LOW = ...
262
    DATA_HIGH = ...
263
    DATA = ...
264
    DATA_LOW = ...
265
    BACKGROUND = ...
266
    DEFAULT = DATA
267

268
class CongestionControl:
269
    DROP = ...
270
    BLOCK = ...
271
    DEFAULT = DROP
272

273
class Reliability:  # Unstable
274
    BEST_EFFORT = ...
275
    RELIABLE = ...
276
```
277

278
## Error Handling
279

280
```python { .api }
281
class ZError(Exception):
282
    """Base exception for all Zenoh errors"""
283

284
class ReplyError:
285
    payload: ZBytes
286
    encoding: Encoding
287
```
288

289
All Zenoh operations may raise `ZError` exceptions. Handle them appropriately in production code:
290

291
```python
292
try:
293
    session = zenoh.open(config)
294
    # ... operations
295
except zenoh.ZError as e:
296
    print(f"Zenoh error: {e}")
297
```