plexus-python 0.4.3__tar.gz → 0.4.5__tar.gz

{plexus_python-0.4.3 → plexus_python-0.4.5}/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [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
+`f`-prefix in `plexus/client.py:488`. PyPI doesn't allow re-uploading a
+version, so 0.4.5 is the corrected re-release.
+
+## [0.4.4] - 2026-04-27 - Stderr status output
+
+### Added
+
+- `[plexus] …` status lines on stderr at every meaningful state change so
+  scripts that don't configure the `logging` module still tell the user
+  what's going on. Set `PLEXUS_QUIET=1` to suppress.
+  - `✓ Connected to gateway as <source_id>` on first WS auth
+  - `✓ Reconnected as <source_id>` after a drop
+  - `✓ First N points landed (via ws|http)` on first successful send
+  - `⚠ WebSocket unavailable, falling back to POST /ingest` on WS failure
+  - `✗ Auth rejected by gateway: …` / `✗ Gateway rejected the API key (401)`
+    on auth failures, with a `plexus whoami` hint
+  - `⏸ Send failed, buffering points locally (N queued)` when offline
+  - `✓ Sending again (drained the local buffer)` on recovery
+
+### Why
+
+Users running `python my_script.py` saw nothing — by default Python's
+`logging` module emits at WARNING and above only on the console, so a
+silent SDK was indistinguishable from "everything's working" until they
+checked the dashboard. This makes the trip from `python my_script.py` to
+"first row visible in the UI" auditable in one terminal.
+
 ## [0.4.3] - 2026-04-27 - Re-release of 0.4.2 with correct __version__
 
 The 0.4.2 wheel shipped with `plexus.__version__ == "0.4.1"` because the

{plexus_python-0.4.3 → plexus_python-0.4.5}/PKG-INFO

@@ -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.3 → plexus_python-0.4.5}/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_python-0.4.3 → plexus_python-0.4.5}/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_python-0.4.3 → plexus_python-0.4.5}/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 → plexus_python-0.4.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "plexus-python"
-version = "0.4.3"
+version = "0.4.5"
 description = "Thin Python SDK for Plexus — send telemetry in one line"
 readme = "README.md"
 license = "Apache-2.0"