0
# Kazoo
1

2
A comprehensive Python library that provides a higher-level API for Apache Zookeeper, designed to simplify distributed coordination and configuration management. Kazoo offers a rich set of distributed computing primitives including locks, leader elections, queues, barriers, and watchers, with built-in support for both synchronous and asynchronous programming models using threads, gevent, or eventlet.
3

4
## Package Information
5

6
- **Package Name**: kazoo
7
- **Language**: Python
8
- **Installation**: `pip install kazoo`
9
- **Version**: 2.10.0
10
- **Requirements**: Python 3.8+
11

12
## Core Imports
13

14
```python
15
from kazoo.client import KazooClient
16
```
17

18
Common patterns:
19

20
```python
21
from kazoo.client import KazooClient
22
from kazoo.exceptions import KazooException, NoNodeError, NodeExistsError
23
from kazoo.security import make_digest_acl, OPEN_ACL_UNSAFE
24
from kazoo.recipe.lock import Lock
25
from kazoo.recipe.election import Election
26
from kazoo.recipe.queue import Queue
27
```
28

29
## Basic Usage
30

31
```python
32
from kazoo.client import KazooClient
33
import logging
34

35
logging.basicConfig()
36

37
# Create and start client
38
zk = KazooClient(hosts='127.0.0.1:2181')
39
zk.start()
40

41
# Create a node
42
zk.create("/myapp", b"some data")
43

44
# Get data and stat
45
data, stat = zk.get("/myapp")
46
print(f"Version: {stat.version}, data: {data.decode('utf-8')}")
47

48
# Set data
49
zk.set("/myapp", b"updated data")
50

51
# List children
52
children = zk.get_children("/myapp")
53

54
# Clean up
55
zk.delete("/myapp")
56
zk.stop()
57
```
58

59
## Architecture
60

61
Kazoo provides a layered architecture for Zookeeper interaction:
62

63
- **KazooClient**: Main client class handling connection, session management, and basic operations
64
- **Protocol Layer**: Low-level Zookeeper protocol implementation with serialization and connection handling
65
- **Recipe Layer**: High-level distributed algorithms (locks, barriers, queues, elections)
66
- **Handler Layer**: Pluggable async implementations (threading, gevent, eventlet)
67
- **Security Layer**: ACL management and authentication mechanisms
68

69
This design enables Kazoo to serve as both a low-level Zookeeper client and a high-level toolkit for building distributed systems with reliable coordination primitives.
70

71
## Capabilities
72

73
### Core Client Operations
74

75
Primary Zookeeper client functionality including connection management, CRUD operations, watches, transactions, and session handling. The KazooClient class provides the foundation for all Zookeeper interactions.
76

77
```python { .api }
78
class KazooClient:
79
    def __init__(self, hosts="127.0.0.1:2181", timeout=10.0, client_id=None, 
80
                 handler=None, default_acl=None, auth_data=None, read_only=None,
81
                 randomize_hosts=True, connection_retry=None, command_retry=None,
82
                 logger=None, keyfile=None, certfile=None, ca=None, use_ssl=False, 
83
                 verify_certs=True, **kwargs): ...
84
    
85
    def start(self, timeout=15): ...
86
    def stop(self): ...
87
    def restart(self): ...
88
    def close(self): ...
89
    
90
    def create(self, path, value=b"", acl=None, ephemeral=False, sequence=False, makepath=False): ...
91
    def get(self, path, watch=None): ...
92
    def set(self, path, value, version=-1): ...
93
    def delete(self, path, version=-1, recursive=False): ...
94
    def exists(self, path, watch=None): ...
95
    def get_children(self, path, watch=None, include_data=False): ...
96
```
97

98
[Core Client](./core-client.md)
99

100
### Distributed Recipes
101

102
High-level distributed coordination primitives built on top of Zookeeper. These recipes provide common distributed systems patterns like locks, leader elections, queues, barriers, and counters with reliable semantics.
103

