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

etcd3/endpoint.py

@@ -0,0 +1,79 @@
+"""Base endpoint implementation for etcd3 client.
+
+This module provides the BaseEndpoint class that contains shared logic
+for both synchronous and asynchronous endpoints.
+"""
+
+import grpc
+import time
+
+
+class BaseEndpoint:
+    """Base endpoint with shared logic.
+
+    :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
+    ):
+        self.host = host
+        self.netloc = f"{host}:{port}"
+        self.secure = secure
+        self.protocol = "https" if secure else "http"
+        if self.secure and creds is None:
+            raise ValueError("Please set TLS credentials for secure connections")
+        self.credentials = creds
+        self.time_retry = time_retry
+        self.opts = opts
+        self.in_use = False
+        self.last_failed = 0
+        self.channel = None  # To be set by subclasses
+
+    def fail(self):
+        """Transition the endpoint to a failed state."""
+        self.in_use = False
+        self.last_failed = time.time()
+
+    def use(self):
+        """Transition the endpoint to an active state."""
+        if self.is_failed():
+            raise ValueError("Trying to use a failed node")
+        self.in_use = True
+        self.last_failed = 0
+        return self.channel
+
+    def is_failed(self):
+        """Check if the current endpoint is failed."""
+        return (time.time() - self.last_failed) < self.time_retry
+
+    def is_healthy(self):
+        """Check if the endpoint is healthy.
+
+        Only READY state is considered healthy. CONNECTING state is excluded
+        to ensure the connection is fully established before use.
+
+        :returns: True if the endpoint is healthy (READY state)
+        :rtype: bool
+        """
+        if self.channel is None:
+            return False
+        try:
+            state = self.channel.get_state()
+            # Only READY is considered healthy, not CONNECTING
+            return state == grpc.ChannelConnectivity.READY
+        except Exception:
+            return False
+
+    def __str__(self):
+        return f"Endpoint({self.protocol}://{self.netloc})"

etcd3/events.py

@@ -0,0 +1,40 @@
+class Event(object):
+    def __init__(self, event):
+        self.key = event.kv.key
+        self._event = event
+
+    def __getattr__(self, name):
+        if name.startswith("prev_"):
+            return getattr(self._event.prev_kv, name[5:])
+        return getattr(self._event.kv, name)
+
+    def __str__(self):
+        return "{type} key={key} value={value}".format(
+            type=self.__class__, key=self.key, value=self.value
+        )
+
+
+class PutEvent(Event):
+    pass
+
+
+class DeleteEvent(Event):
+    pass
+
+
+def new_event(event):
+    """
+    Wrap a raw gRPC event in a friendlier containing class.
+
+    This picks the appropriate class from one of PutEvent or DeleteEvent and
+    returns a new instance.
+    """
+    op_name = event.EventType.DESCRIPTOR.values_by_number[event.type].name
+    if op_name == "PUT":
+        cls = PutEvent
+    elif op_name == "DELETE":
+        cls = DeleteEvent
+    else:
+        raise Exception("Invalid op_name")
+
+    return cls(event)

etcd3/exceptions.py

@@ -0,0 +1,47 @@
+class Etcd3Exception(Exception):
+    pass
+
+
+class WatchTimedOut(Etcd3Exception):
+    pass
+
+
+class InternalServerError(Etcd3Exception):
+    pass
+
+
+class ConnectionFailedError(Etcd3Exception):
+    def __str__(self):
+        return "etcd connection failed"
+
+
+class ConnectionTimeoutError(Etcd3Exception):
+    def __str__(self):
+        return "etcd connection timeout"
+
+
+class PreconditionFailedError(Etcd3Exception):
+    pass
+
+
+class RevisionCompactedError(Etcd3Exception):
+    def __init__(self, compacted_revision):
+        self.compacted_revision = compacted_revision
+        super(RevisionCompactedError, self).__init__()
+
+    def __str__(self):
+        return "etcd revision {} has been compacted".format(self.compacted_revision)
+
+
+class NoServerAvailableError(Etcd3Exception):
+    pass
+
+
+class LockReleaseError(Etcd3Exception):
+    """Raised when a lock release operation fails."""
+    pass
+
+
+class BatchOperationError(Etcd3Exception):
+    """Raised when a batch operation fails."""
+    pass

etcd3/exporters/__init__.py

@@ -0,0 +1,18 @@
+"""Exporters for etcd3 observability.
+
+This package provides various exporters for metrics and traces.
+"""
+
+from etcd3.exporters.prometheus import (
+    EtcdPrometheusExporter,
+    get_exporter,
+    init_exporter,
+    is_prometheus_available,
+)
+
+__all__ = [
+    "EtcdPrometheusExporter",
+    "get_exporter",
+    "init_exporter",
+    "is_prometheus_available",
+]

etcd3/exporters/prometheus.py

@@ -0,0 +1,365 @@
+"""Prometheus metrics exporter for etcd3 client.
+
+This module provides Prometheus-compatible metrics export for the etcd3 client,
+supporting various metric types including counters, gauges, and histograms.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Optional
+import logging
+
+if TYPE_CHECKING:
+    from prometheus_client import CollectorRegistry
+
+try:
+    from prometheus_client import (
+        Counter,
+        Gauge,
+        Histogram,
+        CollectorRegistry,
+        generate_latest,
+    )
+
+    PROMETHEUS_AVAILABLE = True
+except ImportError:
+    PROMETHEUS_AVAILABLE = False
+
+
+logger = logging.getLogger("etcd3.exporters")
+
+
+class EtcdPrometheusExporter:
+    """Prometheus metrics exporter for etcd3 client.
+
+    Provides Prometheus-compatible metrics with labels for operation,
+    endpoint, and status dimensions.
+
+    Example:
+        >>> exporter = EtcdPrometheusExporter()
+        >>> exporter.record_request("kv.get", endpoint="localhost:2379", duration=0.001)
+        >>> print(exporter.metrics())  # Get Prometheus format output
+    """
+
+    def __init__(self, registry: Optional[CollectorRegistry] = None):
+        """Initialize Prometheus exporter.
+
+        Args:
+            registry: Optional Prometheus registry. Uses default if None.
+        """
+        if not PROMETHEUS_AVAILABLE:
+            raise ImportError(
+                "prometheus_client is required for metrics export. "
+                "Install with: pip install prometheus-client"
+            )
+
+        self._registry = registry or CollectorRegistry()
+
+        # Request metrics
+        self._request_counter = Counter(
+            "etcd3_requests_total",
+            "Total number of requests",
+            ["operation", "endpoint", "status"],
+            registry=self._registry,
+        )
+
+        self._request_duration = Histogram(
+            "etcd3_request_duration_seconds",
+            "Request duration in seconds",
+            ["operation", "endpoint"],
+            buckets=[0.001, 0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0],
+            registry=self._registry,
+        )
+
+        # Error metrics
+        self._error_counter = Counter(
+            "etcd3_errors_total",
+            "Total number of errors",
+            ["operation", "endpoint", "error_type"],
+            registry=self._registry,
+        )
+
+        # Retry metrics
+        self._retry_counter = Counter(
+            "etcd3_retries_total",
+            "Total number of retries",
+            ["operation", "endpoint"],
+            registry=self._registry,
+        )
+
+        # Connection metrics
+        self._connection_gauge = Gauge(
+            "etcd3_connections",
+            "Number of active connections",
+            ["endpoint", "state"],
+            registry=self._registry,
+        )
+
+    def record_request(
+        self,
+        operation: str,
+        endpoint: str,
+        duration: float,
+        status: str = "success",
+    ):
+        """Record a request metric.
+
+        Args:
+            operation: Operation name (e.g., "kv.get", "lease.grant")
+            endpoint: Endpoint address
+            duration: Request duration in seconds
+            status: Request status ("success" or "error")
+        """
+        status_label = "success" if status in ("success", "ok", 200, 0) else "error"
+
+        self._request_counter.labels(
+            operation=operation,
+            endpoint=endpoint,
+            status=status_label,
+        ).inc()
+
+        self._request_duration.labels(
+            operation=operation,
+            endpoint=endpoint,
+        ).observe(duration)
+
+    def record_error(
+        self,
+        operation: str,
+        endpoint: str,
+        error_type: str,
+    ):
+        """Record an error metric.
+
+        Args:
+            operation: Operation name
+            endpoint: Endpoint address
+            error_type: Error type/class name
+        """
+        self._error_counter.labels(
+            operation=operation,
+            endpoint=endpoint,
+            error_type=error_type,
+        ).inc()
+
+    def record_retry(
+        self,
+        operation: str,
+        endpoint: str,
+    ):
+        """Record a retry metric.
+
+        Args:
+            operation: Operation name
+            endpoint: Endpoint address
+        """
+        self._retry_counter.labels(
+            operation=operation,
+            endpoint=endpoint,
+        ).inc()
+
+    def set_connection_state(
+        self,
+        endpoint: str,
+        state: str,
+    ):
+        """Set connection state gauge.
+
+        Args:
+            endpoint: Endpoint address
+            state: Connection state ("active", "idle", "failed")
+        """
+        self._connection_gauge.labels(
+            endpoint=endpoint,
+            state=state,
+        ).set(1)
+
+    def unset_connection(self, endpoint: str):
+        """Unset connection for an endpoint.
+
+        Args:
+            endpoint: Endpoint address
+        """
+        for state in ("active", "idle", "failed"):
+            try:
+                self._connection_gauge.labels(
+                    endpoint=endpoint,
+                    state=state,
+                ).dec(1)
+            except ValueError:
+                pass  # Value already 0
+
+    def record_endpoint_failure(self, endpoint: str):
+        """Record an endpoint failure."""
+        self.set_connection_state(endpoint, "failed")
+
+    def record_endpoint_usage(self, endpoint: str):
+        """Record an endpoint usage."""
+        self.record_request("endpoint.usage", endpoint, 0, "success")
+
+    def record_endpoint_recovery(self, endpoint: str):
+        """Record an endpoint recovery."""
+        self.set_connection_state(endpoint, "active")
+
+    def metrics(self) -> bytes:
+        """Get metrics in Prometheus format.
+
+        Returns:
+            Prometheus metrics text format
+        """
+        return generate_latest(self._registry)
+
+    def reset(self):
+        """Reset all metrics."""
+        logger.warning("Reset not fully supported in Prometheus exporter")
+
+
+# Global exporter instance
+_exporter: Optional[EtcdPrometheusExporter] = None
+
+
+def get_exporter() -> Optional[EtcdPrometheusExporter]:
+    """Get the global Prometheus exporter instance.
+
+    Returns:
+        Global EtcdPrometheusExporter instance or None if not available
+    """
+    global _exporter
+    if _exporter is None and PROMETHEUS_AVAILABLE:
+        try:
+            _exporter = EtcdPrometheusExporter()
+        except Exception as e:
+            logger.warning(f"Failed to create Prometheus exporter: {e}")
+            return None
+    return _exporter
+
+
+def init_exporter(
+    registry: Optional[CollectorRegistry] = None,
+) -> EtcdPrometheusExporter:
+    """Initialize the global Prometheus exporter.
+
+    Args:
+        registry: Optional Prometheus registry
+
+    Returns:
+        Initialized EtcdPrometheusExporter instance
+    """
+    global _exporter
+    _exporter = EtcdPrometheusExporter(registry)
+    return _exporter
+
+
+def is_prometheus_available() -> bool:
+    """Check if Prometheus client is available.
+
+    Returns:
+        True if prometheus_client is installed
+    """
+    return PROMETHEUS_AVAILABLE
+
+
+class _NoOpMetrics:
+    """No-op metrics collector when Prometheus is not available."""
+
+    def record_request(
+        self, operation: str, endpoint: str, duration: float, status: str = "success"
+    ):
+        pass
+
+    def record_error(self, operation: str, endpoint: str, error_type: str):
+        pass
+
+    def record_retry(self, operation: str, endpoint: str):
+        pass
+
+    def record_endpoint_failure(self, endpoint: str):
+        pass
+
+    def record_endpoint_usage(self, endpoint: str):
+        pass
+
+    def record_endpoint_recovery(self, endpoint: str):
+        pass
+
+    def set_connection_state(self, endpoint: str, state: str):
+        pass
+
+    def unset_connection(self, endpoint: str):
+        pass
+
+    def metrics(self) -> bytes:
+        return b""
+
+
+def get_metrics_interface():
+    """Get the metrics interface.
+
+    Returns:
+        EtcdPrometheusExporter if available, otherwise NoOpMetrics
+    """
+    if PROMETHEUS_AVAILABLE:
+        exporter = get_exporter()
+        if exporter is not None:
+            return exporter
+    return _NoOpMetrics()
+
+
+def monitor_request(operation: str, is_async: bool = False):
+    """Decorator factory to monitor request latency and errors.
+
+    Args:
+        operation: Name of the operation
+        is_async: Whether the decorated function is async
+
+    Returns:
+        Decorator function
+    """
+    import time
+
+    def decorator(func):
+        if is_async:
+
+            async def async_wrapper(*args, **kwargs):
+                start_time = time.time()
+                try:
+                    result = await func(*args, **kwargs)
+                    latency = time.time() - start_time
+                    get_metrics_interface().record_request(
+                        operation, "unknown", latency, "success"
+                    )
+                    return result
+                except Exception as e:
+                    latency = time.time() - start_time
+                    get_metrics_interface().record_request(
+                        operation, "unknown", latency, "error"
+                    )
+                    get_metrics_interface().record_error(
+                        operation, "unknown", type(e).__name__
+                    )
+                    raise
+
+            return async_wrapper
+
+        def sync_wrapper(*args, **kwargs):
+            start_time = time.time()
+            try:
+                result = func(*args, **kwargs)
+                latency = time.time() - start_time
+                get_metrics_interface().record_request(
+                    operation, "unknown", latency, "success"
+                )
+                return result
+            except Exception as e:
+                latency = time.time() - start_time
+                get_metrics_interface().record_request(
+                    operation, "unknown", latency, "error"
+                )
+                get_metrics_interface().record_error(
+                    operation, "unknown", type(e).__name__
+                )
+                raise
+
+        return sync_wrapper
+
+    return decorator

