mirror of
https://github.com/ruvnet/RuView
synced 2026-06-17 11:33:19 +00:00
ruv
5d90d4fef2
ADR-117 P1 — the python/ directory is now a working maturin-buildable
crate that produces the v2.x replacement for the legacy pure-Python
wifi-densepose==1.1.0 PyPI wheel.
## What lands
- `python/Cargo.toml` — PyO3 0.22 with `extension-module` + `abi3-py310`
(one binary covers Python 3.10–3.13 per OS/arch — keeps the
cibuildwheel matrix to 5 wheels per release, not 20). Depends on
`wifi-densepose-core` from the existing v2/ workspace via relative
path.
- `python/pyproject.toml` — maturin>=1.7 build backend with
`python-source = "python"` and `module-name = "wifi_densepose._native"`
so the compiled module loads as an internal underscore-private
submodule of the user-facing `wifi_densepose` package. PEP 621
metadata + classifiers + project URLs. Optional-deps:
`wifi-densepose[client]` for the P4 WS/MQTT pure-Python layer,
`wifi-densepose[dev]` for the test toolchain (pytest, ruff, mypy).
- `python/src/lib.rs` — minimal `#[pymodule] wifi_densepose_native`
exporting `__rust_version__`, `__rust_build_tag__`,
`__build_features__`, and a `hello()` smoke function. P2 will land
the core type bindings here.
- `python/wifi_densepose/__init__.py` — pure-Python facade re-exporting
the compiled module's symbols under their stable user-facing names.
Docstring teaches the v1→v2 migration story up-front.
- `python/wifi_densepose/py.typed` — PEP 561 marker so `mypy --strict`
in user code treats the wheel as fully typed (real stubs land in P2).
- `python/tests/test_smoke.py` — 6 P1 acceptance tests:
1. package imports without error
2. version string is PEP 440-compliant
3. `__rust_version__` is reachable from Python (the diagnostic
surface ADR-117 §5.2 promised)
4. `__build_features__` lists `p1-scaffold` marker
5. `wifi_densepose.hello()` returns "ok" (FFI round-trip)
6. `wifi_densepose._native` is reachable but the leading underscore
conveys "private; users should import the parent package"
- `python/README.md` — phase ledger, local build instructions
(`maturin develop`), layout diagram.
## What's deferred to P2+
- Core type bindings (`CsiFrame`, `Keypoint`, `PoseEstimate`) — P2
- Vitals + signal DSP bindings + witness v2 — P3
- Pure-Python WS/MQTT client layer (`wifi_densepose[client]`) — P4
- cibuildwheel + PyPI publish — P5
- v1.99.0 tombstone — concurrent with P5
The new `python/` crate is intentionally OUTSIDE the v2/ Cargo
workspace — it has its own Cargo.toml with `[package]` not
`[workspace.package]` inheritance — to keep maturin's `python-source`
+ `module-name` config self-contained and to avoid forcing every
`cargo test --workspace` invocation in v2/ to compile pyo3.
Refs ADR-117 §5 (Detailed design) and §6 (Phased migration).
Refs #785 (tracking issue).
Co-Authored-By: claude-flow <ruv@ruv.net>
69 lines
2.4 KiB
Markdown
69 lines
2.4 KiB
Markdown
# `wifi-densepose` v2.x — PyO3 bindings for the Rust core
|
||
|
||
This directory contains the source for the `wifi-densepose` PyPI wheel
|
||
(v2.0+). It's a PyO3 + maturin build that wraps the Rust crates in
|
||
[`v2/crates/`](../v2/crates/) and replaces the legacy pure-Python
|
||
`wifi-densepose==1.1.0` (released 2025-06-07).
|
||
|
||
See [ADR-117](../docs/adr/ADR-117-pip-wifi-densepose-modernization.md)
|
||
for the full modernization plan.
|
||
|
||
## Build locally
|
||
|
||
```bash
|
||
# Install maturin + dev deps
|
||
pip install maturin pytest
|
||
|
||
# Develop-install — builds the Rust extension in-place
|
||
cd python
|
||
maturin develop
|
||
|
||
# Run the smoke tests
|
||
pytest tests/
|
||
```
|
||
|
||
The `maturin develop` command produces a debug-build wheel installed
|
||
into your current Python environment. For release builds:
|
||
|
||
```bash
|
||
maturin build --release --strip
|
||
```
|
||
|
||
The wheel lands under `python/target/wheels/`.
|
||
|
||
## Layout
|
||
|
||
```
|
||
python/
|
||
├── Cargo.toml # PyO3 + abi3-py310 + Rust deps
|
||
├── pyproject.toml # maturin backend + Python metadata
|
||
├── README.md # this file
|
||
├── src/
|
||
│ └── lib.rs # #[pymodule] — Rust binding glue
|
||
├── wifi_densepose/ # pure-Python facade (the user-facing API)
|
||
│ ├── __init__.py # re-exports compiled module symbols
|
||
│ └── py.typed # PEP 561 typed-package marker
|
||
└── tests/
|
||
└── test_smoke.py # P1 acceptance tests
|
||
```
|
||
|
||
## Phase status (per ADR-117 §6)
|
||
|
||
- ✅ **P1 — Scaffold (this commit)**: module loads, version constant
|
||
exposed, 6 smoke tests pass via `maturin develop`.
|
||
- ⏳ **P2 — Core type bindings**: `CsiFrame`, `Keypoint`, `PoseEstimate`.
|
||
- ⏳ **P3 — Vitals + signal DSP**: 4-stage HR/BR pipeline + `CsiProcessor`
|
||
+ `PhaseSanitizer`, with `allow_threads` GIL release on hot loops.
|
||
- ⏳ **P4 — WS/MQTT client**: pure-Python `wifi_densepose.client` extra.
|
||
- ⏳ **P5 — cibuildwheel + PyPI publish**: Linux/macOS/Windows × abi3-py310.
|
||
|
||
Each phase ends with a checkbox PR. Tests are additive — every phase's
|
||
smoke tests must still pass after later phases land.
|
||
|
||
## Migrating from v1.x
|
||
|
||
The v1 line was a separate pure-Python implementation. v2 is a hard
|
||
break (semver-justified by 11.5 months of stack drift). Migration
|
||
guide ships in [docs/migrations/wifi-densepose-1-to-2.md](../docs/migrations/wifi-densepose-1-to-2.md)
|
||
(landing in P5).
|