feat: add Python pip-publishable SDK for CSM-TCP-Router

[Copilot]

• Create _errors.py – shared _parse_server_error helper (removes duplication between client.py and async_client.py)
• _transport.py – close socket in exception path (fixes fd leak in retry loops)
• client.py – add _resp_lock/_cmd_resp_lock threading locks to serialise concurrent waiters; fix docstring; disconnect() injects sentinels to unblock blocked threads; import from _errors
• async_client.py – add _resp_lock/_cmd_resp_lock asyncio locks; disconnect() injects sentinels; use inspect.isawaitable for callback detection; import from _errors
• CHANGELOG.md – fix duplicate ### Added block; move 0.1.0 content into proper ## [0.1.0] section
• tests/test_async_client.py – update _client_with_queues() and test_send_when_not_connected_raises to call _init_async_objects() so locks are also initialised
• Lint: ruff – all checks passed
• Tests: 114/114 passed

[Copilot]

Pull request overview

This PR introduces a pip-publishable Python SDK (csm-tcp-router-client) for the CSM-TCP-Router protocol v0, expanding the existing sync client with a full asyncio client, packaging metadata, CI, docs, examples, and a comprehensive test suite.

Changes:

• Added AsyncTcpRouterClient (asyncio-based API) alongside a sync TcpRouterClient, plus internal protocol/transport layers and public models/exceptions.
• Added unit + integration tests (including a TCP MockServer fixture) covering protocol, sync client, and async client behavior.
• Added packaging/CI/docs/examples for PyPI/TestPyPI publishing and end-user onboarding.

Reviewed changes

Copilot reviewed 22 out of 22 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
SDK/python-package/tests/test_protocol.py	Adds unit tests for protocol encode/decode/parse behavior.
SDK/python-package/tests/test_integration.py	Adds integration tests for the sync client against a real TCP mock server.
SDK/python-package/tests/test_client.py	Adds sync client unit tests using mocked transport + direct packet injection.
SDK/python-package/tests/test_async_client.py	Adds async client unit + integration tests.
SDK/python-package/tests/conftest.py	Provides MockServer fixture used by integration tests.
SDK/python-package/tests/init.py	Marks tests as a package.
SDK/python-package/src/csm_tcp_router/models.py	Defines public enums/models (PacketType, responses, notifications).
SDK/python-package/src/csm_tcp_router/exceptions.py	Defines the SDK exception hierarchy.
SDK/python-package/src/csm_tcp_router/client.py	Implements the sync TcpRouterClient API on top of the transport.
SDK/python-package/src/csm_tcp_router/async_client.py	Implements AsyncTcpRouterClient using asyncio streams/queues.
SDK/python-package/src/csm_tcp_router/_transport.py	Implements the internal threaded TCP transport and receive loop.
SDK/python-package/src/csm_tcp_router/_protocol.py	Implements protocol v0 framing/codec utilities.
SDK/python-package/src/csm_tcp_router/init.py	Exposes top-level public API and sets version to 0.2.0.
SDK/python-package/pyproject.toml	Adds build/test/lint configuration and package metadata for v0.2.0.
SDK/python-package/examples/subscribe_status.py	Adds sync example demonstrating status subscription callbacks.
SDK/python-package/examples/basic_usage.py	Adds sync quickstart example (connect/ping/list modules).
SDK/python-package/examples/async_usage.py	Adds asyncio quickstart example covering core features.
SDK/python-package/README.zh-cn.md	Adds full Chinese documentation for installation, API, and usage.
SDK/python-package/README.md	Adds English documentation for installation, API, and usage.
SDK/python-package/LICENSE	Adds MIT license file.
SDK/python-package/CHANGELOG.md	Adds changelog entries for 0.2.0 and initial release notes.
.github/workflows/Python_SDK.yml	Adds CI for lint/test/build and gated TestPyPI→PyPI publishing on tags.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

_parse_server_error() is duplicated in both client.py and async_client.py. To avoid the two implementations drifting over time, consider moving this into a shared internal helper (e.g., _errors.py) and importing it from both clients.

[Copilot]

The 0.2.0 section contains a second "### Added" block that appears to describe the initial release (0.1.0), but it’s still nested under 0.2.0. This makes the changelog ambiguous. Consider adding a dedicated ## [0.1.0] – <date> section (or moving these bullets under [Unreleased] if appropriate) instead of repeating "### Added" under 0.2.0.

Suggested change

	## [0.1.0]

[Copilot]

Transport.connect() creates the socket inside the try, but on OSError it raises without closing the partially-created socket. In retry loops like wait_for_server(), this can leak file descriptors. Close sock in the exception path (e.g., sock.close() in a finally/except block) before re-raising RouterConnectionError.

