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)

close()

Call the GRPC channel close semantics.

get(key)

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')

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)

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')

Get all keys currently stored in etcd.

Returns:sequence of (value, metadata) tuples

put(key, value, lease=None, prev_kv=False)

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)

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)

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)

Delete a range of keys with a prefix in etcd.

status()

Get the status of the responding member.

add_watch_callback(*args, **kwargs)

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)

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)

Watches a range of keys with a prefix.

watch_once(key, timeout=None, **kwargs)

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)

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)

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)

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)

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)

Revoke a lease.

Parameters:lease_id – ID of the lease to revoke.

lock(name, ttl=60)

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)

Add a member into the cluster.

Returns:new member Return type:Member

remove_member(member_id)

Remove an existing member from the cluster.

Parameters:member_id – ID of the member to remove

update_member(member_id, peer_urls)

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)

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()

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

hash()

Return the hash of the local KV state.

Returns:kv state hash Return type:int

create_alarm(member_id=0)

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')

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)

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)

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)

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()

Remove this member from the cluster.

update(peer_urls)

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)

A lease.

Variables:

• id – ID of the lease
• ttl – time to live for this lease

revoke()

Revoke this lease.

refresh()

Refresh the time to live for this lease.

class etcd3.Lock(name, ttl=60, etcd_client=None)

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)

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()

Release the lock.

refresh()

Refresh the time to live on this lock.

is_acquired()

Check if this lock is currently acquired.