clients/python/README.md

@@ -0,0 +1,57 @@
+# Python Client
+
+The Python client package contains generated MXAccess Gateway protobuf
+bindings, the `mxgateway` package scaffold, and the `mxgw-py` test CLI
+scaffold. The package uses the shared proto inputs documented in
+`../../docs/client-proto-generation.md` so gateway and client contracts stay in
+sync.
+
+## Layout
+
+```text
+clients/python/
+  pyproject.toml
+  generate-proto.ps1
+  src/mxgateway/
+  src/mxgateway/generated/
+  src/mxgateway_cli/
+  tests/
+```
+
+`src/mxgateway/generated` contains code produced by `grpc_tools.protoc`. Do not
+edit generated files by hand.
+
+## Regenerating Protobuf Bindings
+
+Run generation after the shared `.proto` files or the Python output path
+changes:
+
+```powershell
+./generate-proto.ps1
+```
+
+The script uses the Python tool path recorded in
+`../../docs/toolchain-links.md`.
+
+## Build And Test
+
+Run the Python checks from `clients/python`:
+
+```powershell
+python -m pip install -e ".[dev]"
+python -m pytest
+python -m pip wheel . --no-deps --wheel-dir "$env:TEMP\mxgateway-python-wheel"
+```
+
+The scaffold tests import the generated gateway and worker stubs and exercise
+the deterministic CLI version output.
+
+## CLI
+
+The scaffold CLI exposes version information:
+
+```powershell
+mxgw-py version --json
+```
+
+Additional commands are implemented with the async client/session wrapper work.

clients/python/generate-proto.ps1

