The etcd3gw.client Module

class etcd3gw.client.Etcd3Client(host: str = 'localhost', port: int = 2379, protocol: str = 'http', ca_cert: str | None = None, cert_key: str | None = None, cert_cert: str | None = None, timeout: float | int | None = None, api_path: str | None = None, session: Session | None = None)[source]

Bases: object

property api_path: str
property base_url: str
create(key: str, value: str, lease: Lease | None = None) → bool[source]

Atomically create the given key only if the key doesn’t exist.

This verifies that the create_revision of a key equales to 0, then creates the key with the value. This operation takes place in a transaction.

Parameters:

  • key – key in etcd to create

  • value – value of the key

  • lease – lease to connect with, optional

Returns:

status of transaction, True if the create was successful, False otherwise

Return type:

bool

delete(key: str, *, range_end: str | None = None, prev_kv: bool | None = None, **kwargs: Any) → bool[source]

DeleteRange deletes the given range from the key-value store.

A delete request increments the revision of the key-value store and generates a delete event in the event history for every deleted key.

Parameters:

  • key – key (or start of range) to delete

  • range_end – end of range to delete; if unset, only key is deleted

  • prev_kv – if set, return the deleted key-value pairs

Returns:

True if any key was deleted, False otherwise

delete_prefix(key_prefix: str) → bool[source]

Delete a range of keys with a prefix in etcd.

get(key: str, metadata: Literal[False] = False, sort_order: Literal['none', 'ascend', 'descend'] | None = None, sort_target: Literal['key', 'version', 'create', 'mod', 'value'] | None = None, *, range_end: str | None = None, limit: int | None = None, revision: int | None = None, serializable: bool | None = None, keys_only: bool | None = None, count_only: bool | None = None, min_mod_revision: int | None = None, max_mod_revision: int | None = None, min_create_revision: int | None = None, max_create_revision: int | None = None, **kwargs: Any) → list[bytes][source]
get(key: str, metadata: Literal[True] = False, sort_order: Literal['none', 'ascend', 'descend'] | None = None, sort_target: Literal['key', 'version', 'create', 'mod', 'value'] | None = None, *, range_end: str | None = None, limit: int | None = None, revision: int | None = None, serializable: bool | None = None, keys_only: bool | None = None, count_only: bool | None = None, min_mod_revision: int | None = None, max_mod_revision: int | None = None, min_create_revision: int | None = None, max_create_revision: int | None = None, **kwargs: Any) → list[tuple[bytes, KeyValue]]

Range gets the keys in the range from the key-value store.

Parameters:

  • key

  • metadata

  • sort_order – ‘ascend’ or ‘descend’ or None

  • sort_target – ‘key’ or ‘version’ or ‘create’ or ‘mod’ or ‘value’

Returns:

get_all(sort_order: Literal['none', 'ascend', 'descend'] | None = None, sort_target: Literal['key', 'version', 'create', 'mod', 'value'] | None = 'key') → list[tuple[bytes, KeyValue]][source]

Get all keys currently stored in etcd.

Returns:

sequence of (value, metadata) tuples

get_prefix(key_prefix: str, sort_order: Literal['none', 'ascend', 'descend'] | None = None, sort_target: Literal['key', 'version', 'create', 'mod', 'value'] | None = None) → list[tuple[bytes, KeyValue]][source]

Get a range of keys with a prefix.

Parameters:

  • sort_order – ‘ascend’ or ‘descend’ or None

  • key_prefix – first key in range

Returns:

sequence of (value, metadata) tuples

get_url(path: str) → str[source]

Construct a full url to the v3 API given a specific path

Parameters:

path

Returns:

url

lease(ttl: int = 30) → Lease[source]

Create a Lease object given a timeout

Parameters:

ttl – timeout

Returns:

Lease object

lock(id: str | None = None, ttl: int = 30) → Lock[source]

Create a Lock object given an ID and timeout

Parameters:

  • id – ID for the lock, creates a new uuid if not provided

  • ttl – timeout

Returns:

Lock object

members() → list[Member][source]

Lists all the members in the cluster.

Returns:

json response

post(url: str, *args: Any, json: Any = None, **kwargs: Any) → Any[source]

helper method for HTTP POST

Parameters:

  • args

  • kwargs

Returns:

json response

put(key: str, value: str, lease: Lease | None = None) → bool[source]

Put puts the given key into the key-value store.

A put request increments the revision of the key-value store and generates one event in the event history.

