phystack-hub-client 6.18.2__tar.gz → 6.20.0__tar.gz

phystack_hub_client-6.20.0/CLAUDE.md

@@ -0,0 +1,41 @@
+# hub-client-py (Python)
+
+Python port of `packages/hub-client` (Node). Published to PyPI as
+`phystack-hub-client`, import path `phystack.hub_client`. Build backend:
+hatchling. Not part of the Bun workspace (no package.json — deliberate).
+
+Imported from the archived `phystack/phystack-pypi` repo; its full commit
+history lives on the `imported/phystack-pypi-main` branch of this repo.
+
+## Commands
+
+- `uv venv && uv pip install -e '.[dev]'` — set up (requires uv)
+- `uv run --no-sync pytest` — offline test suite (exactly what the
+  hub-client-py PR job runs)
+- `uv run --no-sync ruff check .` and `uv run --no-sync black .` — lint/format
+  (CI-gated, pinned versions in pyproject)
+- `tests/communication_harness.py` — LIVE two-device interop harness
+  (ROLE/PEER_TWIN_ID env vars); deliberately not named `test_*.py` so pytest
+  never collects it. Never runs in CI.
+- `scripts/python-node-test.sh` / `scripts/webrtc-test.sh` — live Node↔Python
+  interop; need `.env.interop-test` / `.env.webrtc-test` credentials.
+
+## Parity with the Node client
+
+`packages/hub-client` is the reference implementation. **Before finishing any
+change here, evaluate the Node client** — port behavior changes both ways, or
+record in the PR why the other client is unaffected. Wire formats and protocol
+constants MUST stay byte-identical.
+
+## Releasing
+
+**Python-only changes still need a changeset.** Both clients are in the same
+changesets fixed group: `bunx changeset`, select `@phystack/hub-client` — the
+Python version follows the Node bump automatically at publish. No changeset =
+no release. Never hand-edit `version` in `pyproject.toml`
+(`scripts/sync-py-version.ts` owns it).
+
+## Typing
+
+`[tool.mypy] strict = true` is configured but not CI-gated yet (dependencies
+lack stubs). Keep new code annotated; don't regress it.

{phystack_hub_client-6.18.2 → phystack_hub_client-6.20.0}/PKG-INFO

@@ -1,10 +1,10 @@
 Metadata-Version: 2.5
 Name: phystack-hub-client
-Version: 6.18.2
+Version: 6.20.0
 Summary: Python client for PhyHub - events, actions, DataChannel, and MediaStream
-Project-URL: Homepage, https://github.com/phystack/phystack-pypi
+Project-URL: Homepage, https://github.com/phystack/ps-platform
 Project-URL: Documentation, https://docs.phystack.com
-Project-URL: Repository, https://github.com/phystack/phystack-pypi
+Project-URL: Repository, https://github.com/phystack/ps-platform/tree/master/packages/hub-client-py
 Author-email: Phystack <dev@phystack.com>
 License-Expression: MIT
 Classifier: Development Status :: 3 - Alpha
@@ -22,11 +22,11 @@ Requires-Dist: opencv-python<5.0.0,>=4.8.0
 Requires-Dist: python-engineio<4.12.0,>=4.9.0
 Requires-Dist: python-socketio[asyncio-client]<5.12.0,>=5.11.0
 Provides-Extra: dev
-Requires-Dist: black>=23.0.0; extra == 'dev'
+Requires-Dist: black<26,>=25; extra == 'dev'
 Requires-Dist: mypy>=1.5.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
 Requires-Dist: pytest>=7.4.0; extra == 'dev'
-Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Requires-Dist: ruff<0.17,>=0.16; extra == 'dev'
 Description-Content-Type: text/markdown
 
 # Phystack Hub Client (Python)
@@ -36,6 +36,32 @@ Python client for PhyHub that provides:
 - WebRTC DataChannel for P2P data
 - WebRTC MediaStream for P2P video/audio (with webcam support)
 