104
```python { .api }
105
class Lock:
106
    def __init__(self, client, path, identifier=None): ...
107
    def acquire(self, blocking=True, timeout=None): ...
108
    def release(self): ...
109

110
class Election:
111
    def __init__(self, client, path, identifier=None): ...
112
    def run(self, func, *args, **kwargs): ...
113
    def cancel(self): ...
114

115
class Queue:
116
    def __init__(self, client, path): ...
117
    def put(self, value, priority=100): ...
118
    def get(self, timeout=None): ...
119

120
class Barrier:
121
    def __init__(self, client, path, num_clients): ...
122
    def create(self): ...
123
    def wait(self, timeout=None): ...
124
```
125

126
[Distributed Recipes](./recipes.md)
127

128
### Exception Handling
129

130
Comprehensive exception hierarchy for handling all Zookeeper error conditions, including connection issues, node state conflicts, authentication failures, and protocol errors. Each exception includes appropriate error codes and context.
131

132
```python { .api }
133
class KazooException(Exception): ...
134
class ZookeeperError(KazooException): ...
135
class ConnectionLoss(ZookeeperError): ...
136
class NoNodeError(ZookeeperError): ...
137
class NodeExistsError(ZookeeperError): ...
138
class SessionExpiredError(ZookeeperError): ...
139
class AuthFailedError(ZookeeperError): ...
140
```
141

142
[Exception Handling](./exceptions.md)
143

144
### Security and ACL Management
145

146
Access control and authentication mechanisms for securing Zookeeper nodes. Includes ACL creation, permission management, and authentication schemes with support for digest, IP, and world authentication.
147

148
```python { .api }
149
class ACL:
150
    def __init__(self, perms, id): ...
151

152
class Permissions:
153
    READ: int
154
    WRITE: int
155
    CREATE: int
156
    DELETE: int
157
    ADMIN: int
158
    ALL: int
159

160
def make_digest_acl(username, password, read=False, write=False, create=False, delete=False, admin=False, all=False): ...
161
def make_acl(scheme, credential, perms): ...
162
```
163

164
[Security and ACLs](./security.md)
165

166
### Async Handlers
167

168
Pluggable concurrency models supporting different async frameworks. Handlers manage callback execution, timeouts, and async result objects with support for threading, gevent, and eventlet paradigms.
169

170
```python { .api }
171
class SequentialThreadingHandler:
172
    def __init__(self): ...
173
    def start(self): ...
174
    def stop(self): ...
175

176
class SequentialGeventHandler:
177
    def __init__(self): ...
178

179
class SequentialEventletHandler:
180
    def __init__(self): ...
181
```
182

183
[Async Handlers](./handlers.md)
184

185
### Testing Infrastructure
186

187
Testing utilities and harnesses for developing Zookeeper-based applications. Includes managed Zookeeper server instances, test clusters, and base test classes with automatic client setup and teardown.
188

189
```python { .api }
190
class KazooTestHarness:
191
    def setup_zookeeper(self): ...
192
    def teardown_zookeeper(self): ...
193

194
class KazooTestCase:
195
    def setUp(self): ...
196
    def tearDown(self): ...
197
```
198

199
[Testing Infrastructure](./testing.md)
200

201
## Types
202

203
```python { .api }
204
from collections import namedtuple
205
from typing import Optional, List, Tuple, Callable, Any, Union
206

207
# Core types
208
ZnodeStat = namedtuple('ZnodeStat', 'czxid mzxid ctime mtime version cversion aversion ephemeralOwner dataLength numChildren pzxid')
209
WatchedEvent = namedtuple('WatchedEvent', 'type state path')
210
ACL = namedtuple('ACL', 'perms id')
211
Id = namedtuple('Id', 'scheme id')
212

213
# State enums
214
class KazooState:
215
    SUSPENDED: str
216
    CONNECTED: str
217
    LOST: str
218

219
class KeeperState:
220
    EXPIRED_SESSION: int
221
    AUTH_FAILED: int
222
    CLOSED: int
223
    CONNECTED: int
224
    CONNECTING: int
225

226
class EventType:
227
    CREATED: int
228
    DELETED: int
229
    CHANGED: int
230
    CHILD: int
231
```