API Usage¶
To use python-etcd3 in a project:
import etcd3
and create a client:
etcd = etcd3.client()
This defaults to localhost, but you can specify the host and port:
etcd = etcd3.client(host='etcd-host-01', port=2379)
If you would like to specify options for the underlying GRPC connection, you can also pass it as a parameter:
etcd = etcd3.client(grpc_options={
'grpc.http2.true_binary': 1,
'grpc.http2.max_pings_without_data': 0,
}.items())
Putting values into etcd¶
Values can be stored with the put
method:
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 etcd3.Etcd3Client(host='localhost', port=2379, ca_cert=None, cert_key=None, cert_cert=None, timeout=None, user=None, password=None, grpc_options=None)[source]¶
-
- get(key, **kwargs)[source]¶
Get the value of a key from etcd.
example usage:
>>> import etcd3 >>> etcd = etcd3.client() >>> etcd.get('/thing/key') 'hello world'
- 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, **kwargs)[source]¶
Get a range of keys with a prefix.
- Parameters:
key_prefix – first key in range
keys_only – if True, retrieve only the keys, not the values
- Returns:
sequence of (value, metadata) tuples
- get_range_response(range_start, range_end, sort_order=None, sort_target='key', **kwargs)[source]¶
Get a range of keys.
- get_range(range_start, range_end, **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_response(sort_order=None, sort_target='key', keys_only=False)[source]¶
Get all keys currently stored in etcd.
- get_all(**kwargs)[source]¶
Get all keys currently stored in etcd.
- Parameters:
keys_only – if True, retrieve only the keys, not the values
- Returns:
sequence of (value, metadata) tuples
- put(key, value, lease=None, prev_kv=False)[source]¶
Save a value to etcd.
Example usage:
>>> import etcd3 >>> etcd = etcd3.client() >>> 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
- put_if_not_exists(key, value, lease=None)[source]¶
Atomically puts a value only if the key previously had no value.
This is the etcdv3 equivalent to setting a key with the etcdv2 parameter prevExist=false.
- Parameters:
key – key in etcd to put
value (bytes) – value to be written to key
lease (either
Lease
, or int (ID of lease)) – Lease to associate with this key.
- Returns:
state of transaction,
True
if the put was successful,False
otherwise- Return type:
bool
- 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:
status of transaction,
True
if the replace was successful,False
otherwise- Return type:
bool
- delete(key, prev_kv=False, return_response=False)[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
- add_watch_callback(*args, **kwargs)[source]¶
Watch a key or range of keys and call a callback on every response.
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.
- add_watch_prefix_callback(key_prefix, callback, **kwargs)[source]¶
Watch a prefix and call a callback on every response.
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_prefix – prefix to watch
callback – callback function
- Returns:
watch_id. Later it could be used for cancelling watch.
- watch_response(key, **kwargs)[source]¶
Watch a key.
Example usage:
- Parameters:
key – key to watch
- Returns:
tuple of
responses_iterator
andcancel
. Useresponses_iterator
to get the watch responses, each of which contains a header and a list of events. Usecancel
to cancel the watch request.
- watch(key, **kwargs)[source]¶
Watch a key.
Example usage:
- 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.
- watch_prefix_response(key_prefix, **kwargs)[source]¶
Watch a range of keys with a prefix.
- Parameters:
key_prefix – prefix to watch
- Returns:
tuple of
responses_iterator
andcancel
.
- watch_prefix(key_prefix, **kwargs)[source]¶
Watch a range of keys with a prefix.
- Parameters:
key_prefix – prefix to watch
- Returns:
tuple of
events_iterator
andcancel
.
- watch_once_response(key, timeout=None, **kwargs)[source]¶
Watch a key and stop after the first response.
If the timeout was specified and response didn’t arrive method will raise
WatchTimedOut
exception.- Parameters:
key – key to watch
timeout – (optional) timeout in seconds.
- Returns:
WatchResponse
- watch_once(key, timeout=None, **kwargs)[source]¶
Watch a key and stop after the first event.
If the timeout was specified and event didn’t arrive method will raise
WatchTimedOut
exception.- Parameters:
key – key to watch
timeout – (optional) timeout in seconds.
- Returns:
Event
- watch_prefix_once_response(key_prefix, timeout=None, **kwargs)[source]¶
Watch a range of keys with a prefix and stop after the first response.
If the timeout was specified and response didn’t arrive method will raise
WatchTimedOut
exception.
- watch_prefix_once(key_prefix, timeout=None, **kwargs)[source]¶
Watch a range of keys with a prefix and stop after the first event.
If the timeout was specified and event didn’t arrive method will raise
WatchTimedOut
exception.
- cancel_watch(watch_id)[source]¶
Stop watching a key or range of keys.
- Parameters:
watch_id – watch_id returned by
add_watch_callback
method
- transaction(compare, success=None, failure=None)[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)
- 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 – Requested time to live
lease_id – Requested ID for the lease
- Returns:
new lease
- Return type:
- lock(name, ttl=60)[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:
- remove_member(member_id)[source]¶
Remove an existing member from the cluster.
- Parameters:
member_id – ID of the member to remove
- 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
- 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
- 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:
list of
Alarm
- list_alarms(member_id=0, alarm_type='none')[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
- class etcd3.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
- 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
- property active_alarms¶
Get active alarms of the member.
- Returns:
Alarms
- class etcd3.Lease(lease_id, ttl, etcd_client=None)[source]¶
A lease.
- Variables:
id – ID of the lease
ttl – time to live for this lease
- class etcd3.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