plexus-python 0.6.2__py3-none-any.whl → 0.7.0__py3-none-any.whl

plexus/__init__.py

@@ -7,8 +7,8 @@ Plexus — thin Python SDK for sending telemetry to the Plexus gateway.
     px.send("temperature", 72.5)
 """
 
-from plexus.client import Plexus, read_mjpeg_frames
-from plexus.ws import WebSocketTransport
+from plexus.client import Plexus, PlexusError, AuthenticationError, read_mjpeg_frames
+from plexus.config import RetryConfig
 
-__version__ = "0.6.2"
-__all__ = ["Plexus", "WebSocketTransport", "read_mjpeg_frames"]
+__version__ = "0.7.0"
+__all__ = ["Plexus", "PlexusError", "AuthenticationError", "RetryConfig", "read_mjpeg_frames"]

plexus/_log.py

@@ -1,12 +1,10 @@
 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:
+    if os.environ.get("PLEXUS_QUIET", "").lower() in ("1", "true", "yes"):
         return
     try:
         sys.stderr.write(f"[plexus] {line}\n")

plexus/buffer.py

@@ -41,6 +41,10 @@ class BufferBackend(ABC):
     def size(self) -> int:
         """Return current number of buffered points."""
 
+    @abstractmethod
+    def resize(self, max_size: int) -> None:
+        """Update the maximum buffer capacity."""
+
     def drain(self, batch_size: int = 5000) -> Tuple[List[Dict[str, Any]], int]:
         """Remove and return the oldest batch_size points atomically.
 
@@ -97,6 +101,10 @@ class MemoryBuffer(BufferBackend):
         with self._lock:
             return len(self._buffer)
 
+    def resize(self, max_size: int) -> None:
+        with self._lock:
+            self._max_size = max_size
+
     def drain(self, batch_size: int = 5000) -> Tuple[List[Dict[str, Any]], int]:
         with self._lock:
             batch = self._buffer[:batch_size]
@@ -185,6 +193,10 @@ class SqliteBuffer(BufferBackend):
             cursor = self._conn.execute("SELECT COUNT(*) FROM points")
             return cursor.fetchone()[0]
 
+    def resize(self, max_size: int) -> None:
+        with self._lock:
+            self._max_size = max_size
+
     def drain(self, batch_size: int = 5000) -> Tuple[List[Dict[str, Any]], int]:
         """Remove and return the oldest batch_size points atomically.
 

plexus/cameras/thermal.py

@@ -8,8 +8,9 @@ ThermalFrame containing a colorized JPEG image plus temperature metadata.
 Usage:
     from plexus.cameras.thermal import ThermalSource
 
-    cam = ThermalSource.open()          # auto-detect
     cam = ThermalSource.open("sim")     # simulated, no hardware
+    cam = ThermalSource.open("mlx90640")  # I2C MLX90640
+    cam = ThermalSource.open("usb")     # USB thermal at index 0
 
     while True:
         px.send_thermal_frame(cam.read_frame(), camera_id="thermal")
@@ -325,19 +326,33 @@ class MLX90641Camera(ThermalCamera):
 
 
 class ThermalSource:
-    """Factory that opens the first available thermal camera.
+    """Factory for opening a thermal camera by type.
+
+    A camera type must be specified explicitly — auto-detection is not supported
+    because USB thermal cameras and regular webcams are indistinguishable at the
+    OS level without knowing what you're looking for.
+
+    Args:
+        hint: Which camera to open. One of:
+            "sim"      — simulated 32×24 camera, no hardware required
+            "mlx90640" — MLX90640 32×24 I2C sensor (Raspberry Pi, 3.3V)
+            "mlx90641" — MLX90641 16×12 I2C sensor (Raspberry Pi, 3.3V)
+            "usb"      — USB thermal camera at device index 0
+            <int>      — USB thermal camera at a specific device index
+
+    Raises:
+        ValueError: If hint is None or unrecognised.
+        NoCameraFound: If the specified device cannot be opened.
 
     Examples:
-        ThermalSource.open()             # auto-detect
-        ThermalSource.open("sim")        # simulated
-        ThermalSource.open("mlx90640")   # force I2C MLX90640
-        ThermalSource.open("mlx90641")   # force I2C MLX90641
-        ThermalSource.open("usb")        # USB thermal at index 0
-        ThermalSource.open(2)            # USB thermal at index 2
+        cam = ThermalSource.open("sim")        # no hardware
+        cam = ThermalSource.open("mlx90640")   # I2C MLX90640
+        cam = ThermalSource.open("usb")        # USB at index 0
+        cam = ThermalSource.open(2)            # USB at index 2
     """
 
     @staticmethod
