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

clients/python/README.md

@@ -1,8 +1,8 @@
 # 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
+bindings, the async `mxgateway` package, and the `mxgw-py` test CLI. The
+package uses the shared proto inputs documented in
 `../../docs/client-proto-generation.md` so gateway and client contracts stay in
 sync.
 
@@ -43,15 +43,65 @@ 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.
+The tests import the generated gateway and worker stubs, run fake async gateway
+stubs, verify API key metadata, exercise stream cancellation, load shared value
+and command fixtures, and check deterministic CLI output.
+
+## Library Usage
+
+The library is async-first:
+
+```python
+from mxgateway import GatewayClient
+
+async with await GatewayClient.connect(
+    endpoint="localhost:5000",
+    api_key="mxgw_example",
+    plaintext=True,
+) as client:
+    session = await client.open_session(client_session_name="python-client")
+    try:
+        server_handle = await session.register("python-client")
+        item_handle = await session.add_item(server_handle, "Object.Attribute")
+        await session.advise(server_handle, item_handle)
+    finally:
+        await session.close()
+```
+
+`GatewayClient.open_session_raw`, `GatewayClient.invoke_raw`, and
+`GatewayClient.stream_events_raw` keep the generated protobuf replies and
+events available for parity tests. `Session` helpers call the method-specific
+MXAccess commands and preserve raw replies on typed command exceptions.
+
+Canceling a Python task cancels the client-side gRPC call or stream wait. It
+does not abort an in-flight MXAccess COM call inside the worker process.
+
+## Authentication And TLS
+
+`ClientOptions.api_key` adds this metadata to unary calls and streams:
+
+```text
+authorization: Bearer <api-key>
+```
+
+The client supports plaintext channels for local development, TLS with system
+roots, TLS with a custom `ca_file`, and an optional test server name override.
+API keys are redacted from option repr output and CLI error output.
 
 ## CLI
 
-The scaffold CLI exposes version information:
+The CLI emits deterministic JSON for automation:
 
 ```powershell
 mxgw-py version --json
+mxgw-py open-session --endpoint localhost:5000 --plaintext --json
+mxgw-py register --session-id <id> --client-name python-client --json
+mxgw-py add-item --session-id <id> --server-handle 1 --item Object.Attribute --json
+mxgw-py advise --session-id <id> --server-handle 1 --item-handle 2 --json
+mxgw-py stream-events --session-id <id> --max-events 1 --json
+mxgw-py write --session-id <id> --server-handle 1 --item-handle 2 --type int32 --value 123 --json
 ```
 
-Additional commands are implemented with the async client/session wrapper work.
+Use `--api-key` or `--api-key-env MXGATEWAY_API_KEY` to attach API key
+metadata. `smoke` opens a session, registers, adds an item, advises, streams a
+bounded event count, and closes the session in a `finally` block.