+Python port of the Node client at `packages/hub-client` (`@phystack/hub-client`);
+both release under the same version.
+
+## Architecture
+
+```mermaid
+graph LR
+    App[Python App] --> HubClient[phystack-hub-client]
+    HubClient -->|Socket.IO| PhyHub[PhyHub Server]
+    HubClient -->|WebRTC| Peer[Peer Twin / Browser]
+    PhyHub --> TwinRegistry[Twin Registry]
+    PhyHub --> TwinMessaging[Twin Messaging]
+```
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+| Language | Python 3.10+ |
+| Build system | Hatch / hatchling |
+| WebSocket | python-socketio (async) |
+| WebRTC | aiortc |
+| Video capture | OpenCV |
+| Linting | Black, Ruff, mypy |
+| Testing | pytest, pytest-asyncio |
+
 ## Installation
 
 ```bash

{phystack_hub_client-6.18.2 → phystack_hub_client-6.20.0}/README.md

@@ -5,6 +5,32 @@ Python client for PhyHub that provides:
 - WebRTC DataChannel for P2P data
 - WebRTC MediaStream for P2P video/audio (with webcam support)
 
+Python port of the Node client at `packages/hub-client` (`@phystack/hub-client`);
+both release under the same version.
+
+## Architecture
+
+```mermaid
+graph LR
+    App[Python App] --> HubClient[phystack-hub-client]
+    HubClient -->|Socket.IO| PhyHub[PhyHub Server]
+    HubClient -->|WebRTC| Peer[Peer Twin / Browser]
+    PhyHub --> TwinRegistry[Twin Registry]
+    PhyHub --> TwinMessaging[Twin Messaging]
+```
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|------------|
+| Language | Python 3.10+ |
+| Build system | Hatch / hatchling |
+| WebSocket | python-socketio (async) |
+| WebRTC | aiortc |
+| Video capture | OpenCV |
+| Linting | Black, Ruff, mypy |
+| Testing | pytest, pytest-asyncio |
+
 ## Installation
 
 ```bash

{phystack_hub_client-6.18.2 → phystack_hub_client-6.20.0}/examples/browser_test_backend.py

@@ -24,7 +24,7 @@ from typing import Any, Optional
 # Add src to path for local development
 sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
 
-from phystack.hub_client import PhyHubClient, TwinMessageResult, TwinMessageResultStatus
+from phystack.hub_client import PhyHubClient, TwinMessageResult
 
 
 # ANSI colors
@@ -123,10 +123,13 @@ class BrowserTestRunner:
 
         # Send events
         for i in range(1, expected_count + 1):
-            instance.to(self.peer_twin_id).emit("test-event", {
-                "count": i,
-                "timestamp": int(time.time() * 1000),
-            })
+            instance.to(self.peer_twin_id).emit(
+                "test-event",
+                {
+                    "count": i,
+                    "timestamp": int(time.time() * 1000),
+                },
+            )
             log_info(f"  Sent event {i}")
             await asyncio.sleep(0.2)
 
@@ -302,7 +305,7 @@ async def run_interactive() -> None:
 
     try:
         async with PhyHubClient.from_env() as client:
-            log_success(f"Connected to PhyHub")
+            log_success("Connected to PhyHub")
 
             instance = await client.get_instance()
             if instance:
@@ -317,6 +320,7 @@ async def run_interactive() -> None:
     except Exception as e:
         log_error(f"Error: {e}")
         import traceback
+
         traceback.print_exc()
         sys.exit(1)
 
@@ -366,15 +370,20 @@ async def run_continuous() -> None:
                         break
                     elif cmd == "e":
                         if instance:
-                            instance.to(peer_twin_id).emit("test-event", {
-                                "count": 1,
-                                "timestamp": int(time.time() * 1000),
-                            })
+                            instance.to(peer_twin_id).emit(
+                                "test-event",
+                                {
+                                    "count": 1,
+                                    "timestamp": int(time.time() * 1000),
+                                },
+                            )
                             log_info("Sent event")
                     elif cmd == "a":
                         if instance:
