Issue #46: implement Python async client values errors and CLI

clients/python/src/mxgateway/client.py

@@ -0,0 +1,165 @@
+"""Async MXAccess Gateway client wrapper."""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import AsyncIterator, Sequence
+from typing import Any
+
+import grpc
+
+from .auth import merge_metadata
+from .errors import ensure_protocol_success, map_rpc_error
+from .generated import mxaccess_gateway_pb2 as pb
+from .generated import mxaccess_gateway_pb2_grpc as pb_grpc
+from .options import ClientOptions, create_channel
+
+
+class GatewayClient:
+    """Async client for the public MXAccess Gateway gRPC API."""
+
+    def __init__(
+        self,
+        *,
+        options: ClientOptions,
+        stub: Any,
+        channel: grpc.aio.Channel | None = None,
+    ) -> None:
+        self.options = options
+        self.raw_stub = stub
+        self._channel = channel
+        self._closed = False
+
+    @classmethod
+    async def connect(
+        cls,
+        options: ClientOptions | None = None,
+        *,
+        endpoint: str | None = None,
+        api_key: str | None = None,
+        plaintext: bool = False,
+        ca_file: str | None = None,
+        server_name_override: str | None = None,
+        stub: Any | None = None,
+    ) -> "GatewayClient":
+        """Create a client with either a real async channel or a supplied fake stub."""
+
+        resolved = options or ClientOptions(
+            endpoint=endpoint or "",
+            api_key=api_key,
+            plaintext=plaintext,
+            ca_file=ca_file,
+            server_name_override=server_name_override,
+        )
+
+        if stub is not None:
+            return cls(options=resolved, stub=stub)
+
+        channel = create_channel(resolved)
+        return cls(
+            options=resolved,
+            stub=pb_grpc.MxAccessGatewayStub(channel),
+            channel=channel,
+        )
+
+    async def __aenter__(self) -> "GatewayClient":
+        return self
+
+    async def __aexit__(self, *_exc_info: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the owned gRPC channel."""
+
+        if self._closed:
+            return
+
+        self._closed = True
+        if self._channel is not None:
+            await self._channel.close()
+
+    async def open_session(
+        self,
+        request: pb.OpenSessionRequest | None = None,
+        *,
+        requested_backend: str = "",
+        client_session_name: str = "",
+        client_correlation_id: str = "",
+    ) -> "Session":
+        """Open a gateway session and return a high-level session wrapper."""
+
+        from .session import Session
+
+        raw_request = request or pb.OpenSessionRequest(
+            requested_backend=requested_backend,
+            client_session_name=client_session_name,
+            client_correlation_id=client_correlation_id,
+        )
+        reply = await self.open_session_raw(raw_request)
+        return Session(client=self, session_id=reply.session_id, open_reply=reply)
+
+    async def open_session_raw(self, request: pb.OpenSessionRequest) -> pb.OpenSessionReply:
+        reply = await self._unary("open session", self.raw_stub.OpenSession, request)
+        ensure_protocol_success("open session", reply.protocol_status, reply)
+        return reply
+
+    async def close_session_raw(
+        self,
+        request: pb.CloseSessionRequest,
+    ) -> pb.CloseSessionReply:
+        reply = await self._unary("close session", self.raw_stub.CloseSession, request)
+        ensure_protocol_success("close session", reply.protocol_status, reply)
+        return reply
+
+    async def invoke_raw(self, request: pb.MxCommandRequest) -> pb.MxCommandReply:
+        reply = await self._unary("invoke", self.raw_stub.Invoke, request)
+        ensure_protocol_success("invoke", reply.protocol_status, reply)
+        return reply
+
+    def stream_events_raw(
+        self,
+        request: pb.StreamEventsRequest,
+        *,
+        metadata: Sequence[tuple[str, str]] | None = None,
+    ) -> AsyncIterator[pb.MxEvent]:
+        """Return an async event iterator and cancel the stream when iteration stops."""
+
+        call = self.raw_stub.StreamEvents(
+            request,
+            metadata=merge_metadata(self.options.api_key, metadata),
+        )
+        return _canceling_iterator(call)
+
+    async def _unary(
+        self,
+        operation: str,
+        method: Any,
+        request: Any,
+        *,
+        metadata: Sequence[tuple[str, str]] | None = None,
+    ) -> Any:
+        call = method(
+            request,
+            metadata=merge_metadata(self.options.api_key, metadata),
+        )
+        try:
+            return await call
+        except asyncio.CancelledError:
+            cancel = getattr(call, "cancel", None)
+            if cancel is not None:
+                cancel()
+            raise
+        except grpc.RpcError as error:
+            raise map_rpc_error(operation, error) from error
+
+
+async def _canceling_iterator(call: Any) -> AsyncIterator[pb.MxEvent]:
+    try:
+        async for event in call:
+            yield event
+    except grpc.RpcError as error:
+        raise map_rpc_error("stream events", error) from error
+    finally:
+        cancel = getattr(call, "cancel", None)
+        if cancel is not None:
+            cancel()