plexus-python 0.4.8__py3-none-any.whl → 0.5.1__py3-none-any.whl

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.8"
+__version__ = "0.5.1"
 __all__ = ["Plexus", "WebSocketTransport", "read_mjpeg_frames"]

plexus/client.py

@@ -33,21 +33,21 @@ Usage:
 Note: Requires authentication. Run 'plexus start' or set PLEXUS_API_KEY.
 """
 
-import base64
 import gzip
 import json
 import logging
 import os
 import shutil
+import socket
 import subprocess
 import sys
 import threading
 import time
+import urllib.error
+import urllib.request
 from contextlib import contextmanager
 from typing import Any, Dict, Generator, List, Optional, Tuple, Union
 
-import requests
-
 from plexus.buffer import BufferBackend, MemoryBuffer, SqliteBuffer
 from plexus.config import (
     RetryConfig,
@@ -61,6 +61,46 @@ from plexus.config import (
 )
 logger = logging.getLogger(__name__)
 
+
+class _Response:
+    __slots__ = ("status_code", "text")
+
+    def __init__(self, status_code: int, text: str):
+        self.status_code = status_code
+        self.text = text
+
+
+class _Session:
+    def __init__(self):
+        self.headers: Dict[str, str] = {}
+
+    def post(self, url: str, data: bytes = b"", headers: Optional[Dict[str, str]] = None, timeout: float = 10.0) -> "_Response":
+        req_headers = {**self.headers, **(headers or {})}
+        req = urllib.request.Request(url, data=data, headers=req_headers, method="POST")
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                return _Response(resp.status, resp.read().decode("utf-8", errors="replace"))
+        except urllib.error.HTTPError as e:
+            return _Response(e.code, e.read().decode("utf-8", errors="replace"))
+        except urllib.error.URLError as e:
+            if isinstance(e.reason, socket.timeout):
+                raise _Timeout(str(e.reason))
+            raise _ConnError(str(e.reason))
+        except (TimeoutError, socket.timeout) as e:
+            raise _Timeout(str(e))
+
+    def close(self) -> None:
+        pass
+
+
+class _Timeout(OSError):
+    pass
+
+
+class _ConnError(OSError):
+    pass
+
+
 # Status messages to stderr so users running `python my_script.py` see what's
 # happening without having to configure logging. Set PLEXUS_QUIET=1 to disable.
 _QUIET = os.environ.get("PLEXUS_QUIET", "").lower() in ("1", "true", "yes")
@@ -166,7 +206,7 @@ class Plexus:
         self._max_buffer_size = max_buffer_size
 
         self._run_id: Optional[str] = None
-        self._session: Optional[requests.Session] = None
+        self._session: Optional[_Session] = None
         self._store_frames: bool = False
         self._cv2 = None
         self._pil_image = None  # lazy PIL.Image import
@@ -202,10 +242,9 @@ class Plexus:
         self._max_buffer_size = value
         self._buffer._max_size = value
 
-    def _get_session(self) -> requests.Session:
-        """Get or create a requests session for connection pooling."""
+    def _get_session(self) -> _Session:
         if self._session is None:
-            self._session = requests.Session()
+            self._session = _Session()
             if self.api_key:
                 self._session.headers["x-api-key"] = self.api_key
             self._session.headers["Content-Type"] = "application/json"
@@ -524,21 +563,15 @@ class Plexus:
 
         jpeg_bytes, width, height = self._encode_frame(frame, quality)
         jpeg_bytes = self._fit_to_wire(jpeg_bytes, quality)
-        b64 = base64.b64encode(jpeg_bytes).decode()
 
         ws = self._ensure_ws()
         if not ws.is_authenticated:
             ws.wait_authenticated(timeout=min(self.timeout, 5.0))
 
-        return ws._send_frame({
-            "type": "video_frame",
-            "source_id": self.source_id,
-            "camera_id": camera_id,
-            "frame": b64,
-            "width": width,
-            "height": height,
-            "timestamp": self._normalize_ts_ms(timestamp),
-        })
+        return ws.send_video_frame_async(
+            self.source_id, camera_id, jpeg_bytes, width, height,
+            self._normalize_ts_ms(timestamp),
+        )
 
     def stream_camera(
         self,
@@ -732,14 +765,14 @@ class Plexus:
                         f"API error: {response.status_code} - {response.text}"
                     )
 
-            except requests.exceptions.Timeout:
+            except _Timeout:
                 last_error = PlexusError(f"Request timed out after {self.timeout}s")
                 if attempt < self.retry_config.max_retries:
                     time.sleep(self.retry_config.get_delay(attempt))
                     continue
                 break
 
-            except requests.exceptions.ConnectionError as e:
+            except _ConnError as e:
                 last_error = PlexusError(f"Connection failed: {e}")
                 if attempt < self.retry_config.max_retries:
                     time.sleep(self.retry_config.get_delay(attempt))
@@ -839,13 +872,13 @@ class Plexus:
         try:
             self._get_session().post(
                 f"{self.endpoint}/api/runs",
-                json={
+                data=json.dumps({
                     "run_id": run_id,
                     "source_id": self.source_id,
                     "status": "started",
                     "tags": tags,
                     "timestamp": (int(time.time() * 1000) + self._clock_offset_ms) / 1000,
-                },
+                }).encode("utf-8"),
                 timeout=self.timeout,
             )
         except Exception as e:
@@ -858,12 +891,12 @@ class Plexus:
             try:
                 self._get_session().post(
                     f"{self.endpoint}/api/runs",
-                    json={
+                    data=json.dumps({
                         "run_id": run_id,
                         "source_id": self.source_id,
                         "status": "ended",
                         "timestamp": (int(time.time() * 1000) + self._clock_offset_ms) / 1000,
-                    },
+                    }).encode("utf-8"),
                     timeout=self.timeout,
                 )
             except Exception as e:

plexus/ws.py

@@ -29,7 +29,9 @@ import atexit
 import json
 import logging
 import os
+import queue
 import random
+import struct
 import sys
 import threading
 import time
@@ -134,6 +136,8 @@ class WebSocketTransport:
         self._thread: Optional[threading.Thread] = None
         self._backoff_attempt = 0
         self._clock_offset_ms: int = 0
+        self._video_queue: "queue.Queue[bytes]" = queue.Queue(maxsize=2)
+        self._video_thread: Optional[threading.Thread] = None
 
     # ------------------------------------------------------------------ public
 
@@ -159,6 +163,10 @@ class WebSocketTransport:
             target=self._run, name="plexus-ws", daemon=True
         )
         self._thread.start()
+        self._video_thread = threading.Thread(
+            target=self._video_sender_loop, name="plexus-video", daemon=True
+        )
+        self._video_thread.start()
         atexit.register(self.stop)
 
     def stop(self, timeout: float = 2.0) -> None:
@@ -172,6 +180,8 @@ class WebSocketTransport:
                 pass
         if self._thread:
             self._thread.join(timeout=timeout)
+        if self._video_thread:
+            self._video_thread.join(timeout=timeout)
 
     def wait_authenticated(self, timeout: float = AUTH_TIMEOUT_S) -> bool:
         return self._authenticated.wait(timeout=timeout)
@@ -194,6 +204,28 @@ class WebSocketTransport:
         frame = {"type": "telemetry", "points": points}
         return self._send_frame(frame)
 
+    def send_video_frame_async(
+        self,
+        source_id: str,
+        camera_id: str,
+        jpeg_bytes: bytes,
+        width: int,
+        height: int,
+        timestamp_ms: int,
+    ) -> bool:
+        """Encode and enqueue a binary video frame. Non-blocking — drops the
+        frame if the queue is full rather than blocking the caller."""
+        if not self._authenticated.is_set():
+            return False
+        payload = _encode_binary_video_frame(
+            source_id, camera_id, jpeg_bytes, width, height, timestamp_ms
+        )
+        try:
+            self._video_queue.put_nowait(payload)
+            return True
+        except queue.Full:
+            return False
+
     # ------------------------------------------------------------------ thread
 
     def _run(self) -> None:
@@ -228,6 +260,28 @@ class WebSocketTransport:
             if self._stop.wait(timeout=delay):
                 break
 
+    def _video_sender_loop(self) -> None:
+        """Drain _video_queue and send binary WebSocket frames.
+
+        Runs on a dedicated thread so slow sends never block the caller.
+        Drops frames during reconnect rather than queuing stale video.
+        """
+        while not self._stop.is_set():
+            try:
+                payload = self._video_queue.get(timeout=0.5)
+            except queue.Empty:
+                continue
+            if not self._authenticated.is_set():
+                continue  # drop during auth / reconnect
+            with self._ws_lock:
+                ws = self._ws
+            if ws is None:
+                continue
+            try:
+                ws.send_binary(payload)
+            except Exception as e:
+                logger.debug("plexus video send failed: %s", e)
+
     def _connect_and_serve(self) -> None:
         ws = websocket.create_connection(self.ws_url, timeout=AUTH_TIMEOUT_S)
         with self._ws_lock:
@@ -400,6 +454,37 @@ class WebSocketTransport:
 # --------------------------------------------------------------------- helpers
 
 
+def _encode_binary_video_frame(
+    source_id: str,
+    camera_id: str,
+    jpeg_bytes: bytes,
+    width: int,
+    height: int,
+    timestamp_ms: int,
+) -> bytes:
+    """Pack a video frame into the binary wire format.
+
+    Wire layout:
+        [0x01]          1 byte   version
+        [src_len]       1 byte   source_id byte length (capped at 255)
+        [source_id]     N bytes
+        [cam_len]       1 byte   camera_id byte length (capped at 255)
+        [camera_id]     M bytes
+        [width]         4 bytes  uint32 big-endian
+        [height]        4 bytes  uint32 big-endian
+        [timestamp_ms]  8 bytes  int64  big-endian
+        [jpeg_bytes]    rest
+    """
+    src = source_id.encode("utf-8")[:255]
+    cam = camera_id.encode("utf-8")[:255]
+    header = (
+        bytes([0x01, len(src)]) + src
+        + bytes([len(cam)]) + cam
+        + struct.pack(">IIq", width, height, timestamp_ms)
+    )
+    return header + jpeg_bytes
+
+
 def _ensure_device_path(url: str) -> str:
     url = url.rstrip("/")
     if url.endswith("/ws/device"):

{plexus_python-0.4.8.dist-info → plexus_python-0.5.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexus-python
-Version: 0.4.8
+Version: 0.5.1
 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,23 +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.8
-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.8
-Requires-Dist: requests>=2.28.0
+Requires-Python: >=3.10
 Requires-Dist: websocket-client>=1.7
 Provides-Extra: dev
-Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-cov; 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>=9.0; extra == 'video'
+Requires-Dist: pillow>=12.2.0; extra == 'video'
 Description-Content-Type: text/markdown
 
 # plexus-python
@@ -71,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.5.1.dist-info/RECORD

@@ -0,0 +1,11 @@
+plexus/__init__.py,sha256=mNRP4PCXuMoMvaKh05M-1u3GrJL4TAhqA8nEY1xdiSY,385
+plexus/buffer.py,sha256=3ykybqLs7yMXxQWFajAT8nGe3cs_lW8_6Xvn0vQ69dE,9262
+plexus/cli.py,sha256=-2wvHXQzobx3_tDGTXpaE2PlHv884y93Mu29kZE8qZE,14214
+plexus/client.py,sha256=z8CNy0EFA0Ol3If1lIKgyndYYaqD67lvB0iuGV62Nsc,34034
+plexus/config.py,sha256=wsG6lhNLmKe3JRlVycyRUKQeywnPUPPfrWkXFxYwELE,6179
+plexus/ws.py,sha256=lSVv-Yf4ODZ0TaziKEF9pEmgVOLAJHMlluULqVydePs,17683
+plexus_python-0.5.1.dist-info/METADATA,sha256=HHSsxh19qh99fkDFErlFzdCqxtT3zj0q4VCj8jre72Y,11531
+plexus_python-0.5.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+plexus_python-0.5.1.dist-info/entry_points.txt,sha256=YlkOtTn_7Q_IGuJaKdvpU-90dCeBSPx2p_UTGMAz5Zs,43
+plexus_python-0.5.1.dist-info/licenses/LICENSE,sha256=nm3qP1F-JAGcfLpRVtIX24L20LMnRpxmZ2oKZzFpLVo,10755
+plexus_python-0.5.1.dist-info/RECORD,,

plexus_python-0.4.8.dist-info/RECORD

@@ -1,11 +0,0 @@
-plexus/__init__.py,sha256=TSQdqBAXxoyHxbeAr-UNcqZG411PCmxiM8kpI-hcc2s,385
-plexus/buffer.py,sha256=3ykybqLs7yMXxQWFajAT8nGe3cs_lW8_6Xvn0vQ69dE,9262
-plexus/cli.py,sha256=-2wvHXQzobx3_tDGTXpaE2PlHv884y93Mu29kZE8qZE,14214
-plexus/client.py,sha256=qWooAr2-Y8FUr_wpwnjXwdygGuHhPZLCYuVVU2cBziY,33047
-plexus/config.py,sha256=wsG6lhNLmKe3JRlVycyRUKQeywnPUPPfrWkXFxYwELE,6179
-plexus/ws.py,sha256=4nmNganwS_1BujdFkH3u3lLBB7rEkPYd_oYrbdYkdY4,14818
-plexus_python-0.4.8.dist-info/METADATA,sha256=ssT_r6xkkeT5E6SBx2RWCP008vYhlMqtFMyi1yBRhd4,8188
-plexus_python-0.4.8.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-plexus_python-0.4.8.dist-info/entry_points.txt,sha256=YlkOtTn_7Q_IGuJaKdvpU-90dCeBSPx2p_UTGMAz5Zs,43
-plexus_python-0.4.8.dist-info/licenses/LICENSE,sha256=nm3qP1F-JAGcfLpRVtIX24L20LMnRpxmZ2oKZzFpLVo,10755
-plexus_python-0.4.8.dist-info/RECORD,,