Reference guide
- class aetcd.client.Alarm(alarm_type, member_id)[source]
A cluster member alarm.
- Parameters:
alarm_type – Type of the alarm.
member_id – Cluster member ID.
- class aetcd.client.Client(host: str = 'localhost', port: int = 2379, username: str | None = None, password: str | None = None, timeout: int | None = None, options: Dict[str, Any] | None = None, connect_wait_timeout: int = 3)[source]
Client provides and manages a client session.
The client can be used as an async context manager.
- Parameters:
host (str) – etcd host address, as IP address or a domain name.
port (int) – etcd port number to connect to.
username (str) – The name of the user used for authentication.
password (str) – Password to be used for authentication.
timeout (int) – Connection timeout in seconds.
options (dict) – Options provided to the underlying gRPC channel.
connect_wait_timeout (int) – Connecting wait timeout, since connection could be initiated from multiple coroutines.
- Returns:
A
Client
instance.
- async close() None [source]
Close established connection and frees allocated resources.
It could be called while other operation is being executed.
- async get(key: bytes, serializable: bool = False) Get | None [source]
Get a single key from the key-value store.
- Parameters:
key (bytes) – Key in etcd to get.
serializable (bool) – Whether to allow serializable reads. This can result in stale reads.
- Returns:
A instance of
Get
orNone
, if the the key was not found.
Usage example:
import aetcd client = aetcd.Client() await client.get(b'key')
- async get_prefix(key_prefix: bytes, sort_order: str | None = None, sort_target: str = 'key', keys_only: bool = False) GetRange [source]
Get a range of keys with a prefix from the key-value store.
- Parameters:
key_prefix (bytes) – Key prefix to get.
- Returns:
An instance of
GetRange
.
- async get_range(range_start: bytes, range_end: bytes, sort_order: str | None = None, sort_target: str = 'key') GetRange [source]
Get a range of keys from the key-value store.
- Parameters:
range_start (bytes) – First key in range.
range_end (bytes) – Last key in range.
- Returns:
An instance of
GetRange
.
- async get_all(sort_order=None, sort_target='key', keys_only=False) GetRange [source]
Get all keys from the key-value store.
- Returns:
An instance of
GetRange
.
- async put(key: bytes, value: bytes, lease: int | Lease | None = None, prev_kv: bool = False) Put [source]
Put the given key into the key-value store.
- Parameters:
key (bytes) – Key in etcd to set.
value (bytes) – Value to set key to.
lease (either
Lease
, orint
(ID of a lease), orNone
) – Lease to associate with this key.prev_kv (bool) – Whether to return the previous key-value pair.
- Returns:
A instance of
Put
.
Usage example:
import aetcd client = aetcd.Client() await client.put(b'key', b'value')
- async delete(key: bytes, prev_kv: bool = False) Delete | None [source]
Delete a single key from the key-value store.
- Parameters:
key (bytes) – Key in etcd to delete.
prev_kv (bool) – Whether to return the deleted key-value pair.
- Returns:
A instance of
Delete
orNone
, if the the key was not found.
Usage example:
import aetcd client = aetcd.Client() await client.put(b'key', b'value') await client.delete(b'key')
- async delete_prefix(key_prefix: bytes, prev_kv: bool = False) DeleteRange [source]
Delete a range of keys with a prefix from the key-value store.
- Parameters:
key_prefix (bytes) – Key prefix to delete.
prev_kv (bool) – Whether to return deleted key-value pairs.
- Returns:
An instance of
DeleteRange
.
- async delete_range(range_start: bytes, range_end: bytes, prev_kv: bool = False) DeleteRange [source]
Delete a range of keys from the key-value store.
- Parameters:
range_start (bytes) – First key in range.
range_end (bytes) – Last key in range.
prev_kv (bool) – Whether to return deleted key-value pairs.
- Returns:
An instance of
DeleteRange
.
- async replace(key: bytes, initial_value: bytes, new_value: bytes, lease: int | Lease | None = None)[source]
Atomically replace the value of a key with a new value.
This compares the current value of a key, then replaces it with a new value if it is equal to a specified value. This operation takes place in a transaction.
- Parameters:
key – Key in etcd to replace.
initial_value (bytes) – Old value to replace.
new_value (bytes) – New value of the key
lease (either
Lease
, orint
(ID of a lease), orNone
) – Lease to associate with this key.
- Returns:
A status of transaction,
True
if the replace was successful,False
otherwise.
- async watch(key: bytes, range_end: bytes | None = None, start_revision: int | None = None, progress_notify: bool = False, kind: EventKind | None = None, prev_kv: bool = False, watch_id: int | None = None, fragment: bool = False)[source]
Watch a key.
- Parameters:
key (bytes) – Key to watch.
range_end (bytes) – End of the range
[key, range_end)
to watch. Ifrange_end
is not given, only thekey
argument is watched. Ifrange_end
is equal tox00
, all keys greater than or equal to thekey
argument are watched. If therange_end
is one bit larger than the givenkey
, then all keys with the prefix (the givenkey
) will be watched.start_revision (int) – Revision to watch from (inclusive).
progress_notify (bool) – If set, the server will periodically send a response with no events to the new watcher if there are no recent events.
kind (aetcd.rtypes.EventKind) – Filter the events by
EventKind
, at server side before it sends back to the watcher.prev_kv (bool) – If set, created watcher gets the previous key-value before the event happend. If the previous key-value is already compacted, nothing will be returned.
watch_id (int) – If provided and non-zero, it will be assigned as ID to this watcher.
fragment (bool) – Enable splitting large revisions into multiple watch responses.
- Returns:
A instance of
Watch
.
Usage example:
async for event in await client.watch(b'key'): print(event)
- async watch_prefix(key_prefix: bytes, range_end: bytes | None = None, start_revision: int | None = None, progress_notify: bool = False, kind: EventKind | None = None, prev_kv: bool = False, watch_id: int | None = None, fragment: bool = False)[source]
Watch a range of keys with a prefix.
- Parameters:
key_prefix (bytes) – Key prefix to watch.
range_end (bytes) – End of the range
[key, range_end)
to watch. Ifrange_end
is not given, only thekey
argument is watched. Ifrange_end
is equal tox00
, all keys greater than or equal to thekey
argument are watched. If therange_end
is one bit larger than the givenkey
, then all keys with the prefix (the givenkey
) will be watched.start_revision (int) – Revision to watch from (inclusive).
progress_notify (bool) – If set, the server will periodically send a response with no events to the new watcher if there are no recent events.
kind (aetcd.rtypes.EventKind) – Filter the events by
EventKind
, at server side before it sends back to the watcher.prev_kv (bool) – If set, created watcher gets the previous key-value before the event happend. If the previous key-value is already compacted, nothing will be returned.
watch_id (int) – If provided and non-zero, it will be assigned as ID to this watcher.
fragment (bool) – Enable splitting large revisions into multiple watch responses.
- Returns:
A instance of
Watch
.
- async watch_once(key: bytes, timeout: int | None = None, range_end: bytes | None = None, start_revision: int | None = None, progress_notify: bool = False, kind: EventKind | None = None, prev_kv: bool = False, watch_id: int | None = None, fragment: bool = False)[source]
Watch a key and stops after the first event.
If the timeout was specified and event didn’t arrived method will raise
WatchTimeoutError
exception.- Parameters:
key (bytes) – Key to watch.
range_end (bytes) – End of the range
[key, range_end)
to watch. Ifrange_end
is not given, only thekey
argument is watched. Ifrange_end
is equal tox00
, all keys greater than or equal to thekey
argument are watched. If therange_end
is one bit larger than the givenkey
, then all keys with the prefix (the givenkey
) will be watched.start_revision (int) – Revision to watch from (inclusive).
progress_notify (bool) – If set, the server will periodically send a response with no events to the new watcher if there are no recent events.
kind (aetcd.rtypes.EventKind) – Filter the events by
EventKind
, at server side before it sends back to the watcher.prev_kv (bool) – If set, created watcher gets the previous key-value before the event happend. If the previous key-value is already compacted, nothing will be returned.
watch_id (int) – If provided and non-zero, it will be assigned as ID to this watcher.
fragment (bool) – Enable splitting large revisions into multiple watch responses.
- Returns:
An instance of
Event
.
- async watch_prefix_once(key_prefix: bytes, timeout: int | None = None, range_end: bytes | None = None, start_revision: int | None = None, progress_notify: bool = False, kind: EventKind | None = None, prev_kv: bool = False, watch_id: int | None = None, fragment: bool = False)[source]
Watch a range of keys with a prefix and stops after the first event.
If the timeout was specified and event didn’t arrived method will raise
WatchTimeoutError
exception.- Parameters:
key_prefix (bytes) – Key prefix to watch.
range_end (bytes) – End of the range
[key, range_end)
to watch. Ifrange_end
is not given, only thekey
argument is watched. Ifrange_end
is equal tox00
, all keys greater than or equal to thekey
argument are watched. If therange_end
is one bit larger than the givenkey
, then all keys with the prefix (the givenkey
) will be watched.start_revision (int) – Revision to watch from (inclusive).
progress_notify (bool) – If set, the server will periodically send a response with no events to the new watcher if there are no recent events.
kind (aetcd.rtypes.EventKind) – Filter the events by
EventKind
, at server side before it sends back to the watcher.prev_kv (bool) – If set, created watcher gets the previous key-value before the event happend. If the previous key-value is already compacted, nothing will be returned.
watch_id (int) – If provided and non-zero, it will be assigned as ID to this watcher.
fragment (bool) – Enable splitting large revisions into multiple watch responses.
- Returns:
An instance of
Event
.
- async transaction(compare, success=None, failure=None)[source]
Perform a transaction.
- Parameters:
compare – A list of comparisons to make
success – A list of operations to perform if all the comparisons are true.
failure – A list of operations to perform if any of the comparisons are false.
- Returns:
A tuple of (operation status, responses).
Usage example:
await client.transaction( compare=[ client.transactions.value(b'key') == b'value', client.transactions.version(b'key') > 0, ], success=[ client.transactions.put(b'key', b'success'), ], failure=[ client.transactions.put(b'key', b'failure'), ] )
- async lease(ttl, lease_id=None)[source]
Create a new lease.
All keys attached to this lease will be expired and deleted if the lease expires. A lease can be sent keep alive messages to refresh the ttl.
- Parameters:
ttl (int) – Requested time to live.
lease_id – Requested ID for the lease.
- Returns:
A new lease, an instance of
Lease
.
- async revoke_lease(lease_id)[source]
Revoke a lease.
- Parameters:
lease_id – ID of the lease to revoke.
- lock(key: bytes, ttl: int = 60)[source]
Create a new lock.
- Parameters:
key (bytes) – The key under which the lock will be stored.
ttl (int) – Length of time for the lock to live for in seconds. The lock will be released after this time elapses, unless refreshed.
- Returns:
A new lock, an instance of
Lock
.
- async add_member(urls)[source]
Add a member into the cluster.
- Returns:
A new member, an instance of
Member
.
- async remove_member(member_id)[source]
Remove an existing member from the cluster.
- Parameters:
member_id – ID of the member to remove.
- async update_member(member_id, peer_urls)[source]
Update the configuration of an existing member in the cluster.
- Parameters:
member_id – ID of the member to update.
peer_urls – New list of peer URLs the member will use to communicate with the cluster.
- async members()[source]
List of all members associated with the cluster.
- Returns:
A sequence of
Member
.
- async compact(revision, physical=False)[source]
Compact the event history in etcd up to a given revision.
All superseded keys with a revision less than the compaction revision will be removed.
- Parameters:
revision – Revision for the compaction operation.
physical – If set to
True
, the request will wait until the compaction is physically applied to the local database such that compacted entries are totally removed from the backend database.
- async create_alarm(member_id=0)[source]
Create an alarm.
If no member id is given, the alarm is activated for all the members of the cluster. Only the no space alarm can be raised.
- Parameters:
member_id – The cluster member ID to create an alarm to. If 0, the alarm is created for all the members of the cluster.
- Returns:
A sequence of
Alarm
.
- async list_alarms(member_id=0, alarm_type='none')[source]
List the activated alarms.
- Parameters:
member_id – The cluster member ID.
alarm_type – The cluster member ID to create an alarm to. If 0, the alarm is created for all the members of the cluster.
- Returns:
A sequence of
Alarm
.
- exception aetcd.exceptions.ConnectionTimeoutError[source]
Raises on etcd server connection timeout errors.
- exception aetcd.exceptions.InvalidArgumentError[source]
Raises on errors associated with incorrect arguments being provided.
- exception aetcd.exceptions.PreconditionFailedError[source]
Raises on etcd server precondition errors.
- exception aetcd.exceptions.DuplicateLeaseError[source]
Raises on attempt to create a lease with already existing ID.
- exception aetcd.exceptions.RevisionCompactedError(compacted_revision)[source]
Raises when requested and previous revisions were already compacted.
- compacted_revision
Revision bellow values were compacted.
- exception aetcd.exceptions.WatchTimeoutError[source]
Raises on watch operation timeouts.
Please note, this error is different from
ConnectionTimeoutError
and may be raised only in two cases: when watch create operation was not completed in time and when watch event was not emitted within provided timeout.
- class aetcd.leases.Lease(lease_id, ttl, etcd_client)[source]
A lease.
- Parameters:
id – ID of the lease
ttl – time to live for this lease
etcd_client – Instance of
aetcd.client.Client
- class aetcd.locks.Lock(client, key: bytes, ttl: int)[source]
A distributed lock.
This can be used as a context manager, with the lock being acquired and released as you would expect:
client = aetcd.Client() # Create a lock that expires after 20 seconds with client.lock(b'key', ttl=20) as lock: # do something that requires the lock print(lock.is_acquired()) # refresh the timeout on the lease lock.refresh()
- Parameters:
client (aetcd.client.Client) – An instance of
Client
key (bytes) – The key under which the lock will be stored.
ttl (int) – Length of time for the lock to live for in seconds. The lock will be released after this time elapses, unless refreshed.
- class aetcd.members.Member(id, name, peer_urls, client_urls, etcd_client)[source]
A member of the etcd cluster.
- Parameters:
id – ID of the cluster member
name – Human-readable name of the cluster member
peer_urls – List of URLs the cluster member exposes to the cluster for communication
client_urls – List of URLs the cluster member exposes to clients for communication
etcd_client – Instance of
aetcd.client.Client
- async update(peer_urls)[source]
Update the configuration of this cluster member.
- Parameters:
peer_urls – New list of peer URLs the cluster member will use to communicate with the cluster
- async active_alarms()[source]
Get active alarms of the cluster member.
- Returns:
List of
aetcd.client.Alarm
- class aetcd.rtypes.ResponseHeader(header)[source]
Represents the metadata for the response.
- cluster_id: int
The ID of the cluster which sent the response.
- member_id: int
The ID of the member which sent the response.
- revision: int
The key-value store revision when the request was applied. For watch progress responses, the revision indicates progress. All future events recieved in this stream are guaranteed to have a higher revision number than the revision number.
- raft_term: int
The raft term when the request was applied.
- class aetcd.rtypes.KeyValue(keyvalue)[source]
Represents the requested key-value.
- key: bytes
Key in bytes, empty key is not allowed.
- value: bytes
Value held by the key, in bytes.
- create_revision: int
Revision of last creation on this key.
- mod_revision: int
Revision of last modificatioin on this key.
- version: int
Version of the key, a deletion resets the version to zero and any modification of the key increases its version.
- lease: int
ID of the lease that attached to the key, when the attached lease expires, the key will be deleted, if the lease is zero, then no lease is attached to the key.
- class aetcd.rtypes.Get(header, keyvalue)[source]
Represents the result of get operation.
- header: ResponseHeader
Response header.
- key: bytes
Key in bytes, empty key is not allowed.
- value: bytes
Value held by the key, in bytes.
- create_revision: int
Revision of last creation on this key.
- mod_revision: int
Revision of last modificatioin on this key.
- version: int
Version of the key, a deletion resets the version to zero and any modification of the key increases its version.
- lease: int
ID of the lease that attached to the key, when the attached lease expires, the key will be deleted, if the lease is zero, then no lease is attached to the key.
- class aetcd.rtypes.GetRange(header, kvs, more, count)[source]
Represents the result of get range operation.
Implements
__bool__
,__len__
,__iter__
and__getitem__
.If a number of
count
keys is above zero iterpret the result as truthy, otherwise as falsy.It is possible to iterate over the collection or use indexing, as a result
KeyValue
will be returned.Note
Also, it is possible to access raw
kvs
provided by the underlyingRPC
call, that is the most effective way to access the keys from performance and memory perspective, but keep in mind that the overall performance highly depends on usage pattern and the size of dataset, use wisely. Generally, it is recommended to useKeyValue
wrapped results.- header: ResponseHeader
Response header.
- kvs
The list of key-value pairs matched by the range request, empty when
count_only
flag was set in the request.
- more: bool
Indicates if there are more keys to return in the requested range.
- count: int
The number of keys within the requested range.
- class aetcd.rtypes.Put(header, prev_kv=None)[source]
Represents the result of put operation.
- header: ResponseHeader
Response header.
- class aetcd.rtypes.Delete(header, deleted, prev_kv=None)[source]
Represents the result of delete operation.
- header: ResponseHeader
Response header.
- deleted: int
The number of keys deleted by the delete request.
- class aetcd.rtypes.DeleteRange(header, deleted, prev_kvs)[source]
Represents the result of delete range operation.
Implements
__bool__
,__len__
,__iter__
and__getitem__
.If a number of
deleted
keys is above zero iterpret the result as truthy, otherwise as falsy.It is possible to iterate over the collection or use indexing, as a result
KeyValue
will be returned.Note
Also, it is possible to access raw
prev_kvs
provided by the underlyingRPC
call, that is the most effective way to access the keys from performance and memory perspective, but keep in mind that the overall performance highly depends on usage pattern and the size of dataset, use wisely. Generally, it is recommended to useKeyValue
wrapped results.- header: ResponseHeader
Response header.
- deleted: int
The number of keys deleted by the delete request.
- prev_kvs
The list of deleted key-value pairs matched by the delete range request, filled when
prev_kv
flag was set in the request, otherwise empty.
- class aetcd.rtypes.EventKind(value)[source]
An enumeration.
- PUT = 'PUT'
Designates a
PUT
event.
- DELETE = 'DELETE'
Designates a
DELETE
event.
- class aetcd.rtypes.Event(kind, kv, prev_kv=None)[source]
Reperesents a watch event.
- kind: EventKind
The kind of event. If the type is a
PUT
, it indicates new data has been stored to the key. If the type is aDELETE
, it indicates the key was deleted.
- class aetcd.rtypes.Watch(iterator, cancel_func, watch_id)[source]
Reperesents the result of a watch operation.
To get emitted events use as an asynchronous iterator, emitted events are instances of an
Event
.Usage example:
async for event in client.watch(b'key'): print(event)
- watch_id: int
The ID of the watcher that emits the events.
- aetcd.utils.prefix_range_end(prefix: bytes) bytes [source]
Create a bytestring that can be used as a
range_end
for a prefix.
- aetcd.utils.to_bytes(maybe_bytes: bytes | str) bytes [source]
Encode string to bytes.
Convenience function to do a simple
encode('utf-8')
if the input is not already bytes, return the data unmodified if the input is bytes.
- aetcd.utils.lease_to_id(lease: Lease | int) int [source]
Resolve lease ID based on the provided argument.
If provided argument is a
Lease
object, just return its ID, otherwise cast provided argument toint
and return the result or0
if the cast failed.
- class aetcd.watcher.WatcherCallback(callback: Callable)[source]
Represents the result of a callback watch operation.
- callback: Callable
A callback function that will be called when new events are emitted.
- watch_id: int | None
ID of the watcher.
- prev_kv: bool
Get the previous key-value before the event happend.
- error: Exception | None
Error that was raised by the underlying machinery, if any.
- class aetcd.watcher.Watcher(watchstub, timeout=None, metadata=None)[source]
Watch for events happening or that have happened.
One watcher can watch on multiple key ranges, streaming events for several watches at once. The entire event history can be watched starting from the last compaction revision.
Note
The implementation is mostly for internal use, it is advised to use appropriate client watch methods.
- async add_callback(key: bytes, callback: Callable, range_end: bytes | None = None, start_revision: int | None = None, progress_notify: bool = False, kind: EventKind | None = None, prev_kv: bool = False, watch_id: int | None = None, fragment: bool = False) WatcherCallback [source]
Add a callback that will be called when new events are emitted.
- Parameters:
key (bytes) – Key to watch.
callback (callable) – Callback function.
range_end (bytes) – End of the range
[key, range_end)
to watch. Ifrange_end
is not given, only thekey
argument is watched. Ifrange_end
is equal tox00
, all keys greater than or equal to thekey
argument are watched. If therange_end
is one bit larger than the givenkey
, then all keys with the prefix (the givenkey
) will be watched.start_revision (int) – Revision to watch from (inclusive).
progress_notify (bool) – If set, the server will periodically send a response with no events to the new watcher if there are no recent events. It is useful when clients wish to recover a disconnected watcher starting from a recent known revision. The server may decide how often it will send notifications based on the current load.
kind (aetcd.rtypes.EventKind) – Filter the events by
EventKind
, at server side before it sends back to the watcher.prev_kv (bool) – If set, created watcher gets the previous key-value before the event happend. If the previous key-value is already compacted, nothing will be returned.
watch_id (int) – If provided and non-zero, it will be assigned as ID to this watcher. Since creating a watcher in
etcd
is not a synchronous operation, this can be used ensure that ordering is correct when creating multiple watchers on the same stream. Creating a watcher with an ID already in use on the stream will cause an error to be returned.fragment (bool) – Enable splitting large revisions into multiple watch responses.
- Returns:
A instance of
WatcherCallback
.