Introducing a new way to review your PRs.

Read the announcement

ruvnet / ruview

π RuView turns commodity WiFi signals into real-time spatial intelligence, vital sign monitoring, and presence detection — all without a single pixel of video.

View on GitHub

13 documents · Updated Nov 19, 2026

docs / python-bindings-package

Python bindings package

Overview

The v2 Python package is rooted in python/ and builds the wifi-densepose PyPI wheel as a PyO3/maturin project. python/pyproject.toml declares the package metadata, Python >=3.10, optional extras, pytest/ruff/mypy settings, and maturin configuration. The important maturin contract is python-source = "." and module-name = "wifi_densepose._native": pure Python files are shipped from python/wifi_densepose/, while the compiled extension is imported as the private module wifi_densepose._native. python/Cargo.toml defines the Rust crate wifi-densepose-py, with [lib] name = "wifi_densepose_native", crate-type = ["cdylib", "rlib"], and PyO3 abi3-py310, so one native artifact covers Python 3.10+ for each OS/architecture.

The Rust entry point is python/…/lib.rs. Its #[pymodule] function is named _native via #[pyo3(name = "_native")], matching python/pyproject.toml; it registers the bound classes and functions from python/…/*.rs, adds diagnostic constants __rust_version__, __rust_build_tag__, __build_features__, and exposes hello() for smoke tests. The pure facade in python/…/__init__.py imports wifi_densepose._native, re-exports the stable public API (Keypoint, PoseEstimate, BreathingExtractor, BfldFrame, etc.), sets the package __version__ = "2.0.0", and wraps the witness verifier as verify_witness(). End users should import from wifi_densepose, not _native.

The default compiled API binds these Rust-backed areas:

  • Core pose/keypoint types in python/…/keypoint.rs and python/…/pose.rs: KeypointType, Keypoint, BoundingBox, PersonPose, and PoseEstimate wrap wifi-densepose-core types. The binding validates confidence ranges on input, exposes COCO-17 keypoint ordering, keeps PersonPose mutable as a builder, and freezes top-level estimates.
  • Vitals in python/…/vitals.rs: CsiVitalPreprocessor, BreathingExtractor, HeartRateExtractor, VitalEstimate, VitalReading, and VitalStatus wrap wifi-densepose-vitals. The extractor calls run inside py.detach(...), so DSP work releases the GIL. HeartRateExtractor.extract() takes phases, not the older weights keyword, and empty phases fall back to equal weighting.
  • Beamforming feedback in python/…/bfld.rs: BfldKind, BfldFrame, and BfldReport expose a forward-compatible BFLD surface. BfldFrame.from_compressed_feedback(...) accepts a NumPy complex128 3-D array, checks the subcarrier dimension against BfldKind, copies it into Rust-owned row-major storage, and can allocate a fresh NumPy array through feedback_matrix().
  • Privacy gating in python/…/privacy_gate.rs: PrivacyClass and allows_hap/allows_network/allows_matter wrap wifi-densepose-bfld::PrivacyClass, making HomeKit/Matter eligibility checks use the Rust enum semantics.

Three SOTA subsystems are compiled only when Cargo features are enabled in python/Cargo.toml: aether, meridian, and mat, with sota as a convenience superset. Their Python modules are pure facades in python/…/aether.py, python/…/meridian.py, and python/…/mat.py; each imports _native, checks for its feature-specific symbols, and raises an ImportError that tells users to rebuild with maturin ... --features <name> when the base wheel lacks compiled code. Their .pyi files (python/wifi_densepose/aether.pyi, python/wifi_densepose/meridian.pyi, python/wifi_densepose/mat.pyi) provide strict type stubs for feature builds. The Rust implementations live in python/…/aether.rs (CSI embeddings, augmentation, InfoNCE, weight load/save), python/…/meridian.rs (hardware normalization, geometry encoding, rapid adaptation, cross-domain metrics), and python/…/mat.rs (disaster response config, event/zone setup, CSI ingestion, one-shot scanning, survivor triage). These bindings also use py.detach(...) for numeric work; MAT owns a current-thread Tokio runtime inside DisasterResponse to drive the async Rust scan once.

The optional pure-Python client layer lives under python/wifi_densepose/client/ and is controlled by the [client] extra in python/pyproject.toml. python/…/__init__.py eagerly re-exports stdlib-only HA/primitives helpers and lazily resolves SensingClient and RuViewMqttClient so importing wifi_densepose.client does not require websockets or paho-mqtt. python/…/ws.py decodes the sensing-server WebSocket stream into dataclasses, adds bearer auth from token= or RUVIEW_API_TOKEN, and inspects the installed websockets.connect signature to choose additional_headers vs extra_headers. python/…/mqtt.py wraps paho-mqtt v2, tracks per-topic-pattern handlers, JSON-decodes payloads when possible, and isolates user callback exceptions. python/…/ha.py parses Home Assistant MQTT discovery payloads, and python/…/primitives.py routes HA-MIND semantic primitive state topics into typed events.

