plexus-python 0.4.3__py3-none-any.whl → 0.4.5__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
 from plexus.ws import WebSocketTransport
 
-__version__ = "0.4.3"
+__version__ = "0.4.5"
 __all__ = ["Plexus", "WebSocketTransport"]

plexus/client.py

@@ -36,6 +36,8 @@ Note: Requires authentication. Run 'plexus start' or set PLEXUS_API_KEY.
 import gzip
 import json
 import logging
+import os
+import sys
 import time
 from contextlib import contextmanager
 from typing import Any, Dict, List, Optional, Tuple, Union
@@ -55,6 +57,20 @@ from plexus.config import (
 )
 logger = logging.getLogger(__name__)
 
+# 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")
+
+
+def _say(line: str) -> None:
+    if _QUIET:
+        return
+    try:
+        sys.stderr.write(f"[plexus] {line}\n")
+        sys.stderr.flush()
+    except Exception:
+        pass
+
 # Flexible value type - supports any JSON-serializable value
 FlexValue = Union[int, float, str, bool, Dict[str, Any], List[Any]]
 
@@ -133,6 +149,12 @@ class Plexus:
         else:
             self._buffer: BufferBackend = MemoryBuffer(max_size=max_buffer_size)
 
+        # State that drives the [plexus] stderr status line.
+        self._announced_first_send = False
+        self._announced_http_fallback = False
+        self._announced_buffering = False
+        self._send_count = 0
+
     @property
     def max_buffer_size(self):
         return self._max_buffer_size
@@ -344,8 +366,14 @@ class Plexus:
                 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
@@ -372,8 +400,11 @@ class Plexus:
 
                 # Auth errors - don't retry, raise immediately
                 if response.status_code == 401:
+                    _say("✗ Gateway rejected the API key (401).")
+                    _say("  Run `plexus whoami` to confirm what's on disk.")
                     raise AuthenticationError("Invalid API key")
                 elif response.status_code == 403:
+                    _say("✗ API key lacks write scope (403).")
                     raise AuthenticationError("API key doesn't have write permissions")
 
                 # Bad request errors - don't retry (client error)
@@ -403,6 +434,7 @@ class Plexus:
                 # Success - clear the buffer and return
                 elif response.status_code < 400:
                     self._clear_buffer()
+                    self._note_send(len(all_points), via="http")
                     return True
 
                 # Other 4xx errors - don't retry
@@ -427,11 +459,35 @@ class Plexus:
 
         # All retries failed - buffer the points for later
         self._add_to_buffer(points)
+        if not self._announced_buffering:
+            _say(
+                f"⏸ Send failed, buffering points locally ({self.buffer_size()} queued). "
+                f"Will retry on next call."
+            )
+            self._announced_buffering = True
 
         if last_error:
             raise last_error
         raise PlexusError("Send failed after all retries")
 
+    def _note_send(self, count: int, via: str) -> None:
+        """Bookkeeping so the user sees the moment data starts flowing.
+
+        First successful send → "✓ First N points landed (via WS/HTTP)".
+        Recovery from a buffering state → "✓ Sending again (was buffered)".
+        Otherwise silent — every-send chatter would be unbearable at 100 Hz.
+        """
+        self._send_count += count
+        if not self._announced_first_send:
+            _say(
+                f"✓ First {count} point{'s' if count != 1 else ''} landed "
+                f"(via {via}). source_id={self.source_id!r}"
+            )
+            self._announced_first_send = True
+        elif self._announced_buffering:
+            _say("✓ Sending again (drained the local buffer).")
+            self._announced_buffering = False
+
     def _add_to_buffer(self, points: List[Dict[str, Any]]) -> None:
         """Add points to the local buffer for later retry."""
         self._buffer.add(points)

plexus/ws.py

@@ -27,7 +27,9 @@ from __future__ import annotations
 
 import json
 import logging
+import os
 import random
+import sys
 import threading
 import time
 from dataclasses import dataclass, field
@@ -43,6 +45,23 @@ except ImportError as e:  # pragma: no cover - import-time failure is obvious
 
 logger = logging.getLogger(__name__)
 
+# By default, print connection status to stderr so users running
+# `python my_script.py` can see what's happening without having to
+# configure the logging module. Set PLEXUS_QUIET=1 to disable.
+_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:
+        # Stderr blew up — don't take the whole client down with it.
+        pass
+
 AUTH_TIMEOUT_S = 10.0
 HEARTBEAT_INTERVAL_S = 30.0
 BACKOFF_BASE_S = 1.0
@@ -169,11 +188,22 @@ class WebSocketTransport:
     # ------------------------------------------------------------------ thread
 
     def _run(self) -> None:
+        first_attempt = True
         while not self._stop.is_set():
             try:
                 self._connect_and_serve()
             except Exception as e:
