etha.kvstore.base
=================

.. py:module:: etha.kvstore.base

.. autoapi-nested-parse::

   KV Store abstraction - designed around etcd capabilities.



Classes
-------

.. autoapisummary::

   etha.kvstore.base.KVStore


Module Contents
---------------

.. py:class:: KVStore(namespace: str, component: str)

   Bases: :py:obj:`abc.ABC`


   Abstract KV store interface.

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

   Initialize KVStore.

   :param namespace: Namespace for key isolation
   :param component: Default component name


   .. py:method:: close(cleanup: bool = True) -> None
      :abstractmethod:


      Close the store and release resources.

      :param cleanup: If True, delete coordination keys (etcd only)



   .. py:method:: delete(key: str, *, component: str | None = None) -> bool
      :abstractmethod:


      Delete a key.

      :param key: The key to delete
      :param component: Override default component for this call

      :returns: True if key was deleted, False if it didn't exist



   .. py:method:: exists(key: str, *, component: str | None = None) -> bool
      :abstractmethod:


      Check if a key exists.

      :param key: The key to check
      :param component: Override default component for this call

      :returns: True if key exists, False otherwise



   .. py:method:: get(key: str, *, component: str | None = None) -> bytes | None
      :abstractmethod:


      Get value for a key.

      :param key: The key to retrieve
      :param component: Override default component for this call

      :returns: The value as bytes, or None if key doesn't exist



   .. py:method:: get_bytes(key: str, *, component: str | None = None) -> bytes | None
      :abstractmethod:


      Retrieve binary data.

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

      :param key: The key to retrieve
      :param component: Override default component for this call

      :returns: Binary data, or None if key doesn't exist



   .. py:method:: set(key: str, value: str, *, component: str | None = None) -> None
      :abstractmethod:


      Set a key-value pair.

      :param key: The key to set
      :param value: The value to store (string)
      :param component: Override default component for this call



   .. py:method:: set_bytes(key: str, data: bytes, *, component: str | None = None) -> None
      :abstractmethod:


      Store binary data.

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

      :param key: The key to set
      :param data: Binary data to store
      :param component: Override default component for this call



   .. py:method:: wait_for_key(key: str, timeout: float = 3600.0, *, component: str | None = None) -> bytes
      :abstractmethod:


      Wait for a key to exist and return its value.

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

      :param key: The key to wait for
      :param timeout: Maximum time to wait in seconds
      :param component: Override default component for this call

      :returns: The value as bytes

      :raises TimeoutError: If timeout is reached before key exists



   .. py:method:: 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]
      :abstractmethod:


      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)

      :param key_pattern: Pattern with '*' wildcard
      :param expected_count: Number of matching keys to wait for
      :param value: Expected value for matching keys (default "1")
      :param timeout: Maximum time to wait in seconds
      :param candidate_keys: List of candidate keys to check (required for TCPStore, ignored by etcd)
      :param component: Override default component for this call

      :returns: List of matched keys

      :raises TimeoutError: If timeout is reached before expected_count keys are found



   .. py:method:: wait_for_value(key: str, expected: str, timeout: float = 3600.0, *, component: str | None = None) -> bytes
      :abstractmethod:


      Wait for a key to have a specific value.

      :param key: The key to watch
      :param expected: Expected value to match
      :param timeout: Maximum time to wait in seconds
      :param component: Override default component for this call

      :returns: The value as bytes when matched

      :raises TimeoutError: If timeout is reached before value matches



   .. py:attribute:: component
      :type:  str


   .. py:attribute:: namespace
      :type:  str