Add gateway implementation planning docs

docs/style-guides/PythonStyleGuide.md

@@ -0,0 +1,68 @@
+# Python Style Guide
+
+This guide defines Python conventions for the MXAccess Gateway Python package,
+CLI, and tests.
+
+## Baseline
+
+- Target modern supported Python versions defined by `pyproject.toml`.
+- Use `pyproject.toml` for package metadata and tool configuration.
+- Use type hints for public APIs and non-trivial internal functions.
+- Run the configured formatter and linter when the package is available.
+- Keep generated protobuf code separate from handwritten modules.
+
+## Source Documentation
+
+- Maintain the existing documentation style in the file, package, and
+  surrounding component.
+- Write comments that include business-specific or domain-specific context when
+  that context is available from the code, surrounding docs, or naming.
+- Use docstrings for public classes, functions, and modules when behavior,
+  parity constraints, or security requirements are not obvious from the name and
+  type hints.
+- Avoid comments that restate syntax or control flow.
+
+## Package Structure
+
+- Put library code under `src/mxgateway/`.
+- Put CLI entry points under `src/mxgateway_cli/`.
+- Keep generated protobuf modules under a clearly named `generated` package.
+- Avoid import side effects that open channels, read environment variables, or
+  start background tasks.
+
+## Naming
+
+- Use `snake_case` for functions, variables, modules, and methods.
+- Use `PascalCase` for classes and exceptions.
+- Use `UPPER_SNAKE_CASE` for constants.
+- Keep MXAccess names recognizable in public APIs, even when Python wrappers
+  use idiomatic method names.
+
+## Async
+
+- Make the client async-first.
+- Use async context managers for clients and sessions when practical.
+- Cancel gRPC streams when async iteration is canceled.
+- Document that canceling a Python task does not abort an in-flight MXAccess
+  COM call inside the worker.
+
+## Errors
+
+- Use typed exceptions for transport, authentication, authorization, session,
+  worker, command, and MXAccess failures.
+- Attach raw protobuf replies to command exceptions when available.
+- Redact API keys, passwords, and secured write values in exception messages and
+  CLI output.
+
+## CLI
+
+- Keep CLI output deterministic for tests.
+- Support JSON output for automation.
+- Load API keys from explicit flags or named environment variables. Do not read
+  secrets implicitly during module import.
+
+## Tests
+
+- Use `pytest` and `pytest-asyncio`.
+- Use fake generated stubs or an in-process test gRPC server for unit tests.
+- Keep live integration tests behind `MXGATEWAY_INTEGRATION=1`.