plexus-python 0.4.3__py3-none-any.whl → 0.4.6__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.6"
 __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]]
 
@@ -124,6 +140,7 @@ class Plexus:
         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
 
         # Pluggable buffer backend for failed sends
         if persistent_buffer:
@@ -133,6 +150,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
@@ -153,17 +176,16 @@ class Plexus:
             self._session.headers["User-Agent"] = f"plexus-python/{__version__}"
         return self._session
 
-    @staticmethod
-    def _normalize_ts_ms(timestamp: Optional[float] = None) -> int:
+    def _normalize_ts_ms(self, timestamp: Optional[float] = None) -> int:
         """Normalize a timestamp to milliseconds.
 
         Accepts:
-            - None: returns current time in ms
-            - float seconds (e.g. time.time()): converts to ms
-            - int/float ms: returned as-is
+            - None: returns current time in ms, corrected by server clock offset
+            - float seconds (e.g. time.time()): converts to ms (no offset applied)
+            - int/float ms: returned as-is (no offset applied)
         """
         if timestamp is None:
-            return int(time.time() * 1000)
+            return int(time.time() * 1000) + self._clock_offset_ms
         # Heuristic: values < 1e12 are seconds
         if timestamp > 0 and timestamp < 1e12:
             return int(timestamp * 1000)
@@ -236,6 +258,30 @@ class Plexus:
         point = self._make_point(metric, value, timestamp, tags, data_class)
         return self._send_points([point])
 
+    def event(
+        self,
+        name: str,
+        data: FlexValue,
+        timestamp: Optional[float] = None,
+        tags: Optional[Dict[str, str]] = None,
+    ) -> bool:
+        """
+        Send a named event with text or structured data.
+
+        Args:
+            name: Event type (e.g., "fault", "state_change", "log")
+            data: Text or JSON-serializable value (string, dict, list, bool, number)
+            timestamp: Unix timestamp. If not provided, uses current time.
+            tags: Optional key-value tags
+
+        Example:
+            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"})
+        """
+        point = self._make_point(name, data, timestamp, tags, data_class="event")
+        return self._send_points([point])
+
     def send_batch(
         self,
         points: List[Tuple[str, FlexValue]],
@@ -261,8 +307,8 @@ class Plexus:
                 ("position", {"x": 1.0, "y": 2.0}),
             ])
         """
-        ts = timestamp if timestamp is not None else time.time()
-        data_points = [self._make_point(m, v, ts, tags) for m, v in points]
+        ts_ms = self._normalize_ts_ms(timestamp)
+        data_points = [self._make_point(m, v, ts_ms, tags) for m, v in points]
         return self._send_points(data_points)
 
     def _ensure_ws(self):
@@ -278,10 +324,14 @@ class Plexus:
             install_id=get_install_id(),
             agent_version=__version__,
             on_source_id_assigned=self._on_source_id_assigned,
+            on_clock_synced=self._on_clock_synced,
         )
         self._ws.start()
         return self._ws
 
+    def _on_clock_synced(self, offset_ms: int) -> None:
+        self._clock_offset_ms = offset_ms
+
     def _on_source_id_assigned(self, assigned: str) -> None:
         """Callback from WebSocketTransport when the gateway returns an
         auto-suffixed source_id. Persists it so subsequent runs (and the HTTP
@@ -344,8 +394,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 +428,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 +462,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 +487,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)
@@ -499,7 +583,7 @@ class Plexus:
                     "source_id": self.source_id,
                     "status": "started",
                     "tags": tags,
-                    "timestamp": time.time(),
+                    "timestamp": (int(time.time() * 1000) + self._clock_offset_ms) / 1000,
                 },
                 timeout=self.timeout,
             )
@@ -517,7 +601,7 @@ class Plexus:
                         "run_id": run_id,
                         "source_id": self.source_id,
                         "status": "ended",
-                        "timestamp": time.time(),
+                        "timestamp": (int(time.time() * 1000) + self._clock_offset_ms) / 1000,
                     },
                     timeout=self.timeout,
                 )

plexus/ws.py

@@ -25,9 +25,12 @@ Runs the read loop on a background daemon thread so callers can stay sync.
 
 from __future__ import annotations
 
+import atexit
 import json
 import logging
+import os
 import random
+import sys
 import threading
 import time
 from dataclasses import dataclass, field
@@ -43,6 +46,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
@@ -89,6 +109,7 @@ class WebSocketTransport:
         platform: str = "python-sdk",
         auto_reconnect: bool = True,
         on_source_id_assigned: Optional[Callable[[str], None]] = None,
+        on_clock_synced: Optional[Callable[[int], None]] = None,
     ):
         if not api_key:
             raise ValueError("api_key required")
@@ -103,6 +124,7 @@ class WebSocketTransport:
         self.platform = platform
         self.auto_reconnect = auto_reconnect
         self._on_source_id_assigned = on_source_id_assigned
+        self._on_clock_synced = on_clock_synced
 
         self._commands: Dict[str, _RegisteredCommand] = {}
         self._ws: Optional[websocket.WebSocket] = None