-    def open(hint: str | int | None = None) -> ThermalCamera:
+    def open(hint: str | int) -> ThermalCamera:
         if hint == "sim":
             return SimulatedThermalCamera()
         if hint == "mlx90640":
@@ -346,43 +361,7 @@ class ThermalSource:
             return MLX90641Camera()
         if hint == "usb" or isinstance(hint, int):
             return USBThermalCamera(0 if hint == "usb" else hint)
-        return ThermalSource._autodetect()
-
-    @staticmethod
-    def _autodetect() -> ThermalCamera:
-        cam = ThermalSource._try_i2c()
-        if cam:
-            return cam
-        cam = ThermalSource._try_usb()
-        if cam:
-            return cam
-        raise NoCameraFound(
-            "No thermal camera detected. Use ThermalSource.open('sim') to run without hardware."
+        raise ValueError(
+            f"Unknown camera hint {hint!r}. "
+            "Valid options: 'sim', 'mlx90640', 'mlx90641', 'usb', or a device index (int)."
         )
-
-    @staticmethod
-    def _try_i2c() -> ThermalCamera | None:
-        try:
-            import board
-            import busio
-
-            i2c = busio.I2C(board.SCL, board.SDA)
-            i2c.try_lock()
-            addrs = i2c.scan()
-            i2c.unlock()
-            if 0x33 in addrs:
-                return MLX90640Camera()
-            if 0x60 in addrs:
-                return MLX90641Camera()
-        except Exception:
-            pass
-        return None
-
-    @staticmethod
-    def _try_usb() -> ThermalCamera | None:
-        for idx in range(10):
-            try:
-                return USBThermalCamera(idx)
-            except NoCameraFound:
-                continue
-        return None

plexus/client.py

@@ -187,7 +187,6 @@ class Plexus:
         max_buffer_size: int = 10000,
         persistent_buffer: bool = True,
         buffer_path: Optional[str] = None,
-        transport: str = "ws",
         ws_url: Optional[str] = None,
     ):
         self.api_key = api_key or get_api_key()
@@ -212,9 +211,6 @@ class Plexus:
         self._pil_image = None  # lazy PIL.Image import
         self._fit_warned: bool = False
 
-        if transport not in ("ws", "http"):
-            raise ValueError(f"transport must be 'ws' or 'http', got {transport!r}")
-        self.transport = transport
         self._ws_url = (ws_url or get_gateway_ws_url())
         self._ws = None  # lazily constructed in _ensure_ws()
         self._clock_offset_ms: int = 0
@@ -222,10 +218,14 @@ class Plexus:
         # Pluggable buffer backend for failed sends
         if persistent_buffer:
             self._buffer: BufferBackend = SqliteBuffer(
-                path=buffer_path, max_size=max_buffer_size
+                path=buffer_path, max_size=max_buffer_size,
+                on_overflow=self._on_buffer_overflow,
             )
         else:
-            self._buffer: BufferBackend = MemoryBuffer(max_size=max_buffer_size)
+            self._buffer: BufferBackend = MemoryBuffer(
+                max_size=max_buffer_size,
+                on_overflow=self._on_buffer_overflow,
+            )
 
         # State that drives the [plexus] stderr status line.
         self._announced_first_send = False
@@ -240,7 +240,7 @@ class Plexus:
     @max_buffer_size.setter
     def max_buffer_size(self, value):
         self._max_buffer_size = value
-        self._buffer._max_size = value
+        self._buffer.resize(value)
 
     def _get_session(self) -> _Session:
         if self._session is None:
@@ -422,6 +422,9 @@ class Plexus:
         self._ws.start()
         return self._ws
 
+    def _on_buffer_overflow(self, dropped: int) -> None:
+        _say(f"⚠ buffer full, dropped {dropped} oldest points (gateway unreachable?)")
+
     def _on_clock_synced(self, offset_ms: int) -> None:
         self._clock_offset_ms = offset_ms
 
