API References¶

ZKClient¶

class aiozk.ZKClient(servers, chroot=None, session_timeout=10, default_acl=None, retry_policy=None, allow_read_only=False, read_timeout=None, loop=None)¶

The class of Zookeeper Client

Parameters

servers (str) – Server list to which ZKClient tries connecting. Specify a comma (,) separated server list. A server is defined as address:port format.
chroot (str) – Root znode path inside Zookeeper data hierarchy.
session_timeout (float) – Zookeeper session timeout.
default_acl (aiozk.ACL) – Default ACL for .create and .ensure_path coroutines. If acl parameter of them is not passed this ACL is used instead. If None is passed for default_acl, then ACL for unrestricted access is applied. This means that scheme is world, id is anyone and all READ/WRITE/CREATE/DELETE/ADMIN permission bits will be set to the new znode.
retry_policy (aiozk.RetryPolicy) – Retry policy. If None, RetryPolicy.forever() is used instead.
allow_read_only (bool) – True if you allow this client to make use of read only Zookeeper session, otherwise False.
read_timeout (float) – Timeout on reading from Zookeeper server in seconds.
loop – event loop. If None, asyncio.get_event_loop() is used.

async start()¶: Start Zookeeper session and await for session connected.

async close()¶: Close Zookeeper session and await for session closed.

async exists(path, watch=False)¶

Check whether the path exists.

Parameters

path (str) – Path of znode
watch (bool) – If True, a watch is set as a side effect

Returns

True if it exists otherwise False

Return type

bool

async create(path, data=None, acl=None, ephemeral=False, sequential=False, container=False)¶

Create a znode at the path.

Parameters

path (str) – Path of znode
data (str, bytes) – Data which will be stored at the znode if the request succeeds
acl (aiozk.ACL) – ACL to be set to the new znode.
ephemeral (bool) – True for creating ephemeral znode otherwise False
sequential (bool) – True for creating seqeuence znode otherwise False
container (bool) – True for creating container znode otherwise False

Returns

Path of the created znode

Return type

str

Raises

aiozk.exc.NodeExists – Can be raised if a znode at the same path already exists.

async ensure_path(path, acl=None)¶

Ensure all znodes exist in the path. Missing Znodes will be created.

Parameters

path (str) – Path of znode
acl (aiozk.ACL) – ACL to be set to the new znodes

async delete(path, force=False)¶

Delete a znode at the path.

Parameters

path (str) – Path of znode
force (bool) – True for ignoring version of the znode. A version of a znode is used as an optimistic lock mechanism. Set false for making use of a version that is tracked by a stat cache of ZKClient.

Raises

aiozk.exc.NoNode – Raised if path does not exist.

async deleteall(path)¶

Delete all znodes in the path recursively.

Parameters: path (str) – Path of znode
Raises: aiozk.exc.NoNode – Raised if path does not exist.

async get(path, watch=False)¶

Get data as bytes and stat of znode.

Parameters

path (str) – Path of znode
watch (bool) – True for setting a watch event as a side effect, otherwise False

Returns

Data and stat of znode

Return type

(bytes, aiozk.protocol.stat.Stat)

Raises

aiozk.exc.NoNode – Can be raised if path does not exist

async get_data(path, watch=False)¶

Get data as bytes.

Parameters

path (str) – Path of znode
watch (bool) – True for setting a watch event as a side effect, otherwise False

Returns

Data

Return type

bytes

Raises

aiozk.exc.NoNode – Can be raised if path does not exist

async set(path, data, version)¶

Set data to znode. Prefer using .set_data than this method unless you have to control the concurrency.

Parameters

path (str) – Path of znode
data (str or bytes) – Data to store at znode
version (int) – Version of znode data to be modified.

Returns

Response stat

Return type

aiozk.protocol.stat.Stat

Raises

aiozk.exc.NoNode – Raised if znode does not exist
aiozk.exc.BadVersion – Raised if version does not match the actual version of the data. The update failed.

async set_data(path, data, force=False)¶

