0
# Session Management
1
2
Session management provides the core functionality for establishing connections, managing configuration, and discovering network peers in the Zenoh ecosystem. The Session is the central hub for all Zenoh operations.
3
4
## Capabilities
5
6
### Session Creation and Configuration
7
8
Create and configure Zenoh sessions with various connection options.
9
10
```python { .api }
11
class Config:
12
"""Main configuration structure for Zenoh"""
13
14
def __init__(self):
15
"""Create a default configuration"""
16
17
@staticmethod
18
def from_env() -> Config:
19
"""Create configuration from environment variables"""
20
21
@staticmethod
22
def from_file(path: str) -> Config:
23
"""Load configuration from a JSON5 file"""
24
25
@staticmethod
26
def from_json5(config: str) -> Config:
27
"""Create configuration from JSON5 string"""
28
29
def get_json(self, key: str) -> str:
30
"""Get configuration value as JSON string"""
31
32
def insert_json5(self, key: str, value: str) -> Config:
33
"""Insert configuration key-value pair from JSON5"""
34
```
35
36
```python { .api }
37
def open(config: Config = None) -> Session:
38
"""
39
Open a zenoh Session.
40
41
Parameters:
42
- config: Configuration for the session. If None, uses default config.
43
44
Returns:
45
Session object for Zenoh operations
46
"""
47
```
48
49
### Session Operations
50
51
Core session functionality for managing the connection lifecycle and retrieving session information.
52
53
```python { .api }
54
class Session:
55
"""A zenoh session"""
56
57
@property
58
def info(self) -> SessionInfo:
59
"""Get session information"""
60
61
def zid(self) -> ZenohId:
62
"""Get the session's ZenohId"""
63
64
def is_closed(self) -> bool:
65
"""Check if session is closed"""
66
67
def close(self) -> None:
68
"""Close the session and release resources"""
69
70
def undeclare(self, entity) -> None:
71
"""Undeclare an entity (publisher, subscriber, etc.)"""
72
73
def new_timestamp(self) -> Timestamp:
74
"""Create a new timestamp for this session"""
75
76
def declare_keyexpr(self, key_expr: str) -> KeyExpr:
77
"""Declare a key expression to optimize repeated usage"""
78
79
def declare_querier(self, key_expr, **kwargs) -> Querier:
80
"""Declare a querier for repeated queries on the same key expression"""
81
82
def put(self, key_expr, payload, **kwargs) -> None:
83
"""Put data directly through the session"""
84
85
def delete(self, key_expr, **kwargs) -> None:
86
"""Delete data directly through the session"""
87
88
def get(self, selector, **kwargs):
89
"""Query data through the session"""
90
91
@property
92
def liveliness(self) -> Liveliness:
93
"""Access liveliness operations for this session"""
94
```
95
96
### Network Discovery
97
98
Discover available Zenoh peers and routers on the network.
99
100
```python { .api }
101
def scout(
102
what: WhatAmIMatcher = None,
103
timeout: float = None,
104
handler = None
105
) -> Scout:
106
"""
107
Scout for routers and/or peers.
108
109
Parameters:
110
- what: What to scout for (routers, peers, clients)
111
- timeout: Scout timeout in seconds
112
- handler: Handler for receiving Hello messages
113
114
Returns:
115
Scout object for receiving discovery results
116
"""
117
118
class Scout:
119
"""Scout handler for network discovery"""
120
121
@property
122
def handler(self):
123
"""Get the scout handler"""
124
125
def stop(self) -> None:
126
"""Stop scouting"""
127
128
def try_recv(self):
129
"""Try to receive a Hello message without blocking"""
130
131
def recv(self):
132
"""Receive a Hello message (blocking)"""
133
134
def __iter__(self):
135
"""Iterate over Hello messages"""
136
```
137
138
### Session Information
139
140
Access information about the current session and connected peers.
141
142
```python { .api }
143
class SessionInfo:
144
"""Session information"""
145
146
def zid(self) -> ZenohId:
147
"""Get session ZenohId"""
148
149
def routers_zid(self) -> list:
150
"""Get list of connected routers' ZenohIds"""
151
152
def peers_zid(self) -> list:
153
"""Get list of connected peers' ZenohIds"""
154
155
class ZenohId:
156
"""Global unique peer identifier"""
157
158
def __str__(self) -> str:
159
"""String representation of ZenohId"""
160
```
161
162
### Discovery Messages
163
164
Handle network discovery responses.
165
166
```python { .api }
167
class Hello:
168
"""Scout discovery message"""
169
170
@property
171
def whatami(self) -> WhatAmI:
172
"""What type of Zenoh node this is"""
173
174
@property
175
def zid(self) -> ZenohId:
176
"""ZenohId of the discovered node"""
177
178
@property
179
def locators(self) -> list:
180
"""List of locators for the node"""
181
```
182
183
### Node Types
184
185
Identify and match different types of Zenoh nodes.
186
187
```python { .api }
188
class WhatAmI:
189
"""Node type identification"""
190
ROUTER = ...
191
PEER = ...
192
CLIENT = ...
193
194
class WhatAmIMatcher:
195
"""Node type matcher for scouting"""
196
197
@staticmethod
198
def empty() -> WhatAmIMatcher:
199
"""Empty matcher (matches nothing)"""
200
201
@staticmethod
202
def router() -> WhatAmIMatcher:
203
"""Match routers only"""
204
205
@staticmethod
206
def peer() -> WhatAmIMatcher:
207
"""Match peers only"""
208
209
@staticmethod
210
def client() -> WhatAmIMatcher:
211
"""Match clients only"""
212
213
def is_empty(self) -> bool:
214
"""Check if matcher is empty"""
215
216
def matches(self, what: WhatAmI) -> bool:
217
"""Check if matcher matches a node type"""
218
```
219
220
### Timestamp Management
221
222
Create and manage timestamps for ordering and synchronization.
223
224
```python { .api }
225
class Timestamp:
226
"""Timestamp for ordering and synchronization"""
227
228
def __init__(self, time: datetime, id: TimestampId):
229
"""Create timestamp with time and identifier"""
230
231
def get_time(self) -> datetime:
232
"""Get the datetime component"""
233
234
def get_id(self) -> TimestampId:
235
"""Get the timestamp identifier"""
236
237
def get_diff_duration(self, other: Timestamp) -> timedelta:
238
"""Get duration difference with another timestamp"""
239
240
def to_string_rfc3339_lossy(self) -> str:
241
"""Convert to RFC3339 string representation"""
242
243
@staticmethod
244
def parse_rfc3339(rfc3839: str) -> Timestamp:
245
"""Parse RFC3339 timestamp string"""
246
247
class TimestampId:
248
"""Unique identifier component of timestamp"""
249
250
def __init__(self, bytes: bytes):
251
"""Create from byte array"""
252
253
def __bytes__(self) -> bytes:
254
"""Convert to bytes"""
255
```
256
257
### Logging Configuration
258
259
Configure logging for Zenoh operations.
260
261
```python { .api }
262
def try_init_log_from_env() -> bool:
263
"""
264
Initialize logging from RUST_LOG environment variable.
265
Returns True if successful, False otherwise.
266
"""
267
268
def init_log_from_env_or(level: str):
269
"""
270
Initialize logging from environment or use provided level.
271
272
Parameters:
273
- level: Default log level if RUST_LOG not set
274
"""
275
```
276
277
## Usage Examples
278
279
### Basic Session Setup
280
281
```python
282
import zenoh
283
284
# Default configuration
285
config = zenoh.Config()
286
session = zenoh.open(config)
287
288
print(f"Session ID: {session.zid()}")
289
session.close()
290
```
291
292
### Configuration from File
293
294
```python
295
import zenoh
296
297
# Load configuration from file
298
config = zenoh.Config.from_file("zenoh-config.json5")
299
session = zenoh.open(config)
300
301
# Session operations...
302
session.close()
303
```
304
305
### Network Discovery
306
307
```python
308
import zenoh
309
310
def handle_hello(hello):
311
print(f"Discovered {hello.whatami}: {hello.zid}")
312
313
# Scout for all node types
314
scout = zenoh.scout(handler=handle_hello)
315
316
# Let it run for a while
317
import time
318
time.sleep(2)
319
320
scout.stop()
321
```
322
323
### Session Information
324
325
```python
326
import zenoh
327
328
session = zenoh.open()
329
info = session.info
330
331
print(f"Session ZID: {info.zid()}")
332
print(f"Connected routers: {len(info.routers_zid())}")
333
print(f"Connected peers: {len(info.peers_zid())}")
334
335
session.close()
336
```