plexus-python 0.4.6__tar.gz → 0.4.8__tar.gz

{plexus_python-0.4.6 → plexus_python-0.4.8}/CHANGELOG.md

@@ -1,5 +1,52 @@
 # Changelog
 
+## [0.4.8] - 2026-05-19 - Video input broadening and wire safety
+
+### Added
+
+- `send_video_frame` now accepts raw bytes/bytearray: JPEG bytes are passed
+  through without re-encoding (zero CPU cost on hardware that outputs JPEG
+  natively); other formats (PNG, BMP, WebP) are decoded via Pillow and
+  re-encoded as JPEG. Install `plexus-python[video]` for Pillow support.
+- `stream_camera(url, camera_id, fps, quality)` — streams from any
+  FFmpeg-supported source (RTSP, video file, capture device). Requires FFmpeg
+  on `$PATH`. Returns a `threading.Event`; call `.set()` to stop.
+- `read_mjpeg_frames(pipe)` — public generator that parses raw MJPEG byte
+  streams (e.g. FFmpeg stdout) into individual JPEG frames by SOI/EOI markers.
+  Useful for custom FFmpeg pipelines before handing off to `send_video_frame`.
+- Optional `video` extras group: `pip install plexus-python[video]` installs
+  Pillow for non-JPEG input decoding and automatic oversized-frame downsampling.
+
+### Changed
+
+- Frames that would exceed the gateway's 1 MB wire limit are automatically
+  re-encoded at a proportionally lower quality. A one-time warning is printed
+  to stderr; subsequent frames are silently clamped.
+- `stream_camera` raises `PlexusError` synchronously (before spawning a thread)
+  when FFmpeg is not found, rather than silently dying in the background.
+
+## [0.4.7] - 2026-05-14 - Video streaming API
+
+### Added
+
+- `Plexus.send_video_frame(frame, camera_id, quality, timestamp)` — high-level
+  API for streaming camera frames. Accepts a numpy array (e.g. from
+  `cv2.VideoCapture.read()`), handles JPEG encoding, base64, dimensions, and
+  auth wait internally. Requires `transport="ws"` and `opencv-python`.
+
+### Changed
+
+- Gateway WebSocket URL (`wss://plexus-gateway.fly.dev`) is now the SDK
+  default — no need to pass `ws_url` explicitly.
+- Removed the `[plexus]   endpoint: …` line from the connection printout.
+
+### Performance
+
+- Eliminated per-frame `buf.tobytes()` copy in `send_video_frame` by passing
+  the numpy buffer directly to `base64.b64encode` (buffer protocol).
+- `base64` imported at module level; `cv2` imported once on first call and
+  cached, removing repeated import overhead from the hot path.
+
 ## [0.4.5] - 2026-04-27 - Stderr status output (re-release of 0.4.4)
 
 Same code as 0.4.4 — the 0.4.4 publish workflow failed lint on a stray