Set data to znode without needing to handle version.

Parameters

path (str) – Path of znode
data (bytes or str) – Data to be stored at znode
force (bool) – True for ignoring data version. False for using version from stat cache.

Raises

aiozk.exc.NoNode – Raised if znode does not exist
aiozk.exc.BadVersion – Raised if force parameter is False and only if supplied version from stat cache does not match the actual version of znode data.

async get_children(path, watch=False)¶

Get all children names. Returned names are only basename and they does not include dirname.

Parameters

path (str) – Path of znode
watch (bool) – True for setting a watch event as a side effect otherwise False

Returns

Names of children znodes

Return type

[str]

Raises

aiozk.exc.NoNode – Raised if znode does not exist

async get_acl(path)¶

Get list of ACLs associated with the znode

Parameters: path (str) – Path of znode
Returns: List of ACLs associated with the znode
Return type: [aiozk.ACL]

async set_acl(path, acl, force=False)¶

Set ACL to the znode.

Parameters

path (str) – Path of znode
acl (aiozk.ACL) – ACL for the znode
force (bool) – True for ignoring ACL version of the znode when setting ACL to the actual znode. False for using ACL version from the stat cache.

Raises

aiozk.exc.NoNode – Raised if znode does not exist
aiozk.exc.BadVersion – Raised if force parameter is False and only if the supplied version from stat cache does not match the actual ACL version of the znode.

begin_transaction()¶

Return Transaction instance which provides methods for read/write operations and commit method. This instance is used for transaction request.

Returns: Transaction instance which can be used for adding read/write operations
Return type: aiozk.transaction.Transaction

Transaction¶

class aiozk.transaction.Transaction(client)¶

Transaction request builder

Parameters: client (aiozk.ZKClient) – Client instance

check_version(path, version)¶

Check znode version

Parameters

path (str) – Znode path
version (int) – Znode version

Returns

None

coroutine commit()¶

Send all calls in transaction request and return results

Returns: Transaction results
Return type: aiozk.transaction.Result
Raises: ValueError – On no operations to commit

create(path, data=None, acl=None, ephemeral=False, sequential=False, container=False)¶

Create new znode

Parameters

path (str) – Znode path
data (str or bytes) – Data to store in node
acl ([aiozk.ACL]) – List of ACLs
ephemeral (bool) – Ephemeral node type
sequential (bool) – Sequential node type
container (bool) – Container node type

Returns

None

Raises

ValueError – when containers feature is not supported by Zookeeper server (< 3.5.1)

delete(path, version=- 1)¶

Delete znode

Parameters

path (str) – Znode path
version (int) – Current version of node

Returns

None

set_data(path, data, version=- 1)¶

Set data to znode

Parameters

path (str) – Znode path
data (str or bytes) – Data to store in node
version (int) – Current version of node

Returns

None

class aiozk.transaction.Result¶

Transaction result aggregator

Contains attributes:

checked Set with results of check_version() methods
created Set with results of create() methods
updated Set with results of set_data() methods
deleted Set with results of delete() methods

ACL¶

class aiozk.ACL(**kwargs)¶

ACL object. Used to control access to its znodes.

Do not create this object directly, use aiozk,ACL.make() instead.

classmethod make(scheme, id, read=False, write=False, create=False, delete=False, admin=False)¶

Create ACL

Parameters

scheme (str) –
ACL scheme, one of following:
- world has a single id, anyone, that represents anyone.
- auth doesn’t use any id, represents any authenticated user.
- digest uses a username:password string to generate MD5 hash which is then used as an ACL ID identity.
- host uses the client host name as an ACL ID identity.
- ip uses the client host IP or CIDR as an ACL ID identity.
id (str) – ACL ID identity.
read (bool) – Permission, can get data from a node and list its children
write (bool) – Permission, can set data for a node
create (bool) – Permission, can create a child node
delete (bool) – Permission, can delete a child node
admin (bool) – Permission, can set permissions

Returns

ACL instance

Return type

aiozk.ACL

