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
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 whenreturn_response
is True
-
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
andcancel
. Useevents_iterator
to get the events of key changes andcancel
to cancel the watch request
-
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
-
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
-
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
-
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
-
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
-
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