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

etcd3/async_endpoint.py

@@ -0,0 +1,140 @@
+"""Async endpoint implementation for etcd3 client.
+
+This module provides the AsyncEndpoint class for managing etcd cluster endpoints
+in async operations.
+"""
+
+import asyncio
+
+import grpc
+
+from etcd3.endpoint import BaseEndpoint
+
+
+class AsyncEndpointConfig:
+    """Configuration for AsyncEndpoint creation.
+
+    :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.port = port
+        self.secure = secure
+        self.creds = creds
+        self.time_retry = time_retry
+        self.opts = opts
+
+
+class AsyncEndpoint(BaseEndpoint):
+    """Represents an etcd cluster endpoint for async operations.
+
+    :param config: AsyncEndpointConfig object with endpoint configuration
+    :param str host: Endpoint host (ignored if config is provided)
+    :param int port: Endpoint port (ignored if config is provided)
+    :param bool secure: Use secure channel, default True (ignored if config is provided)
+    :param creds: Credentials to use for secure channel, required if
+                  secure=True (ignored if config is provided)
+    :type creds: grpc.ChannelCredentials, optional
+    :param time_retry: Seconds to wait before retrying this endpoint after
+                       failure, default 300.0 (ignored if config is provided)
+    :type time_retry: int or float
+    :param opts: Additional gRPC options (ignored if config is provided)
+    :type opts: dict, optional
+    """
+
+    def __init__(
+        self,
+        config=None,
+        host=None,
+        port=None,
+        secure=True,
+        creds=None,
+        time_retry=300.0,
+        opts=None,
+    ):
+        # Use config object if provided, otherwise use individual parameters
+        if config is not None:
+            host = config.host
+            port = config.port
+            secure = config.secure
+            creds = config.creds
+            time_retry = config.time_retry
+            opts = config.opts
+
+        if host is None or port is None:
+            raise ValueError("Host and port must be provided")
+
+        super().__init__(host, port, secure, creds, time_retry, opts)
+        self.channel = self._mkchannel(opts)
+
+    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
+        """
+        try:
+            state = self.channel.get_state()
+            # Only READY is considered healthy, not CONNECTING
+            return state == grpc.ChannelConnectivity.READY
+        except Exception:
+            return False
+
+    async def health_check_async(self):
+        """Perform an asynchronous health check using gRPC status check.
+
+        This method uses the channel's await_ready() for a more robust
+        connectivity check.
+
+        :returns: True if the endpoint is healthy
+        :rtype: bool
+        """
+        try:
+            await asyncio.wait_for(self.channel.healthy(), timeout=2.0)
+            return True
+        except asyncio.TimeoutError:
+            return False
+        except Exception:
+            return False
+
+    async 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:
+            await self.channel.close()
+        except Exception:
+            pass  # Ignore close errors
+
+        self.channel = self._mkchannel(self.opts)
+
+    async def close(self):
+        """Close the gRPC channel."""
+        try:
+            await self.channel.close()
+        except Exception:
+            pass  # Ignore close errors
+
+    def _mkchannel(self, opts):
+        if self.secure:
+            return grpc.aio.secure_channel(self.netloc, self.credentials, options=opts)
+        return grpc.aio.insecure_channel(self.netloc, options=opts)

etcd3/async_managers.py