Parameters:

  • key

  • value

  • lease

Returns:

boolean

replace(key: str, initial_value: str, new_value: str) → bool[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 – old value to replace

  • new_value – new value of the key

Returns:

status of transaction, True if the replace was successful, False otherwise

Return type:

bool

status() → StatusResponse[source]

Status gets the status of the etcd cluster member.

Returns:

json response

transaction(txn: dict[str, Any]) → TxnResponse[source]

Txn processes multiple requests in a single transaction.

A txn request increments the revision of the key-value store and generates events with the same revision for every completed request. It is not allowed to modify the same key several times within one txn.

Parameters:

txn

Returns:

watch(key: str, *, start_revision: int | None = None, progress_notify: bool | None = None, filters: list[Literal['NOPUT', 'NODELETE']] | None = None, prev_kv: bool | None = None, range_end: str | None = None, watch_id: int | None = None, fragment: bool | None = None, **kwargs: Any) → tuple[Iterator[Event], Callable[[], None]][source]

Watch a key.

Parameters:

  • key – key to watch

  • start_revision – revision to watch from

  • progress_notify – get periodic progress notifications

  • filters – filter types ("NOPUT" or "NODELETE")

  • prev_kv – return the previous key-value on event

  • range_end – end of the range to watch (key is the start)

  • watch_id – ID to assign to this watcher; 0 means auto-assign (etcd >= 3.4)

  • fragment – split large watch responses into multiple smaller responses (etcd >= 3.4)

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: str, timeout: float | int | None = None, *, start_revision: int | None = None, progress_notify: bool | None = None, filters: list[Literal['NOPUT', 'NODELETE']] | None = None, prev_kv: bool | None = None, range_end: str | None = None, watch_id: int | None = None, fragment: bool | None = None, **kwargs: Any) → Event[source]

Watch a key and stops after the first event.

Parameters:

  • key – key to watch

  • timeout – (optional) timeout in seconds.

  • start_revision – revision to watch from

  • progress_notify – get periodic progress notifications

  • filters – filter types ("NOPUT" or "NODELETE")

  • prev_kv – return the previous key-value on event

  • range_end – end of the range to watch (key is the start)

  • watch_id – ID to assign to this watcher; 0 means auto-assign (etcd >= 3.4)

  • fragment – split large watch responses into multiple smaller responses (etcd >= 3.4)

Returns:

event

watch_prefix(key_prefix: str, *, start_revision: int | None = None, progress_notify: bool | None = None, filters: list[Literal['NOPUT', 'NODELETE']] | None = None, prev_kv: bool | None = None, watch_id: int | None = None, fragment: bool | None = None, **kwargs: Any) → tuple[Iterator[Event], Callable[[], None]][source]

The same as watch, but watches a range of keys with a prefix.

Parameters:

  • key_prefix – key prefix to watch

  • start_revision – revision to watch from

  • progress_notify – get periodic progress notifications

  • filters – filter types ("NOPUT" or "NODELETE")

  • prev_kv – return the previous key-value on event

  • watch_id – ID to assign to this watcher; 0 means auto-assign (etcd >= 3.4)

  • fragment – split large watch responses into multiple smaller responses (etcd >= 3.4)

watch_prefix_once(key_prefix: str, timeout: float | int | None = None, *, start_revision: int | None = None, progress_notify: bool | None = None, filters: list[Literal['NOPUT', 'NODELETE']] | None = None, prev_kv: bool | None = None, watch_id: int | None = None, fragment: bool | None = None, **kwargs: Any) → Event[source]

Watches a range of keys with a prefix, similar to watch_once.

Parameters:

  • key_prefix – key prefix to watch

  • timeout – (optional) timeout in seconds.

  • start_revision – revision to watch from

  • progress_notify – get periodic progress notifications

  • filters – filter types ("NOPUT" or "NODELETE")

  • prev_kv – return the previous key-value on event

  • watch_id – ID to assign to this watcher; 0 means auto-assign (etcd >= 3.4)

  • fragment – split large watch responses into multiple smaller responses (etcd >= 3.4)

etcd3gw.client.client(host: str = 'localhost', port: int = 2379, ca_cert: str | None = None, cert_key: str | None = None, cert_cert: str | None = None, timeout: float | None = None, protocol: str = 'http', api_path: str | None = None, session: Session | None = None) → Etcd3Client[source]

Return an instance of an Etcd3Client.