API Usage

To use aetcd3 in a project:

import aetcd3

and create a client:

etcd = aetcd3.client()

This defaults to localhost, but you can specify the host and port:

etcd = etcd3.client(host='etcd-host-01', port=2379)

Putting values into etcd

Values can be stored with the put method:

await etcd.put('/key', 'dooot')

You can check this has been stored correctly by testing with etcdctl:

$ ETCDCTL_API=3 etcdctl get /key
/key
dooot

API

class aetcd3.Etcd3Client(host='localhost', port=2379, ca_cert=None, cert_key=None, cert_cert=None, timeout=None, user=None, password=None, grpc_options=None)[source]
async open()[source]

Open GRPC channel.

async close()[source]

Call the GRPC channel close semantics.

async get(**kwargs)[source]

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

Get a range of keys with a prefix.

Parameters

key_prefix – first key in range

Returns

sequence of (value, metadata) tuples

get_range(**kwargs)[source]

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

Get all keys currently stored in etcd.

Returns

sequence of (value, metadata) tuples

async put(**kwargs)[source]

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(**kwargs)[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

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

Return type

bool

async delete(**kwargs)[source]

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

Delete a range of keys with a prefix in etcd.

async status(**kwargs)[source]

Get the status of the responding member.

async add_watch_callback(**kwargs)[source]

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

Watch a key.

Example usage:

events_iterator, cancel = etcd.watch('/doot/key')
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(**kwargs)[source]

Watches a range of keys with a prefix.

async watch_once(**kwargs)[source]

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

Event

async watch_prefix_once(**kwargs)[source]

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

Stop watching a key or range of keys.

Parameters

watch_id – watch_id returned by add_watch_callback method

async transaction(**kwargs)[source]

Perform a transaction.

Example usage:

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(**kwargs)[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 – Requested time to live

  • lease_id – Requested ID for the lease

Returns

new lease

Return type

Lease

async revoke_lease(**kwargs)[source]

Revoke a lease.

Parameters

lease_id – ID of the lease to revoke.

lock(**kwargs)[source]

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

Add a member into the cluster.

Returns

new member

Return type

members.Member

async remove_member(**kwargs)[source]

Remove an existing member from the cluster.

Parameters

member_id – ID of the member to remove

async update_member(**kwargs)[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

members(**kwargs)[source]

List of all members associated with the cluster.

Type

sequence of members.Member

async compact(**kwargs)[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(**kwargs)[source]

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

async hash(**kwargs)[source]

Return the hash of the local KV state.

Returns

kv state hash

Return type

int

async create_alarm(**kwargs)[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

list of Alarm

list_alarms(**kwargs)[source]

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(**kwargs)[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

List of Alarm

async snapshot(**kwargs)[source]

Take a snapshot of the database.

Parameters

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

class aetcd3.Member(id, name, peer_urls, client_urls, etcd_client=None)[source]

A member of the etcd cluster.

Variables

  • id – ID of the member

  • name – human-readable name of the member

  • peer_urls – list of URLs the member exposes to the cluster for communication

  • client_urls – list of URLs the member exposes to clients for communication

async remove()[source]

Remove this member from the cluster.

async update(peer_urls)[source]

Update the configuration of this member.

Parameters

peer_urls – new list of peer urls the member will use to communicate with the cluster

async active_alarms()[source]

Get active alarms of the member.

Returns

Alarms

class aetcd3.Lease(lease_id, ttl, etcd_client=None)[source]

A lease.

Variables

  • id – ID of the lease

  • ttl – time to live for this lease

async revoke()[source]

Revoke this lease.

async refresh()[source]

Refresh the time to live for this lease.

class aetcd3.Lock(name, ttl=60, etcd_client=None)[source]

A distributed lock.

This can be used as a context manager, with the lock being acquired and released as you would expect:

etcd = etcd3.client()

# create a lock that expires after 20 seconds
with etcd.lock('toot', ttl=20) as lock:
    # do something that requires the lock
    print(lock.is_acquired())

    # refresh the timeout on the lease
    lock.refresh()
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

async acquire(timeout=10)[source]

Acquire the lock.

Params timeout

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.