@@ -0,0 +1,498 @@
+"""Manager classes for etcd3 async client.
+
+This module provides manager classes to handle specific functionality
+for the etcd3 async client, reducing the size of the main client class.
+"""
+
+import asyncio
+
+import grpc
+import etcdrpc
+
+from etcd3 import utils
+from etcd3.members import Member
+from etcd3.client import Status, Alarm
+from etcd3.async_watch import AsyncWatcher
+
+
+class AsyncWatchManager:
+    """Manager for watch-related operations.
+
+    :param etcd_client: The etcd client instance
+    :type etcd_client: AsyncMultiEndpointEtcd3Client
+    """
+
+    def __init__(self, etcd_client):
+        self.etcd_client = etcd_client
+        self._watcher = None
+
+    def _get_watcher(self):
+        """Get or create a watcher instance."""
+        if self._watcher is None:
+            watchstub = etcdrpc.WatchStub(self.etcd_client.channel)
+            self._watcher = AsyncWatcher(
+                watchstub,
+                timeout=self.etcd_client.timeout,
+                call_credentials=self.etcd_client.call_credentials,
+                metadata=self.etcd_client.metadata,
+            )
+        return self._watcher
+
+    async 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()
+        return await watcher.add_callback(*args, **kwargs)
+
+    async 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 await self.add_watch_callback(key_prefix, callback, **kwargs)
+
+    async def watch_response(self, key, **kwargs):
+        """
+        Watch a key.
+
+        Example usage:
+
+        .. code-block:: python
+            responses_iterator, cancel = await etcd.watch_response('/doot/key')
+            async for response in responses_iterator:
+                print(response)
+
+        :param key: key to watch
+
+        :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.
+        """
+        watcher = self._get_watcher()
+        event_iter = watcher.watch(key, **kwargs)
+
+        cancel_event = asyncio.Event()
+
+        async def cancel():
+            cancel_event.set()
+            await watcher.cancel(0)
+
+        async def event_iterator():
+            try:
+                async for event in event_iter:
+                    if cancel_event.is_set():
+                        break
+                    yield event
+            except grpc.RpcError as exc:
+                if not cancel_event.is_set():
+                    self.etcd_client._manage_grpc_errors(exc)
+
+        return event_iterator(), cancel
+
+    async def watch(self, key, **kwargs):
+        """
+        Watch a key.
+
+        Example usage:
+
+        .. code-block:: python
+            events_iterator, cancel = await etcd.watch('/doot/key')
+            async for event in events_iterator:
+                print(event)
+
+        :param key: key to watch
+
+        :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 = await self.watch_response(key, **kwargs)
+        return utils.async_response_to_event_iterator(response_iterator), cancel
+
+    async def watch_prefix_response(self, key_prefix, **kwargs):
+        """
+        Watch a range of keys with a prefix.
+
+        :param key_prefix: prefix to watch
+
+        :returns: tuple of ``responses_iterator`` and ``cancel``.
+        """
+        kwargs["range_end"] = utils.prefix_range_end(utils.to_bytes(key_prefix))
+        return await self.watch_response(key_prefix, **kwargs)
+
+    async def watch_prefix(self, key_prefix, **kwargs):
+        """
+        Watch a range of keys with a prefix.
+
+        :param key_prefix: prefix to watch
+
+        :returns: tuple of ``events_iterator`` and ``cancel``.
+        """
+        kwargs["range_end"] = utils.prefix_range_end(utils.to_bytes(key_prefix))
+        return await self.watch(key_prefix, **kwargs)
+
+    async 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``
+        """
+        watcher = self._get_watcher()
+        return await watcher.watch_once(key, timeout=timeout, **kwargs)
+
+    async 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 = await self.watch_once_response(key, timeout=timeout, **kwargs)
+        if not response.events:
+            raise IndexError("No events in watch response")
+        return response.events[0]
+
+    async 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 await self.watch_once_response(key_prefix, timeout=timeout, **kwargs)
+
+    async 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 await self.watch_once(key_prefix, timeout=timeout, **kwargs)
+
+    async 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()
+        await watcher.cancel(watch_id)
+
+
+class AsyncClusterManager:
+    """Manager for cluster-related operations.
+
+    :param etcd_client: The etcd client instance
+    :type etcd_client: AsyncMultiEndpointEtcd3Client
+    """
+
+    def __init__(self, etcd_client):
+        self.etcd_client = etcd_client
+
+    async 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.etcd_client.channel)
+        member_add_response = await cluster_stub.MemberAdd(
+            member_add_request,
+            timeout=self.etcd_client.timeout,
+            credentials=self.etcd_client.call_credentials,
+            metadata=self.etcd_client.metadata,
+        )
+
+        member = member_add_response.member
+        return Member(
+            member.ID,
+            member.name,
+            member.peerURLs,
+            member.clientURLs,
+            etcd_client=self.etcd_client,
+        )
+
+    async 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.etcd_client.channel)
+        await cluster_stub.MemberRemove(
+            member_rm_request,
+            timeout=self.etcd_client.timeout,
+            credentials=self.etcd_client.call_credentials,
+            metadata=self.etcd_client.metadata,
+        )
+
+    async 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.etcd_client.channel)
+        await cluster_stub.MemberUpdate(
+            member_update_request,
+            timeout=self.etcd_client.timeout,
+            credentials=self.etcd_client.call_credentials,
+            metadata=self.etcd_client.metadata,
+        )
+
+    async 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.etcd_client.channel)
+        member_list_response = await cluster_stub.MemberList(
+            member_list_request,
+            timeout=self.etcd_client.timeout,
+            credentials=self.etcd_client.call_credentials,
+            metadata=self.etcd_client.metadata,
+        )
+
+        for member in member_list_response.members:
+            yield Member(
+                member.ID,
+                member.name,
+                member.peerURLs,
+                member.clientURLs,
+                etcd_client=self.etcd_client,
+            )
+
+
+class AsyncMaintenanceManager:
+    """Manager for maintenance-related operations.
+
+    :param etcd_client: The etcd client instance
+    :type etcd_client: AsyncMultiEndpointEtcd3Client
+    """
+
+    def __init__(self, etcd_client):
+        self.etcd_client = etcd_client
+
+    async def status(self):
+        """Get the status of the responding member."""
+        status_request = etcdrpc.StatusRequest()
+        # Create maintenance stub directly
+        maintenance_stub = etcdrpc.MaintenanceStub(self.etcd_client.channel)
+        status_response = await maintenance_stub.Status(
+            status_request,
+            timeout=self.etcd_client.timeout,
+            credentials=self.etcd_client.call_credentials,
+            metadata=self.etcd_client.metadata,
+        )
+
+        members_list = []
+        async for member in self.etcd_client.cluster_manager.members():
+            members_list.append(member)
+
+        for m in members_list:
+            if m.id == status_response.leader:
+                leader = m
+                break
+        else:
+            leader = None
+
+        return Status(
+            status_response.version,
+            status_response.dbSize,
+            leader,
+            status_response.raftIndex,
+            status_response.raftTerm,
+        )
+
+    async 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.etcd_client.channel)
+        await maintenance_stub.Defragment(
+            defrag_request,
+            timeout=self.etcd_client.timeout,
+            credentials=self.etcd_client.call_credentials,
+            metadata=self.etcd_client.metadata,
+        )
+
+    async 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.etcd_client.channel)
+        hash_response = await maintenance_stub.Hash(
+            hash_request,
+            timeout=self.etcd_client.timeout,
+            credentials=self.etcd_client.call_credentials,
+            metadata=self.etcd_client.metadata,
+        )
+        return hash_response.hash
+
+    async 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.etcd_client.channel)
+        alarm_response = await maintenance_stub.Alarm(
+            alarm_request,
+            timeout=self.etcd_client.timeout,
+            credentials=self.etcd_client.call_credentials,
+            metadata=self.etcd_client.metadata,
+        )
+
+        return [Alarm(alarm.alarm, alarm.memberID) for alarm in alarm_response.alarms]
+
+    async 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.etcd_client.channel)
+        alarm_response = await maintenance_stub.Alarm(
+            alarm_request,
+            timeout=self.etcd_client.timeout,
+            credentials=self.etcd_client.call_credentials,
+            metadata=self.etcd_client.metadata,
+        )
+
+        for alarm in alarm_response.alarms:
+            yield Alarm(alarm.alarm, alarm.memberID)
+
+    def _build_alarm_request(self, alarm_action, member_id, alarm_type):
+        """Build an alarm request.
+
+        :param alarm_action: The alarm action ('get', 'activate', 'deactivate')
+        :param member_id: The member ID
+        :param alarm_type: The alarm type
+        :return: AlarmRequest instance
+        """
+        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(f"Unknown alarm action: {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(f"Unknown alarm type: {alarm_type}")
+
+        return alarm_request
+
+    async 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.etcd_client.channel)
+        alarm_response = await maintenance_stub.Alarm(
+            alarm_request,
+            timeout=self.etcd_client.timeout,
+            credentials=self.etcd_client.call_credentials,
+            metadata=self.etcd_client.metadata,
+        )
+
+        return [Alarm(alarm.alarm, alarm.memberID) for alarm in alarm_response.alarms]
+
+    async 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.etcd_client.channel)
+        snapshot_response = maintenance_stub.Snapshot(
+            snapshot_request,
+            timeout=self.etcd_client.timeout,
+            credentials=self.etcd_client.call_credentials,
+            metadata=self.etcd_client.metadata,
+        )
+
+        async for response in snapshot_response:
+            await file_obj.write(response.blob)

etcd3/async_monitor.py

@@ -0,0 +1,16 @@
+"""Monitoring utilities for etcd3 async client.
+
+.. deprecated::
+    Use etcd3.exporters.prometheus instead for metrics collection.
+
+This module provides monitoring functionality for the etcd3 async client,
+including metrics collection and logging utilities.
+"""
+
+# Re-export from prometheus exporter
+from etcd3.exporters.prometheus import (
+    get_metrics_interface as get_monitor,
+    monitor_request,
+)
+
+__all__ = ["get_monitor", "monitor_request"]