Stat¶

class aiozk.protocol.stat.Stat(**kwargs)¶

Znode stat structure

Contains attributes:

created_zxid The zxid of the change that created this znode.
last_modified_zxid The zxid of the change that last modified this znode.
created The time in milliseconds from epoch when this znode was created.
modified The time in milliseconds from epoch when this znode was last modified.
version The number of changes to the data of this znode.
child_version The number of changes to the children of this znode.
acl_version The number of changes to the ACL of this znode.
ephemeral_owner The session id of the owner of this znode if the znode is an ephemeral node. If it is not an ephemeral node, it will be zero.
data_length The length of the data field of this znode.
num_children The number of children of this znode.
last_modified_children The zxid of the change that last modified this znode children.

RetryPolicy¶

class aiozk.RetryPolicy(try_limit, sleep_func)¶

The class of Retry policy enforcer for Zookeper calls.

Class methods of this class implement several different retry policies.

Custom implementation can be provided using constructor directly with following parameters:

Parameters

try_limit (int) – Retry attempts limit
sleep_func (func) – function that calculates sleep time. Accepts one parameter, list of timestamps of each attempt

classmethod once()¶

One retry policy

Returns: Rolicy with one retry
Return type: aiozk.RetryPolicy

classmethod n_times(n)¶

n times retry policy, no delay between retries

Parameters: n – retries limit
Returns: Policy with n retries
Return type: aiozk.RetryPolicy

classmethod forever()¶

Forever retry policy, no delay between retries

Returns: Retry forever policy
Return type: aiozk.RetryPolicy

classmethod exponential_backoff(base=2, maximum=None)¶

Exponential backoff retry policy.

Parameters

base – base of exponentiation
maximum – optional timeout in seconds

Returns

Exponential backoff policy

Return type

aiozk.RetryPolicy

classmethod until_elapsed(timeout)¶

Retry until timeout elapsed policy

Parameters: timeout – retry time delay
Returns: Retry until elapsed policy.
Return type: aiozk.RetryPolicy

Exceptions¶

exception aiozk.exc.APIError¶

exception aiozk.exc.AuthFailed¶

exception aiozk.exc.BadArguments¶

exception aiozk.exc.BadVersion¶

exception aiozk.exc.ConnectError(host, port, server_id=None)¶

exception aiozk.exc.ConnectionLoss¶

exception aiozk.exc.DataInconsistency¶

exception aiozk.exc.EphemeralOnLocalSession¶

exception aiozk.exc.FailedRetry¶

exception aiozk.exc.InvalidACL¶

exception aiozk.exc.InvalidCallback¶

exception aiozk.exc.InvalidClientState¶

exception aiozk.exc.InvalidStateTransition¶

exception aiozk.exc.MarshallingError¶

exception aiozk.exc.NewConfigNoQuorum¶

exception aiozk.exc.NoAuth¶

exception aiozk.exc.NoChildrenForEphemerals¶

exception aiozk.exc.NoNode¶

exception aiozk.exc.NoServersError¶

exception aiozk.exc.NoWatcher¶

exception aiozk.exc.NodeExists¶

exception aiozk.exc.NotEmpty¶

exception aiozk.exc.NotReadOnly¶

exception aiozk.exc.OperationTimeout¶

exception aiozk.exc.ReconfigInProcess¶

exception aiozk.exc.ResponseError¶

exception aiozk.exc.RolledBack¶

exception aiozk.exc.RuntimeInconsistency¶

exception aiozk.exc.SessionExpired¶

exception aiozk.exc.SessionLost¶

exception aiozk.exc.SessionMoved¶

exception aiozk.exc.TimeoutError¶

exception aiozk.exc.TransactionFailed¶

exception aiozk.exc.UnfinishedRead¶

exception aiozk.exc.Unimplemented¶

exception aiozk.exc.UnknownError(error_code)¶

exception aiozk.exc.UnknownSession¶

exception aiozk.exc.ZKError¶

exception aiozk.exc.ZKSystemError¶