@@ -575,9 +578,6 @@ class Plexus:
             ValueError: If frame type is not supported.
             ImportError: If a required optional dependency is missing.
         """
-        if self.transport != "ws":
-            raise PlexusError("send_video_frame requires transport='ws'")
-
         jpeg_bytes, width, height = self._encode_frame(frame, quality)
         jpeg_bytes = self._fit_to_wire(jpeg_bytes, quality)
 
@@ -613,9 +613,6 @@ class Plexus:
             PlexusError: If transport is not 'ws'.
             ImportError: If opencv-python-headless is not installed.
         """
-        if self.transport != "ws":
-            raise PlexusError("send_thermal_frame requires transport='ws'")
-
         try:
             from plexus.cameras.thermal import build_thermal_frame
         except ImportError as e:
@@ -663,8 +660,6 @@ class Plexus:
             time.sleep(60)
             stop.set()
         """
-        if self.transport != "ws":
-            raise PlexusError("stream_camera requires transport='ws'")
         if shutil.which("ffmpeg") is None:
             raise PlexusError(
                 "FFmpeg not found. Install it: https://ffmpeg.org/download.html"
@@ -715,24 +710,21 @@ class Plexus:
         Must be called before the first send() so the command is advertised
         in the auth frame.
         """
-        if self.transport != "ws":
-            raise PlexusError("on_command requires transport='ws'")
         ws = self._ensure_ws()
         if ws.is_authenticated:
