API Usage

To use pyetcd in a project:

import pyetcd

and create a client:

etcd = pyetcd.client()

This defaults to localhost, but you can specify the host and port:

etcd = pyetcd.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 = pyetcd.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 pyetcd.MultiEndpointEtcd3Client(endpoints=None, timeout=None, user=None, password=None, failover=False)

etcd v3 API client with multiple endpoints.

When failover is enabled, requests still will not be auto-retried. Instead, the application may retry the request, and the Etcd3Client will then attempt to send it to a different endpoint that has not recently failed. If all configured endpoints have failed and are not ready to be retried, an exceptions.NoServerAvailableError will be raised.

Parameters:

• endpoints (Iterable(Endpoint), optional) – Endpoints to use in lieu of host and port

• timeout (int or float, optional) – Timeout for all RPC in seconds

• user (str, optional) – Username for authentication

• password (str, optional) – Password for authentication

• failover (bool) – Failover between endpoints, default False

add_member(urls)

Add a member into the cluster.

Returns:

new member

Return type:

Member

add_watch_callback(*args, **kwargs)

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)

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.

cancel_watch(watch_id)

Stop watching a key or range of keys.

Parameters:

watch_id – watch_id returned by add_watch_callback method

property channel

Get an available channel on the first node that’s not failed.

Raises an exception if no node is available

close()

Call the GRPC channel close semantics.

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

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

defragment()

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

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.

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

property endpoint_in_use

Get the current endpoint in use.

get(key, **kwargs)

Get the value of a key from etcd.

example usage:

>>> import pyetcd
>>> etcd = pyetcd.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_all(**kwargs)

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

get_all_response(sort_order=None, sort_target='key', keys_only=False)

Get all keys currently stored in etcd.

get_prefix(key_prefix, **kwargs)

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_prefix_response(key_prefix, **kwargs)

Get a range of keys with a prefix.

get_range(range_start, range_end, **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_range_response(range_start, range_end, sort_order=None, sort_target='key', **kwargs)

Get a range of keys.

get_response(key, **kwargs)

Get the value of a key from etcd.

hash()

Return the hash of the local KV state.

Returns:

kv state hash

Return type:

int

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

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

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

property members

List of all members associated with the cluster.

Type:

sequence of Member

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

Save a value to etcd.

Example usage:

>>> import pyetcd
>>> etcd = pyetcd.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)

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

remove_member(member_id)

Remove an existing member from the cluster.

Parameters:

member_id – ID of the member to remove

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

revoke_lease(lease_id)

Revoke a lease.

Parameters:

lease_id – ID of the lease to revoke.

snapshot(file_obj)

Take a snapshot of the database.

Parameters:

file_obj – A file-like object to write the database contents in.

status()

Get the status of the responding member.

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)

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

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_once(key, timeout=None, **kwargs)

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_once_response(key, timeout=None, **kwargs)

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_prefix(key_prefix, **kwargs)

Watch a range of keys with a prefix.

Parameters:

key_prefix – prefix to watch

Returns:

tuple of events_iterator and cancel.

watch_prefix_once(key_prefix, timeout=None, **kwargs)

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.

watch_prefix_once_response(key_prefix, timeout=None, **kwargs)

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_response(key_prefix, **kwargs)

Watch a range of keys with a prefix.

Parameters:

key_prefix – prefix to watch

Returns:

tuple of responses_iterator and cancel.

watch_response(key, **kwargs)

Watch a key.

Example usage:

Parameters:

key – key to watch

Returns:

tuple of responses_iterator and cancel. Use responses_iterator to get the watch responses, each of which contains a header and a list of events. Use cancel to cancel the watch request.

class pyetcd.Etcd3Client(host='localhost', port=2379, ca_cert=None, cert_key=None, cert_cert=None, timeout=None, user=None, password=None, grpc_options=None)

etcd v3 API client.

Parameters:

• host (str, optional) – Host to connect to, ‘localhost’ if not specified

• port (int, optional) – Port to connect to on host, 2379 if not specified

• ca_cert (str or os.PathLike, optional) – Filesystem path of etcd CA certificate

• cert_key (str or os.PathLike, optional) – Filesystem path of client key

• cert_cert (str or os.PathLike, optional) – Filesystem path of client certificate

• timeout (int or float, optional) – Timeout for all RPC in seconds

• user (str, optional) – Username for authentication

• password (str, optional) – Password for authentication

• grpc_options (dict, optional) – Additional gRPC options

class pyetcd.Endpoint(host, port, secure=True, creds=None, time_retry=300.0, opts=None)

Represents an etcd cluster endpoint.

Parameters:

• host (str) – Endpoint host

• port (int) – Endpoint port

• secure (bool) – Use secure channel, default True

• creds (grpc.ChannelCredentials, optional) – Credentials to use for secure channel, required if secure=True

• time_retry (int or float) – Seconds to wait before retrying this endpoint after failure, default 300.0

• opts (dict, optional) – Additional gRPC options

fail()

Transition the endpoint to a failed state.

is_failed()

Check if the current endpoint is failed.

use()

Transition the endpoint to an active state.

class pyetcd.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

property active_alarms

Get active alarms of the member.

Returns:

Alarms

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

class pyetcd.Lease(lease_id, ttl, etcd_client=None)

A lease.

Variables:

• id – ID of the lease

• ttl – time to live for this lease

refresh()

Refresh the time to live for this lease.

revoke()

Revoke this lease.

class pyetcd.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 = pyetcd.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.

is_acquired()

Check if this lock is currently acquired.

refresh()

Refresh the time to live on this lock.

release()

Release the lock.