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