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

Call the GRPC channel close semantics.

get(key)[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
Returns:value of key and metadata
Return type:bytes, KVMetadata
get_prefix(key_prefix, sort_order=None, sort_target='key')[source]

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)[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(sort_order=None, sort_target='key')[source]

Get all keys currently stored in etcd.

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

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 when return_response is True

delete_prefix(prefix)[source]

Delete a range of keys with a prefix in etcd.

status()[source]

Get the status of the responding member.

add_watch_callback(*args, **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.

watch(key, **kwargs)[source]

Watch a key.

Example usage:

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

Watches a range of keys with a prefix.

watch_once(key, timeout=None, **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

watch_prefix_once(key_prefix, timeout=None, **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.

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:

Lease

revoke_lease(lease_id)[source]

Revoke a lease.

Parameters:lease_id – ID of the lease to revoke.
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:

Lock

add_member(urls)[source]

Add a member into the cluster.

Returns:new member
Return type:Member
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
members

List of all members associated with the cluster.

Type:sequence of Member
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
defragment()[source]

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

hash()[source]

Return the hash of the local KV state.

Returns:kv state hash
Return type:int
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

disarm_alarm(member_id=0)[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
snapshot(file_obj)[source]

Take a snapshot of the database.

Parameters:file_obj – A file-like object to write the database contents in.
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
remove()[source]

Remove this member from the cluster.

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

Revoke this lease.

refresh()[source]

Refresh the 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
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.
release()[source]

Release the lock.

refresh()[source]

Refresh the time to live on this lock.

is_acquired()[source]

Check if this lock is currently acquired.