-                logger.warning("plexus ws loop error: %s", e)
+                msg = str(e)
+                logger.warning("plexus ws loop error: %s", msg)
+                # Loud the first time so users running a script see it,
+                # quieter on subsequent retries to avoid log spam.
+                if first_attempt:
+                    if "auth failed" in msg.lower() or "invalid api key" in msg.lower():
+                        _say(f"✗ Auth rejected by gateway: {msg}")
+                        _say("  Check your key — `plexus whoami` shows what's on disk.")
+                    else:
+                        _say(f"✗ Connection failed: {msg}")
+                        _say("  SDK will keep retrying with backoff.")
             finally:
                 self._authenticated.clear()
                 with self._ws_lock:
@@ -185,6 +215,7 @@ class WebSocketTransport:
             delay = _backoff_delay(self._backoff_attempt)
             self._backoff_attempt = min(self._backoff_attempt + 1, 10)
             logger.info("plexus ws reconnect in %.1fs", delay)
+            first_attempt = False
             if self._stop.wait(timeout=delay):
                 break
 
@@ -235,9 +266,15 @@ class WebSocketTransport:
                 except Exception as e:  # pragma: no cover - callback errors must not break auth
                     logger.debug("on_source_id_assigned callback raised: %s", e)
 
+        was_reconnect = self._backoff_attempt > 0
         self._authenticated.set()
         self._backoff_attempt = 0
         logger.info("plexus ws authenticated as %s", self.source_id)
+        if was_reconnect:
+            _say(f"✓ Reconnected as {self.source_id}")
+        else:
+            _say(f"✓ Connected to gateway as {self.source_id}")
+            _say(f"  endpoint: {self.ws_url}")
 
         # 3. Read loop with heartbeat pump
         ws.settimeout(1.0)

{plexus_python-0.4.3.dist-info → plexus_python-0.4.5.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexus-python
-Version: 0.4.3
+Version: 0.4.5
 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.4.5.dist-info/RECORD

@@ -0,0 +1,11 @@
+plexus/__init__.py,sha256=9USZDYoueDQVWKI7HREgzoDRIaPaxNCYmf8ng-CcDn0,345
+plexus/buffer.py,sha256=3ykybqLs7yMXxQWFajAT8nGe3cs_lW8_6Xvn0vQ69dE,9262
+plexus/cli.py,sha256=-2wvHXQzobx3_tDGTXpaE2PlHv884y93Mu29kZE8qZE,14214
+plexus/client.py,sha256=YtPa7lT5gC0etglIJEs1DInsE3qtPBaMZDZ552DKgS4,21706
+plexus/config.py,sha256=wsG6lhNLmKe3JRlVycyRUKQeywnPUPPfrWkXFxYwELE,6179
+plexus/ws.py,sha256=qGZL9TsYUpzUwEew1tgXIvQdYm1GNxnFu-pLqxfAulA,14134
+plexus_python-0.4.5.dist-info/METADATA,sha256=SLGrAflShkZdfXBbyjZwJIsFUt63tGnd38Hd0ZrwOI0,6800
+plexus_python-0.4.5.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+plexus_python-0.4.5.dist-info/entry_points.txt,sha256=YlkOtTn_7Q_IGuJaKdvpU-90dCeBSPx2p_UTGMAz5Zs,43
+plexus_python-0.4.5.dist-info/licenses/LICENSE,sha256=nm3qP1F-JAGcfLpRVtIX24L20LMnRpxmZ2oKZzFpLVo,10755
+plexus_python-0.4.5.dist-info/RECORD,,

plexus_python-0.4.3.dist-info/RECORD

@@ -1,11 +0,0 @@
-plexus/__init__.py,sha256=5og5cc398OVi85SxHJzxsQk7aZqLNC-MJYPnkBDdmYc,345
-plexus/buffer.py,sha256=3ykybqLs7yMXxQWFajAT8nGe3cs_lW8_6Xvn0vQ69dE,9262
-plexus/cli.py,sha256=-2wvHXQzobx3_tDGTXpaE2PlHv884y93Mu29kZE8qZE,14214
-plexus/client.py,sha256=Hp-qUdLkZ83OQeF_3d2FH5kCZXK9iJOSmO7o0opOR8U,19395
-plexus/config.py,sha256=wsG6lhNLmKe3JRlVycyRUKQeywnPUPPfrWkXFxYwELE,6179
-plexus/ws.py,sha256=upQ9SpekDYa7MltUW5ZDEuCm_E8hEVpxC0QFNP_jT1g,12581
-plexus_python-0.4.3.dist-info/METADATA,sha256=2GlnmRZqlVdpbSlhFr9jDaKEC370iCktE9KFaLQqUEs,6800
-plexus_python-0.4.3.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-plexus_python-0.4.3.dist-info/entry_points.txt,sha256=YlkOtTn_7Q_IGuJaKdvpU-90dCeBSPx2p_UTGMAz5Zs,43
-plexus_python-0.4.3.dist-info/licenses/LICENSE,sha256=nm3qP1F-JAGcfLpRVtIX24L20LMnRpxmZ2oKZzFpLVo,10755
-plexus_python-0.4.3.dist-info/RECORD,,