chore: import upstream snapshot with attribution

2026-07-13 11:59:54 +08:00
commit 9740bc64c9
2636 changed files with 1330642 additions and 0 deletions
@@ -0,0 +1,93 @@
+"""ADR-117 P4 — Pure-Python client layer.
+
+This sub-package is the **client-facing** half of `wifi-densepose`:
+end users who only want to *consume* live RuView telemetry (rather than
+running DSP locally) get a tight, opt-in client extra:
+
+```
+pip install "wifi-densepose[client]"
+```
+
+The runtime install footprint stays small for users who only need the
+compiled PyO3 surface: `websockets` and `paho-mqtt` are declared as the
+`[client]` extra in `pyproject.toml` and are NOT pulled in by the
+default install.
+
+## Modules
+
+- `ws` — `SensingClient`: asyncio WebSocket client for the
+  sensing-server `/ws/sensing` endpoint (ADR-115 §1)
+- `mqtt` — `RuViewMqttClient`: paho-mqtt v2 wrapper for
+  `ruview/<node>/raw/+` + `homeassistant/+/wifi_densepose_<node>/+/+`
+  topics (ADR-115 §3)
+- `primitives` — `SemanticPrimitiveListener`: typed view over the
+  10 HA-MIND semantic primitives (ADR-115 §3.12)
+- `ha` — `HABlueprintHelper`: parses MQTT-discovery payloads, helps
+  users introspect what entities a node is publishing
+
+No PyO3 here — this module is pure Python so it loads without the
+compiled extension (useful for users who only want the client surface
+and not the DSP pipeline).
+"""
+
+from __future__ import annotations
+
+# Re-export the user-facing types. Import errors are deferred to the
+# moment the user actually instantiates one of these classes — that way
+# `from wifi_densepose.client import HABlueprintHelper` still works
+# even if the user hasn't installed `[client]` extras yet (HABlueprint
+# is pure stdlib).
+from wifi_densepose.client.ha import (
+    HaDiscoveryPayload,
+    HaEntity,
+    HABlueprintHelper,
+)
+from wifi_densepose.client.primitives import (
+    SemanticPrimitive,
+    SemanticPrimitiveEvent,
+    SemanticPrimitiveListener,
+)
+
+
+__all__ = [
+    # ws — re-exported lazily; see module docstring
+    "SensingClient",
+    "SensingMessage",
+    "EdgeVitalsMessage",
+    "PoseDataMessage",
+    "ConnectionEstablishedMessage",
+    # mqtt — re-exported lazily; see module docstring
+    "RuViewMqttClient",
+    # ha — pure stdlib
+    "HaDiscoveryPayload",
+    "HaEntity",
+    "HABlueprintHelper",
+    # primitives — pure stdlib
+    "SemanticPrimitive",
+    "SemanticPrimitiveEvent",
+    "SemanticPrimitiveListener",
+]
+
+
+def __getattr__(name: str):
+    """Lazy re-exports for the modules that pull in optional extras.
+
+    `SensingClient` needs `websockets`; `RuViewMqttClient` needs
+    `paho-mqtt`. Importing those at package init would make
+    `wifi_densepose.client` unusable without the extras installed
+    — defeating the point of an *optional* extra. We defer the import
+    until the attribute is actually looked up.
+    """
+    if name in {
+        "SensingClient",
+        "SensingMessage",
+        "EdgeVitalsMessage",
+        "PoseDataMessage",
+        "ConnectionEstablishedMessage",
+    }:
+        from wifi_densepose.client import ws as _ws
+        return getattr(_ws, name)
+    if name == "RuViewMqttClient":
+        from wifi_densepose.client.mqtt import RuViewMqttClient as _R
+        return _R
+    raise AttributeError(f"module 'wifi_densepose.client' has no attribute {name!r}")