Suggested change

	)
	try:
	sock=socket.socket(socket.AF_INET, socket.SOCK_STREAM)
	sock.settimeout(timeout)
	sock.connect((host, port))
	sock.settimeout(None) # switch to blocking for the recv loop
	exceptOSErrorasexc:
	)
	sock: Optional[socket.socket] =None
	try:
	sock=socket.socket(socket.AF_INET, socket.SOCK_STREAM)
	sock.settimeout(timeout)
	sock.connect((host, port))
	sock.settimeout(None) # switch to blocking for the recv loop
	exceptOSErrorasexc:
	ifsockisnotNone:
	try:
	sock.close()
	exceptOSError:
	pass

[Copilot]

The class docstring claims the client is thread-safe and that multiple threads may call methods concurrently, but synchronous commands share a single _resp_queue/_cmd_resp_queue with no request correlation or serialization. Concurrent send_and_wait() calls can consume each other’s responses (and an ERROR/disconnect sentinel only unblocks one waiter), so the concurrency guarantee is not correct as written. Either (a) enforce a single in-flight waiter per queue via locks, or (b) revise the docstring to document the single-in-flight limitation.

[Copilot]

disconnect() only closes the transport; it does not notify/unblock any threads currently waiting in _wait_for_resp() / _wait_for_cmd_resp(). If a disconnect happens while another thread is blocked, it will wait until timeout even though the connection is already gone. Consider having disconnect() (or Transport.disconnect()) inject a connection-lost sentinel into the internal queues (and ensure it wakes all waiters).

Suggested change

	defdisconnect(self) ->None:
	"""Disconnectfromtheserverandreleaseallresources.
	Safetocallevenifnotcurrentlyconnected.
	"""
	def_enqueue_disconnect_sentinel(self, q: object) ->None:
	"""Wake queue-based waiters with a connection-lost error."""
	ifnotisinstance(q, queue.Queue):
	return
	# Enqueue enough sentinels to wake any threads currently blocked on
	# queue.get() without relying on timeout expiry.
	waiter_count=max(1, threading.active_count())
	for_inrange(waiter_count):
	try:
	q.put_nowait(RouterConnectionError("Disconnected from server"))
	exceptqueue.Full:
	break
	def_notify_disconnect_waiters(self) ->None:
	"""Inject connection-lost sentinels into internal response queues."""
	self._enqueue_disconnect_sentinel(getattr(self, "_resp_queue", None))
	self._enqueue_disconnect_sentinel(getattr(self, "_cmd_resp_queue", None))
	defdisconnect(self) ->None:
	"""Disconnectfromtheserverandreleaseallresources.
	Safetocallevenifnotcurrentlyconnected.
	"""
	self._notify_disconnect_waiters()

[Copilot]

Async callbacks are detected via asyncio.iscoroutinefunction(cb), but that misses callables where __call__ returns an awaitable (callable objects, some wrappers), which can lead to un-awaited coroutine warnings and dropped work. A more robust pattern is to call the callback and then await the result if it is awaitable (e.g., via inspect.isawaitable). Apply the same approach for both async-resp and status callbacks.

[Copilot]

_notify_disconnect() only enqueues a single ConnectionError sentinel into each waiter queue. If multiple coroutines are concurrently blocked on _wait_for_resp() / _wait_for_cmd_resp(), only one will be released and the others can hang until timeout. Consider re-queueing the sentinel after a waiter consumes it, or switch to an event/flag checked by waiters so all pending operations fail fast on disconnect.

[Copilot]

send_and_wait() awaits the next item from the shared _resp_queue, but there is no serialization/correlation between requests. If multiple tasks call send_and_wait() concurrently, responses can be delivered to the wrong caller. Consider adding an async lock to allow only one in-flight send_and_wait() at a time (and similarly for cmd-resp waiters), or document that these methods must not be used concurrently on the same client instance.

[nevstop]

@copilot apply changes based on the comments in this thread

[Copilot]

@copilot apply changes based on the comments in this thread

All 8 review-comment issues addressed in commit 716b7bb:

1. _parse_server_error duplication → extracted to _errors.py, imported by both client.py and async_client.py.
2. Socket leak in Transport.connect() → sock initialised to None before try; closed in except path before re-raising.
3. Thread-safety docstring → updated to document the single-in-flight limitation; added _resp_lock / _cmd_resp_lock threading locks to actually enforce it.
4. disconnect() not unblocking waiters (sync) → disconnect() now injects a ConnectionError sentinel into both queues before tearing down the transport.
5. send_and_wait() concurrent access (async) → added _resp_lock / _cmd_resp_lock asyncio locks (created in _init_async_objects); all command methods acquire the appropriate lock.
6. _notify_disconnect() single sentinel (async) → with at-most-one-waiter-per-queue enforced by the new locks, one sentinel per queue is sufficient; disconnect() also injects sentinels for explicit-disconnect cases.
7. Async callback detection → replaced asyncio.iscoroutinefunction(cb) with inspect.isawaitable(result) after calling the callback, covering callable objects and wrappers.
8. CHANGELOG duplicate ### Added → removed the duplicate block under [0.2.0]; 0.1.0 content moved to its own ## [0.1.0] section.

114/114 tests pass; ruff and CodeQL clean.