etcd3/leases.py

@@ -0,0 +1,106 @@
+class Lease(object):
+    """
+    A lease.
+
+    :ivar id: ID of the lease
+    :ivar ttl: time to live for this lease
+    """
+
+    def __init__(self, lease_id, ttl, etcd_client=None):
+        if ttl <= 0:
+            raise ValueError("ttl must be a positive integer")
+        self.id = lease_id
+        self.ttl = ttl
+
+        self.etcd_client = etcd_client
+
+    def _get_lease_info(self):
+        return self.etcd_client.get_lease_info(self.id)
+
+    def revoke(self):
+        """Revoke this lease."""
+        self.etcd_client.revoke_lease(self.id)
+
+    def refresh(self):
+        """Refresh the time to live for this lease.
+
+        Returns a generator that yields keep-alive responses.
+        The caller should iterate over this generator to keep the lease alive.
+
+        Example:
+            for response in lease.refresh():
+                # Lease is kept alive while iterating
+                pass
+        """
+        return self.etcd_client.refresh_lease(self.id)
+
+    @property
+    def remaining_ttl(self):
+        return self._get_lease_info().TTL
+
+    @property
+    def granted_ttl(self):
+        return self._get_lease_info().grantedTTL
+
+    @property
+    def keys(self):
+        return self._get_lease_info().keys
+
+
+class AsyncLease(object):
+    """
+    An asynchronous lease.
+
+    :ivar id: ID of the lease
+    :ivar ttl: time to live for this lease
+    """
+
+    def __init__(self, lease_id, ttl, etcd_client=None):
+        if ttl <= 0:
+            raise ValueError("ttl must be a positive integer")
+        self.id = lease_id
+        self.ttl = ttl
+
+        self.etcd_client = etcd_client
+
+    async def _get_lease_info(self):
+        """Get lease information from etcd."""
+        return await self.etcd_client.get_lease_info(self.id)
+
+    async def revoke(self):
+        """Revoke this lease."""
+        await self.etcd_client.revoke_lease(self.id)
+
+    def refresh(self):
+        """Refresh the time to live for this lease.
+
+        Returns an async generator that yields keep-alive responses.
+        """
+        return self.etcd_client.refresh_lease(self.id)
+
+    async def get_remaining_ttl(self):
+        """Get the remaining time to live for this lease.
+
+        :returns: remaining TTL in seconds
+        :rtype: int
+        """
+        info = await self._get_lease_info()
+        return info.TTL
+
+    async def get_granted_ttl(self):
+        """Get the granted time to live for this lease.
+
+        :returns: granted TTL in seconds
+        :rtype: int
+        """
+        info = await self._get_lease_info()
+        return info.grantedTTL
+
+    async def get_keys(self):
+        """Get the keys attached to this lease.
+
+        :returns: list of keys attached to this lease
+        :rtype: list
+        """
+        info = await self._get_lease_info()
+        return list(info.keys)