{plexus_python-0.4.6 → plexus_python-0.4.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexus-python
-Version: 0.4.6
+Version: 0.4.8
 Summary: Thin Python SDK for Plexus — send telemetry in one line
 Project-URL: Homepage, https://plexus.dev
 Project-URL: Documentation, https://docs.plexus.dev
@@ -30,6 +30,8 @@ Requires-Dist: pytest; extra == 'dev'
 Requires-Dist: pytest-cov; extra == 'dev'
 Requires-Dist: ruff; extra == 'dev'
 Requires-Dist: websockets>=12; extra == 'dev'
+Provides-Extra: video
+Requires-Dist: pillow>=9.0; extra == 'video'
 Description-Content-Type: text/markdown
 
 # plexus-python

plexus_python-0.4.8/examples/.python-version

@@ -0,0 +1 @@
+3.12

{plexus_python-0.4.6 → plexus_python-0.4.8}/examples/README.md

@@ -9,5 +9,6 @@ Each script is standalone — copy into your project, adjust the `source_id`, an
 | `can.py` | Vehicle CAN bus (with optional DBC decode) | `python-can`, `cantools` |
 | `mqtt.py` | MQTT broker → Plexus bridge | `paho-mqtt` |
 | `i2c_bme280.py` | Raspberry Pi environmental sensor | `adafruit-circuitpython-bme280` |
+| `mac_metrics.py` | Mac system metrics + spike/pressure events | `psutil` |
 
 The pattern is always the same: use whatever library you'd use anyway, then call `px.send(metric, value)`. Plexus stays out of your decode path.

plexus_python-0.4.8/examples/mac_metrics.py

@@ -0,0 +1,81 @@
+"""
+Mac system metrics with structured event logs.
+
+Install deps:
+    pip install plexus-python psutil
+
+Run:
+    python examples/mac_metrics.py --api-key plx_xxx
+    python examples/mac_metrics.py --api-key plx_xxx --interval 10
+"""
+
+import argparse
+import time
+import psutil
+from plexus import Plexus
+
+parser = argparse.ArgumentParser(description="Stream Mac system metrics to Plexus.")
+parser.add_argument("--api-key", required=True, help="Plexus API key (plx_xxx)")
+parser.add_argument("--interval", type=float, default=5.0, metavar="SECONDS",
+                    help="Sampling interval in seconds (default: 5)")
+parser.add_argument("--source-id", default="macbook", help="Device source ID (default: macbook)")
+args = parser.parse_args()
+
+px = Plexus(api_key=args.api_key, source_id=args.source_id)
+
+CPU_SPIKE_THRESHOLD = 80.0   # %
+MEM_PRESSURE_THRESHOLD = 85.0  # %
+
+prev_net = psutil.net_io_counters()
+prev_disk = psutil.disk_io_counters()
+prev_charging = None
+
+while True:
+    net = psutil.net_io_counters()
+    disk = psutil.disk_io_counters()
+
+    cpu = psutil.cpu_percent(interval=None)
+    mem = psutil.virtual_memory()
+
+    # Numeric metrics
+    px.send("cpu.percent",     cpu)
+    px.send("memory.used_gb",  mem.used / 1e9)
+    px.send("memory.percent",  mem.percent)
+    px.send("net.rx_mbps",     (net.bytes_recv  - prev_net.bytes_recv)   / 1e6)
+    px.send("net.tx_mbps",     (net.bytes_sent  - prev_net.bytes_sent)   / 1e6)
+    px.send("disk.read_mbps",  (disk.read_bytes  - prev_disk.read_bytes)  / 1e6)
+    px.send("disk.write_mbps", (disk.write_bytes - prev_disk.write_bytes) / 1e6)
+    px.send("disk.free_gb",    psutil.disk_usage("/").free / 1e9)
+
+    # Battery metrics + charge-state change event
+    battery = psutil.sensors_battery()
+    if battery:
+        px.send("battery.percent", battery.percent)
+        charging = battery.power_plugged
+        if charging != prev_charging and prev_charging is not None:
+            px.event("battery.state_change", {
+                "charging": charging,
+                "percent": battery.percent,
+            })
+        prev_charging = charging
+
+    # CPU spike event — fires once per interval when threshold is crossed
+    if cpu >= CPU_SPIKE_THRESHOLD:
+        top = max(psutil.process_iter(["name", "cpu_percent"]), key=lambda p: p.info["cpu_percent"] or 0)
+        px.event("cpu.spike", {
+            "cpu_percent": cpu,
+            "top_process": top.info["name"],
+            "top_process_percent": top.info["cpu_percent"],
+        })
+
+    # Memory pressure event
+    if mem.percent >= MEM_PRESSURE_THRESHOLD:
+        top = max(psutil.process_iter(["name", "memory_percent"]), key=lambda p: p.info["memory_percent"] or 0)
+        px.event("memory.pressure", {
+            "memory_percent": mem.percent,
+            "top_process": top.info["name"],
+            "top_process_percent": round(top.info["memory_percent"], 1),
+        })
+
+    prev_net, prev_disk = net, disk
+    time.sleep(args.interval)

{plexus_python-0.4.6 → plexus_python-0.4.8}/examples/mqtt.py

@@ -41,7 +41,7 @@ def on_message(_client, _userdata, msg):
         px.send(name, data)
 
 
-client = mqtt.Client()
+client = mqtt.Client(mqtt.CallbackAPIVersion.VERSION1)
 client.on_message = on_message
 client.connect(broker)
 client.subscribe(topic)

plexus_python-0.4.8/examples/pyproject.toml

@@ -0,0 +1,15 @@
+[project]
+name = "examples"
+version = "0.1.0"
+description = "Standalone example scripts for plexus-python"
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "adafruit-circuitpython-bme280>=2.6.32",
+    "cantools>=41.3.1",
+    "paho-mqtt>=2.1.0",
+    "plexus-python>=0.4.6",
+    "psutil>=7.2.2",
+    "pymavlink>=2.4.49",
+    "python-can>=4.6.1",
+]