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 the KazooClient.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 chroot

New 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.

remove_listener(listener)[source]

Remove a listener function

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.

restart()[source]

Stop and restart the Zookeeper session.

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 a socket.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:

IAsyncResult

unchroot(path)[source]

Strip the chroot if applicable from the path.

sync_async(path)[source]

Asynchronous sync.

Return type:

IAsyncResult

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() and get() API calls, and the watches left on the parent node by get_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.

  • aclACL 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:

IAsyncResult

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:

IAsyncResult

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:

IAsyncResult

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:

IAsyncResult

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:

IAsyncResult

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:

tuple of (ACL list, ZnodeStat)

Raises:

NoNodeError if the node doesn’t exist.

ZookeeperError if the server returns a non-zero error code

New 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:

IAsyncResult

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:

IAsyncResult

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:

IAsyncResult

transaction()[source]

Create and return a TransactionRequest object

Creates 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:

TransactionRequest

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:

IAsyncResult

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:

IAsyncResult

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.

commit_async()[source]

Commit the transaction asynchronously.

Return type:

IAsyncResult

commit()[source]

Commit the transaction.

Returns:

A list of the results for each operation in the transaction.