+
                             def cb(r: TwinMessageResult) -> None:
                                 log_info(f"Response: {r.status.value} - {r.message}")
+
                             instance.to(peer_twin_id).emit("test-action", {"count": 1}, callback=cb)
                             log_info("Sent action")
                     elif cmd == "d":

{phystack_hub_client-6.18.2 → phystack_hub_client-6.20.0}/pyproject.toml

@@ -4,10 +4,11 @@ build-backend = "hatchling.build"
 
 [project]
 name = "phystack-hub-client"
-# Fixed version group with the Node hub-client (@phystack/hub-client in
-# phystack/ps-platform): both clients implement the same twin/WebRTC contract
-# and are released together under the same version.
-version = "6.18.2"
+# Fixed version group with the Node hub-client (@phystack/hub-client): both
+# clients implement the same twin/WebRTC contract and release under the same
+# version. Managed by scripts/sync-py-version.ts during ci:version - do not
+# edit by hand.
+version = "6.20.0"
 description = "Python client for PhyHub - events, actions, DataChannel, and MediaStream"
 readme = "README.md"
 license = "MIT"
@@ -47,15 +48,17 @@ dependencies = [
 dev = [
     "pytest>=7.4.0",
     "pytest-asyncio>=0.21.0",
-    "black>=23.0.0",
-    "ruff>=0.1.0",
+    # black/ruff are CI formatting gates; pinned to a minor so a new linter
+    # release cannot redden master.
+    "black>=25,<26",
+    "ruff>=0.16,<0.17",
     "mypy>=1.5.0",
 ]
 
 [project.urls]
-Homepage = "https://github.com/phystack/phystack-pypi"
+Homepage = "https://github.com/phystack/ps-platform"
 Documentation = "https://docs.phystack.com"
-Repository = "https://github.com/phystack/phystack-pypi"
+Repository = "https://github.com/phystack/ps-platform/tree/master/packages/hub-client-py"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/phystack"]
@@ -66,6 +69,8 @@ target-version = ["py310"]
 
 [tool.ruff]
 line-length = 100
+
+[tool.ruff.lint]
 select = ["E", "F", "I", "W"]
 
 [tool.mypy]

{phystack_hub_client-6.18.2 → phystack_hub_client-6.20.0}/scripts/python-node-test.sh

@@ -198,7 +198,7 @@ run_python_initiator() {
     PEER_TWIN_ID="$DEVICE_B_TWIN_ID" \
     PHYHUB_REGION="$PHYHUB_REGION" \
     ROLE=initiator \
-    python tests/test_communication.py 2>&1 | tee "$LOCAL_LOG"
+    python tests/communication_harness.py 2>&1 | tee "$LOCAL_LOG"
 }
 
 # Start Python responder
@@ -213,7 +213,7 @@ start_python_responder() {
     PEER_TWIN_ID="$DEVICE_B_TWIN_ID" \
     PHYHUB_REGION="$PHYHUB_REGION" \
     ROLE=responder \
-    python tests/test_communication.py > "$LOCAL_LOG" 2>&1 &
+    python tests/communication_harness.py > "$LOCAL_LOG" 2>&1 &
 
     log_info "Waiting for Python responder to be ready..."
     sleep 5
@@ -259,7 +259,7 @@ collect_results() {
 cleanup() {
     log_info "Cleaning up..."
     pkill -f 'communication-comprehensive-test' 2>/dev/null || true
-    pkill -f 'test_communication.py' 2>/dev/null || true
+    pkill -f 'communication_harness.py' 2>/dev/null || true
     rm -f "$REMOTE_LOG" "$LOCAL_LOG" 2>/dev/null || true
     log_success "Cleanup complete"
 }

{phystack_hub_client-6.18.2 → phystack_hub_client-6.20.0}/scripts/webrtc-test.sh

@@ -184,7 +184,7 @@ start_remote_responder() {
     log_info "Starting Python responder on remote host..."
 
     # Kill any existing responder process
-    ssh "$REMOTE_HOST" "pkill -f 'test_communication.py' 2>/dev/null || true"
+    ssh "$REMOTE_HOST" "pkill -f 'communication_harness.py' 2>/dev/null || true"
     sleep 1
 
     # Copy env file to remote
@@ -202,7 +202,7 @@ export ACCESS_KEY="\$DEVICE_B_KEY"
 export PEER_TWIN_ID="\$DEVICE_A_TWIN_ID"
 export PHYHUB_REGION="\$PHYHUB_REGION"
 export ROLE=responder
-./venv/bin/python tests/test_communication.py
+./venv/bin/python tests/communication_harness.py
 EOF
     scp -q "$tmp_script" "$REMOTE_HOST:$REMOTE_PATH/run-responder.sh"
     rm -f "$tmp_script"
@@ -241,7 +241,7 @@ run_local_initiator() {
     PEER_TWIN_ID="$DEVICE_B_TWIN_ID" \
     PHYHUB_REGION="$PHYHUB_REGION" \
     ROLE=initiator \
-    python tests/test_communication.py 2>&1 | tee "$LOCAL_LOG"
+    python tests/communication_harness.py 2>&1 | tee "$LOCAL_LOG"
 }
 
 # Collect and display results
@@ -264,7 +264,7 @@ cleanup() {
     log_info "Cleaning up..."
 
     # Kill remote responder
-    ssh "$REMOTE_HOST" "pkill -f 'test_communication.py' 2>/dev/null || true"
+    ssh "$REMOTE_HOST" "pkill -f 'communication_harness.py' 2>/dev/null || true"
 
     # Clean remote logs
     ssh "$REMOTE_HOST" "rm -f $REMOTE_LOG 2>/dev/null || true"
@@ -281,7 +281,7 @@ cmd_clean() {
 
     log_info "Cleaning up remote host..."
 
-    ssh "$REMOTE_HOST" "pkill -f 'test_communication.py' 2>/dev/null || true"
+    ssh "$REMOTE_HOST" "pkill -f 'communication_harness.py' 2>/dev/null || true"
     ssh "$REMOTE_HOST" "rm -rf $REMOTE_PATH 2>/dev/null || true"
     ssh "$REMOTE_HOST" "rm -f $REMOTE_LOG 2>/dev/null || true"
 

{phystack_hub_client-6.18.2 → phystack_hub_client-6.20.0}/src/phystack/hub_client/__init__.py

@@ -44,44 +44,61 @@ Or with context manager:
         stream = await instance.get_media_stream(peer_twin_id)
 """
 
+from importlib.metadata import PackageNotFoundError, version
+
+from phystack.hub_client.advisory_validation import (
+    CompiledValidator,
+    DescriptorValidator,
+    validate_emitted_facet,
+)
 from phystack.hub_client.client import PhyHubClient, connect_phy_client
-from phystack.hub_client.types.twin_types import (
-    PeripheralCreateResult,
-    PeripheralHandover,
-    PeripheralOwnershipLoss,
-    TwinMessageResult,
-    TwinMessageResultStatus,
-    TwinProperties,
-    TwinTypeEnum,
-    TwinStatusEnum,
+from phystack.hub_client.cloud_twins import CloudTwinStore
+from phystack.hub_client.instances import (
+    BaseInstance,
+    EdgeInstance,
+    PeripheralInstance,
 )
 from phystack.hub_client.scoped_hardware_id import (
     HARDWARE_ID_SCOPES,
     HARDWARE_ID_USER_PART_MAX_LENGTH,
     format_scoped_hardware_id,
 )
-from phystack.hub_client.instances import (
-    BaseInstance,
-    EdgeInstance,
-    PeripheralInstance,
+from phystack.hub_client.services.cloud_app_connection import (
+    CloudAppConnection,
+    CloudAppConnectionParams,
+    CloudAppConnectResult,
+)
+from phystack.hub_client.services.cloud_app_token import (
+    CloudAppToken,
+    CloudAppTokenExchangeError,
+    exchange_cloud_app_token,
+)
+from phystack.hub_client.services.signals import (
+    CheckoutProduct,
+    CheckoutProps,
+    DataRequestTypeEnum,
+    DataResidencyEnum,
+    EventTypeEnum,
+    InitSignalPayload,
+    PurchaseProps,
+    SignalsService,
+)
+from phystack.hub_client.services.web_session_code import (
+    WebSessionCode,
+    WebSessionCodeConfigError,
+    WebSessionCodeIssuer,
+    WebSessionCodeListener,
+    WebSessionCodeState,
 )
-from phystack.hub_client.twin_registry import TwinRegistry
 from phystack.hub_client.services.webrtc.data_channel import (
     DataChannelHandler,
     DataChannelOptions,
     PhygridDataChannel,
 )
-from phystack.hub_client.services.webrtc.media_stream import (
-    MediaStreamHandler,
-    MediaStreamOptions,
-    MediaTrackKind,
-    MissingMediaTrackError,
-    PhygridMediaStream,
-    WebcamVideoTrack,
-)
-from phystack.hub_client.services.webrtc.media_source import (
-    FrameSourceTrack,
-    VideoFrameSource,
+from phystack.hub_client.services.webrtc.data_responder import (
+    DataChannelResponder,
+    DataChannelResponderOptions,
+    ResponderChannel,
 )
 from phystack.hub_client.services.webrtc.media_responder import (
     MediaStreamResponder,
@@ -89,48 +106,37 @@ from phystack.hub_client.services.webrtc.media_responder import (
     PeerCapReachedError,
     ResponderPeer,
 )
-from phystack.hub_client.services.webrtc.data_responder import (
-    DataChannelResponder,
-    DataChannelResponderOptions,
-    ResponderChannel,
-)
-from phystack.hub_client.advisory_validation import (
-    CompiledValidator,
-    DescriptorValidator,
-    validate_emitted_facet,
-)
-from phystack.hub_client.services.cloud_app_token import (
-    CloudAppToken,
-    CloudAppTokenExchangeError,
-    exchange_cloud_app_token,
-)
-from phystack.hub_client.services.cloud_app_connection import (
-    CloudAppConnection,
-    CloudAppConnectionParams,
-    CloudAppConnectResult,
+from phystack.hub_client.services.webrtc.media_source import (
+    FrameSourceTrack,
+    VideoFrameSource,
 )
-from phystack.hub_client.cloud_twins import CloudTwinStore
-from phystack.hub_client.services.web_session_code import (
-    WebSessionCode,
-    WebSessionCodeConfigError,
-    WebSessionCodeIssuer,
-    WebSessionCodeListener,
-    WebSessionCodeState,
+from phystack.hub_client.services.webrtc.media_stream import (
+    MediaStreamHandler,
+    MediaStreamOptions,
+    MediaTrackKind,
+    MissingMediaTrackError,
+    PhygridMediaStream,
+    WebcamVideoTrack,
 )
-from phystack.hub_client.services.signals import (
-    SignalsService,
-    InitSignalPayload,
-    DataRequestTypeEnum,
-    DataResidencyEnum,
-    EventTypeEnum,
-    CheckoutProps,
-    CheckoutProduct,
-    PurchaseProps,
+from phystack.hub_client.twin_registry import TwinRegistry
+from phystack.hub_client.types.twin_types import (
+    PeripheralCreateResult,
+    PeripheralHandover,
+    PeripheralOwnershipLoss,
+    TwinMessageResult,
+    TwinMessageResultStatus,
+    TwinProperties,
+    TwinStatusEnum,
+    TwinTypeEnum,
 )
 
 # Kept in a fixed version group with @phystack/hub-client (npm) — same
 # contract, same release version.
-__version__ = "6.16.0"
+try:
+    __version__ = version("phystack-hub-client")
+except PackageNotFoundError:
+    # Running from an uninstalled source tree (no dist metadata).
+    __version__ = "0.0.0"
 __all__ = [
     # Client
     "PhyHubClient",