plexus-python 0.4.9__tar.gz → 0.5.2__tar.gz

{plexus_python-0.4.9 → plexus_python-0.5.2}/.github/workflows/ci.yml

@@ -31,7 +31,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
+        python-version: ['3.10', '3.11', '3.12', '3.13']
 
     steps:
       - uses: actions/checkout@v4

{plexus_python-0.4.9 → plexus_python-0.5.2}/CHANGELOG.md

@@ -1,5 +1,87 @@
 # Changelog
 
+## [0.5.2] - 2026-05-21 - DX hardening for hardware engineers
+
+### Fixed
+
+- Error messages now reference `plexus init` instead of the non-existent `plexus start`.
+- `close()` now attempts to flush any buffered points before tearing down the transport,
+  preventing silent data loss on graceful shutdown.
+- `persistent_buffer` default changed from `False` to `True` — store-and-forward is now
+  on by default, matching the `~/.plexus/config.json` default and the right choice for
+  field hardware. Pass `persistent_buffer=False` to opt out (e.g. in test fixtures).
+
+### Added
+
+- `send_batch()` now accepts 3-tuples `(metric, value, timestamp)` alongside the existing
+  2-tuple form. Per-point timestamps let sensors on different interrupt timers share a
+  single batch call. 2-tuples continue to use the shared `timestamp` argument.
+- `on_command()` now warns immediately via stderr if called after the WebSocket has already
+  authenticated, making the "register before first send()" ordering requirement visible
+  rather than silently broken.
+- `source_id` is validated against `^[a-z0-9][a-z0-9_-]{1,62}$` at construction time.
+  Invalid names now raise `ValueError` with a clear message instead of failing obscurely
+  at the gateway.
+
+### Changed
+
+- `_say()` / `_QUIET` consolidated into a new internal `plexus/_log.py` module.
+  Previously duplicated verbatim between `client.py` and `ws.py`.
+
+## [0.5.1] - 2026-05-19 - Binary video frames + non-blocking send
+
+### Performance
+
+- `send_video_frame()` now sends a compact binary WebSocket frame instead of
+  JSON+base64. The binary header encodes source_id, camera_id, width, height,
+  and timestamp_ms; the JPEG payload follows raw. Eliminates the 33% base64
+  wire overhead, reducing per-frame bandwidth by ~25% and raising the
+  sustainable FPS ceiling from ~15–20 fps to ~20–25 fps at 1280×720 quality 85.
+- Gateway decodes the binary header and re-encodes as JSON+base64 before
+  relaying to browsers — no changes required in the frontend, data_api, or any
+  other consumer.
+
+### Reliability
+
+- `send_video_frame()` is now non-blocking. Frames are placed into a
+  `queue.Queue(maxsize=2)` drained by a dedicated `plexus-video` daemon thread.
+  When the queue is full (sender backlogged) frames are dropped rather than
+  blocking the capture pipeline, preventing deadlocks at any FPS.
+- `stop()` / `close()` now exits cleanly within 0.5 s regardless of in-flight
+  sends. Previously a slow or hung WebSocket write could stall shutdown
+  indefinitely.
+
+### Changed
+
+- Removed `import base64` from `client.py` (no longer needed on the send path).
+- `send_video_frame()` calls `ws.send_video_frame_async()` instead of the
+  internal `ws._send_frame()`.
+
+### Wire protocol
+
+- Gateway handles both binary frames (SDK ≥ 0.5.1) and legacy JSON text frames
+  transparently — older SDKs continue to work unchanged.
+
+## [0.5.0] - 2026-05-19 - Security hardening, dep cleanup, Python 3.10+ only
+
+### Security
+
+- Removed `requests` (and its transitive deps `urllib3`, `idna`) entirely —
+  replaced with stdlib `urllib.request`. Closes 6 Dependabot alerts (#6, #9,
+  #10, #11, #12, #13, #19) by eliminating the vulnerability surface rather than
+  patching it.
+- Bumped `Pillow>=12.2.0` (fixes #14, #15, #16, #17, #18, #20 — OOB write,
+  FITS decompression bomb, font integer overflow, PDF parsing DoS, and related
+  CVEs).
+- Bumped `pytest>=9.0.3` in dev deps (fixes #7).
+
+### Changed
+
+- Dropped Python 3.8 and 3.9 support — both are past EOL and the patched
+  versions of Pillow and pytest all require `>=3.10`. `requires-python` is now
+  `>=3.10`.
+- CI matrix: removed 3.8/3.9 runners, added 3.13.
+
 ## [0.4.9] - 2026-05-19 - Video input broadening and wire safety
 
 ### Added

{plexus_python-0.4.9 → plexus_python-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexus-python
-Version: 0.4.9
+Version: 0.5.2
 Summary: Thin Python SDK for Plexus — send telemetry in one line
 Project-URL: Homepage, https://plexus.dev
 Project-URL: Documentation, https://docs.plexus.dev
@@ -15,22 +15,20 @@ Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Scientific/Engineering
 Classifier: Topic :: System :: Hardware
-Requires-Python: >=3.9
-Requires-Dist: requests>=2.32.4
+Requires-Python: >=3.10
 Requires-Dist: websocket-client>=1.7
 Provides-Extra: dev
 Requires-Dist: pytest-cov; extra == 'dev'
-Requires-Dist: pytest>=8.3.5; extra == 'dev'
+Requires-Dist: pytest>=9.0.3; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Requires-Dist: websockets>=12; extra == 'dev'
 Provides-Extra: video
-Requires-Dist: pillow>=11.2.1; extra == 'video'
+Requires-Dist: pillow>=12.2.0; extra == 'video'
 Description-Content-Type: text/markdown
 
 # plexus-python
@@ -70,34 +68,108 @@ The name must match `^[a-z0-9][a-z0-9_-]{1,62}$`. `setup.sh` refuses to run with
 
 In normal code, you usually just pass `source_id=...` explicitly to `Plexus(...)` and never have to think about it.
 
-## Usage
+## Core methods
 
-```python
-from plexus import Plexus
+### `send(metric, value)` — stream a reading
+
+The main method. Call it every time you have a new sensor reading.
 
+```python
 px = Plexus(source_id="rig-01")   # reads PLEXUS_API_KEY from env
 
-# Numbers
 px.send("engine.rpm", 3450)
-px.send("coolant.temperature", 82.3, tags={"unit": "C"})
+px.send("coolant.temp", 82.3)
+```
 
-# Strings, bools, objects, arrays — all JSON-serializable
-px.send("vehicle.state", "RUNNING")
-px.send("motor.enabled", True)
-px.send("position", {"x": 1.5, "y": 2.3, "z": 0.8})
+`metric` is a dot-namespaced string (`"motor.rpm"`, `"gps.fix_quality"`). `value` accepts any JSON-serializable type:
 
-# Batch
+| Type | Example | When to use |
+|------|---------|-------------|
+| `float` / `int` | `72.5`, `3450` | Sensor readings, counters |
+| `str` | `"RUNNING"`, `"E_STALL"` | State machines, error codes |
+| `bool` | `True` | Binary flags |
+| `dict` | `{"x": 1.5, "y": 2.3}` | Vectors, structured readings |
+| `list` | `[0.5, 1.2, -0.3]` | Waveforms, joint angles |
+
+Optional arguments:
+- `tags={"motor_id": "A1"}` — key-value labels for filtering in the dashboard
+- `timestamp=t` — explicit Unix timestamp in seconds; omit to let the SDK pick (see [Timestamps](#timestamps-and-clock-correction))
+
+### `send_batch(points)` — send multiple readings at once
+
+Use this when you sample several sensors together and want them to share a timestamp and land in one network call.
+
+```python
 px.send_batch([
-    ("temperature", 72.5),
-    ("pressure", 1013.25),
+    ("temperature", 22.4),
+    ("humidity",    58.1),
+    ("pressure",    1013.2),
 ])
+```
+
+`points` is a list of `(metric, value)` tuples. All points share the same timestamp (now, unless you pass `timestamp=t`). For independent timestamps per point, call `send()` in a loop instead.
+
+### `event(name, data)` — record a discrete occurrence
+
+Use `event()` for things that *happen* rather than things you *measure continuously*. Faults, state transitions, operator actions, log entries — anything you'd put on a timeline as a marker rather than plot as a graph.
+
+```python
+px.event("fault",        "E-stop triggered")
+px.event("state_change", {"from": "IDLE", "to": "RUNNING"})
+px.event("sensor_error", {"sensor": "imu", "code": 42}, tags={"motor": "A"})
+```
+
+The platform displays events as markers overlaid on your telemetry charts, not as time-series lines.
+
+### `run(run_id)` — group data into a named recording
 
-# Named run for grouping related data
+```python
 with px.run("thermal-cycle-001"):
     while running:
         px.send("temperature", read_temp())
 ```
 
+All `send()` calls inside the context are tagged with `run_id`, making it easy to isolate and replay that slice of data in the dashboard.
+
+## Video streaming
+
+Two methods depending on whether you control the capture loop or just have a URL.
+
+### `send_video_frame(frame, camera_id)` — send frames you capture yourself
+
+Use this when your code owns the capture loop — a `picamera2` callback, an OpenCV `VideoCapture` loop, or an FFmpeg pipe you manage. Pass each frame and the SDK ships it to Plexus over WebSocket.
+
+```python
+import cv2
+
+cap = cv2.VideoCapture(0)
+while True:
+    ok, frame = cap.read()
+    if ok:
+        px.send_video_frame(frame, camera_id="front")
+```
+
+Accepted frame types:
+- **numpy ndarray** (H × W × C) — from OpenCV or picamera2; requires `opencv-python`
+- **JPEG bytes** — passed through as-is, zero re-encode overhead
+- **Other image bytes** (PNG, BMP, WebP) — decoded and re-encoded as JPEG via Pillow; requires `pip install plexus-python[video]`
+
+`camera_id` identifies which camera the frame came from. Use distinct IDs when streaming from multiple cameras simultaneously (`"front"`, `"rear"`, `"cam:0"`).
+
+### `stream_camera(url, camera_id)` — stream from an RTSP URL or file
+
+Use this when you have an RTSP stream or video file and don't want to manage the capture loop yourself. The SDK runs FFmpeg internally and handles the rest. Requires FFmpeg on `$PATH`.
+
+```python
+stop = px.stream_camera("rtsp://192.168.1.100/stream", camera_id="front")
+# ... do other work ...
+stop.set()  # stop streaming
+```
+
+Returns a `threading.Event` — call `.set()` to stop. Runs in a background thread so it doesn't block your main loop.
+
+**Which to use:** if you're piping from `rpicam-vid`, `picamera2`, or your own capture process, use `send_video_frame()`. If you have an RTSP URL or file path, use `stream_camera()`.
+
 ## Bring Your Own Protocol
 
 This package ships no adapters, auto-detection, or daemons — just the client. Use whatever library you'd use anyway and pipe values into `px.send()`.

{plexus_python-0.4.9 → plexus_python-0.5.2}/README.md

@@ -35,34 +35,108 @@ The name must match `^[a-z0-9][a-z0-9_-]{1,62}$`. `setup.sh` refuses to run with
 
 In normal code, you usually just pass `source_id=...` explicitly to `Plexus(...)` and never have to think about it.
 
-## Usage
+## Core methods
 
-```python
-from plexus import Plexus
+### `send(metric, value)` — stream a reading
+
+The main method. Call it every time you have a new sensor reading.
 
+```python
 px = Plexus(source_id="rig-01")   # reads PLEXUS_API_KEY from env
 
-# Numbers
 px.send("engine.rpm", 3450)
-px.send("coolant.temperature", 82.3, tags={"unit": "C"})
+px.send("coolant.temp", 82.3)
+```
 
-# Strings, bools, objects, arrays — all JSON-serializable
-px.send("vehicle.state", "RUNNING")
-px.send("motor.enabled", True)
-px.send("position", {"x": 1.5, "y": 2.3, "z": 0.8})
+`metric` is a dot-namespaced string (`"motor.rpm"`, `"gps.fix_quality"`). `value` accepts any JSON-serializable type:
 
-# Batch
+| Type | Example | When to use |
+|------|---------|-------------|
+| `float` / `int` | `72.5`, `3450` | Sensor readings, counters |
+| `str` | `"RUNNING"`, `"E_STALL"` | State machines, error codes |
+| `bool` | `True` | Binary flags |
+| `dict` | `{"x": 1.5, "y": 2.3}` | Vectors, structured readings |
+| `list` | `[0.5, 1.2, -0.3]` | Waveforms, joint angles |
+
+Optional arguments:
+- `tags={"motor_id": "A1"}` — key-value labels for filtering in the dashboard
+- `timestamp=t` — explicit Unix timestamp in seconds; omit to let the SDK pick (see [Timestamps](#timestamps-and-clock-correction))
+
+### `send_batch(points)` — send multiple readings at once
+
+Use this when you sample several sensors together and want them to share a timestamp and land in one network call.
+
+```python
 px.send_batch([
-    ("temperature", 72.5),
-    ("pressure", 1013.25),
+    ("temperature", 22.4),
+    ("humidity",    58.1),
+    ("pressure",    1013.2),
 ])
+```
+
+`points` is a list of `(metric, value)` tuples. All points share the same timestamp (now, unless you pass `timestamp=t`). For independent timestamps per point, call `send()` in a loop instead.
+
+### `event(name, data)` — record a discrete occurrence
+
+Use `event()` for things that *happen* rather than things you *measure continuously*. Faults, state transitions, operator actions, log entries — anything you'd put on a timeline as a marker rather than plot as a graph.
+
+```python
+px.event("fault",        "E-stop triggered")
+px.event("state_change", {"from": "IDLE", "to": "RUNNING"})
+px.event("sensor_error", {"sensor": "imu", "code": 42}, tags={"motor": "A"})
+```
+
+The platform displays events as markers overlaid on your telemetry charts, not as time-series lines.
+
+### `run(run_id)` — group data into a named recording
 
-# Named run for grouping related data
+```python
 with px.run("thermal-cycle-001"):
     while running:
         px.send("temperature", read_temp())
 ```
 
+All `send()` calls inside the context are tagged with `run_id`, making it easy to isolate and replay that slice of data in the dashboard.
+
+## Video streaming
+
+Two methods depending on whether you control the capture loop or just have a URL.
+
+### `send_video_frame(frame, camera_id)` — send frames you capture yourself
+
+Use this when your code owns the capture loop — a `picamera2` callback, an OpenCV `VideoCapture` loop, or an FFmpeg pipe you manage. Pass each frame and the SDK ships it to Plexus over WebSocket.
+
+```python
+import cv2
+
+cap = cv2.VideoCapture(0)
+while True:
+    ok, frame = cap.read()
+    if ok:
+        px.send_video_frame(frame, camera_id="front")
+```
+
+Accepted frame types:
+- **numpy ndarray** (H × W × C) — from OpenCV or picamera2; requires `opencv-python`
+- **JPEG bytes** — passed through as-is, zero re-encode overhead
+- **Other image bytes** (PNG, BMP, WebP) — decoded and re-encoded as JPEG via Pillow; requires `pip install plexus-python[video]`
+
+`camera_id` identifies which camera the frame came from. Use distinct IDs when streaming from multiple cameras simultaneously (`"front"`, `"rear"`, `"cam:0"`).
+
+### `stream_camera(url, camera_id)` — stream from an RTSP URL or file
+
+Use this when you have an RTSP stream or video file and don't want to manage the capture loop yourself. The SDK runs FFmpeg internally and handles the rest. Requires FFmpeg on `$PATH`.
+
+```python
+stop = px.stream_camera("rtsp://192.168.1.100/stream", camera_id="front")
+# ... do other work ...
+stop.set()  # stop streaming
+```
+
+Returns a `threading.Event` — call `.set()` to stop. Runs in a background thread so it doesn't block your main loop.
+
+**Which to use:** if you're piping from `rpicam-vid`, `picamera2`, or your own capture process, use `send_video_frame()`. If you have an RTSP URL or file path, use `stream_camera()`.
+
 ## Bring Your Own Protocol
 
 This package ships no adapters, auto-detection, or daemons — just the client. Use whatever library you'd use anyway and pipe values into `px.send()`.

{plexus_python-0.4.9 → plexus_python-0.5.2}/examples/uv.lock

@@ -674,11 +674,11 @@ wheels = [
 
 [[package]]
 name = "urllib3"
-version = "2.6.3"
+version = "2.7.0"
 source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/c7/24/5f1b3bdffd70275f6661c76461e25f024d5a38a46f04aaca912426a2b1d3/urllib3-2.6.3.tar.gz", hash = "sha256:1b62b6884944a57dbe321509ab94fd4d3b307075e0c2eae991ac71ee15ad38ed", size = 435556, upload-time = "2026-01-07T16:24:43.925Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/53/0c/06f8b233b8fd13b9e5ee11424ef85419ba0d8ba0b3138bf360be2ff56953/urllib3-2.7.0.tar.gz", hash = "sha256:231e0ec3b63ceb14667c67be60f2f2c40a518cb38b03af60abc813da26505f4c", size = 433602, upload-time = "2026-05-07T16:13:18.596Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/39/08/aaaad47bc4e9dc8c725e68f9d04865dbcb2052843ff09c97b08904852d84/urllib3-2.6.3-py3-none-any.whl", hash = "sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4", size = 131584, upload-time = "2026-01-07T16:24:42.685Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/3e/5db95bcf282c52709639744ca2a8b149baccf648e39c8cc87553df9eae0c/urllib3-2.7.0-py3-none-any.whl", hash = "sha256:9fb4c81ebbb1ce9531cce37674bbc6f1360472bc18ca9a553ede278ef7276897", size = 131087, upload-time = "2026-05-07T16:13:17.151Z" },
 ]
 
 [[package]]

{plexus_python-0.4.9 → plexus_python-0.5.2}/plexus/__init__.py

@@ -10,5 +10,5 @@ Plexus — thin Python SDK for sending telemetry to the Plexus gateway.
 from plexus.client import Plexus, read_mjpeg_frames
 from plexus.ws import WebSocketTransport
 
-__version__ = "0.4.9"
+__version__ = "0.5.2"
 __all__ = ["Plexus", "WebSocketTransport", "read_mjpeg_frames"]

plexus_python-0.5.2/plexus/_log.py

@@ -0,0 +1,15 @@
+import os
+import sys
+
+_QUIET = os.environ.get("PLEXUS_QUIET", "").lower() in ("1", "true", "yes")
+
+
+def _say(line: str) -> None:
+    """Single-line status message to stderr. Skipped if PLEXUS_QUIET=1."""
+    if _QUIET:
+        return
+    try:
+        sys.stderr.write(f"[plexus] {line}\n")
+        sys.stderr.flush()
+    except Exception:
+        pass