Client

class aetcd3.client.Alarm(alarm_type, member_id)

A cluster member alarm.

Parameters

• alarm_type – Type of the alarm

• member_id – Cluster member ID

class aetcd3.client.Etcd3Client(host='localhost', port=2379, ca_cert=None, cert_key=None, cert_cert=None, timeout=None, user=None, password=None, grpc_options=None)

Client.

async open()

Open GRPC channel.

async close()

Call the GRPC channel close semantics.

async get(key, serializable=False)

Get the value of a key from etcd.

example usage:

import aetcd3
etcd = aetcd3.client()
await etcd.get('/thing/key')

Parameters

• key – key in etcd to get

• serializable – whether to allow serializable reads. This can result in stale reads

Returns

value of key and metadata

Return type

bytes, KVMetadata

get_prefix(key_prefix, sort_order=None, sort_target='key', keys_only=False)

Get a range of keys with a prefix.

Parameters

key_prefix – first key in range

Returns

sequence of (value, metadata) tuples

get_range(range_start, range_end, sort_order=None, sort_target='key', **kwargs)

Get a range of keys.

Parameters

• range_start – first key in range

• range_end – last key in range

Returns

sequence of (value, metadata) tuples

get_all(sort_order=None, sort_target='key', keys_only=False)

Get all keys currently stored in etcd.

Returns

sequence of (value, metadata) tuples

async put(key, value, lease=None, prev_kv=False)

Save a value to etcd.

Example usage:

import aetcd3
etcd = aetcd3.client()
await etcd.put('/thing/key', 'hello world')

Parameters

• key – key in etcd to set

• value (bytes) – value to set key to

• lease (either Lease, or int (ID of lease)) – Lease to associate with this key.

• prev_kv (bool) – return the previous key-value pair

Returns

a response containing a header and the prev_kv

Return type

rpc_pb2.PutResponse

async replace(key, initial_value, new_value)

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

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

Return type

bool

async delete(key, prev_kv=False, return_response=False)

Delete a single key in etcd.

Parameters

• key – key in etcd to delete

• prev_kv (bool) – return the deleted key-value pair

• return_response (bool) – return the full response

Returns

True if the key has been deleted when return_response is False and a response containing a header, the number of deleted keys and prev_kvs when return_response is True

async delete_prefix(prefix)

Delete a range of keys with a prefix in etcd.

async status()

Get the status of the responding member.

async add_watch_callback(*args, **kwargs)

Watch a key or range of keys and call a callback on every event.

If timeout was declared during the client initialization and the watch cannot be created during that time the method raises a WatchTimedOut exception.

Parameters

• key – key to watch

• callback – callback function

Returns

watch_id. Later it could be used for cancelling watch.

async watch(key, **kwargs)

Watch a key.

Example usage:

events_iterator, cancel = await etcd.watch('/doot/key')
async for event in events_iterator:
    print(event)

Parameters

key – key to watch

Returns

tuple of events_iterator and cancel. Use events_iterator to get the events of key changes and cancel to cancel the watch request

async watch_prefix(key_prefix, **kwargs)

Watches a range of keys with a prefix.

async watch_once(key, timeout=None, **kwargs)

Watch a key and stops after the first event.

If the timeout was specified and event didn’t arrived method will raise WatchTimedOut exception.

Parameters

• key – key to watch

• timeout – (optional) timeout in seconds.

Returns

aetcd3.Event

async watch_prefix_once(key_prefix, timeout=None, **kwargs)

Watches 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 WatchTimedOut exception.

async cancel_watch(watch_id)

Stop watching a key or range of keys.

Parameters

watch_id – watch_id returned by add_watch_callback method

async transaction(compare, success=None, failure=None)

Perform a transaction.

Example usage:

await etcd.transaction(
    compare=[
        etcd.transactions.value('/doot/testing') == 'doot',
        etcd.transactions.version('/doot/testing') > 0,
    ],
    success=[
        etcd.transactions.put('/doot/testing', 'success'),
    ],
    failure=[
        etcd.transactions.put('/doot/testing', 'failure'),
    ]
)

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)

async lease(ttl, lease_id=None)

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 – Requested time to live

• lease_id – Requested ID for the lease

Returns

new lease

Return type

Lease

async revoke_lease(lease_id)

Revoke a lease.

Parameters

lease_id – ID of the lease to revoke.

lock(name, ttl=60)

Create a new lock.

Parameters

• name (string or bytes) – name of the lock

• 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

new lock

Return type

Lock

async add_member(urls)

Add a member into the cluster.

Returns

new member

Return type

members.Member

async remove_member(member_id)

Remove an existing member from the cluster.

Parameters

member_id – ID of the member to remove

async update_member(member_id, peer_urls)

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

members()

List of all members associated with the cluster.

Type

sequence of members.Member

async compact(revision, physical=False)

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()

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

async hash()

Return the hash of the local KV state.

Returns

kv state hash

Return type

int

async create_alarm(member_id=0)

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

list of Alarm

list_alarms(member_id=0, alarm_type='none')

List the activated alarms.

Parameters

• 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

sequence of Alarm

async disarm_alarm(member_id=0)

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

List of Alarm

async snapshot(file_obj)

Take a snapshot of the database.

Parameters

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

aetcd3.client.client(host='localhost', port=2379, ca_cert=None, cert_key=None, cert_cert=None, timeout=None, user=None, password=None, **kwargs)

Return an instance of an Etcd3Client.