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 asaddress
: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 isanyone
and allREAD
/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
- 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
-
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
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
- 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()
methodscreated Set with results of
create()
methodsupdated Set with results of
set_data()
methodsdeleted 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
-
classmethod
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
-
classmethod
n_times
(n)¶ n times retry policy, no delay between retries
- Parameters
n – retries limit
- Returns
Policy with n retries
- Return type
-
classmethod
forever
()¶ Forever retry policy, no delay between retries
- Returns
Retry forever policy
- Return type
-
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
-
classmethod
until_elapsed
(timeout)¶ Retry until timeout elapsed policy
- Parameters
timeout – retry time delay
- Returns
Retry until elapsed policy.
- Return type
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
¶