python-etcd3-async 0.1.0__py3-none-any.whl

etcd3/client.py

@@ -0,0 +1,2021 @@
+"""Synchronous etcd3 client implementation.
+
+This module provides synchronous client classes for interacting with etcd v3 API.
+"""
+
+import random
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Optional, Literal, Any
+
+import grpc
+import etcdrpc
+import queue
+
+
+import etcd3.exceptions as exceptions
+import etcd3.leases as leases
+import etcd3.locks as locks
+import etcd3.members
+import etcd3.transactions as transactions
+import etcd3.utils as utils
+import etcd3.watch as watch
+from etcd3.log import log_operation
+from etcd3.exporters.prometheus import get_metrics_interface, monitor_request
+
+from etcd3.shared import (
+    Transactions,
+    KVMetadata,
+    Status,
+    Alarm,
+    EtcdTokenCallCredentials,
+    _EXCEPTIONS_BY_CODE,
+    _FAILED_EP_CODES,
+    get_secure_creds,
+    _make_sync_handle_errors_with_tracing,
+    _make_sync_handle_generator_errors_with_tracing,
+    RequestBuilder,
+)
+from etcd3.endpoint import BaseEndpoint
+
+
+def _manage_client_errors(self, exc):
+    """Error handler for sync operations that routes to client's error handler."""
+    self._manage_grpc_errors(exc)
+
+
+# Create trace-aware error handlers for sync operations
+_sync_handle_errors = _make_sync_handle_errors_with_tracing(
+    _manage_client_errors, "etcd3.operation"
+)
+_sync_handle_generator_errors = _make_sync_handle_generator_errors_with_tracing(
+    _manage_client_errors, "etcd3.operation"
+)
+# Error handler for lease keepalive that propagates errors to allow detection of connection loss
+_sync_handle_keepalive_errors = _make_sync_handle_generator_errors_with_tracing(
+    _manage_client_errors, "etcd3.keepalive", propagate_errors=True
+)
+
+
+@dataclass(kw_only=True)
+class RangeRequestConfig:
+    """Configuration for range request.
+
+    :param range_end: End of the key range
+    :type range_end: str or bytes
+    :param limit: Maximum number of keys to return
+    :type limit: int
+    :param revision: Revision to get
+    :type revision: int
+    :param sort_order: Sort order ('ascend' or 'descend')
+    :type sort_order: str
+    :param sort_target: Sort target ('key', 'version', 'create', 'mod')
+    :type sort_target: str
+    :param serializable: Whether to use serializable read
+    :type serializable: bool
+    :param keys_only: Whether to return only keys
+    :type keys_only: bool
+    :param count_only: Whether to return only count
+    :type count_only: bool
+    :param min_mod_revision: Minimum modification revision
+    :type min_mod_revision: int
+    :param max_mod_revision: Maximum modification revision
+    :type max_mod_revision: int
+    :param min_create_revision: Minimum creation revision
+    :type min_create_revision: int
+    :param max_create_revision: Maximum creation revision
+    :type max_create_revision: int
+    """
+
+    range_end: Optional[bytes | str] = None
+    limit: Optional[int] = None
+    revision: Optional[int] = None
+    sort_order: Optional[Literal["ascend", "descend"]] = None
+    sort_target: Literal["key", "version", "create", "mod"] = "key"
+    serializable: bool = False
+    keys_only: bool = False
+    count_only: bool = False
+    min_mod_revision: Optional[int] = None
+    max_mod_revision: Optional[int] = None
+    min_create_revision: Optional[int] = None
+    max_create_revision: Optional[int] = None
+
+    def __post_init__(self):
+        if self.limit is not None and self.limit < 1:
+            raise ValueError("limit must be a positive integer")
+        if self.revision is not None and self.revision < 0:
+            raise ValueError("revision must be a non-negative integer")
+        if self.min_mod_revision is not None and self.min_mod_revision < 0:
+            raise ValueError("min_mod_revision must be a non-negative integer")
+        if self.max_mod_revision is not None and self.max_mod_revision < 0:
+            raise ValueError("max_mod_revision must be a non-negative integer")
+        if self.min_create_revision is not None and self.min_create_revision < 0:
+            raise ValueError("min_create_revision must be a non-negative integer")
+        if self.max_create_revision is not None and self.max_create_revision < 0:
+            raise ValueError("max_create_revision must be a non-negative integer")
+
+
+@dataclass(kw_only=True)
+class ClientConfig:
+    """Configuration for single endpoint client creation.
+
+    :param host: etcd host
+    :type host: str
+    :param port: etcd port
+    :type port: int
+    :param ca_cert: CA certificate path
+    :type ca_cert: str
+    :param cert_key: client certificate key path
+    :type cert_key: str
+    :param cert_cert: client certificate path
+    :type cert_cert: str
+    :param timeout: request timeout in seconds
+    :type timeout: int or float
+    :param user: username for authentication
+    :type user: str
+    :param password: password for authentication
+    :type password: str
+    :param grpc_options: additional gRPC options
+    :type grpc_options: dict[str, Any]
+    """
+
+    host: str = "localhost"
+    port: int = 2379
+    ca_cert: Optional[str] = None
+    cert_key: Optional[str] = None
+    cert_cert: Optional[str] = None
+    timeout: Optional[float] = None
+    user: Optional[str] = None
+    password: Optional[str] = None
+    grpc_options: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        if self.port < 1 or self.port > 65535:
+            raise ValueError("port must be between 1 and 65535")
+        if self.timeout is not None and self.timeout <= 0:
+            raise ValueError("timeout must be a positive number")
+
+
+@dataclass(kw_only=True)
+class MultiEndpointConfig:
+    """Configuration for MultiEndpointEtcd3Client creation.
+
+    :param endpoints: Endpoints to use
+    :type endpoints: Iterable[Endpoint]
+    :param timeout: Timeout for all RPC in seconds
+    :type timeout: float, optional
+    :param user: Username for authentication
+    :type user: str, optional
+    :param password: Password for authentication
+    :type password: str, optional
+    :param failover: Failover between endpoints, default False
+    :type failover: bool
+    :param max_retries: Maximum number of retries for transient errors
+    :type max_retries: int
+    :param retry_backoff: Initial backoff time in seconds for retries
+    :type retry_backoff: float
+    :param retry_max_backoff: Maximum backoff time in seconds for retries
+    :type retry_max_backoff: float
+    :param load_balancer: Load balancing strategy
+    :type load_balancer: LoadBalancerStrategy
+    :param health_check_interval: Health check interval in seconds
+    :type health_check_interval: float
+    """
+
+    endpoints: Optional[list] = None
+    timeout: Optional[float] = None
+    user: Optional[str] = None
+    password: Optional[str] = None
+    failover: bool = False
+    max_retries: int = 3
+    retry_backoff: float = 0.1
+    retry_max_backoff: float = 10.0
+    load_balancer: utils.LoadBalancerStrategy = utils.LoadBalancerStrategy.PRIORITY
+    health_check_interval: float = 30.0
+
+    def __post_init__(self):
+        if self.max_retries < 0:
+            raise ValueError("max_retries must be a non-negative integer")
+        if self.retry_backoff < 0:
+            raise ValueError("retry_backoff must be a non-negative number")
+        if self.retry_max_backoff < 0:
+            raise ValueError("retry_max_backoff must be a non-negative number")
+        if self.retry_backoff > self.retry_max_backoff:
+            raise ValueError("retry_backoff must not exceed retry_max_backoff")
+        if self.health_check_interval <= 0:
+            raise ValueError("health_check_interval must be a positive number")
+
+
+class Endpoint(BaseEndpoint):
+    """Represents an etcd cluster endpoint.
+
+    :param str host: Endpoint host
+    :param int port: Endpoint port
+    :param bool secure: Use secure channel, default True
+    :param creds: Credentials to use for secure channel, required if
+                  secure=True
+    :type creds: grpc.ChannelCredentials, optional
+    :param time_retry: Seconds to wait before retrying this endpoint after
+                       failure, default 300.0
+    :type time_retry: int or float
+    :param opts: Additional gRPC options
+    :type opts: dict, optional
+    """
+
+    def __init__(
+        self, host, port, secure=True, creds=None, time_retry=300.0, opts=None
+    ):
+        super().__init__(host, port, secure, creds, time_retry, opts)
+        self.channel = self._mkchannel(opts)
+
+    def close(self):
+        """Close the gRPC channel."""
+        try:
+            self.channel.close()
+        except Exception:
+            pass  # Ignore close errors
+
+    def rebuild_channel(self):
+        """Rebuild the gRPC channel.
+
+        This method closes the existing channel and creates a new one,
+        which is useful when the connection has become stale (e.g., after
+        etcd server restart).
+        """
+        try:
+            self.channel.close()
+        except Exception:
+            pass  # Ignore close errors
+
+        self.channel = self._mkchannel(self.opts)
+
+    def _mkchannel(self, opts):
+        if self.secure:
+            return grpc.secure_channel(self.netloc, self.credentials, options=opts)
+        else:
+            return grpc.insecure_channel(self.netloc, options=opts)
+
+
+class MultiEndpointEtcd3Client(object):
+    """
+    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.
+
+    :param config: MultiEndpointConfig object with client configuration
+    :param endpoints: Endpoints to use in lieu of host and port
+    :type endpoints: Iterable(Endpoint), optional
+    :param timeout: Timeout for all RPC in seconds
+    :type timeout: int or float, optional
+    :param user: Username for authentication
+    :type user: str, optional
+    :param password: Password for authentication
+    :type password: str, optional
+    :param bool failover: Failover between endpoints, default False
+    :param int max_retries: Maximum number of retries for transient errors
+    :param float retry_backoff: Initial backoff time in seconds for retries
+    :param float retry_max_backoff: Maximum backoff time in seconds for retries
+    """
+
+    def __init__(
+        self,
+        config=None,
+        endpoints=None,
+        timeout=None,
+        user=None,
+        password=None,
+        failover=False,
+        max_retries=3,
+        retry_backoff=0.1,
+        retry_max_backoff=10.0,
+        load_balancer=None,
+        health_check_interval=30.0,
+    ):
+        if config is not None:
+            endpoints = config.endpoints
+            timeout = config.timeout
+            user = config.user
+            password = config.password
+            failover = config.failover
+            max_retries = config.max_retries
+            retry_backoff = config.retry_backoff
+            retry_max_backoff = config.retry_max_backoff
+            load_balancer = config.load_balancer
+            health_check_interval = config.health_check_interval
+
+        if endpoints is None:
+            raise ValueError("Endpoints must be provided")
+
+        if not endpoints:
+            raise ValueError("Endpoints list cannot be empty")
+
+        self.metadata = None
+        self.failover = failover
+        self.max_retries = max_retries
+        self.retry_backoff = retry_backoff
+        self.retry_max_backoff = retry_max_backoff
+        self.load_balancer = load_balancer or utils.LoadBalancerStrategy.PRIORITY
+        self.health_check_interval = health_check_interval
+        self._rr_index = 0  # Round-robin index
+
+        # Endpoint lock for thread-safe endpoint management
+        self._endpoint_lock = threading.Lock()
+
+        # Step 1: setup endpoints
+        self.endpoints = {ep.netloc: ep for ep in endpoints}
+        self._current_ep_label = random.choice(list(self.endpoints.keys()))
+
+        # Step 2: if auth is enabled, call the auth endpoint
+        self.timeout = timeout
+        self.call_credentials = None
+        cred_params = [c is not None for c in (user, password)]
+
+        if all(cred_params):
+            auth_request = etcdrpc.AuthenticateRequest(name=user, password=password)
+
+            # Create auth stub directly (no caching needed)
+            auth_stub = etcdrpc.AuthStub(self.channel)
+            resp = auth_stub.Authenticate(auth_request, self.timeout)
+            self.metadata = (("token", resp.token),)
+            self.call_credentials = grpc.metadata_call_credentials(
+                EtcdTokenCallCredentials(resp.token)
+            )
+
+        elif any(cred_params):
+            raise Exception(
+                "if using authentication credentials both user and password "
+                "must be specified."
+            )
+
+        self.transactions = Transactions()
+
+        # Initialize metrics
+        self.metrics = get_metrics_interface()
+
+    @property
+    def _current_endpoint_label(self):
+        return self._current_ep_label
+
+    @_current_endpoint_label.setter
+    def _current_endpoint_label(self, value):
+        with self._endpoint_lock:
+            self._current_ep_label = value
+
+    @property
+    def endpoint_in_use(self):
+        """Get the current endpoint in use."""
+        if self._current_endpoint_label is None:
+            return None
+        return self.endpoints[self._current_endpoint_label]
+
+    @property
+    def channel(self):
+        """
+        Get an available channel on the first node that's not failed.
+
+        Raises an exception if no node is available
+        """
+        with self._endpoint_lock:
+            try:
+                channel = self.endpoint_in_use.use()
+                # Record endpoint usage
+                self.metrics.record_endpoint_usage(str(self.endpoint_in_use))
+                return channel
+            except ValueError:
+                if not self.failover:
+                    raise
+            # We're failing over. We get the first non-failed channel
+            # we encounter, and use it by calling this function again,
+            # recursively
+            for label, endpoint in self.endpoints.items():
+                if endpoint.is_failed():
+                    continue
+                self._current_endpoint_label = label
+                channel = self.endpoint_in_use.use()
+                # Record endpoint usage for the new endpoint
+                self.metrics.record_endpoint_usage(str(self.endpoint_in_use))
+                return channel
+            raise exceptions.NoServerAvailableError(
+                "No endpoint available and not failed"
+            )
+
+    def _get_next_endpoint(self):
+        """Get the next endpoint based on load balancing strategy.
+
+        :returns: A tuple of (endpoint_label, endpoint) or (None, None) if no healthy endpoint
+        """
+        healthy_endpoints = [
+            (label, ep) for label, ep in self.endpoints.items() if not ep.is_failed()
+        ]
+
+        if not healthy_endpoints:
+            return None, None
+
+        if self.load_balancer == utils.LoadBalancerStrategy.ROUND_ROBIN:
+            # Round-robin: select next endpoint in order
+            self._rr_index = (self._rr_index + 1) % len(healthy_endpoints)
+            return healthy_endpoints[self._rr_index - 1]
+
+        elif self.load_balancer == utils.LoadBalancerStrategy.RANDOM:
+            # Random: select random endpoint
+            return random.choice(healthy_endpoints)
+
+        elif self.load_balancer == utils.LoadBalancerStrategy.STICKY:
+            # Sticky: keep current endpoint if healthy
+            current = self.endpoint_in_use
+            if current is not None and not current.is_failed():
+                return self._current_ep_label, current
+            # Fallback to first healthy endpoint
+            return healthy_endpoints[0]
+
+        else:
+            # PRIORITY (default): keep current endpoint if healthy
+            current = self.endpoint_in_use
+            if current is not None and not current.is_failed():
+                return self._current_ep_label, current
+            # Fallback to first healthy endpoint
+            return healthy_endpoints[0]
+
+    def _try_rebuild_channel(self, endpoint):
+        """Try to rebuild the channel, return True on success, False on failure."""
+        try:
+            endpoint.rebuild_channel()
+            return True
+        except Exception:
+            return False
+
+    def _get_channel(self):
+        """Get an available channel with automatic reconnection support.
+
+        Uses a two-phase locking strategy:
+        1. Quick status check (locked)
+        2. I/O operations outside the lock
+        3. Status update (locked again)
+
+        :returns: gRPC channel
+        :rtype: grpc.Channel
+        """
+        # Phase 1: Quick status check (locked)
+        with self._endpoint_lock:
+            endpoint = self.endpoint_in_use
+            if endpoint is None:
+                raise ValueError("No current endpoint")
+
+            # Check if endpoint has recovered health
+            if endpoint.is_failed() and endpoint.is_healthy():
+                # Recovered health, reset failure mark
+                endpoint.last_failed = 0
+                endpoint.in_use = True
+                self.metrics.record_endpoint_recovery(str(endpoint))
+                channel = endpoint.channel
+                self.metrics.record_endpoint_usage(str(endpoint))
+                return channel
+
+            needs_rebuild = endpoint.is_failed()
+
+        # Phase 2: I/O operations outside the lock (critical optimization)
+        rebuild_success = False
+        if needs_rebuild:
+            rebuild_success = self._try_rebuild_channel(endpoint)
+            if not rebuild_success:
+                raise exceptions.NoServerAvailableError("Failed to rebuild connection")
+
+        # Phase 3: Update status (acquire lock again)
+        with self._endpoint_lock:
+            # Double-check: confirm status wasn't modified by other threads during I/O
+            if endpoint.is_failed() and endpoint.is_healthy():
+                # Status has recovered
+                endpoint.last_failed = 0
+                endpoint.in_use = True
+                self.metrics.record_endpoint_recovery(str(endpoint))
+            elif needs_rebuild and not endpoint.is_failed():
+                # Status after successful rebuild
+                endpoint.in_use = True
+                self.metrics.record_endpoint_recovery(str(endpoint))
+
+            channel = endpoint.channel
+            self.metrics.record_endpoint_usage(str(endpoint))
+            return channel
+
+    def close(self):
+        """Call the GRPC channel close semantics."""
+        for endpoint in self.endpoints.values():
+            endpoint.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()
+
+    def _manage_grpc_errors(self, exc):
+        """Handle gRPC errors and convert to library exceptions."""
+        code = exc.code()
+        if code in _FAILED_EP_CODES:
+            # This sets the current node to failed.
+            # If others are available, they will be used on
+            # subsequent requests.
+            with self._endpoint_lock:
+                self.endpoint_in_use.fail()
+            # Record endpoint failure for monitoring
+            if hasattr(self, "monitor") and self.endpoint_in_use:
+                self.metrics.record_endpoint_failure(str(self.endpoint_in_use))
+        exception = _EXCEPTIONS_BY_CODE.get(code)
+        if exception is None:
+            raise exc  # Re-raise the original exception
+        raise exception()
+
+    def _should_retry(self, exc):
+        """Check if the error is retryable."""
+        code = getattr(exc, "code", lambda: None)()
+        if code in [
+            grpc.StatusCode.UNAVAILABLE,
+            grpc.StatusCode.DEADLINE_EXCEEDED,
+            grpc.StatusCode.INTERNAL,
+            grpc.StatusCode.RESOURCE_EXHAUSTED,
+        ]:
+            return True
+        return False
+
+    def _retry_with_backoff(self, func, *args, **kwargs):
+        """Retry function with exponential backoff."""
+        retries = 0
+        backoff = self.retry_backoff
+
+        while retries <= self.max_retries:
+            try:
+                return func(*args, **kwargs)
+            except Exception as exc:
+                if not self._should_retry(exc) or retries >= self.max_retries:
+                    raise
+
+                retries += 1
+                if retries > self.max_retries:
+                    raise
+
+                # Record retry
+                self.metrics.record_retry(func.__name__, "unknown")
+
+                # Exponential backoff with jitter
+                backoff_time = min(
+                    backoff * (2 ** (retries - 1)), self.retry_max_backoff
+                )
+                jitter = random.uniform(0, backoff_time * 0.1)
+                time.sleep(backoff_time + jitter)
+
+    def _build_get_range_request(
+        self,
+        key,
+        range_end=None,
+        limit=None,
+        revision=None,
+        sort_order=None,
+        sort_target="key",
+        serializable=False,
+        keys_only=False,
+        count_only=False,
+        min_mod_revision=None,
+        max_mod_revision=None,
+        min_create_revision=None,
+        max_create_revision=None,
+    ):
+        return RequestBuilder.build_get_range_request(
+            key=key,
+            range_end=range_end,
+            limit=limit,
+            revision=revision,
+            sort_order=sort_order,
+            sort_target=sort_target,
+            serializable=serializable,
+            keys_only=keys_only,
+            count_only=count_only,
+            min_mod_revision=min_mod_revision,
+            max_mod_revision=max_mod_revision,
+            min_create_revision=min_create_revision,
+            max_create_revision=max_create_revision,
+        )
+
+    @_sync_handle_errors
+    @monitor_request("kv.get_response")
+    @log_operation("kv.get")
+    def get_response(self, key, **kwargs):
+        """Get the value of a key from etcd."""
+        range_request = self._build_get_range_request(key, **kwargs)
+
+        # Create KV stub directly
+        kv_stub = etcdrpc.KVStub(self.channel)
+        return kv_stub.Range(
+            range_request,
+            self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+
+    def get(self, key, **kwargs):
+        """
+        Get the value of a key from etcd.
+
+        example usage:
+
+        .. code-block:: python
+
+            >>> import etcd3
+            >>> etcd = etcd3.client()
+            >>> etcd.get('/thing/key')
+            'hello world'
+
+        :param key: key in etcd to get
+        :returns: value of key and metadata
+        :rtype: bytes, ``KVMetadata``
+        """
+        range_response = self.get_response(key, **kwargs)
+        if range_response.count < 1:
+            return None, None
+        else:
+            kv = range_response.kvs.pop()
+            return kv.value, KVMetadata(kv, range_response.header)
+
+    @_sync_handle_errors
+    def get_prefix_response(self, key_prefix, **kwargs):
+        """Get a range of keys with a prefix."""
+        if any(kwarg in kwargs for kwarg in ("key", "range_end")):
+            raise TypeError("Don't use key or range_end with prefix")
+
+        range_request = self._build_get_range_request(
+            key=key_prefix,
+            range_end=utils.prefix_range_end(utils.to_bytes(key_prefix)),
+            **kwargs,
+        )
+
+        # Create KV stub directly
+        kv_stub = etcdrpc.KVStub(self.channel)
+        return kv_stub.Range(
+            range_request,
+            self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+
+    def get_prefix(self, key_prefix, **kwargs):
+        """
+        Get a range of keys with a prefix.
+
+        :param key_prefix: first key in range
+        :param keys_only: if True, retrieve only the keys, not the values
+
+        :returns: sequence of (value, metadata) tuples
+        """
+        range_response = self.get_prefix_response(key_prefix, **kwargs)
+        return (
+            (kv.value, KVMetadata(kv, range_response.header))
+            for kv in range_response.kvs
+        )
+
+    @_sync_handle_errors
+    def get_range_response(
+        self, range_start, range_end, sort_order=None, sort_target="key", **kwargs
+    ):
+        """Get a range of keys."""
+        range_request = self._build_get_range_request(
+            key=range_start,
+            range_end=range_end,
+            sort_order=sort_order,
+            sort_target=sort_target,
+            **kwargs,
+        )
+
+        # Create KV stub directly
+        kv_stub = etcdrpc.KVStub(self.channel)
+        return kv_stub.Range(
+            range_request,
+            self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+
+    def get_range(self, range_start, range_end, **kwargs):
+        """
+        Get a range of keys.
+
+        :param range_start: first key in range
+        :param range_end: last key in range
+        :returns: sequence of (value, metadata) tuples
+        """
+        range_response = self.get_range_response(range_start, range_end, **kwargs)
+        for kv in range_response.kvs:
+            yield (kv.value, KVMetadata(kv, range_response.header))
+
+    @_sync_handle_errors
+    def get_all_response(self, sort_order=None, sort_target="key", keys_only=False):
+        """Get all keys currently stored in etcd."""
+        # Use b'\x00' as the minimum key and b'\xff' * 16 as range_end to get all keys
+        # This works because etcd stores keys in sorted order by key bytes
+        # b'\x00' is the smallest non-empty key, and b'\xff' * 16 is a key that is
+        # larger than any valid key (max key length in etcd is 16 bytes)
+        range_request = self._build_get_range_request(
+            key=b"\x00",
+            range_end=b"\xff" * 16,
+            sort_order=sort_order,
+            sort_target=sort_target,
+            keys_only=keys_only,
+        )
+
+        # Create KV stub directly
+        kv_stub = etcdrpc.KVStub(self.channel)
+        return kv_stub.Range(
+            range_request,
+            self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+
+    def get_all(self, **kwargs):
+        """
+        Get all keys currently stored in etcd.
+
+        :param keys_only: if True, retrieve only the keys, not the values
+        :returns: sequence of (value, metadata) tuples
+        """
+        range_response = self.get_all_response(**kwargs)
+        for kv in range_response.kvs:
+            yield (kv.value, KVMetadata(kv, range_response.header))
+
+    def _build_put_request(
+        self,
+        key,
+        value=None,
+        lease=None,
+        prev_kv=False,
+        ignore_value=False,
+        ignore_lease=False,
+    ):
+        return RequestBuilder.build_put_request(
+            key=key,
+            value=value,
+            lease=lease,
+            prev_kv=prev_kv,
+            ignore_value=ignore_value,
+            ignore_lease=ignore_lease,
+        )
+
+    @_sync_handle_errors
+    @monitor_request("kv.put")
+    @log_operation("kv.put")
+    def put(
+        self,
+        key,
+        value=None,
+        lease=None,
+        prev_kv=False,
+        ignore_value=False,
+        ignore_lease=False,
+    ):
+        """
+        Save a value to etcd.
+
+        Example usage:
+
+        .. code-block:: python
+
+            >>> import etcd3
+            >>> etcd = etcd3.client()
+            >>> etcd.put('/thing/key', 'hello world')
+
+        :param key: key in etcd to set
+        :param value: value to set key to
+        :type value: bytes
+        :param lease: Lease to associate with this key.
+        :type lease: either :class:`.Lease`, or int (ID of lease)
+        :param prev_kv: return the previous key-value pair
+        :type prev_kv: bool
+        :param ignore_value: if True, update the key using the current value
+        :type ignore_value: bool
+        :param ignore_lease: if True, update the key using the current lease
+        :type ignore_lease: bool
+        :returns: a response containing a header and the prev_kv
+        :rtype: :class:`.rpc_pb2.PutResponse`
+        """
+        put_request = self._build_put_request(
+            key,
+            value=value,
+            lease=lease,
+            prev_kv=prev_kv,
+            ignore_value=ignore_value,
+            ignore_lease=ignore_lease,
+        )
+        # Create KV stub directly
+        kv_stub = etcdrpc.KVStub(self.channel)
+        return kv_stub.Put(
+            put_request,
+            self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+
+    @_sync_handle_errors
+    def put_if_not_exists(self, 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.
+
+        :param key: key in etcd to put
+        :param value: value to be written to key
+        :type value: bytes
+        :param lease: Lease to associate with this key.
+        :type lease: either :class:`.Lease`, or int (ID of lease)
+        :returns: state of transaction, ``True`` if the put was successful,
+                  ``False`` otherwise
+        :rtype: bool
+        """
+        status, _ = self.transaction(
+            compare=[self.transactions.create(key) == "0"],
+            success=[self.transactions.put(key, value, lease=lease)],
+            failure=[],
+        )
+
+        return status
+
+    @_sync_handle_errors
+    def replace(self, 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.
+
+        :param key: key in etcd to replace
+        :param initial_value: old value to replace
+        :type initial_value: bytes
+        :param new_value: new value of the key
+        :type new_value: bytes
+        :returns: status of transaction, ``True`` if the replace was
+                  successful, ``False`` otherwise
+        :rtype: bool
+        """
+        status, _ = self.transaction(
+            compare=[self.transactions.value(key) == initial_value],
+            success=[self.transactions.put(key, new_value)],
+            failure=[],
+        )
+
+        return status
+
+    def _build_delete_request(self, key, range_end=None, prev_kv=False):
+        return RequestBuilder.build_delete_request(
+            key=key,
+            range_end=range_end,
+            prev_kv=prev_kv,
+        )
+
+    @_sync_handle_errors
+    @monitor_request("kv.delete")
+    @log_operation("kv.delete")
+    def delete(self, key, prev_kv=False, return_response=False, range_end=None):
+        """
+        Delete a key or range of keys in etcd.
+
+        :param key: key in etcd to delete
+        :type key: str or bytes
+        :param prev_kv: return the deleted key-value pair
+        :type prev_kv: bool
+        :param return_response: return the full response
+        :type return_response: bool
+        :param range_end: End of the key range (for range deletes)
+        :type range_end: str or bytes, optional
+        :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_request = self._build_delete_request(
+            key, range_end=range_end, prev_kv=prev_kv
+        )
+        # Create KV stub directly
+        kv_stub = etcdrpc.KVStub(self.channel)
+        delete_response = kv_stub.DeleteRange(
+            delete_request,
+            self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+        if return_response:
+            return delete_response
+        return delete_response.deleted >= 1
+
+    @_sync_handle_errors
+    @monitor_request("kv.delete_prefix")
+    @log_operation("kv.delete_prefix")
+    def delete_prefix(self, prefix):
+        """Delete a range of keys with a prefix in etcd."""
+        delete_request = self._build_delete_request(
+            prefix, range_end=utils.prefix_range_end(utils.to_bytes(prefix))
+        )
+        # Create KV stub directly
+        kv_stub = etcdrpc.KVStub(self.channel)
+        return kv_stub.DeleteRange(
+            delete_request,
+            self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+
+    @_sync_handle_errors
+    @monitor_request("maintenance.status")
+    @log_operation("maintenance.status")
+    def status(self):
+        """Get the status of the responding member."""
+        status_request = etcdrpc.StatusRequest()
+        # Create maintenance stub directly
+        maintenance_stub = etcdrpc.MaintenanceStub(self.channel)
+        status_response = maintenance_stub.Status(
+            status_request,
+            self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+
+        for m in self.members:
+            if m.id == status_response.leader:
+                leader = m
+                break
+        else:
+            # raise exception?
+            leader = None
+
+        return Status(
+            status_response.version,
+            status_response.dbSize,
+            leader,
+            status_response.raftIndex,
+            status_response.raftTerm,
+        )
+
+    def _get_watcher(self):
+        """Create a new watcher instance."""
+        watchstub = etcdrpc.WatchStub(self.channel)
+        return watch.Watcher(
+            watchstub,
+            timeout=self.timeout,
+            call_credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+
+    @_sync_handle_errors
+    @monitor_request("watch.add_callback")
+    @log_operation("watch.add_callback")
+    def add_watch_callback(self, *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.
+
+        :param key: key to watch
+        :param callback: callback function
+
+        :returns: watch_id. Later it could be used for cancelling watch.
+        """
+        watcher = self._get_watcher()
+        try:
+            return watcher.add_callback(*args, **kwargs)
+        except queue.Empty:
+            raise exceptions.WatchTimedOut()
+
+    @_sync_handle_errors
+    def add_watch_prefix_callback(self, 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.
+
+        :param key_prefix: prefix to watch
+        :param callback: callback function
+
+        :returns: watch_id. Later it could be used for cancelling watch.
+        """
+        kwargs["range_end"] = utils.prefix_range_end(utils.to_bytes(key_prefix))
+
+        return self.add_watch_callback(key_prefix, callback, **kwargs)
+
+    @_sync_handle_errors
+    def watch_response(self, key, timeout=None, **kwargs):
+        """
+        Watch a key.
+
+        Example usage:
+
+        .. code-block:: python
+
+            responses_iterator, cancel = etcd.watch_response('/doot/key')
+            for response in responses_iterator:
+                print(response)
+
+        :param key: key to watch
+        :param timeout: (optional) timeout in seconds for each response.
+                       If None, blocks indefinitely.
+
+        :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.
+        """
+        response_queue = queue.Queue()
+
+        def callback(response):
+            response_queue.put(response)
+
+        watch_id = self.add_watch_callback(key, callback, **kwargs)
+        canceled = threading.Event()
+
+        def cancel():
+            canceled.set()
+            response_queue.put(None)
+            self.cancel_watch(watch_id)
+
+        def iterator():
+            try:
+                while not canceled.is_set():
+                    try:
+                        response = response_queue.get(timeout=timeout)
+                    except queue.Empty:
+                        # Timeout reached, exit iterator
+                        canceled.set()
+                        return
+                    if response is None:
+                        canceled.set()
+                    if isinstance(response, Exception):
+                        canceled.set()
+                        raise response
+                    if not canceled.is_set():
+                        yield response
+            except grpc.RpcError as exc:
+                self._manage_grpc_errors(exc)
+
+        return iterator(), cancel
+
+    def watch(self, key, timeout=None, **kwargs):
+        """
+        Watch a key.
+
+        Example usage:
+
+        .. code-block:: python
+
+            events_iterator, cancel = etcd.watch('/doot/key')
+            for event in events_iterator:
+                print(event)
+
+        :param key: key to watch
+        :param timeout: (optional) timeout in seconds for each response.
+                       If None, blocks indefinitely.
+
+        :returns: tuple of ``events_iterator`` and ``cancel``.
+                  Use ``events_iterator`` to get the events of key changes
+                  and ``cancel`` to cancel the watch request.
+        """
+        response_iterator, cancel = self.watch_response(key, timeout=timeout, **kwargs)
+        return utils.response_to_event_iterator(response_iterator), cancel
+
+    def watch_prefix_response(self, key_prefix, timeout=None, **kwargs):
+        """
+        Watch a range of keys with a prefix.
+
+        :param key_prefix: prefix to watch
+        :param timeout: (optional) timeout in seconds for each response.
+                       If None, blocks indefinitely.
+
+        :returns: tuple of ``responses_iterator`` and ``cancel``.
+        """
+        kwargs["range_end"] = utils.prefix_range_end(utils.to_bytes(key_prefix))
+        return self.watch_response(key_prefix, timeout=timeout, **kwargs)
+
+    def watch_prefix(self, key_prefix, timeout=None, **kwargs):
+        """
+        Watch a range of keys with a prefix.
+
+        :param key_prefix: prefix to watch
+        :param timeout: (optional) timeout in seconds for each response.
+                       If None, blocks indefinitely.
+
+        :returns: tuple of ``events_iterator`` and ``cancel``.
+        """
+        kwargs["range_end"] = utils.prefix_range_end(utils.to_bytes(key_prefix))
+        return self.watch(key_prefix, timeout=timeout, **kwargs)
+
+    @_sync_handle_errors
+    def watch_once_response(self, 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.
+
+        :param key: key to watch
+        :param timeout: (optional) timeout in seconds.
+
+        :returns: ``WatchResponse``
+        """
+        response_queue = queue.Queue()
+
+        def callback(response):
+            response_queue.put(response)
+
+        watch_id = self.add_watch_callback(key, callback, **kwargs)
+
+        try:
+            return response_queue.get(timeout=timeout)
+        except queue.Empty:
+            raise exceptions.WatchTimedOut()
+        finally:
+            self.cancel_watch(watch_id)
+
+    def watch_once(self, 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.
+
+        :param key: key to watch
+        :param timeout: (optional) timeout in seconds.
+
+        :returns: ``Event``
+        """
+        response = self.watch_once_response(key, timeout=timeout, **kwargs)
+        if not response.events:
+            raise IndexError("No events in watch response")
+        return response.events[0]
+
+    def watch_prefix_once_response(self, 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.
+        """
+        kwargs["range_end"] = utils.prefix_range_end(utils.to_bytes(key_prefix))
+        return self.watch_once_response(key_prefix, timeout=timeout, **kwargs)
+
+    def watch_prefix_once(self, 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.
+        """
+        kwargs["range_end"] = utils.prefix_range_end(utils.to_bytes(key_prefix))
+        return self.watch_once(key_prefix, timeout=timeout, **kwargs)
+
+    @_sync_handle_errors
+    @monitor_request("watch.cancel")
+    @log_operation("watch.cancel")
+    def cancel_watch(self, watch_id):
+        """
+        Stop watching a key or range of keys.
+
+        :param watch_id: watch_id returned by ``add_watch_callback`` method
+        """
+        watcher = self._get_watcher()
+        watcher.cancel(watch_id)
+
+    def _ops_to_requests(self, ops):
+        """
+        Return a list of grpc requests.
+
+        Returns list from an input list of etcd3.transactions.{Put, Get,
+        Delete, Txn} objects.
+        """
+        request_ops = []
+        for op in ops:
+            if isinstance(op, transactions.Put):
+                request = self._build_put_request(
+                    op.key,
+                    op.value,
+                    op.lease,
+                    op.prev_kv,
+                    op.ignore_value,
+                    op.ignore_lease,
+                )
+                request_op = etcdrpc.RequestOp(request_put=request)
+                request_ops.append(request_op)
+
+            elif isinstance(op, transactions.Get):
+                request = self._build_get_range_request(op.key, op.range_end)
+                request_op = etcdrpc.RequestOp(request_range=request)
+                request_ops.append(request_op)
+
+            elif isinstance(op, transactions.Delete):
+                request = self._build_delete_request(op.key, op.range_end, op.prev_kv)
+                request_op = etcdrpc.RequestOp(request_delete_range=request)
+                request_ops.append(request_op)
+
+            elif isinstance(op, transactions.Txn):
+                compare = [c.build_message() for c in op.compare]
+                success_ops = self._ops_to_requests(op.success)
+                failure_ops = self._ops_to_requests(op.failure)
+                request = etcdrpc.TxnRequest(
+                    compare=compare, success=success_ops, failure=failure_ops
+                )
+                request_op = etcdrpc.RequestOp(request_txn=request)
+                request_ops.append(request_op)
+
+            else:
+                raise Exception("Unknown request class {}".format(op.__class__))
+        return request_ops
+
+    @_sync_handle_errors
+    @monitor_request("kv.transaction")
+    @log_operation("kv.transaction")
+    def transaction(self, compare, success=None, failure=None):
+        """
+        Perform a transaction.
+
+        Example usage:
+
+        .. code-block:: python
+
+            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')
+                ]
+            )
+
+        :param compare: A list of comparisons to make
+        :param success: A list of operations to perform if all the comparisons
+                        are true
+        :param failure: A list of operations to perform if any of the
+                        comparisons are false
+        :return: A tuple of (operation status, responses)
+        """
+        compare = [c.build_message() for c in compare]
+
+        success_ops = self._ops_to_requests(success)
+        failure_ops = self._ops_to_requests(failure)
+
+        transaction_request = etcdrpc.TxnRequest(
+            compare=compare, success=success_ops, failure=failure_ops
+        )
+
+        # Create KV stub directly
+        kv_stub = etcdrpc.KVStub(self.channel)
+        txn_response = kv_stub.Txn(
+            transaction_request,
+            self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+
+        responses = []
+        for response in txn_response.responses:
+            response_type = response.WhichOneof("response")
+            if response_type == "response_range":
+                responses.append(
+                    [
+                        (kv.value, KVMetadata(kv, txn_response.header))
+                        for kv in response.response_range.kvs
+                    ]
+                )
+            elif response_type == "response_put":
+                responses.append(response.response_put)
+            elif response_type == "response_delete_range":
+                responses.append(response.response_delete_range)
+            elif response_type == "response_txn":
+                responses.append(response.response_txn)
+            else:
+                # Unknown response type - raise error for visibility
+                raise exceptions.InternalServerError(
+                    f"Unknown transaction response type: {response_type}"
+                )
+
+        return txn_response.succeeded, responses
+
+    @_sync_handle_errors
+    @monitor_request("lease.create")
+    @log_operation("lease.create")
+    def lease(self, 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.
+
+        :param ttl: Requested time to live
+        :param lease_id: Requested ID for the lease
+
+        :returns: new lease
+        :rtype: :class:`.Lease`
+        """
+        lease_grant_request = etcdrpc.LeaseGrantRequest(TTL=ttl, ID=lease_id)
+        # Create lease stub directly
+        lease_stub = etcdrpc.LeaseStub(self.channel)
+        lease_grant_response = lease_stub.LeaseGrant(
+            lease_grant_request,
+            self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+        return leases.Lease(
+            lease_id=lease_grant_response.ID,
+            ttl=lease_grant_response.TTL,
+            etcd_client=self,
+        )
+
+    @_sync_handle_errors
+    @monitor_request("lease.revoke")
+    @log_operation("lease.revoke")
+    def revoke_lease(self, lease_id):
+        """
+        Revoke a lease.
+
+        :param lease_id: ID of the lease to revoke.
+        """
+        lease_revoke_request = etcdrpc.LeaseRevokeRequest(ID=lease_id)
+        # Create lease stub directly
+        lease_stub = etcdrpc.LeaseStub(self.channel)
+        lease_stub.LeaseRevoke(
+            lease_revoke_request,
+            self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+
+    @_sync_handle_keepalive_errors
+    def refresh_lease(
+        self,
+        lease_id,
+        max_consecutive_errors=10,
+        base_retry_delay=1.0,
+        max_retry_delay=30.0,
+    ):
+        """Refresh a lease continuously with automatic reconnection.
+
+        This method creates a long-lived gRPC stream that sends keep-alive requests
+        periodically to maintain the lease alive. The caller should iterate over
+        this generator as long as they want the lease to be kept alive.
+
+        The stream will yield a response whenever the lease TTL is refreshed by
+        the server (typically when TTL drops below a threshold).
+
+        This method automatically retries on connection errors, allowing recovery
+        from temporary ETCD server restarts (as long as the lease hasn't expired).
+
+        :param lease_id: ID of the lease to refresh
+        :param max_consecutive_errors: Maximum consecutive errors before giving up (default: 10)
+        :param base_retry_delay: Base retry delay in seconds (default: 1.0)
+        :param max_retry_delay: Maximum retry delay in seconds (default: 30.0)
+
+        Raises:
+            grpc.RpcError: When connection errors exceed max retry attempts or
+                          lease is permanently not found
+        """
+        import logging
+
+        logger = logging.getLogger(__name__)
+
+        consecutive_errors = 0
+
+        while True:
+            try:
+                lease_stub = etcdrpc.LeaseStub(self.channel)
+                keep_alive_request = etcdrpc.LeaseKeepAliveRequest(ID=lease_id)
+                # Note: We use iter([request]) for each iteration. The gRPC stream
+                # remains open, and etcd server will send keep-alive responses
+                # periodically when the TTL approaches expiration.
+                for response in lease_stub.LeaseKeepAlive(
+                    iter([keep_alive_request]),
+                    self.timeout,
+                    credentials=self.call_credentials,
+                    metadata=self.metadata,
+                ):
+                    # Reset error count on successful response
+                    consecutive_errors = 0
+                    yield response
+            except grpc.RpcError as exc:
+                code = exc.code()
+
+                # Lease not found (expired or revoked) - permanent failure, stop retrying
+                if code == grpc.StatusCode.NOT_FOUND:
+                    logger.debug(f"Lease {lease_id} not found, stopping keepalive")
+                    break
+
+                # Connection errors - retry with exponential backoff
+                if code in (
+                    grpc.StatusCode.UNAVAILABLE,
+                    grpc.StatusCode.DEADLINE_EXCEEDED,
+                    grpc.StatusCode.INTERNAL,
+                ):
+                    consecutive_errors += 1
+
+                    if consecutive_errors >= max_consecutive_errors:
+                        logger.error(
+                            f"Lease {lease_id} keepalive failed after "
+                            f"{max_consecutive_errors} consecutive errors"
+                        )
+                        raise  # Exceeded max retries, propagate the error
+
+                    # Exponential backoff with jitter
+                    retry_delay = min(
+                        base_retry_delay * (2 ** (consecutive_errors - 1)),
+                        max_retry_delay,
+                    )
+                    jitter = random.uniform(0, retry_delay * 0.1)
+                    actual_delay = retry_delay + jitter
+
+                    logger.warning(
+                        f"Lease {lease_id} keepalive connection error ({code}), "
+                        f"retrying in {actual_delay:.1f}s "
+                        f"(attempt {consecutive_errors}/{max_consecutive_errors})"
+                    )
+
+                    time.sleep(actual_delay)
+                    continue  # Retry the loop
+
+                # Other errors - propagate to let the decorator handle them
+                raise
+            except GeneratorExit:
+                # Generator was closed externally (e.g., garbage collected or iteration stopped)
+                break
+
+    @_sync_handle_errors
+    @monitor_request("lease.get_info")
+    @log_operation("lease.get_info")
+    def get_lease_info(self, lease_id):
+        # only available in etcd v3.1.0 and later
+        ttl_request = etcdrpc.LeaseTimeToLiveRequest(ID=lease_id, keys=True)
+        # Create lease stub directly
+        lease_stub = etcdrpc.LeaseStub(self.channel)
+        return lease_stub.LeaseTimeToLive(
+            ttl_request,
+            self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+
+    @_sync_handle_errors
+    def lock(self, name, ttl=60):
+        """
+        Create a new lock.
+
+        :param name: name of the lock
+        :type name: string or bytes
+        :param ttl: length of time for the lock to live for in seconds. The
+                    lock will be released after this time elapses, unless
+                    refreshed
+        :type ttl: int
+        :returns: new lock
+        :rtype: :class:`.Lock`
+        """
+        return locks.Lock(name, ttl=ttl, etcd_client=self)
+
+    @_sync_handle_errors
+    def add_member(self, urls):
+        """
+        Add a member into the cluster.
+
+        :returns: new member
+        :rtype: :class:`.Member`
+        """
+        member_add_request = etcdrpc.MemberAddRequest(peerURLs=urls)
+
+        # Create cluster stub directly
+        cluster_stub = etcdrpc.ClusterStub(self.channel)
+        member_add_response = cluster_stub.MemberAdd(
+            member_add_request,
+            self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+
+        member = member_add_response.member
+        return etcd3.members.Member(
+            member.ID, member.name, member.peerURLs, member.clientURLs, etcd_client=self
+        )
+
+    @_sync_handle_errors
+    def remove_member(self, member_id):
+        """
+        Remove an existing member from the cluster.
+
+        :param member_id: ID of the member to remove
+        """
+        member_rm_request = etcdrpc.MemberRemoveRequest(ID=member_id)
+        # Create cluster stub directly
+        cluster_stub = etcdrpc.ClusterStub(self.channel)
+        cluster_stub.MemberRemove(
+            member_rm_request,
+            self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+
+    @_sync_handle_errors
+    def update_member(self, member_id, peer_urls):
+        """
+        Update the configuration of an existing member in the cluster.
+
+        :param member_id: ID of the member to update
+        :param peer_urls: new list of peer urls the member will use to
+                          communicate with the cluster
+        """
+        member_update_request = etcdrpc.MemberUpdateRequest(
+            ID=member_id, peerURLs=peer_urls
+        )
+        # Create cluster stub directly
+        cluster_stub = etcdrpc.ClusterStub(self.channel)
+        cluster_stub.MemberUpdate(
+            member_update_request,
+            self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+
+    @property
+    def members(self):
+        """
+        List of all members associated with the cluster.
+
+        :type: sequence of :class:`.Member`
+
+        """
+        member_list_request = etcdrpc.MemberListRequest()
+        # Create cluster stub directly
+        cluster_stub = etcdrpc.ClusterStub(self.channel)
+        member_list_response = cluster_stub.MemberList(
+            member_list_request,
+            self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+
+        for member in member_list_response.members:
+            yield etcd3.members.Member(
+                member.ID,
+                member.name,
+                member.peerURLs,
+                member.clientURLs,
+                etcd_client=self,
+            )
+
+    @_sync_handle_errors
+    @monitor_request("maintenance.compact")
+    @log_operation("maintenance.compact")
+    def compact(self, 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.
+
+        :param revision: revision for the compaction operation
+        :param 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
+        """
+        compact_request = etcdrpc.CompactionRequest(
+            revision=revision, physical=physical
+        )
+        # Create KV stub directly
+        kv_stub = etcdrpc.KVStub(self.channel)
+        kv_stub.Compact(
+            compact_request,
+            self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+
+    @_sync_handle_errors
+    @monitor_request("maintenance.defragment")
+    @log_operation("maintenance.defragment")
+    def defragment(self):
+        """Defragment a member's backend database to recover storage space."""
+        defrag_request = etcdrpc.DefragmentRequest()
+        # Create maintenance stub directly
+        maintenance_stub = etcdrpc.MaintenanceStub(self.channel)
+        maintenance_stub.Defragment(
+            defrag_request,
+            self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+
+    @_sync_handle_errors
+    def hash(self):
+        """
+        Return the hash of the local KV state.
+
+        :returns: kv state hash
+        :rtype: int
+        """
+        hash_request = etcdrpc.HashRequest()
+        # Create maintenance stub directly
+        maintenance_stub = etcdrpc.MaintenanceStub(self.channel)
+        return maintenance_stub.Hash(hash_request).hash
+
+    def _build_alarm_request(self, alarm_action, member_id, alarm_type):
+        alarm_request = etcdrpc.AlarmRequest()
+
+        if alarm_action == "get":
+            alarm_request.action = etcdrpc.AlarmRequest.GET
+        elif alarm_action == "activate":
+            alarm_request.action = etcdrpc.AlarmRequest.ACTIVATE
+        elif alarm_action == "deactivate":
+            alarm_request.action = etcdrpc.AlarmRequest.DEACTIVATE
+        else:
+            raise ValueError("Unknown alarm action: {}".format(alarm_action))
+
+        alarm_request.memberID = member_id
+
+        if alarm_type == "none":
+            alarm_request.alarm = etcdrpc.NONE
+        elif alarm_type == "no space":
+            alarm_request.alarm = etcdrpc.NOSPACE
+        else:
+            raise ValueError("Unknown alarm type: {}".format(alarm_type))
+
+        return alarm_request
+
+    @_sync_handle_errors
+    def create_alarm(self, 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.
+
+        :param 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 :class:`.Alarm`
+        """
+        alarm_request = self._build_alarm_request("activate", member_id, "no space")
+        # Create maintenance stub directly
+        maintenance_stub = etcdrpc.MaintenanceStub(self.channel)
+        alarm_response = maintenance_stub.Alarm(
+            alarm_request,
+            self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+
+        return [Alarm(alarm.alarm, alarm.memberID) for alarm in alarm_response.alarms]
+
+    @_sync_handle_errors
+    def list_alarms(self, member_id=0, alarm_type="none"):
+        """List the activated alarms.
+
+        :param member_id:
+        :param 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 :class:`.Alarm`
+        """
+        alarm_request = self._build_alarm_request("get", member_id, alarm_type)
+        # Create maintenance stub directly
+        maintenance_stub = etcdrpc.MaintenanceStub(self.channel)
+        alarm_response = maintenance_stub.Alarm(
+            alarm_request,
+            self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+
+        for alarm in alarm_response.alarms:
+            yield Alarm(alarm.alarm, alarm.memberID)
+
+    @_sync_handle_errors
+    def disarm_alarm(self, member_id=0):
+        """Cancel an alarm.
+
+        :param 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 :class:`.Alarm`
+        """
+        alarm_request = self._build_alarm_request("deactivate", member_id, "no space")
+        # Create maintenance stub directly
+        maintenance_stub = etcdrpc.MaintenanceStub(self.channel)
+        alarm_response = maintenance_stub.Alarm(
+            alarm_request,
+            self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+
+        return [Alarm(alarm.alarm, alarm.memberID) for alarm in alarm_response.alarms]
+
+    @_sync_handle_errors
+    def snapshot(self, file_obj):
+        """Take a snapshot of the database.
+
+        :param file_obj: A file-like object to write the database contents in.
+        """
+        snapshot_request = etcdrpc.SnapshotRequest()
+        # Create maintenance stub directly
+        maintenance_stub = etcdrpc.MaintenanceStub(self.channel)
+        snapshot_response = maintenance_stub.Snapshot(
+            snapshot_request,
+            self.timeout,
+            credentials=self.call_credentials,
+            metadata=self.metadata,
+        )
+
+        for response in snapshot_response:
+            file_obj.write(response.blob)
+
+    def batch_put(self, items, atomic=True):
+        """Batch put multiple key-value pairs.
+
+        By default, this method executes all puts as a single atomic transaction,
+        ensuring either all operations succeed or none do. If atomic=False,
+        operations are executed sequentially.
+
+        :param items: Iterable of (key, value) tuples to put
+        :type items: Iterable[tuple[str | bytes, str | bytes]]
+        :param atomic: If True (default), execute as atomic transaction.
+        :type atomic: bool
+        :returns: Number of successful operations (atomic=True: either all or none)
+        :rtype: int
+        :raises BatchOperationError: If atomic=True and some operations fail
+        """
+        # Convert to list to allow multiple iterations
+        items_list = list(items)
+        if not items_list:
+            return 0
+
+        if atomic:
+            # Use atomic transaction for all operations
+            success_ops = [transactions.Put(key, value) for key, value in items_list]
+            # Use a dummy compare that always succeeds (create_revision > -1 is always true)
+            compare = [transactions.Create(key) > -1 for key, _ in items_list]
+
+            try:
+                success, _ = self.transaction(
+                    compare=compare,
+                    success=success_ops,
+                    failure=[],
+                )
+                if success:
+                    return len(items_list)
+                else:
+                    raise exceptions.BatchOperationError(
+                        f"Atomic batch put failed for {len(items_list)} items"
+                    )
+            except Exception as exc:
+                if isinstance(exc, exceptions.BatchOperationError):
+                    raise
+                raise exceptions.BatchOperationError(
+                    f"Batch put failed: {exc}"
+                ) from exc
+        else:
+            # Non-atomic: sequential execution
+            success_count = 0
+            for key, value in items_list:
+                try:
+                    self.put(key, value)
+                    success_count += 1
+                except Exception:
+                    pass  # Continue with next item
+            return success_count
+
+    def batch_delete(self, keys, atomic=True):
+        """Batch delete multiple keys.
+
+        By default, this method executes all deletes as a single atomic transaction,
+        ensuring either all operations succeed or none do. If atomic=False,
+        operations are executed sequentially.
+
+        :param keys: Iterable of keys to delete
+        :type keys: Iterable[str | bytes]
+        :param atomic: If True (default), execute as atomic transaction.
+        :type atomic: bool
+        :returns: Number of successful operations (atomic=True: either all or none)
+        :rtype: int
+        :raises BatchOperationError: If atomic=True and some operations fail
+        """
+        # Convert to list to allow multiple iterations
+        keys_list = list(keys)
+        if not keys_list:
+            return 0
+
+        if atomic:
+            # Use atomic transaction for all operations
+            delete_ops = [transactions.Delete(key) for key in keys_list]
+            # Use a dummy compare that always succeeds (create_revision > -1 is always true)
+            compare = [transactions.Create(key) > -1 for key in keys_list]
+
+            try:
+                success, _ = self.transaction(
+                    compare=compare,
+                    success=delete_ops,
+                    failure=[],
+                )
+                if success:
+                    return len(keys_list)
+                else:
+                    raise exceptions.BatchOperationError(
+                        f"Atomic batch delete failed for {len(keys_list)} keys"
+                    )
+            except Exception as exc:
+                if isinstance(exc, exceptions.BatchOperationError):
+                    raise
+                raise exceptions.BatchOperationError(
+                    f"Batch delete failed: {exc}"
+                ) from exc
+        else:
+            # Non-atomic: sequential execution
+            success_count = 0
+            for key in keys_list:
+                try:
+                    result = self.delete(key)
+                    if isinstance(result, bool):
+                        if result:
+                            success_count += 1
+                    else:
+                        success_count += result
+                except Exception:
+                    pass  # Continue with next item
+            return success_count
+
+    def put_many(self, items, timeout=None):
+        """Put multiple key-value pairs sequentially.
+
+        This is a simpler interface for batch puts that handles all
+        operations sequentially.
+
+        :param items: Dict of {key: value} pairs or iterable of (key, value) tuples
+        :type items: dict or Iterable[tuple]
+        :param timeout: Optional timeout for each individual put operation
+        :type timeout: float
+        :returns: Tuple of (success_count, failed_keys)
+        :rtype: tuple[int, list]
+        """
+        if isinstance(items, dict):
+            items = list(items.items())
+
+        success_count = 0
+        failed_keys = []
+
+        for key, value in items:
+            try:
+                self.put(key, value)
+                success_count += 1
+            except Exception as exc:
+                failed_keys.append((key, exc))
+
+        return success_count, failed_keys
+
+
+class Etcd3Client(MultiEndpointEtcd3Client):
+    """
+    etcd v3 API client.
+
+    :param config: ClientConfig object with client configuration
+    :param host: Host to connect to, 'localhost' if not specified
+    :type host: str, optional
+    :param port: Port to connect to on host, 2379 if not specified
+    :type port: int, optional
+    :param ca_cert: Filesystem path of etcd CA certificate
+    :type ca_cert: str or os.PathLike, optional
+    :param cert_key: Filesystem path of client key
+    :type cert_key: str or os.PathLike, optional
+    :param cert_cert: Filesystem path of client certificate
+    :type cert_cert: str or os.PathLike, optional
+    :param timeout: Timeout for all RPC in seconds
+    :type timeout: int or float, optional
+    :param user: Username for authentication
+    :type user: str, optional
+    :param password: Password for authentication
+    :type password: str, optional
+    :param dict grpc_options: Additional gRPC options
+    :type grpc_options: dict, optional
+    """
+
+    def __init__(
+        self,
+        config=None,
+        host="localhost",
+        port=2379,
+        ca_cert=None,
+        cert_key=None,
+        cert_cert=None,
+        timeout=None,
+        user=None,
+        password=None,
+        grpc_options=None,
+    ):
+        # Use config object if provided
+        if config is not None:
+            host = config.host
+            port = config.port
+            ca_cert = config.ca_cert
+            cert_key = config.cert_key
+            cert_cert = config.cert_cert
+            timeout = config.timeout
+            user = config.user
+            password = config.password
+            grpc_options = config.grpc_options
+
+        # Step 1: verify credentials
+        cert_params = [c is not None for c in (cert_cert, cert_key)]
+        if ca_cert is not None:
+            if all(cert_params):
+                credentials = get_secure_creds(ca_cert, cert_key, cert_cert)
+                self.uses_secure_channel = True
+            elif any(cert_params):
+                # some of the cert parameters are set
+                raise ValueError(
+                    "to use a secure channel ca_cert is required by itself, "
+                    "or cert_cert and cert_key must both be specified."
+                )
+            else:
+                credentials = get_secure_creds(ca_cert, None, None)
+                self.uses_secure_channel = True
+        else:
+            self.uses_secure_channel = False
+            credentials = None
+
+        # Step 2: create Endpoint
+        ep = Endpoint(
+            host,
+            port,
+            secure=self.uses_secure_channel,
+            creds=credentials,
+            opts=grpc_options,
+        )
+
+        super(Etcd3Client, self).__init__(
+            endpoints=[ep], timeout=timeout, user=user, password=password
+        )
+
+
+def client(
+    config=None,
+    host="localhost",
+    port=2379,
+    ca_cert=None,
+    cert_key=None,
+    cert_cert=None,
+    timeout=None,
+    user=None,
+    password=None,
+    grpc_options=None,
+):
+    """Return an instance of an Etcd3Client.
+
+    :param config: ClientConfig object with client configuration
+    :param host: etcd host (ignored if config is provided)
+    :type host: str, optional
+    :param port: etcd port (ignored if config is provided)
+    :type port: int, optional
+    :param ca_cert: CA certificate path (ignored if config is provided)
+    :type ca_cert: str, optional
+    :param cert_key: client certificate key path (ignored if config is provided)
+    :type cert_key: str, optional
+    :param cert_cert: client certificate path (ignored if config is provided)
+    :type cert_cert: str, optional
+    :param timeout: request timeout in seconds (ignored if config is provided)
+    :type timeout: int or float, optional
+    :param user: username for authentication (ignored if config is provided)
+    :type user: str, optional
+    :param password: password for authentication (ignored if config is provided)
+    :type password: str, optional
+    :param grpc_options: additional gRPC options (ignored if config is provided)
+    :type grpc_options: dict[str, Any], optional
+    :return: Etcd3Client instance
+    """
+    # Auto-initialize observability
+    from etcd3.observability import auto_init
+
+    auto_init()
+
+    return Etcd3Client(
+        config=config,
+        host=host,
+        port=port,
+        ca_cert=ca_cert,
+        cert_key=cert_key,
+        cert_cert=cert_cert,
+        timeout=timeout,
+        user=user,
+        password=password,
+        grpc_options=grpc_options,
+    )