Registry / database / kazoo

kazoo

JSON →
library2.11.0pypypi✓ verified 52d ago

Kazoo is a higher-level Python client for Apache ZooKeeper, providing robust abstractions for common distributed coordination tasks like locks, leader election, and queues. Version 2.11.0 is the latest stable release, with development active and releases occurring periodically, often driven by Python version support updates and bug fixes.

databaseworkflow
pip install kazoo
Install & Compatibility
Where this runs
tested against v2.11.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.930 runs
installs and imports cleanly · install 0.0s · import 0.133s · 19.1MB
glibc
py 3.103.930 runs
installs and imports cleanly · install 1.7s · import 0.118s · 20MB
17MB installed
● package 17MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

KazooClient
from kazoo.client import KazooClient
KazooException
from kazoo.exceptions import KazooException

This quickstart demonstrates how to connect to Apache ZooKeeper using Kazoo, set up a connection state listener, create an ephemeral node, and retrieve its data. Remember to have a ZooKeeper instance running and set the `ZOOKEEPER_HOSTS` environment variable accordingly.

import os import time from kazoo.client import KazooClient from kazoo.exceptions import KazooException # Get Zookeeper host(s) from environment variable, e.g., '127.0.0.1:2181,127.0.0.1:2182' ZOOKEEPER_HOSTS = os.environ.get('ZOOKEEPER_HOSTS', '127.0.0.1:2181') zk = KazooClient(hosts=ZOOKEEPER_HOSTS) @zk.add_listener def my_listener(state): """Listener for Zookeeper connection state changes.""" print(f"Zookeeper state changed: {state}") if state == 'CONNECTED': print("Successfully connected to Zookeeper!") elif state == 'LOST': print("Connection to Zookeeper lost. Attempting to reconnect...") elif state == 'SUSPENDED': print("Connection to Zookeeper suspended. Will attempt to reconnect.") try: print(f"Attempting to connect to Zookeeper at {ZOOKEEPER_HOSTS}...") zk.start() zk.ensure_path("/my/kazoo/path") print("Created /my/kazoo/path if it didn't exist.") # Create an ephemeral node that will be deleted when the client disconnects node_path = "/my/kazoo/path/ephemeral_node" zk.create(node_path, b"hello_kazoo", ephemeral=True, sequence=False) print(f"Created ephemeral node: {node_path} with data 'hello_kazoo'") data, stat = zk.get(node_path) print(f"Retrieved data from {node_path}: {data.decode('utf-8')}, Stat: {stat}") # Keep the client alive for a few seconds to observe state changes or for other operations time.sleep(5) except KazooException as e: print(f"A Kazoo-specific error occurred: {e}") except Exception as e: print(f"An unexpected error occurred: {e}") finally: if zk.connected: zk.stop() print("KazooClient stopped.") zk.close() print("KazooClient closed.")
Debug
Known issues
breakingKazoo frequently updates its supported Python versions, often dropping compatibility with older Python releases. Ensure your environment matches the supported versions to avoid compatibility issues.
fix
Refer to the latest Kazoo release notes or documentation for current Python compatibility. For example, Kazoo 2.10.0 dropped support for Python 3.7, now supporting Python 3.8-3.12.
affects: 2.8.0+
gotchaKazooClient operates asynchronously. It's crucial to correctly manage the client's lifecycle (start, stop, close) and handle connection state changes (CONNECTED, SUSPENDED, LOST) using listeners or by checking `zk.connected` before performing operations. Operations performed while not connected can lead to errors or unexpected behavior.
fix
Implement a connection state listener using `@zk.add_listener` and structure your logic to react to connection events. Ensure `zk.start()` is called and the client has connected before attempting Zookeeper operations.
affects: all versions
gotchaThe `hosts` parameter for `KazooClient` expects a comma-separated string of `host:port` pairs (e.g., '127.0.0.1:2181,127.0.0.2:2181'). Using spaces or other delimiters can lead to connection failures.
fix
Always provide the Zookeeper host string in the correct `host:port,host:port` format. Validate the string if it's sourced from configuration or environment variables.
affects: all versions
gotchaKazooClient requires an active and accessible Zookeeper ensemble to establish a connection. Connection failures such as 'Connection refused' or 'Connection time-out' often indicate that the Zookeeper server is not running, is inaccessible due to network issues, or its firewall is blocking connections on the specified port.
fix
Verify that the Zookeeper server (or ensemble) is running and accessible from the client's host and network on the configured port (default 2181). Check firewall rules, network connectivity, and ensure the Zookeeper service is active.
affects: all versions
gotchaKazooClient requires an active and accessible Zookeeper server to establish a connection. Errors like 'Connection refused' or 'Connection time-out' indicate that the client could not establish a network connection to the specified Zookeeper host and port, likely because the server is not running, not listening on the provided address/port, or is unreachable due to network configuration (e.g., firewall).
fix
Ensure your Zookeeper server is running, accessible from the client's network, and configured to listen on the `host:port` provided to `KazooClient`. Verify network connectivity (e.g., using `telnet` or `nc`) to the Zookeeper server's address and port from the client's environment. Check Zookeeper server logs for binding or startup errors.
affects: all versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'kazoo'
The Kazoo library has not been installed in your Python environment.
fix
pip install kazoo
kazoo.exceptions.ConnectionLoss: Connection to the server has been lost.
The Kazoo client lost its connection to the ZooKeeper server due to network issues, server unavailability, or session expiration.
fix
Implement a connection listener to handle state changes (KazooState.SUSPENDED, KazooState.LOST, KazooState.CONNECTED) and consider using `kazoo.retry.KazooRetry` for operations that should be reattempted upon transient connection issues.
kazoo.handlers.threading.KazooTimeoutError: Connection time-out
The Kazoo client failed to establish or re-establish a connection to the ZooKeeper server within the configured timeout period during client startup or an operation.
fix
Verify that the ZooKeeper server is running and accessible from the client. Consider increasing the `timeout` parameter during `KazooClient` initialization or in the `start()` method if network latency or server startup time is a factor.
kazoo.exceptions.NoNodeError: Node does not exist.
You are attempting to perform an operation (e.g., get, set, delete) on a ZooKeeper node that does not exist at the specified path.
fix
Ensure the node path is correct. If the node may or may not exist, use methods like `client.exists(path)` to check before operating, or `client.ensure_path(path)` to create parent nodes if missing before creating a child node.
kazoo.exceptions.AuthFailedError: Client authentication failed.
The authentication credentials provided to the Kazoo client are incorrect or the client is not authorized to perform operations on the ZooKeeper server.
fix
Ensure the correct `auth_data` (scheme and credentials) is provided to the `KazooClient` during initialization or added via `client.add_auth()` to match the ZooKeeper server's authentication requirements.
Upgrade
Version history
2.11.0latest on PyPI
Audit
Dependencies

No dependency data recorded yet.

Agent activity
31 hits · last 30 days
node
4
seranking-bot
4
ahrefsbot
3
Resources