-            _say(
-                f"⚠ on_command('{name}') called after connection is already authenticated — "
+            logger.warning(
+                "on_command('%s') called after connection is already authenticated — "
                 "command will not be advertised to the dashboard until next reconnect. "
-                "Call on_command() before the first send()."
+                "Call on_command() before the first send().",
+                name,
             )
         ws.register_command(name, handler, description=description, params=params)
 
     def _send_points(self, points: List[Dict[str, Any]]) -> bool:
         """Send data points to the gateway with retry and buffering.
 
-        Path:
-        - transport='ws': try the WebSocket first; if not yet authenticated or
-          the socket fails, fall through to the HTTP path so points still land.
-        - transport='http': always POST /ingest with retries.
+        Tries WebSocket first; if not yet authenticated or the socket fails,
+        falls through to HTTP POST so points still land.
 
         Retry behavior (HTTP path):
         - Retries on: Timeout, ConnectionError, HTTP 429, HTTP 5xx
@@ -748,22 +740,21 @@ class Plexus:
         all_points = self._get_buffered_points() + points
 
         # Preferred path: WebSocket.
-        if self.transport == "ws":
-            ws = self._ensure_ws()
-            # Brief wait on first call so startup races don't dump every point
-            # into the HTTP fallback path.
-            if not ws.is_authenticated:
-                ws.wait_authenticated(timeout=min(self.timeout, 5.0))
-            if ws.send_points(all_points):
-                self._clear_buffer()
-                self._note_send(len(all_points), via="ws")
-                return True
-            # Socket unavailable → fall through to HTTP.
-            if not self._announced_http_fallback:
-                _say(
-                    f"⚠ WebSocket unavailable, falling back to POST {self.gateway_url}/ingest"
-                )
-                self._announced_http_fallback = True
+        ws = self._ensure_ws()
+        # Brief wait on first call so startup races don't dump every point
+        # into the HTTP fallback path.
+        if not ws.is_authenticated:
+            ws.wait_authenticated(timeout=min(self.timeout, 5.0))
+        if ws.send_points(all_points):
+            self._clear_buffer()
+            self._note_send(len(all_points), via="ws")
+            return True
+        # Socket unavailable → fall through to HTTP.
+        if not self._announced_http_fallback:
+            _say(
+                f"⚠ WebSocket unavailable, falling back to POST {self.gateway_url}/ingest"
+            )
+            self._announced_http_fallback = True
 
         url = f"{self.gateway_url}/ingest"
         last_error: Optional[Exception] = None

{plexus_python-0.6.2.dist-info → plexus_python-0.7.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexus-python
-Version: 0.6.2
+Version: 0.7.0
 Summary: Thin Python SDK for Plexus — send telemetry in one line
 Project-URL: Homepage, https://plexus.dev
 Project-URL: Documentation, https://docs.plexus.dev

plexus_python-0.7.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+plexus/__init__.py,sha256=HNRVhpDrkyyT-SQqfFzNf3E_uwbwQA-XcDKPoBytdEo,447
+plexus/_log.py,sha256=3fjXrHFZghQ_17umMcvDUjjTH6aTQB3J4SpVDBiH03w,335
+plexus/buffer.py,sha256=0i6PLgoj904jFNv9RCrlskvPQsPSu_KNdYWMasFOvsg,9596
+plexus/cli.py,sha256=-2wvHXQzobx3_tDGTXpaE2PlHv884y93Mu29kZE8qZE,14214
+plexus/client.py,sha256=DaCPURIhVswwjf4oGrp381Atiy02gk3viLy6NioBAtQ,36480
+plexus/config.py,sha256=wsG6lhNLmKe3JRlVycyRUKQeywnPUPPfrWkXFxYwELE,6179
+plexus/ws.py,sha256=_c--U-yySZbMXZsaj0fUaYKF_WesolHsrMDx4oWYfFQ,17428
+plexus/cameras/__init__.py,sha256=OvnU9KGKxkVtFLlk56H9x-ATa6UvpLI7PANa0HQO2cc,490
+plexus/cameras/thermal.py,sha256=7o33QsF1RiZLManTxZ2E36nO8lRAHppCDkS3zXBHCxs,12047
+plexus_python-0.7.0.dist-info/METADATA,sha256=tlsktssdsOI7dyA7O2I6azPay2Xj998Z4zNxbFf4H6s,11739
+plexus_python-0.7.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+plexus_python-0.7.0.dist-info/entry_points.txt,sha256=YlkOtTn_7Q_IGuJaKdvpU-90dCeBSPx2p_UTGMAz5Zs,43
+plexus_python-0.7.0.dist-info/licenses/LICENSE,sha256=nm3qP1F-JAGcfLpRVtIX24L20LMnRpxmZ2oKZzFpLVo,10755
+plexus_python-0.7.0.dist-info/RECORD,,

plexus_python-0.6.2.dist-info/RECORD

@@ -1,14 +0,0 @@
-plexus/__init__.py,sha256=XFUsFY9sq7SzSuCP2D6NVAf8RxP0vsXROezHxPMY0ek,385
-plexus/_log.py,sha256=y1A9ahcPuCefTQ8xsZtOJTb6iT0pP9LAlkeP7U-yvGE,352
-plexus/buffer.py,sha256=3ykybqLs7yMXxQWFajAT8nGe3cs_lW8_6Xvn0vQ69dE,9262
-plexus/cli.py,sha256=-2wvHXQzobx3_tDGTXpaE2PlHv884y93Mu29kZE8qZE,14214
-plexus/client.py,sha256=1SzzqQDIx0B2zLDezO5cYpmwK8XeUrMd5jMdU7YB90M,36995
-plexus/config.py,sha256=wsG6lhNLmKe3JRlVycyRUKQeywnPUPPfrWkXFxYwELE,6179
-plexus/ws.py,sha256=_c--U-yySZbMXZsaj0fUaYKF_WesolHsrMDx4oWYfFQ,17428
-plexus/cameras/__init__.py,sha256=OvnU9KGKxkVtFLlk56H9x-ATa6UvpLI7PANa0HQO2cc,490
-plexus/cameras/thermal.py,sha256=-Ov8pgHGKtu5W-zyHRffVACDbsb50lpTmTGEbs_j4lg,12267
-plexus_python-0.6.2.dist-info/METADATA,sha256=kxGSad9N5G842Pjh_G4RvhJ6hdXrr9xEIjJHRhWXAr8,11739
-plexus_python-0.6.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-plexus_python-0.6.2.dist-info/entry_points.txt,sha256=YlkOtTn_7Q_IGuJaKdvpU-90dCeBSPx2p_UTGMAz5Zs,43
-plexus_python-0.6.2.dist-info/licenses/LICENSE,sha256=nm3qP1F-JAGcfLpRVtIX24L20LMnRpxmZ2oKZzFpLVo,10755
-plexus_python-0.6.2.dist-info/RECORD,,