@@ -111,6 +133,7 @@ class WebSocketTransport:
         self._stop = threading.Event()
         self._thread: Optional[threading.Thread] = None
         self._backoff_attempt = 0
+        self._clock_offset_ms: int = 0
 
     # ------------------------------------------------------------------ public
 
@@ -136,6 +159,7 @@ class WebSocketTransport:
             target=self._run, name="plexus-ws", daemon=True
         )
         self._thread.start()
+        atexit.register(self.stop)
 
     def stop(self, timeout: float = 2.0) -> None:
         self._stop.set()
@@ -156,6 +180,10 @@ class WebSocketTransport:
     def is_authenticated(self) -> bool:
         return self._authenticated.is_set()
 
+    @property
+    def clock_offset_ms(self) -> int:
+        return self._clock_offset_ms
+
     def send_points(self, points: List[Dict[str, Any]]) -> bool:
         """Send a telemetry frame. Returns False if the socket is not
         authenticated — caller is expected to fall back to HTTP."""
@@ -169,11 +197,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 +224,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
 
@@ -219,6 +259,15 @@ class WebSocketTransport:
         if msg.get("type") != "authenticated":
             raise RuntimeError(f"auth failed: {msg}")
 
+        server_ts = msg.get("server_time_ms")
+        if isinstance(server_ts, (int, float)) and server_ts > 0:
+            self._clock_offset_ms = int(server_ts) - int(time.time() * 1000)
+            if self._on_clock_synced is not None:
+                try:
+                    self._on_clock_synced(self._clock_offset_ms)
+                except Exception as e:
+                    logger.debug("on_clock_synced callback raised: %s", e)
+
         # The gateway may return a different source_id if the desired name
         # was already claimed by another install — adopt the assigned value
         # so all subsequent frames (heartbeats, future reconnects) use it.
@@ -235,9 +284,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.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plexus-python
-Version: 0.4.3
+Version: 0.4.6
 Summary: Thin Python SDK for Plexus — send telemetry in one line
 Project-URL: Homepage, https://plexus.dev
 Project-URL: Documentation, https://docs.plexus.dev
@@ -136,6 +136,24 @@ px.buffer_size()
 px.flush_buffer()
 ```
 
+## Timestamps and clock correction
+
+By default — `px.send("temp", 72.5)` with no `timestamp` argument — the SDK picks the time itself. Over WebSocket, it synchronizes with the gateway clock on every connection, so data lands at the right place on the timeline even if the device's system clock is wrong (no NTP on first boot, stale RTC, fresh OS image).
+
+```python
+px.send("temperature", 72.5)                # SDK picks time; gateway-synced over WS
+px.send("temperature", 72.5, timestamp=t)   # your timestamp, used as-is, no correction
+```
+
+**Pass an explicit timestamp when** you have a reliable external time source (GPS, trusted RTC, host NTP) or are replaying historical data with known timestamps.
+
+**Omit timestamp when** the device may have booted without NTP — which is the default on Raspberry Pi, Jetson, and most embedded Linux boards without a network connection at first boot.
+
+**Known limits:**
+- Clock sync refreshes on WebSocket (re)connect. A device with a drifting RTC that stays connected for many days accumulates uncorrected drift between reconnects.
+- HTTP-only transport (`transport="http"`) does not receive clock sync — timestamps default to the uncorrected device clock.
+- `send_batch()` shares one timestamp across the whole batch. For per-point timestamps, call `send()` in a loop.
+
 ## Transport
 
 By default the SDK connects over a **WebSocket** to `/ws/device` on the gateway — same wire protocol as the C SDK. This gives you:

plexus_python-0.4.6.dist-info/RECORD

@@ -0,0 +1,11 @@
+plexus/__init__.py,sha256=upqHP1A19Sp_CnCeCBHHJ1GUKKzeCJiJw5w3wD2K4cE,345
+plexus/buffer.py,sha256=3ykybqLs7yMXxQWFajAT8nGe3cs_lW8_6Xvn0vQ69dE,9262
+plexus/cli.py,sha256=-2wvHXQzobx3_tDGTXpaE2PlHv884y93Mu29kZE8qZE,14214
+plexus/client.py,sha256=JmEKKRu4ik548uBPMEOCcB_r_asRmuNORZF4snjFosQ,22956
+plexus/config.py,sha256=wsG6lhNLmKe3JRlVycyRUKQeywnPUPPfrWkXFxYwELE,6179
+plexus/ws.py,sha256=aynJTH8LHRA4_U1OfIu-2aaOg1tLniUcWbzB2yuiQvU,14865
+plexus_python-0.4.6.dist-info/METADATA,sha256=d6Vp27f4EsfSHeS0NT6z9oWF85UIsLskMzzborehyQQ,8121
+plexus_python-0.4.6.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+plexus_python-0.4.6.dist-info/entry_points.txt,sha256=YlkOtTn_7Q_IGuJaKdvpU-90dCeBSPx2p_UTGMAz5Zs,43
+plexus_python-0.4.6.dist-info/licenses/LICENSE,sha256=nm3qP1F-JAGcfLpRVtIX24L20LMnRpxmZ2oKZzFpLVo,10755
+plexus_python-0.4.6.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,,