# 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_response`(key, serializable=False)

    Get the value of a key from etcd.

  `get`(key, **kwargs)

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

    Get a range of keys with a prefix.

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

    Get a range of keys.

  `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_all_response`(sort_order=None, sort_target='key', keys_only=False)

    Get all keys currently stored in etcd.

  `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

  `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`

  `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

  `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 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.

  `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.

  `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_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_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_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_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_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_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.

  `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

  property `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

  property `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.