Install & Compatibility
Where this runs
tested against v8.1.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
muslpy 3.10–3.930 runs
installs and imports cleanly · install 0.0s · import 0.000s · 44.1MB
glibcpy 3.10–3.930 runs
installs and imports cleanly · install 4.2s · import 0.000s · 46MB
48MB installed
● package 48MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ToozError
✓ from tooz import ToozError
✗ from tooz.drivers import DriverFactory
NotImplemented
✓ from tooz import NotImplemented
✗ from tooz.drivers import DriverFactory
This quickstart demonstrates how to initialize a `tooz` driver using `DriverFactory` and acquire a distributed lock. It uses a file-based driver by default for easy local testing, but can be configured with a `TOOZ_BACKEND` environment variable for real backends like Redis or Zookeeper. The example shows how to acquire a lock with a timeout and ensures proper cleanup.
import os
import time
from tooz.drivers import DriverFactory
# Use a file-based driver for local testing or set an environment variable for a real backend
# e.g., export TOOZ_BACKEND="redis://localhost:6379/0" (for Redis DB 0)
# e.g., export TOOZ_BACKEND="zookeeper://localhost:2181"
connection_string = os.environ.get("TOOZ_BACKEND", "file:///tmp/tooz_locks_example")
# Group ID for coordination primitives, must be bytes
group_id = b"my_application_group"
driver = None
try:
# Initialize the driver factory. This will select the appropriate driver
# based on the connection string prefix (e.g., 'redis://', 'file://').
driver = DriverFactory(connection_string, group_id)
print(f"Connected to tooz backend: {connection_string}")
# Example: Acquire a distributed lock
lock_name = b"my_critical_section"
# `timeout` specifies how long to wait to acquire the lock.
# `heartbeat_timeout` specifies how often to renew the lock if acquired.
lock = driver.get_lock(lock_name, timeout=5, heartbeat_timeout=1)
print(f"Attempting to acquire lock '{lock_name.decode()}'...")
if lock.acquire():
print("Lock acquired successfully! Performing critical work...")
# Simulate some work
time.sleep(2)
print("Work done, releasing lock.")
# Lock is automatically released by the 'finally' block when driver disconnects
# or can be explicitly released with lock.release()
else:
print("Could not acquire lock within timeout.")
finally:
if driver:
# Ensure the driver is disconnected to release resources and locks.
driver.disconnect()
print("Disconnected from tooz backend.")
Upgrade
Version history
8.1.0latest on PyPI · released Feb 19, 2026
Audit
Dependencies
redisoptionalRequired for the Redis driver. Install with 'pip install tooz[redis]'.
kazoooptionalRequired for the Zookeeper driver. Install with 'pip install tooz[zookeeper]'.
python-etcd3optionalRequired for the Etcd driver. Install with 'pip install tooz[etcd3]'.