@@ -0,0 +1,22 @@
+Set-StrictMode -Version Latest
+$ErrorActionPreference = 'Stop'
+
+$repoRoot = Resolve-Path (Join-Path $PSScriptRoot '..\..')
+$protoRoot = Join-Path $repoRoot 'src\MxGateway.Contracts\Protos'
+$outputRoot = Join-Path $PSScriptRoot 'src\mxgateway\generated'
+$python = 'C:\Users\dohertj2\AppData\Local\Programs\Python\Python312\python.exe'
+
+if (-not (Test-Path $python)) {
+    throw "Python was not found at $python. See docs/toolchain-links.md."
+}
+
+New-Item -ItemType Directory -Path $outputRoot -Force | Out-Null
+Get-ChildItem -Path (Join-Path $outputRoot '*_pb2.py') -File | Remove-Item
+Get-ChildItem -Path (Join-Path $outputRoot '*_pb2_grpc.py') -File | Remove-Item
+
+& $python -m grpc_tools.protoc `
+    "-I$protoRoot" `
+    "--python_out=$outputRoot" `
+    "--grpc_python_out=$outputRoot" `
+    mxaccess_gateway.proto `
+    mxaccess_worker.proto

clients/python/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mxaccess-gateway-client"
+version = "0.1.0"
+description = "Async Python client scaffold for MXAccess Gateway."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+  "click>=8.3,<9",
+  "grpcio>=1.80,<2",
+  "protobuf>=6.33,<7",
+]
+
+[project.optional-dependencies]
+dev = [
+  "grpcio-tools>=1.80,<2",
+  "pytest>=9,<10",
+  "pytest-asyncio>=1.3,<2",
+]
+
+[project.scripts]
+mxgw-py = "mxgateway_cli.commands:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+addopts = "-ra"
+pythonpath = ["src"]
+testpaths = ["tests"]

clients/python/src/mxgateway/__init__.py

@@ -0,0 +1,5 @@
+"""MXAccess Gateway Python client package."""
+
+from .version import __version__
+
+__all__ = ["__version__"]

clients/python/src/mxgateway/generated/__init__.py

@@ -0,0 +1,29 @@
+"""Generated protobuf and gRPC modules for MXAccess Gateway.
+
+The Python protobuf generator emits absolute imports between generated modules.
+This package initializer registers package-local aliases so callers can import
+the generated stubs through `mxgateway.generated` without moving the modules to
+the top-level import namespace.
+"""
+
+from importlib import import_module
+import sys
+
+mxaccess_gateway_pb2 = import_module(f"{__name__}.mxaccess_gateway_pb2")
+sys.modules.setdefault("mxaccess_gateway_pb2", mxaccess_gateway_pb2)
+
+mxaccess_gateway_pb2_grpc = import_module(f"{__name__}.mxaccess_gateway_pb2_grpc")
+sys.modules.setdefault("mxaccess_gateway_pb2_grpc", mxaccess_gateway_pb2_grpc)
+
+mxaccess_worker_pb2 = import_module(f"{__name__}.mxaccess_worker_pb2")
+sys.modules.setdefault("mxaccess_worker_pb2", mxaccess_worker_pb2)
+
+mxaccess_worker_pb2_grpc = import_module(f"{__name__}.mxaccess_worker_pb2_grpc")
+sys.modules.setdefault("mxaccess_worker_pb2_grpc", mxaccess_worker_pb2_grpc)
+
+__all__ = [
+    "mxaccess_gateway_pb2",
+    "mxaccess_gateway_pb2_grpc",
+    "mxaccess_worker_pb2",
+    "mxaccess_worker_pb2_grpc",
+]

clients/python/src/mxgateway/generated/mxaccess_gateway_pb2_grpc.py

@@ -0,0 +1,229 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+import warnings
+
+import mxaccess_gateway_pb2 as mxaccess__gateway__pb2
+
+GRPC_GENERATED_VERSION = '1.80.0'
+GRPC_VERSION = grpc.__version__
+_version_not_supported = False
+
+try:
+    from grpc._utilities import first_version_is_lower
+    _version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
+except ImportError:
+    _version_not_supported = True
+
+if _version_not_supported:
+    raise RuntimeError(
+        f'The grpc package installed is at version {GRPC_VERSION},'
+        + ' but the generated code in mxaccess_gateway_pb2_grpc.py depends on'
+        + f' grpcio>={GRPC_GENERATED_VERSION}.'
+        + f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
+        + f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'
+    )
+
+
+class MxAccessGatewayStub(object):
+    """Public client API for MXAccess sessions hosted by the gateway.
+    """
+
+    def __init__(self, channel):
+        """Constructor.
+
+        Args:
+            channel: A grpc.Channel.
+        """
+        self.OpenSession = channel.unary_unary(
+                '/mxaccess_gateway.v1.MxAccessGateway/OpenSession',
+                request_serializer=mxaccess__gateway__pb2.OpenSessionRequest.SerializeToString,
+                response_deserializer=mxaccess__gateway__pb2.OpenSessionReply.FromString,
+                _registered_method=True)
+        self.CloseSession = channel.unary_unary(
+                '/mxaccess_gateway.v1.MxAccessGateway/CloseSession',
+                request_serializer=mxaccess__gateway__pb2.CloseSessionRequest.SerializeToString,
+                response_deserializer=mxaccess__gateway__pb2.CloseSessionReply.FromString,
+                _registered_method=True)
+        self.Invoke = channel.unary_unary(
+                '/mxaccess_gateway.v1.MxAccessGateway/Invoke',
+                request_serializer=mxaccess__gateway__pb2.MxCommandRequest.SerializeToString,
+                response_deserializer=mxaccess__gateway__pb2.MxCommandReply.FromString,
+                _registered_method=True)
+        self.StreamEvents = channel.unary_stream(
+                '/mxaccess_gateway.v1.MxAccessGateway/StreamEvents',
+                request_serializer=mxaccess__gateway__pb2.StreamEventsRequest.SerializeToString,
+                response_deserializer=mxaccess__gateway__pb2.MxEvent.FromString,
+                _registered_method=True)
+
+
+class MxAccessGatewayServicer(object):
+    """Public client API for MXAccess sessions hosted by the gateway.
+    """
+
+    def OpenSession(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def CloseSession(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def Invoke(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+    def StreamEvents(self, request, context):
+        """Missing associated documentation comment in .proto file."""
+        context.set_code(grpc.StatusCode.UNIMPLEMENTED)
+        context.set_details('Method not implemented!')
+        raise NotImplementedError('Method not implemented!')
+
+
+def add_MxAccessGatewayServicer_to_server(servicer, server):
+    rpc_method_handlers = {
+            'OpenSession': grpc.unary_unary_rpc_method_handler(
+                    servicer.OpenSession,
+                    request_deserializer=mxaccess__gateway__pb2.OpenSessionRequest.FromString,
+                    response_serializer=mxaccess__gateway__pb2.OpenSessionReply.SerializeToString,
+            ),
+            'CloseSession': grpc.unary_unary_rpc_method_handler(
+                    servicer.CloseSession,
+                    request_deserializer=mxaccess__gateway__pb2.CloseSessionRequest.FromString,
+                    response_serializer=mxaccess__gateway__pb2.CloseSessionReply.SerializeToString,
+            ),
+            'Invoke': grpc.unary_unary_rpc_method_handler(
+                    servicer.Invoke,
+                    request_deserializer=mxaccess__gateway__pb2.MxCommandRequest.FromString,
+                    response_serializer=mxaccess__gateway__pb2.MxCommandReply.SerializeToString,
+            ),
+            'StreamEvents': grpc.unary_stream_rpc_method_handler(
+                    servicer.StreamEvents,
+                    request_deserializer=mxaccess__gateway__pb2.StreamEventsRequest.FromString,
+                    response_serializer=mxaccess__gateway__pb2.MxEvent.SerializeToString,
+            ),
+    }
+    generic_handler = grpc.method_handlers_generic_handler(
+            'mxaccess_gateway.v1.MxAccessGateway', rpc_method_handlers)
+    server.add_generic_rpc_handlers((generic_handler,))
+    server.add_registered_method_handlers('mxaccess_gateway.v1.MxAccessGateway', rpc_method_handlers)
+
+
+ # This class is part of an EXPERIMENTAL API.
+class MxAccessGateway(object):
+    """Public client API for MXAccess sessions hosted by the gateway.
+    """
+
+    @staticmethod
+    def OpenSession(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/mxaccess_gateway.v1.MxAccessGateway/OpenSession',
+            mxaccess__gateway__pb2.OpenSessionRequest.SerializeToString,
+            mxaccess__gateway__pb2.OpenSessionReply.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def CloseSession(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/mxaccess_gateway.v1.MxAccessGateway/CloseSession',
+            mxaccess__gateway__pb2.CloseSessionRequest.SerializeToString,
+            mxaccess__gateway__pb2.CloseSessionReply.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def Invoke(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_unary(
+            request,
+            target,
+            '/mxaccess_gateway.v1.MxAccessGateway/Invoke',
+            mxaccess__gateway__pb2.MxCommandRequest.SerializeToString,
+            mxaccess__gateway__pb2.MxCommandReply.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)
+
+    @staticmethod
+    def StreamEvents(request,
+            target,
+            options=(),
+            channel_credentials=None,
+            call_credentials=None,
+            insecure=False,
+            compression=None,
+            wait_for_ready=None,
+            timeout=None,
+            metadata=None):
+        return grpc.experimental.unary_stream(
+            request,
+            target,
+            '/mxaccess_gateway.v1.MxAccessGateway/StreamEvents',
+            mxaccess__gateway__pb2.StreamEventsRequest.SerializeToString,
+            mxaccess__gateway__pb2.MxEvent.FromString,
+            options,
+            channel_credentials,
+            insecure,
+            call_credentials,
+            compression,
+            wait_for_ready,
+            timeout,
+            metadata,
+            _registered_method=True)

clients/python/src/mxgateway/generated/mxaccess_worker_pb2.py

@@ -0,0 +1,66 @@
+# -*- coding: utf-8 -*-
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# NO CHECKED-IN PROTOBUF GENCODE
+# source: mxaccess_worker.proto
+# Protobuf Python Version: 6.31.1
+"""Generated protocol buffer code."""
+from google.protobuf import descriptor as _descriptor
+from google.protobuf import descriptor_pool as _descriptor_pool
+from google.protobuf import runtime_version as _runtime_version
+from google.protobuf import symbol_database as _symbol_database
+from google.protobuf.internal import builder as _builder
+_runtime_version.ValidateProtobufRuntimeVersion(
+    _runtime_version.Domain.PUBLIC,
+    6,
+    31,
+    1,
+    '',
+    'mxaccess_worker.proto'
+)
+# @@protoc_insertion_point(imports)
+
+_sym_db = _symbol_database.Default()
+
+
+from google.protobuf import duration_pb2 as google_dot_protobuf_dot_duration__pb2
+from google.protobuf import timestamp_pb2 as google_dot_protobuf_dot_timestamp__pb2
+import mxaccess_gateway_pb2 as mxaccess__gateway__pb2
+
+
+DESCRIPTOR = _descriptor_pool.Default().AddSerializedFile(b'\n\x15mxaccess_worker.proto\x12\x12mxaccess_worker.v1\x1a\x1egoogle/protobuf/duration.proto\x1a\x1fgoogle/protobuf/timestamp.proto\x1a\x16mxaccess_gateway.proto\"\x95\x06\n\x0eWorkerEnvelope\x12\x18\n\x10protocol_version\x18\x01 \x01(\r\x12\x12\n\nsession_id\x18\x02 \x01(\t\x12\x10\n\x08sequence\x18\x03 \x01(\x04\x12\x16\n\x0e\x63orrelation_id\x18\x04 \x01(\t\x12\x39\n\rgateway_hello\x18\n \x01(\x0b\x32 .mxaccess_worker.v1.GatewayHelloH\x00\x12\x37\n\x0cworker_hello\x18\x0b \x01(\x0b\x32\x1f.mxaccess_worker.v1.WorkerHelloH\x00\x12\x37\n\x0cworker_ready\x18\x0c \x01(\x0b\x32\x1f.mxaccess_worker.v1.WorkerReadyH\x00\x12;\n\x0eworker_command\x18\r \x01(\x0b\x32!.mxaccess_worker.v1.WorkerCommandH\x00\x12\x46\n\x14worker_command_reply\x18\x0e \x01(\x0b\x32&.mxaccess_worker.v1.WorkerCommandReplyH\x00\x12\x39\n\rworker_cancel\x18\x0f \x01(\x0b\x32 .mxaccess_worker.v1.WorkerCancelH\x00\x12=\n\x0fworker_shutdown\x18\x10 \x01(\x0b\x32\".mxaccess_worker.v1.WorkerShutdownH\x00\x12\x44\n\x13worker_shutdown_ack\x18\x11 \x01(\x0b\x32%.mxaccess_worker.v1.WorkerShutdownAckH\x00\x12\x37\n\x0cworker_event\x18\x12 \x01(\x0b\x32\x1f.mxaccess_worker.v1.WorkerEventH\x00\x12?\n\x10worker_heartbeat\x18\x13 \x01(\x0b\x32#.mxaccess_worker.v1.WorkerHeartbeatH\x00\x12\x37\n\x0cworker_fault\x18\x14 \x01(\x0b\x32\x1f.mxaccess_worker.v1.WorkerFaultH\x00\x42\x06\n\x04\x62ody\"Z\n\x0cGatewayHello\x12\"\n\x1asupported_protocol_version\x18\x01 \x01(\r\x12\r\n\x05nonce\x18\x02 \x01(\t\x12\x17\n\x0fgateway_version\x18\x03 \x01(\t\"i\n\x0bWorkerHello\x12\x18\n\x10protocol_version\x18\x01 \x01(\r\x12\r\n\x05nonce\x18\x02 \x01(\t\x12\x19\n\x11worker_process_id\x18\x03 \x01(\x05\x12\x16\n\x0eworker_version\x18\x04 \x01(\t\"\x8e\x01\n\x0bWorkerReady\x12\x19\n\x11worker_process_id\x18\x01 \x01(\x05\x12\x17\n\x0fmxaccess_progid\x18\x02 \x01(\t\x12\x16\n\x0emxaccess_clsid\x18\x03 \x01(\t\x12\x33\n\x0fready_timestamp\x18\x04 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\"w\n\rWorkerCommand\x12/\n\x07\x63ommand\x18\x01 \x01(\x0b\x32\x1e.mxaccess_gateway.v1.MxCommand\x12\x35\n\x11\x65nqueue_timestamp\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\"\x81\x01\n\x12WorkerCommandReply\x12\x32\n\x05reply\x18\x01 \x01(\x0b\x32#.mxaccess_gateway.v1.MxCommandReply\x12\x37\n\x13\x63ompleted_timestamp\x18\x02 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\"\x1e\n\x0cWorkerCancel\x12\x0e\n\x06reason\x18\x01 \x01(\t\"Q\n\x0eWorkerShutdown\x12/\n\x0cgrace_period\x18\x01 \x01(\x0b\x32\x19.google.protobuf.Duration\x12\x0e\n\x06reason\x18\x02 \x01(\t\"H\n\x11WorkerShutdownAck\x12\x33\n\x06status\x18\x01 \x01(\x0b\x32#.mxaccess_gateway.v1.ProtocolStatus\":\n\x0bWorkerEvent\x12+\n\x05\x65vent\x18\x01 \x01(\x0b\x32\x1c.mxaccess_gateway.v1.MxEvent\"\xa5\x02\n\x0fWorkerHeartbeat\x12\x19\n\x11worker_process_id\x18\x01 \x01(\x05\x12.\n\x05state\x18\x02 \x01(\x0e\x32\x1f.mxaccess_worker.v1.WorkerState\x12?\n\x1blast_sta_activity_timestamp\x18\x03 \x01(\x0b\x32\x1a.google.protobuf.Timestamp\x12\x1d\n\x15pending_command_count\x18\x04 \x01(\r\x12\"\n\x1aoutbound_event_queue_depth\x18\x05 \x01(\r\x12\x1b\n\x13last_event_sequence\x18\x06 \x01(\x04\x12&\n\x1e\x63urrent_command_correlation_id\x18\x07 \x01(\t\"\xf4\x01\n\x0bWorkerFault\x12\x39\n\x08\x63\x61tegory\x18\x01 \x01(\x0e\x32\'.mxaccess_worker.v1.WorkerFaultCategory\x12\x16\n\x0e\x63ommand_method\x18\x02 \x01(\t\x12\x14\n\x07hresult\x18\x03 \x01(\x05H\x00\x88\x01\x01\x12\x16\n\x0e\x65xception_type\x18\x04 \x01(\t\x12\x1a\n\x12\x64iagnostic_message\x18\x05 \x01(\t\x12<\n\x0fprotocol_status\x18\x06 \x01(\x0b\x32#.mxaccess_gateway.v1.ProtocolStatusB\n\n\x08_hresult*\x97\x02\n\x0bWorkerState\x12\x1c\n\x18WORKER_STATE_UNSPECIFIED\x10\x00\x12\x19\n\x15WORKER_STATE_STARTING\x10\x01\x12\x1c\n\x18WORKER_STATE_HANDSHAKING\x10\x02\x12!\n\x1dWORKER_STATE_INITIALIZING_STA\x10\x03\x12\x16\n\x12WORKER_STATE_READY\x10\x04\x12\"\n\x1eWORKER_STATE_EXECUTING_COMMAND\x10\x05\x12\x1e\n\x1aWORKER_STATE_SHUTTING_DOWN\x10\x06\x12\x18\n\x14WORKER_STATE_STOPPED\x10\x07\x12\x18\n\x14WORKER_STATE_FAULTED\x10\x08*\xc7\x04\n\x13WorkerFaultCategory\x12%\n!WORKER_FAULT_CATEGORY_UNSPECIFIED\x10\x00\x12+\n\'WORKER_FAULT_CATEGORY_INVALID_ARGUMENTS\x10\x01\x12\x37\n3WORKER_FAULT_CATEGORY_GATEWAY_AUTHENTICATION_FAILED\x10\x02\x12+\n\'WORKER_FAULT_CATEGORY_PROTOCOL_MISMATCH\x10\x03\x12,\n(WORKER_FAULT_CATEGORY_PROTOCOL_VIOLATION\x10\x04\x12+\n\'WORKER_FAULT_CATEGORY_PIPE_DISCONNECTED\x10\x05\x12\x32\n.WORKER_FAULT_CATEGORY_MXACCESS_CREATION_FAILED\x10\x06\x12\x31\n-WORKER_FAULT_CATEGORY_MXACCESS_COMMAND_FAILED\x10\x07\x12:\n6WORKER_FAULT_CATEGORY_MXACCESS_EVENT_CONVERSION_FAILED\x10\x08\x12\"\n\x1eWORKER_FAULT_CATEGORY_STA_HUNG\x10\t\x12(\n$WORKER_FAULT_CATEGORY_QUEUE_OVERFLOW\x10\n\x12*\n&WORKER_FAULT_CATEGORY_SHUTDOWN_TIMEOUT\x10\x0b\x42\x1c\xaa\x02\x19MxGateway.Contracts.Protob\x06proto3')
+
+_globals = globals()
+_builder.BuildMessageAndEnumDescriptors(DESCRIPTOR, _globals)
+_builder.BuildTopDescriptorsAndMessages(DESCRIPTOR, 'mxaccess_worker_pb2', _globals)
+if not _descriptor._USE_C_DESCRIPTORS:
+  _globals['DESCRIPTOR']._loaded_options = None
+  _globals['DESCRIPTOR']._serialized_options = b'\252\002\031MxGateway.Contracts.Proto'
+  _globals['_WORKERSTATE']._serialized_start=2316
+  _globals['_WORKERSTATE']._serialized_end=2595
+  _globals['_WORKERFAULTCATEGORY']._serialized_start=2598
+  _globals['_WORKERFAULTCATEGORY']._serialized_end=3181
+  _globals['_WORKERENVELOPE']._serialized_start=135
+  _globals['_WORKERENVELOPE']._serialized_end=924
+  _globals['_GATEWAYHELLO']._serialized_start=926
+  _globals['_GATEWAYHELLO']._serialized_end=1016
+  _globals['_WORKERHELLO']._serialized_start=1018
+  _globals['_WORKERHELLO']._serialized_end=1123
+  _globals['_WORKERREADY']._serialized_start=1126
+  _globals['_WORKERREADY']._serialized_end=1268
+  _globals['_WORKERCOMMAND']._serialized_start=1270
+  _globals['_WORKERCOMMAND']._serialized_end=1389
+  _globals['_WORKERCOMMANDREPLY']._serialized_start=1392
+  _globals['_WORKERCOMMANDREPLY']._serialized_end=1521
+  _globals['_WORKERCANCEL']._serialized_start=1523
+  _globals['_WORKERCANCEL']._serialized_end=1553
+  _globals['_WORKERSHUTDOWN']._serialized_start=1555
+  _globals['_WORKERSHUTDOWN']._serialized_end=1636
+  _globals['_WORKERSHUTDOWNACK']._serialized_start=1638
+  _globals['_WORKERSHUTDOWNACK']._serialized_end=1710
+  _globals['_WORKEREVENT']._serialized_start=1712
+  _globals['_WORKEREVENT']._serialized_end=1770
+  _globals['_WORKERHEARTBEAT']._serialized_start=1773
+  _globals['_WORKERHEARTBEAT']._serialized_end=2066
+  _globals['_WORKERFAULT']._serialized_start=2069
+  _globals['_WORKERFAULT']._serialized_end=2313
+# @@protoc_insertion_point(module_scope)

clients/python/src/mxgateway/generated/mxaccess_worker_pb2_grpc.py

@@ -0,0 +1,24 @@
+# Generated by the gRPC Python protocol compiler plugin. DO NOT EDIT!
+"""Client and server classes corresponding to protobuf-defined services."""
+import grpc
+import warnings
+
+
+GRPC_GENERATED_VERSION = '1.80.0'
+GRPC_VERSION = grpc.__version__
+_version_not_supported = False
+
+try:
+    from grpc._utilities import first_version_is_lower
+    _version_not_supported = first_version_is_lower(GRPC_VERSION, GRPC_GENERATED_VERSION)
+except ImportError:
+    _version_not_supported = True
+
+if _version_not_supported:
+    raise RuntimeError(
+        f'The grpc package installed is at version {GRPC_VERSION},'
+        + ' but the generated code in mxaccess_worker_pb2_grpc.py depends on'
+        + f' grpcio>={GRPC_GENERATED_VERSION}.'
+        + f' Please upgrade your grpc module to grpcio>={GRPC_GENERATED_VERSION}'
+        + f' or downgrade your generated code using grpcio-tools<={GRPC_VERSION}.'
+    )

clients/python/src/mxgateway/version.py

@@ -0,0 +1,3 @@
+"""Package version information."""
+
+__version__ = "0.1.0"

clients/python/src/mxgateway_cli/__init__.py

@@ -0,0 +1 @@
+"""Command-line entry points for the MXAccess Gateway Python client."""

clients/python/src/mxgateway_cli/__main__.py

@@ -0,0 +1,6 @@
+"""Module execution entry point for `python -m mxgateway_cli`."""
+
+from .commands import main
+
+if __name__ == "__main__":
+    main()

clients/python/src/mxgateway_cli/commands.py

@@ -0,0 +1,29 @@
+"""CLI scaffold for the MXAccess Gateway Python client."""
+
+import json
+
+import click
+
+from mxgateway import __version__
+
+
+@click.group()
+def main() -> None:
+    """MXAccess Gateway Python test CLI."""
+
+
+@main.command()
+@click.option("--json", "output_json", is_flag=True, help="Emit JSON output.")
+def version(output_json: bool) -> None:
+    """Print client package version information."""
+    payload = {
+        "client": "mxgw-py",
+        "package": "mxaccess-gateway-client",
+        "version": __version__,
+    }
+
+    if output_json:
+        click.echo(json.dumps(payload, sort_keys=True))
+        return
+
+    click.echo(f"mxgw-py {__version__}")

clients/python/tests/test_cli.py

@@ -0,0 +1,21 @@
+"""Tests for the Python CLI scaffold."""
+
+import json
+
+from click.testing import CliRunner
+
+from mxgateway import __version__
+from mxgateway_cli.commands import main
+
+
+def test_version_json_is_deterministic() -> None:
+    runner = CliRunner()
+
+    result = runner.invoke(main, ["version", "--json"])
+
+    assert result.exit_code == 0
+    assert json.loads(result.output) == {
+        "client": "mxgw-py",
+        "package": "mxaccess-gateway-client",
+        "version": __version__,
+    }

clients/python/tests/test_generated_imports.py

@@ -0,0 +1,30 @@
+"""Tests for generated protobuf and gRPC module importability."""
+
+from mxgateway.generated import mxaccess_gateway_pb2
+from mxgateway.generated import mxaccess_gateway_pb2_grpc
+from mxgateway.generated import mxaccess_worker_pb2
+
+
+def test_gateway_messages_import() -> None:
+    request = mxaccess_gateway_pb2.OpenSessionRequest(
+        client_session_name="pytest",
+        client_correlation_id="test-correlation",
+    )
+
+    assert request.client_session_name == "pytest"
+    assert hasattr(mxaccess_gateway_pb2_grpc, "MxAccessGatewayStub")
+
+
+def test_worker_messages_import_gateway_types() -> None:
+    envelope = mxaccess_worker_pb2.WorkerEnvelope(
+        protocol_version=1,
+        session_id="test-session",
+        worker_command=mxaccess_worker_pb2.WorkerCommand(
+            command=mxaccess_gateway_pb2.MxCommand(
+                kind=mxaccess_gateway_pb2.MX_COMMAND_KIND_PING,
+                ping=mxaccess_gateway_pb2.PingCommand(message="hello"),
+            ),
+        ),
+    )
+
+    assert envelope.worker_command.command.ping.message == "hello"

docs/client-proto-generation.md

@@ -131,6 +131,12 @@ Python clients should use `grpc_tools.protoc` and write generated modules under
 `clients/python/src/mxgateway/generated` so imports stay separate from
 handwritten async wrappers.
 
+The Python scaffold provides a repo-local generation script:
+
+```powershell
+clients/python/generate-proto.ps1
+```
+
 Java clients should use the Gradle protobuf plugin and write generated sources
 under `clients/java/src/main/generated`. The Java client scaffold owns the
 Gradle plugin versions and source-set wiring.