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: Optional[str] = None, password: Optional[str] = None, timeout: Optional[int] = None, options: Optional[Dict[str, Any]] = None)[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.

Returns

A Client instance.

async connect() None[source]

Establish a connection to an etcd.

async close() None[source]

Close established connection and frees allocated resources.

async get(key: bytes, serializable: bool = False) Optional[aetcd.rtypes.Get][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 or None, 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: Optional[str] = None, sort_target: str = 'key', keys_only: bool = False) aetcd.rtypes.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: Optional[str] = None, sort_target: str = 'key') aetcd.rtypes.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) aetcd.rtypes.GetRange[source]

Get all keys from the key-value store.

Returns

An instance of GetRange.

async put(key: bytes, value: bytes, lease: Optional[Union[int, aetcd.leases.Lease]] = None, prev_kv: bool = False) aetcd.rtypes.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, or int (ID of a lease), or None) – 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) Optional[aetcd.rtypes.Delete][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 or None, 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) aetcd.rtypes.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) aetcd.rtypes.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, initial_value, new_value)[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

Returns

A status of transaction, True if the replace was successful, False otherwise.

async watch(key: bytes, range_end: Optional[bytes] = None, start_revision: Optional[int] = None, progress_notify: bool = False, kind: Optional[aetcd.rtypes.EventKind] = None, prev_kv: bool = False, watch_id: Optional[int] = 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. If range_end is not given, only the key argument is watched. If range_end is equal to x00, all keys greater than or equal to the key argument are watched. If the range_end is one bit larger than the given key, then all keys with the prefix (the given key) 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: Optional[bytes] = None, start_revision: Optional[int] = None, progress_notify: bool = False, kind: Optional[aetcd.rtypes.EventKind] = None, prev_kv: bool = False, watch_id: Optional[int] = 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. If range_end is not given, only the key argument is watched. If range_end is equal to x00, all keys greater than or equal to the key argument are watched. If the range_end is one bit larger than the given key, then all keys with the prefix (the given key) 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: Optional[int] = None, range_end: Optional[bytes] = None, start_revision: Optional[int] = None, progress_notify: bool = False, kind: Optional[aetcd.rtypes.EventKind] = None, prev_kv: bool = False, watch_id: Optional[int] = 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. If range_end is not given, only the key argument is watched. If range_end is equal to x00, all keys greater than or equal to the key argument are watched. If the range_end is one bit larger than the given key, then all keys with the prefix (the given key) 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: Optional[int] = None, range_end: Optional[bytes] = None, start_revision: Optional[int] = None, progress_notify: bool = False, kind: Optional[aetcd.rtypes.EventKind] = None, prev_kv: bool = False, watch_id: Optional[int] = 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. If range_end is not given, only the key argument is watched. If range_end is equal to x00, all keys greater than or equal to the key argument are watched. If the range_end is one bit larger than the given key, then all keys with the prefix (the given key) 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 status()[source]

Get the status of the responding member.

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 defragment()[source]

Defragment a member’s backend database to recover storage space.

async hash()[source]

Return the hash of the local KV state.

Returns

KV state hash.

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.

async disarm_alarm(member_id=0)[source]

Cancel an alarm.

Parameters

member_id – The cluster member id to cancel an alarm. If 0, the alarm is canceled for all the members of the cluster.

Returns

A sequence of Alarm.

async snapshot(file_obj)[source]

Take a snapshot of the database.

Parameters

file_obj – A file-like object to write the database contents in.

exception aetcd.exceptions.ClientError[source]

The most generic client error.

exception aetcd.exceptions.ConnectionFailedError[source]

Raises on etcd server connection errors.

exception aetcd.exceptions.ConnectionTimeoutError[source]

Raises on etcd server connection timeout errors.

exception aetcd.exceptions.InternalError[source]

Raises on etcd internal 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.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

async revoke()[source]

Revoke this lease.

async refresh()[source]

Refresh the time to live for this lease.

async remaining_ttl()[source]

Return remaining time to live for this lease.

async granted_ttl()[source]

Return granted time to live for this lease.

async keys()[source]

Return list of keys associated with this lease.

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.

async acquire(timeout: int = 10)[source]

Acquire the lock.

Parameters

timeout (int) – Maximum time to wait before returning. None means forever, any other value equal or greater than 0 is the number of seconds.

Returns

True if the lock has been acquired, False otherwise.

async release()[source]

Release the lock.

async refresh()[source]

Refresh the time to live on this lock.

async is_acquired()[source]

Check if this lock is currently acquired.

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 remove()[source]

Remove this cluster member from the cluster.

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: aetcd.rtypes.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 underlying RPC 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 use KeyValue wrapped results.

header: aetcd.rtypes.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: aetcd.rtypes.ResponseHeader

Response header.

prev_kv: Optional[aetcd.rtypes.KeyValue]

If prev_kv flag was set in the request, the previous key-value pair will be stored in this attribute.

class aetcd.rtypes.Delete(header, deleted, prev_kv=None)[source]

Represents the result of delete operation.

header: aetcd.rtypes.ResponseHeader

Response header.

deleted: int

The number of keys deleted by the delete request.

prev_kv: Optional[aetcd.rtypes.KeyValue]

If prev_kv flag was set in the request, the previous key-value pair will be stored in this attribute.

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 underlying RPC 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 use KeyValue wrapped results.

header: aetcd.rtypes.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: aetcd.rtypes.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 a DELETE, it indicates the key was deleted.

kv: aetcd.rtypes.KeyValue

Holds the key-value for the event. A PUT event contains current key-value pair. A PUT event with version that equals to 1 indicates the creation of a key. A DELETE event contains the deleted key with its modification revision set to the revision of deletion.

prev_kv: Optional[aetcd.rtypes.KeyValue]

Holds the key-value pair before the event happend.

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.

async cancel()[source]

Cancel the watcher so that no more events are emitted.

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: Union[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: Union[aetcd.leases.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 to int and return the result or 0 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: Optional[int]

ID of the watcher.

prev_kv: bool

Get the previous key-value before the event happend.

error: Optional[Exception]

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 setup()[source]

Set up the watcher.

async shutdown()[source]

Shutdown the watcher.

async add_callback(key: bytes, callback: Callable, range_end: Optional[bytes] = None, start_revision: Optional[int] = None, progress_notify: bool = False, kind: Optional[aetcd.rtypes.EventKind] = None, prev_kv: bool = False, watch_id: Optional[int] = None, fragment: bool = False) aetcd.watcher.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. If range_end is not given, only the key argument is watched. If range_end is equal to x00, all keys greater than or equal to the key argument are watched. If the range_end is one bit larger than the given key, then all keys with the prefix (the given key) 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.

async cancel(watch_id: int) None[source]

Cancel the watcher so that no more events are emitted.

Parameters

watch_id (int) – The ID of the watcher to cancel.