etha.kvstore.base

etha.kvstore.base#

KV Store abstraction - designed around etcd capabilities.

Classes#

KVStore

Abstract KV store interface.

Module Contents#

class etha.kvstore.base.KVStore(namespace: str, component: str)#

Bases: abc.ABC

Abstract KV store interface.

Key format: {namespace}/{component}/{key}

Initialize KVStore.

Parameters:

  • namespace – Namespace for key isolation

  • component – Default component name

abstractmethod close(cleanup: bool = True) → None#

Close the store and release resources.

Parameters:

cleanup – If True, delete coordination keys (etcd only)

abstractmethod delete(key: str, *, component: str | None = None) → bool#

Delete a key.

Parameters:

  • key – The key to delete

  • component – Override default component for this call

Returns:

True if key was deleted, False if it didn’t exist

abstractmethod exists(key: str, *, component: str | None = None) → bool#

Check if a key exists.

Parameters:

  • key – The key to check

  • component – Override default component for this call

Returns:

True if key exists, False otherwise

abstractmethod get(key: str, *, component: str | None = None) → bytes | None#

Get value for a key.

Parameters:

  • key – The key to retrieve

  • component – Override default component for this call

Returns:

The value as bytes, or None if key doesn’t exist

abstractmethod get_bytes(key: str, *, component: str | None = None) → bytes | None#

Retrieve binary data.

Implementation: - etcd: Returns bytes directly - TCPStore: Decodes from base64

Parameters:

  • key – The key to retrieve

  • component – Override default component for this call

Returns:

Binary data, or None if key doesn’t exist

abstractmethod set(key: str, value: str, *, component: str | None = None) → None#

Set a key-value pair.

Parameters:

  • key – The key to set

  • value – The value to store (string)

  • component – Override default component for this call

abstractmethod set_bytes(key: str, data: bytes, *, component: str | None = None) → None#

Store binary data.

Implementation: - etcd: Stores bytes directly - TCPStore: Encodes to base64 (TCPStore only accepts strings)

Parameters:

  • key – The key to set

  • data – Binary data to store

  • component – Override default component for this call

abstractmethod wait_for_key(key: str, timeout: float = 3600.0, *, component: str | None = None) → bytes#

Wait for a key to exist and return its value.

Implementation: - etcd: Uses watch for efficient waiting - TCPStore: Uses polling

Parameters:

  • key – The key to wait for

  • timeout – Maximum time to wait in seconds

  • component – Override default component for this call

Returns:

The value as bytes

Raises:

TimeoutError – If timeout is reached before key exists

abstractmethod wait_for_keys(key_pattern: str, expected_count: int, value: str = '1', timeout: float = 3600.0, candidate_keys: list[str] | None = None, *, component: str | None = None) → list[str]#

Wait until expected_count keys matching pattern have the specified value.

Pattern syntax: - ‘*’ matches any sequence of characters - Example: “pair:foo/rank:*/ready” matches “pair:foo/rank:0/ready”, “pair:foo/rank:1/ready”, etc.

Implementation: - etcd: Uses watch + prefix query (event-driven, efficient), ignores candidate_keys - TCPStore: Uses polling with candidate_keys (required)

Parameters:

  • key_pattern – Pattern with ‘*’ wildcard

  • expected_count – Number of matching keys to wait for

  • value – Expected value for matching keys (default “1”)

  • timeout – Maximum time to wait in seconds

  • candidate_keys – List of candidate keys to check (required for TCPStore, ignored by etcd)

  • component – Override default component for this call

Returns:

List of matched keys

Raises:

TimeoutError – If timeout is reached before expected_count keys are found

abstractmethod wait_for_value(key: str, expected: str, timeout: float = 3600.0, *, component: str | None = None) → bytes#

Wait for a key to have a specific value.

Parameters:

  • key – The key to watch

  • expected – Expected value to match

  • timeout – Maximum time to wait in seconds

  • component – Override default component for this call

Returns:

The value as bytes when matched

Raises:

TimeoutError – If timeout is reached before value matches

component: str#
namespace: str#