kazoo.client
¶
Kazoo Zookeeper Client
Public API¶
- class kazoo.client.KazooClient[source]¶
An Apache Zookeeper Python client supporting alternate callback handlers and high-level functionality.
Watch functions registered with this class will not get session events, unlike the default Zookeeper watches. They will also be called with a single argument, a
WatchedEvent
instance.
- __init__(hosts='127.0.0.1:2181', timeout=10.0, client_id=None, handler=None, default_acl=None, auth_data=None, sasl_options=None, read_only=None, randomize_hosts=True, connection_retry=None, command_retry=None, logger=None, keyfile=None, keyfile_password=None, certfile=None, ca=None, use_ssl=False, verify_certs=True, **kwargs)[source]¶
Create a
KazooClient
instance. All time arguments are in seconds.
- Parameters:
hosts – Comma-separated list of hosts to connect to (e.g. 127.0.0.1:2181,127.0.0.1:2182,[::1]:2183).
timeout – The longest to wait for a Zookeeper connection.
client_id – A Zookeeper client id, used when re-establishing a prior session connection.
handler – An instance of a class implementing the
IHandler
interface for callback handling.default_acl – A default ACL used on node creation.
auth_data – A list of authentication credentials to use for the connection. Should be a list of (scheme, credential) tuples as
add_auth()
takes.sasl_options –
SASL options for the connection, if SASL support is to be used. Should be a dict of SASL options passed to the underlying pure-sasl library.
For example using the DIGEST-MD5 mechnism:
sasl_options = { 'mechanism': 'DIGEST-MD5', 'username': 'myusername', 'password': 'mypassword' }For GSSAPI, using the running process’ ticket cache:
sasl_options = { 'mechanism': 'GSSAPI', 'service': 'myzk', # optional 'principal': 'client@EXAMPLE.COM' # optional }read_only – Allow connections to read only servers.
randomize_hosts – By default randomize host selection.
connection_retry – A
kazoo.retry.KazooRetry
object to use for retrying the connection to Zookeeper. Also can be a dict of options which will be used for creating one.command_retry – A
kazoo.retry.KazooRetry
object to use for theKazooClient.retry()
method. Also can be a dict of options which will be used for creating one.logger – A custom logger to use instead of the module global log instance.
keyfile – SSL keyfile to use for authentication
keyfile_password – SSL keyfile password
certfile – SSL certfile to use for authentication
ca – SSL CA file to use for authentication
use_ssl – argument to control whether SSL is used or not
verify_certs – when using SSL, argument to bypass certs verification
Basic Example:
zk = KazooClient() zk.start() children = zk.get_children('/') zk.stop()As a convenience all recipe classes are available as attributes and get automatically bound to the client. For example:
zk = KazooClient() zk.start() lock = zk.Lock('/lock_path')New in version 0.6: The read_only option. Requires Zookeeper 3.4+
New in version 0.6: The retry_max_delay option.
New in version 0.6: The randomize_hosts option.
Changed in version 0.8: Removed the unused watcher argument (was second argument).
New in version 1.2: The connection_retry, command_retry and logger options.
New in version 2.7: The sasl_options option.
- handler¶
The
IHandler
strategy used by this client. Gives access to appropriate synchronization objects.
- retry(func, *args, **kwargs)¶
Runs the given function with the provided arguments, retrying if it fails because the ZooKeeper connection is lost, see Retrying Commands.
- state¶
A
KazooState
attribute indicating the current higher-level connection state.Note
Up to version 2.6.1, requests could only be submitted in the CONNECTED state. Requests submitted while SUSPENDED would immediately raise a
SessionExpiredError
. This was problematic, as sessions are usually recovered on reconnect.Kazoo now simply queues requests submitted in the SUSPENDED state, expecting a recovery. This matches the behavior of the Java and C clients.
Requests submitted in a LOST state still fail immediately with the corresponding exception.
See:
- property client_state¶
Returns the last Zookeeper client state
This is the non-simplified state information and is generally not as useful as the simplified KazooState information.
- property client_id¶
Returns the client id for this Zookeeper session if connected.
- Returns:
client id which consists of the session id and password.
- Return type:
tuple
- property connected¶
Returns whether the Zookeeper connection has been established.
- set_hosts(hosts, randomize_hosts=None)[source]¶
sets the list of hosts used by this client.
This function accepts the same format hosts parameter as the init function and sets the client to use the new hosts the next time it needs to look up a set of hosts. This function does not affect the current connected status.
It is not currently possible to change the chroot with this function, setting a host list with a new chroot will raise a ConfigurationError.
- Parameters:
hosts – see description in
KazooClient.__init__()
randomize_hosts – override client default for host randomization
- Raises:
ConfigurationError
if the hosts argument changes the chrootNew in version 1.4.
Warning
Using this function to point a client to a completely disparate zookeeper server cluster has undefined behavior.
- add_listener(listener)[source]¶
Add a function to be called for connection state changes.
This function will be called with a
KazooState
instance indicating the new connection state on state transitions.Warning
This function must not block. If its at all likely that it might need data or a value that could result in blocking than the
spawn()
method should be used so that the listener can return immediately.
- start(timeout=15)[source]¶
Initiate connection to ZK.
- Parameters:
timeout – Time in seconds to wait for connection to succeed.
- Raises:
timeout_exception
if the connection wasn’t established within timeout seconds.
- start_async()[source]¶
Asynchronously initiate connection to ZK.
- Returns:
An event object that can be checked to see if the connection is alive.
- Return type:
Event
compatible object.
- stop()[source]¶
Gracefully stop this Zookeeper session.
This method can be called while a reconnection attempt is in progress, which will then be halted.
Once the connection is closed, its session becomes invalid. All the ephemeral nodes in the ZooKeeper server associated with the session will be removed. The watches left on those nodes (and on their parents) will be triggered.
- close()[source]¶
Free any resources held by the client.
This method should be called on a stopped client before it is discarded. Not doing so may result in filehandles being leaked.
New in version 1.0.
- command(cmd=b'ruok')[source]¶
Sent a management command to the current ZK server.
Examples are ruok, envi or stat.
- Returns:
An unstructured textual response.
- Return type:
str
- Raises:
ConnectionLoss
if there is no connection open, or possibly asocket.error
if there’s a problem with the connection used just for this command.New in version 0.5.
- server_version(retries=3)[source]¶
Get the version of the currently connected ZK server.
- Returns:
The server version, for example (3, 4, 3).
- Return type:
tuple
New in version 0.5.
- add_auth(scheme, credential)[source]¶
Send credentials to server.
- Parameters:
scheme – authentication scheme (default supported: “digest”).
credential – the credential – value depends on scheme.
- Returns:
True if it was successful.
- Return type:
bool
- Raises:
AuthFailedError
if it failed though the session state will be set to AUTH_FAILED as well.
- add_auth_async(scheme, credential)[source]¶
Asynchronously send credentials to server. Takes the same arguments as
add_auth()
.
- Return type:
- sync(path)[source]¶
Sync, blocks until response is acknowledged.
Flushes channel between process and leader.
- Parameters:
path – path of node.
- Returns:
The node path that was synced.
- Raises:
ZookeeperError
if the server returns a non-zero error code.New in version 0.5.
- create(path, value=b'', acl=None, ephemeral=False, sequence=False, makepath=False, include_data=False)[source]¶
Create a node with the given value as its data. Optionally set an ACL on the node.
The ephemeral and sequence arguments determine the type of the node.
An ephemeral node will be automatically removed by ZooKeeper when the session associated with the creation of the node expires.
A sequential node will be given the specified path plus a suffix i where i is the current sequential number of the node. The sequence number is always fixed length of 10 digits, 0 padded. Once such a node is created, the sequential number will be incremented by one.
If a node with the same actual path already exists in ZooKeeper, a NodeExistsError will be raised. Note that since a different actual path is used for each invocation of creating sequential nodes with the same path argument, the call will never raise NodeExistsError.
If the parent node does not exist in ZooKeeper, a NoNodeError will be raised. Setting the optional makepath argument to True will create all missing parent nodes instead.
An ephemeral node cannot have children. If the parent node of the given path is ephemeral, a NoChildrenForEphemeralsError will be raised.
This operation, if successful, will trigger all the watches left on the node of the given path by
exists()
andget()
API calls, and the watches left on the parent node byget_children()
API calls.The maximum allowable size of the node value is 1 MB. Values larger than this will cause a ZookeeperError to be raised.
- Parameters:
path – Path of node.
value – Initial bytes value of node.
acl –
ACL
list.ephemeral – Boolean indicating whether node is ephemeral (tied to this session).
sequence – Boolean indicating whether path is suffixed with a unique index.
makepath – Whether the path should be created if it doesn’t exist.
include_data – Include the
ZnodeStat
of the node in addition to its real path. This option changes the return value to be a tuple of (path, stat).- Returns:
Real path of the new node, or tuple if include_data is True
- Return type:
str
- Raises:
NodeExistsError
if the node already exists.
NoNodeError
if parent nodes are missing.
NoChildrenForEphemeralsError
if the parent node is an ephemeral node.
ZookeeperError
if the provided value is too large.
ZookeeperError
if the server returns a non-zero error code.New in version 1.1: The makepath option.
New in version 2.7: The include_data option.
- create_async(path, value=b'', acl=None, ephemeral=False, sequence=False, makepath=False, include_data=False)[source]¶
Asynchronously create a ZNode. Takes the same arguments as
create()
.
- Return type:
New in version 1.1: The makepath option.
New in version 2.7: The include_data option.
- ensure_path(path, acl=None)[source]¶
Recursively create a path if it doesn’t exist.
- Parameters:
path – Path of node.
acl – Permissions for node.
- ensure_path_async(path, acl=None)[source]¶
Recursively create a path asynchronously if it doesn’t exist. Takes the same arguments as
ensure_path()
.
- Return type:
New in version 1.1.
- exists(path, watch=None)[source]¶
Check if a node exists.
If a watch is provided, it will be left on the node with the given path. The watch will be triggered by a successful operation that creates/deletes the node or sets the data on the node.
- Parameters:
path – Path of node.
watch – Optional watch callback to set for future changes to this path.
- Returns:
ZnodeStat of the node if it exists, else None if the node does not exist.
- Return type:
ZnodeStat
or None.- Raises:
ZookeeperError
if the server returns a non-zero error code.
- exists_async(path, watch=None)[source]¶
Asynchronously check if a node exists. Takes the same arguments as
exists()
.
- Return type:
- get(path, watch=None)[source]¶
Get the value of a node.
If a watch is provided, it will be left on the node with the given path. The watch will be triggered by a successful operation that sets data on the node, or deletes the node.
- Parameters:
path – Path of node.
watch – Optional watch callback to set for future changes to this path.
- Returns:
Tuple (value,
ZnodeStat
) of node.- Return type:
tuple
- Raises:
NoNodeError
if the node doesn’t exist
ZookeeperError
if the server returns a non-zero error code
- get_async(path, watch=None)[source]¶
Asynchronously get the value of a node. Takes the same arguments as
get()
.
- Return type:
- get_children(path, watch=None, include_data=False)[source]¶
Get a list of child nodes of a path.
If a watch is provided it will be left on the node with the given path. The watch will be triggered by a successful operation that deletes the node of the given path or creates/deletes a child under the node.
The list of children returned is not sorted and no guarantee is provided as to its natural or lexical order.
- Parameters:
path – Path of node to list.
watch – Optional watch callback to set for future changes to this path.
include_data – Include the
ZnodeStat
of the node in addition to the children. This option changes the return value to be a tuple of (children, stat).- Returns:
List of child node names, or tuple if include_data is True.
- Return type:
list
- Raises:
NoNodeError
if the node doesn’t exist.
ZookeeperError
if the server returns a non-zero error code.New in version 0.5: The include_data option.
- get_children_async(path, watch=None, include_data=False)[source]¶
Asynchronously get a list of child nodes of a path. Takes the same arguments as
get_children()
.
- Return type:
- get_acls(path)[source]¶
Return the ACL and stat of the node of the given path.
- Parameters:
path – Path of the node.
- Returns:
The ACL array of the given node and its
ZnodeStat
.- Return type:
- Raises:
NoNodeError
if the node doesn’t exist.
ZookeeperError
if the server returns a non-zero error codeNew in version 0.5.
- get_acls_async(path)[source]¶
Return the ACL and stat of the node of the given path. Takes the same arguments as
get_acls()
.
- Return type:
- set_acls(path, acls, version=-1)[source]¶
Set the ACL for the node of the given path.
Set the ACL for the node of the given path if such a node exists and the given version matches the version of the node.
- Parameters:
path – Path for the node.
acls – List of
ACL
objects to set.version – The expected node version that must match.
- Returns:
The stat of the node.
- Raises:
BadVersionError
if version doesn’t match.
NoNodeError
if the node doesn’t exist.
InvalidACLError
if the ACL is invalid.
ZookeeperError
if the server returns a non-zero error code.New in version 0.5.
- set_acls_async(path, acls, version=-1)[source]¶
Set the ACL for the node of the given path. Takes the same arguments as
set_acls()
.
- Return type:
- set(path, value, version=-1)[source]¶
Set the value of a node.
If the version of the node being updated is newer than the supplied version (and the supplied version is not -1), a BadVersionError will be raised.
This operation, if successful, will trigger all the watches on the node of the given path left by
get()
API calls.The maximum allowable size of the value is 1 MB. Values larger than this will cause a ZookeeperError to be raised.
- Parameters:
path – Path of node.
value – New data value.
version – Version of node being updated, or -1.
- Returns:
Updated
ZnodeStat
of the node.- Raises:
BadVersionError
if version doesn’t match.
NoNodeError
if the node doesn’t exist.
ZookeeperError
if the provided value is too large.
ZookeeperError
if the server returns a non-zero error code.
- set_async(path, value, version=-1)[source]¶
Set the value of a node. Takes the same arguments as
set()
.
- Return type:
- transaction()[source]¶
Create and return a
TransactionRequest
objectCreates a
TransactionRequest
object. A Transaction can consist of multiple operations which can be committed as a single atomic unit. Either all of the operations will succeed or none of them.
- Returns:
A TransactionRequest.
- Return type:
New in version 0.6: Requires Zookeeper 3.4+
- delete(path, version=-1, recursive=False)[source]¶
Delete a node.
The call will succeed if such a node exists, and the given version matches the node’s version (if the given version is -1, the default, it matches any node’s versions).
This operation, if successful, will trigger all the watches on the node of the given path left by exists API calls, and the watches on the parent node left by get_children API calls.
- Parameters:
path – Path of node to delete.
version – Version of node to delete, or -1 for any.
recursive (bool) – Recursively delete node and all its children, defaults to False.
- Raises:
BadVersionError
if version doesn’t match.
NoNodeError
if the node doesn’t exist.
NotEmptyError
if the node has children.
ZookeeperError
if the server returns a non-zero error code.
- delete_async(path, version=-1)[source]¶
Asynchronously delete a node. Takes the same arguments as
delete()
, with the exception of recursive.
- Return type:
- reconfig(joining, leaving, new_members, from_config=-1)[source]¶
Reconfig a cluster.
This call will succeed if the cluster was reconfigured accordingly.
- Parameters:
joining – a comma separated list of servers being added (see example for format) (incremental reconfiguration)
leaving – a comma separated list of servers being removed (see example for format) (incremental reconfiguration)
new_members – a comma separated list of new membership (non-incremental reconfiguration)
from_config (int) – version of the current configuration (optional - causes reconfiguration to throw an exception if configuration is no longer current)
- Returns:
Tuple (value,
ZnodeStat
) of node.- Return type:
tuple
Basic Example:
zk = KazooClient() zk.start() # first add an observer (incremental reconfiguration) joining = 'server.100=10.0.0.10:2889:3888:observer;0.0.0.0:2181' data, _ = zk.reconfig( joining=joining, leaving=None, new_members=None) # wait and then remove it (just by using its id) (incremental) data, _ = zk.reconfig(joining=None, leaving='100', new_members=None) # now do a full change of the cluster (non-incremental) new = [ 'server.100=10.0.0.10:2889:3888:observer;0.0.0.0:2181', 'server.100=10.0.0.11:2889:3888:observer;0.0.0.0:2181', 'server.100=10.0.0.12:2889:3888:observer;0.0.0.0:2181', ] data, _ = zk.reconfig( joining=None, leaving=None, new_members=','.join(new)) zk.stop()
- Raises:
UnimplementedError
if not supported.
NewConfigNoQuorumError
if no quorum of new config is connected and up-to-date with the leader of last commmitted config - try invoking reconfiguration after new servers are connected and synced.
ReconfigInProcessError
if another reconfiguration is in progress.
BadVersionError
if version doesn’t match.
BadArgumentsError
if any of the given lists of servers has a bad format.
ZookeeperError
if the server returns a non-zero error code.
- reconfig_async(joining, leaving, new_members, from_config)[source]¶
Asynchronously reconfig a cluster. Takes the same arguments as
reconfig()
.
- Return type:
- class kazoo.client.TransactionRequest(client)[source]¶
A Zookeeper Transaction Request
A Transaction provides a builder object that can be used to construct and commit an atomic set of operations. The transaction must be committed before its sent.
Transactions are not thread-safe and should not be accessed from multiple threads at once.
Note
The
committed
attribute only indicates whether this transaction has been sent to Zookeeper and is used to prevent duplicate commits of the same transaction. The result should be checked to determine if the transaction executed as desired.New in version 0.6: Requires Zookeeper 3.4+
- create(path, value=b'', acl=None, ephemeral=False, sequence=False)[source]¶
Add a create ZNode to the transaction. Takes the same arguments as
KazooClient.create()
, with the exception of makepath.
- Returns:
None
- delete(path, version=-1)[source]¶
Add a delete ZNode to the transaction. Takes the same arguments as
KazooClient.delete()
, with the exception of recursive.
- set_data(path, value, version=-1)[source]¶
Add a set ZNode value to the transaction. Takes the same arguments as
KazooClient.set()
.
- check(path, version)[source]¶
Add a Check Version to the transaction.
This command will fail and abort a transaction if the path does not match the specified version.