The package also has release-adjacent Python artifacts. python/…/pyproject.toml builds the pure-Python ruview meta-package pinned to wifi-densepose==2.0.0; python/…/__init__.py imports wifi_densepose and re-exports names from its __all__. python/…/pyproject.toml builds the separate wifi-densepose==1.99.0 tombstone wheel, and python/…/__init__.py raises an ImportError with the v2 migration URL on first import. The repository root still has an older pyproject.toml, requirements.txt, requirements-dev.txt, and wifi_densepose/__init__.py for the legacy v1-style package; that root wifi_densepose shim can shadow the v2 wheel when running from the checkout, which is why python/…/witness.py recommends python -I or running outside the repository root.

Tests and examples are organized by surface. python/…/test_smoke.py verifies import, build metadata, _native, and hello(). python/…/test_keypoint.py, python/…/test_pose.py, python/…/test_vitals.py, python/…/test_bfld.py, and python/…/test_witness.py cover the default compiled API and the deterministic Rust vitals witness in python/…/witness.py. Client behavior is covered by python/…/test_client_ws.py, python/…/test_client_mqtt.py, python/…/test_client_ha.py, python/…/test_client_primitives.py, and adversarial client cases in python/…/test_security.py. Feature-gated SOTA tests are in python/…/test_aether.py, python/…/test_meridian.py, and python/…/test_mat.py, with native Rust parity harnesses in python/…/aether_parity.rs, python/…/aether_weights_parity.rs, python/…/meridian_parity.rs, and python/…/mat_parity.rs plus fixtures under python/tests/golden/. Benchmarks under python/bench/ measure vitals extraction, BFLD NumPy copying, WebSocket decode cost, and SOTA hot paths. The runnable examples in python/examples/ show feature-specific AETHER re-ID, MERIDIAN calibration, and MAT triage flows.

Coupling

  • If python/pyproject.toml changes tool.maturin.module-name, update python/…/lib.rs at the same time. The PyO3 initializer is explicitly named _native; a mismatch breaks import wifi_densepose._native before the facade in python/…/__init__.py can re-export anything.
  • If python/Cargo.toml feature names or optional dependency gates change, update the Python feature modules and tests together: python/…/aether.py, python/…/meridian.py, python/…/mat.py, their .pyi stubs, and python/…/test_aether.py / test_meridian.py / test_mat.py all assume symbols appear only in _native when the matching Cargo feature is enabled. The pyproject.toml extras are empty marker extras for compiled-feature builds; they do not add code to an already-built wheel.
  • If Rust core type semantics change in wifi-densepose-core, wifi-densepose-vitals, wifi-densepose-bfld, wifi-densepose-aether, wifi-densepose-train, wifi-densepose-signal, or wifi-densepose-mat, verify the wrappers in python/…/*.rs and the corresponding Python tests. The bindings manually translate enums, error types, dimensions, and Python-facing method names rather than auto-generating them from Rust.
  • If the sensing-server WebSocket or MQTT schemas change, update python/…/ws.py, python/…/mqtt.py, python/…/ha.py, and python/…/primitives.py with their tests. The client layer decodes raw JSON/topic strings directly and intentionally treats unknown WebSocket type values as a plain SensingMessage, so missing fields may fail softly rather than loudly.
  • If python/wifi_densepose/__init__.py.__all__ changes, update python/…/__init__.py expectations and python/tests/test_security.py::test_public_surface_is_stable. The ruview package dynamically mirrors wifi_densepose.__all__, so accidental omissions there also affect import ruview.
  • If the witness canonical format changes in python/…/witness.py, bump SCHEMA, regenerate the expected SHA fixture outside the package, and update python/…/test_witness.py. The witness hashes rounded, packed bytes from CsiVitalPreprocessor, BreathingExtractor, and HeartRateExtractor; changes in any stage can make the committed digest stale.

Risks

  • wifi_densepose/__init__.py at the repository root can shadow the v2 package in python/wifi_densepose/ when tests or examples run from the checkout root. If that happens, imports resolve to the legacy WiFiDensePose facade instead of the PyO3 wheel, so wifi_densepose._native and all v2 classes are missing. Run v2 package tests from python/, install via maturin, or use isolated mode as documented in python/…/witness.py.
  • python/…/bfld.rs copies every NumPy feedback matrix into a Rust Vec and feedback_matrix() allocates a fresh NumPy array on return. High-rate BFR ingestion can become allocation-bound; changes to BFLD throughput should be checked against python/…/test_bench_bfld_and_ws.py.
  • python/…/mat.rs embeds a single current-thread Tokio runtime inside each DisasterResponse and drives start_scanning() through block_on in scan_once(). Calling scan_once() before initialize_event() and add_zone() raises, and long-running scans still occupy that runtime even though the GIL is released.
  • The feature-module import guards in python/…/aether.py, python/…/meridian.py, and python/…/mat.py deliberately reject base wheels even though python/pyproject.toml advertises empty extras. If packaging starts publishing separate feature wheels, these guards and their tests must be updated or users will receive rebuild instructions that no longer match the install path.