spectra-plot 0.2.0__tar.gz → 0.2.2__tar.gz

{spectra_plot-0.2.0/spectra_plot.egg-info → spectra_plot-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spectra-plot
-Version: 0.2.0
+Version: 0.2.2
 Summary: GPU-accelerated scientific plotting via IPC
 License: MIT
 Classifier: Development Status :: 3 - Alpha

spectra_plot-0.2.2/VERSION

@@ -0,0 +1 @@
+0.2.2

{spectra_plot-0.2.0 → spectra_plot-0.2.2}/pyproject.toml

@@ -26,6 +26,9 @@ classifiers = [
 numpy = ["numpy>=1.20"]
 dev = ["pytest>=7.0", "numpy>=1.20"]
 
+[project.scripts]
+spectra-backend = "spectra._cli:backend_main"
+
 [tool.setuptools.dynamic]
 version = {file = "VERSION"}
 

{spectra_plot-0.2.0 → spectra_plot-0.2.2}/spectra/__init__.py

@@ -38,6 +38,8 @@ from ._errors import (
     BackendError,
 )
 from ._animation import ipc_sleep, FramePacer, BackendAnimator
+from ._log import set_log_level, get_log_level
+from .topic import Publisher
 
 # ─── Easy API (one-liners, everything in background) ─────────────────────────
 from ._easy import (
@@ -144,4 +146,7 @@ __all__ = [
     "ipc_sleep",
     "FramePacer",
     "BackendAnimator",
+    "set_log_level",
+    "get_log_level",
+    "Publisher",
 ]

spectra_plot-0.2.2/spectra/_cli.py

@@ -0,0 +1,68 @@
+"""Command-line entry points for spectra."""
+
+import os
+import platform as _platform
+import sys
+
+
+def backend_main():
+    """Entry point for 'spectra-backend' console script.
+
+    Forwards all arguments to the bundled spectra-backend binary.
+    Supports --download to pre-fetch the binary without running it.
+    """
+    # Handle --download: fetch binary and exit
+    if len(sys.argv) > 1 and sys.argv[1] == "--download":
+        from ._download import download_backend
+        try:
+            path = download_backend()
+            print(f"spectra-backend ready: {path}")
+        except Exception as exc:
+            print(f"Download failed: {exc}", file=sys.stderr)
+            sys.exit(1)
+        sys.exit(0)
+
+    from ._launcher import _find_backend_binary
+
+    binary = _find_backend_binary()
+
+    # If not found locally, try auto-download
+    if binary is None:
+        try:
+            from ._download import download_backend
+            download_backend()
+            binary = _find_backend_binary()
+        except Exception as exc:
+            print(f"Auto-download failed: {exc}", file=sys.stderr)
+
+    if binary is None:
+        print(
+            "spectra-backend native binary not found.\n"
+            "Install the spectra-plot wheel (includes the binary), "
+            "set SPECTRA_BACKEND_PATH, or build with CMake "
+            "(cmake -B build -DSPECTRA_RUNTIME_MODE=multiproc).\n"
+            "Or run: spectra-backend --download",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    # Safety: the binary must be a native executable, not this script.
+    # _find_backend_binary already filters non-native binaries, but
+    # guard against future regressions that could cause an exec loop.
+    resolved = os.path.realpath(binary)
+    this_script = os.path.realpath(sys.argv[0])
+    if resolved == this_script:
+        print(
+            "spectra-backend: refusing to exec self (would loop). "
+            "Set SPECTRA_BACKEND_PATH to the native binary.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    if _platform.system() == "Windows":
+        # os.execv on Windows spawns a new process and exits the current one
+        # which can cause issues with console handling. Use subprocess instead.
+        import subprocess
+        sys.exit(subprocess.call([binary] + sys.argv[1:]))
+    else:
+        os.execv(binary, [binary] + sys.argv[1:])

{spectra_plot-0.2.0 → spectra_plot-0.2.2}/spectra/_codec.py

@@ -1,12 +1,17 @@
 """TLV (Tag-Length-Value) codec mirroring src/ipc/codec.hpp.
 
 Wire format per field: [tag: u8] [len: u32 LE] [data: len bytes]
+
+FlatBuffers payloads are prefixed with 0x01; legacy TLV payloads start with
+a raw tag byte (never 0x00 or 0x01 in practice, but 0x00 is reserved).
+Decode functions auto-detect the format and delegate to _codec_fb when needed.
 """
 
 import struct
 from typing import List, Optional, Tuple
 
 from . import _protocol as P
+from . import _codec_fb as fb_codec
 
 
 # ─── Encoder ──────────────────────────────────────────────────────────────────
@@ -188,16 +193,11 @@ def decode_header(data: bytes) -> Optional[dict]:
 # ─── Convenience: encode specific payloads ────────────────────────────────────
 
 def encode_hello(client_type: str = "python", build: str = "") -> bytes:
-    enc = PayloadEncoder()
-    enc.put_u16(P.TAG_PROTOCOL_MAJOR, P.PROTOCOL_MAJOR)
-    enc.put_u16(P.TAG_PROTOCOL_MINOR, P.PROTOCOL_MINOR)
-    enc.put_string(P.TAG_AGENT_BUILD, build)
-    enc.put_u32(P.TAG_CAPABILITIES, 0)
-    enc.put_string(P.TAG_CLIENT_TYPE, client_type)
-    return enc.take()
-
+    return fb_codec.encode_fb_hello(client_type=client_type, build=build)
 
 def decode_welcome(data: bytes) -> dict:
+    if fb_codec._is_fb(data):
+        return fb_codec.decode_fb_welcome(data)
     result = {"session_id": 0, "window_id": 0, "process_id": 0, "heartbeat_ms": 5000, "mode": ""}
     dec = PayloadDecoder(data)
     while dec.next():
@@ -216,42 +216,16 @@ def decode_welcome(data: bytes) -> dict:
 
 
 def encode_req_create_figure(title: str = "", width: int = 1280, height: int = 720) -> bytes:
-    enc = PayloadEncoder()
-    enc.put_string(P.TAG_TITLE, title)
-    enc.put_u32(P.TAG_WIDTH, width)
-    enc.put_u32(P.TAG_HEIGHT, height)
-    return enc.take()
-
+    return fb_codec.encode_fb_req_create_figure(title=title, width=width, height=height)
 
 def encode_req_create_axes(figure_id: int, rows: int, cols: int, index: int, is_3d: bool = False) -> bytes:
-    enc = PayloadEncoder()
-    enc.put_u64(P.TAG_FIGURE_ID, figure_id)
-    enc.put_u32(P.TAG_GRID_ROWS, rows)
-    enc.put_u32(P.TAG_GRID_COLS, cols)
-    enc.put_u32(P.TAG_GRID_INDEX, index)
-    if is_3d:
-        enc.put_bool(P.TAG_IS_3D, True)
-    return enc.take()
-
+    return fb_codec.encode_fb_req_create_axes(figure_id=figure_id, rows=rows, cols=cols, index=index, is_3d=is_3d)
 
 def encode_req_add_series(figure_id: int, axes_index: int, series_type: str, label: str = "") -> bytes:
-    enc = PayloadEncoder()
-    enc.put_u64(P.TAG_FIGURE_ID, figure_id)
-    enc.put_u32(P.TAG_AXES_INDEX, axes_index)
-    enc.put_string(P.TAG_SERIES_TYPE, series_type)
-    enc.put_string(P.TAG_SERIES_LABEL, label)
-    return enc.take()
-
+    return fb_codec.encode_fb_req_add_series(figure_id=figure_id, axes_index=axes_index, series_type=series_type, label=label)
 
 def encode_req_set_data(figure_id: int, series_index: int, data: List[float], dtype: int = 0) -> bytes:
-    enc = PayloadEncoder()
-    enc.put_u64(P.TAG_FIGURE_ID, figure_id)
-    enc.put_u32(P.TAG_SERIES_INDEX, series_index)
-    enc.put_u16(P.TAG_DTYPE, dtype)
-    if data:
-        enc.put_float_array(P.TAG_BLOB_INLINE, data)
-    return enc.take()
-
+    return fb_codec.encode_fb_req_set_data(figure_id=figure_id, series_index=series_index, data=data, dtype=dtype)
 
 def encode_req_set_data_raw(figure_id: int, series_index: int, raw_bytes: bytes, count: int, dtype: int = 0) -> bytes:
     """Encode REQ_SET_DATA with pre-packed float array bytes for zero-copy from numpy."""
@@ -294,14 +268,7 @@ def encode_req_set_data_chunked(
 
 
 def encode_req_append_data(figure_id: int, series_index: int, data: List[float]) -> bytes:
-    """Encode REQ_APPEND_DATA for streaming append."""
-    enc = PayloadEncoder()
-    enc.put_u64(P.TAG_FIGURE_ID, figure_id)
-    enc.put_u32(P.TAG_SERIES_INDEX, series_index)
-    if data:
-        enc.put_float_array(P.TAG_BLOB_INLINE, data)
-    return enc.take()
-
+    return fb_codec.encode_fb_req_append_data(figure_id=figure_id, series_index=series_index, data=data)
 
 def encode_req_append_data_raw(figure_id: int, series_index: int, raw_bytes: bytes, count: int) -> bytes:
     """Encode REQ_APPEND_DATA with pre-packed float array bytes for zero-copy from numpy."""
@@ -325,48 +292,19 @@ def encode_req_update_property(
     bool_val: bool = False,
     str_val: str = "",
 ) -> bytes:
-    enc = PayloadEncoder()
-    enc.put_u64(P.TAG_FIGURE_ID, figure_id)
-    enc.put_u32(P.TAG_AXES_INDEX, axes_index)
-    enc.put_u32(P.TAG_SERIES_INDEX, series_index)
-    enc.put_string(P.TAG_PROPERTY_NAME, prop)
-    enc.put_double(P.TAG_F1, f1)
-    enc.put_double(P.TAG_F2, f2)
-    enc.put_double(P.TAG_F3, f3)
-    enc.put_double(P.TAG_F4, f4)
-    enc.put_bool(P.TAG_BOOL_VAL, bool_val)
-    if str_val:
-        enc.put_string(P.TAG_STR_VAL, str_val)
-    return enc.take()
-
+    return fb_codec.encode_fb_req_update_property(figure_id=figure_id, axes_index=axes_index, series_index=series_index, prop=prop, f1=f1, f2=f2, f3=f3, f4=f4, bool_val=bool_val, str_val=str_val)
 
 def encode_req_show(figure_id: int, window_id: int = 0) -> bytes:
-    enc = PayloadEncoder()
-    enc.put_u64(P.TAG_FIGURE_ID, figure_id)
-    if window_id != 0:
-        enc.put_u64(P.TAG_WINDOW_ID, window_id)
-    return enc.take()
-
+    return fb_codec.encode_fb_req_show(figure_id=figure_id, window_id=window_id)
 
 def encode_req_destroy_figure(figure_id: int) -> bytes:
-    enc = PayloadEncoder()
-    enc.put_u64(P.TAG_FIGURE_ID, figure_id)
-    return enc.take()
-
+    return fb_codec.encode_fb_req_destroy_figure(figure_id=figure_id)
 
 def encode_req_remove_series(figure_id: int, series_index: int) -> bytes:
-    enc = PayloadEncoder()
-    enc.put_u64(P.TAG_FIGURE_ID, figure_id)
-    enc.put_u32(P.TAG_SERIES_INDEX, series_index)
-    return enc.take()
-
+    return fb_codec.encode_fb_req_remove_series(figure_id=figure_id, series_index=series_index)
 
 def encode_req_close_figure(figure_id: int) -> bytes:
-    """Encode REQ_CLOSE_FIGURE — close the window but keep the figure in the model."""
-    enc = PayloadEncoder()
-    enc.put_u64(P.TAG_FIGURE_ID, figure_id)
-    return enc.take()
-
+    return fb_codec.encode_fb_req_close_figure(figure_id=figure_id)
 
 def encode_req_update_batch(updates: list) -> bytes:
     """Encode REQ_UPDATE_BATCH — multiple property updates in one message.
@@ -382,12 +320,7 @@ def encode_req_update_batch(updates: list) -> bytes:
 
 
 def encode_req_reconnect(session_id: int, session_token: str = "") -> bytes:
-    enc = PayloadEncoder()
-    enc.put_u64(P.TAG_SESSION_ID, session_id)
-    if session_token:
-        enc.put_string(P.TAG_SESSION_TOKEN, session_token)
-    return enc.take()
-
+    return fb_codec.encode_fb_req_reconnect(session_id=session_id, session_token=session_token)
 
 def encode_req_list_figures() -> bytes:
     return b""
@@ -397,6 +330,96 @@ def encode_req_disconnect() -> bytes:
     return b""
 
 
+# ─── Request payload decoders (round-trip validation / testing) ───────────────
+
+def decode_req_append_data(data: bytes) -> dict:
+    """Decode REQ_APPEND_DATA payload (FlatBuffers). Returns dict with figure_id, series_index, data."""
+    if fb_codec._is_fb(data):
+        return fb_codec.decode_fb_req_append_data(data)
+    # TLV fallback (legacy)
+    result: dict = {"figure_id": 0, "series_index": 0, "data": []}
+    dec = PayloadDecoder(data)
+    while dec.next():
+        if dec.tag == P.TAG_FIGURE_ID:
+            result["figure_id"] = dec.as_u64()
+        elif dec.tag == P.TAG_SERIES_INDEX:
+            result["series_index"] = dec.as_u32()
+        elif dec.tag == P.TAG_BLOB_INLINE:
+            result["data"] = dec.as_float_array()
+    return result
+
+
+def decode_req_remove_series(data: bytes) -> dict:
+    """Decode REQ_REMOVE_SERIES payload. Returns dict with figure_id, series_index."""
+    if fb_codec._is_fb(data):
+        return fb_codec.decode_fb_req_remove_series(data)
+    result: dict = {"figure_id": 0, "series_index": 0}
+    dec = PayloadDecoder(data)
+    while dec.next():
+        if dec.tag == P.TAG_FIGURE_ID:
+            result["figure_id"] = dec.as_u64()
+        elif dec.tag == P.TAG_SERIES_INDEX:
+            result["series_index"] = dec.as_u32()
+    return result
+
+
+def decode_req_close_figure(data: bytes) -> dict:
+    """Decode REQ_CLOSE_FIGURE payload. Returns dict with figure_id."""
+    if fb_codec._is_fb(data):
+        return fb_codec.decode_fb_req_close_figure(data)
+    result: dict = {"figure_id": 0}
+    dec = PayloadDecoder(data)
+    while dec.next():
+        if dec.tag == P.TAG_FIGURE_ID:
+            result["figure_id"] = dec.as_u64()
+    return result
+
+
+def decode_req_reconnect(data: bytes) -> dict:
+    """Decode REQ_RECONNECT payload. Returns dict with session_id, session_token."""
+    if fb_codec._is_fb(data):
+        return fb_codec.decode_fb_req_reconnect(data)
+    result: dict = {"session_id": 0, "session_token": ""}
+    dec = PayloadDecoder(data)
+    while dec.next():
+        if dec.tag == P.TAG_SESSION_ID:
+            result["session_id"] = dec.as_u64()
+        elif dec.tag == P.TAG_SESSION_TOKEN:
+            result["session_token"] = dec.as_string()
+    return result
+
+
+def decode_req_update_property(data: bytes) -> dict:
+    """Decode REQ_UPDATE_PROPERTY payload. Returns dict with all fields."""
+    if fb_codec._is_fb(data):
+        return fb_codec.decode_fb_req_update_property(data)
+    result: dict = {"figure_id": 0, "axes_index": 0, "series_index": 0,
+                    "prop": "", "f1": 0.0, "f2": 0.0, "f3": 0.0, "f4": 0.0,
+                    "bool_val": False, "str_val": ""}
+    dec = PayloadDecoder(data)
+    while dec.next():
+        if dec.tag == P.TAG_FIGURE_ID:
+            result["figure_id"] = dec.as_u64()
+        elif dec.tag == P.TAG_AXES_INDEX:
+            result["axes_index"] = dec.as_u32()
+        elif dec.tag == P.TAG_SERIES_INDEX:
+            result["series_index"] = dec.as_u32()
+        elif dec.tag == P.TAG_PROPERTY_NAME:
+            result["prop"] = dec.as_string()
+        elif dec.tag == P.TAG_F1:
+            result["f1"] = dec.as_float()
+        elif dec.tag == P.TAG_F2:
+            result["f2"] = dec.as_float()
+        elif dec.tag == P.TAG_F3:
+            result["f3"] = dec.as_float()
+        elif dec.tag == P.TAG_F4:
+            result["f4"] = dec.as_float()
+        elif dec.tag == P.TAG_BOOL_VAL:
+            result["bool_val"] = dec.as_bool()
+        elif dec.tag == P.TAG_STR_VAL:
+            result["str_val"] = dec.as_string()
+    return result
+
 def encode_req_anim_start(figure_id: int, fps: float = 60.0, duration: float = 0.0) -> bytes:
     """Encode REQ_ANIM_START — start backend-driven animation.
 
@@ -447,6 +470,8 @@ def decode_blob_release(data: bytes) -> str:
 
 def decode_resp_err(data: bytes) -> Tuple[int, int, str]:
     """Returns (request_id, code, message)."""
+    if fb_codec._is_fb(data):
+        return fb_codec.decode_fb_resp_err(data)
     request_id = 0
     code = 0
     message = ""
@@ -464,6 +489,8 @@ def decode_resp_err(data: bytes) -> Tuple[int, int, str]:
 
 def decode_resp_figure_created(data: bytes) -> Tuple[int, int]:
     """Returns (request_id, figure_id)."""
+    if fb_codec._is_fb(data):
+        return fb_codec.decode_fb_resp_figure_created(data)
     request_id = 0
     figure_id = 0
     dec = PayloadDecoder(data)
@@ -478,6 +505,8 @@ def decode_resp_figure_created(data: bytes) -> Tuple[int, int]:
 
 def decode_resp_axes_created(data: bytes) -> Tuple[int, int]:
     """Returns (request_id, axes_index)."""
+    if fb_codec._is_fb(data):
+        return fb_codec.decode_fb_resp_axes_created(data)
     request_id = 0
     axes_index = 0
     dec = PayloadDecoder(data)
@@ -492,6 +521,8 @@ def decode_resp_axes_created(data: bytes) -> Tuple[int, int]:
 
 def decode_resp_series_added(data: bytes) -> Tuple[int, int]:
     """Returns (request_id, series_index)."""
+    if fb_codec._is_fb(data):
+        return fb_codec.decode_fb_resp_series_added(data)
     request_id = 0
     series_index = 0
     dec = PayloadDecoder(data)
@@ -506,6 +537,8 @@ def decode_resp_series_added(data: bytes) -> Tuple[int, int]:
 
 def decode_resp_figure_list(data: bytes) -> Tuple[int, List[int]]:
     """Returns (request_id, [figure_ids])."""
+    if fb_codec._is_fb(data):
+        return fb_codec.decode_fb_resp_figure_list(data)
     request_id = 0
     figure_ids: List[int] = []
     dec = PayloadDecoder(data)
@@ -520,6 +553,8 @@ def decode_resp_figure_list(data: bytes) -> Tuple[int, List[int]]:
 
 def decode_resp_ok(data: bytes) -> int:
     """Returns request_id."""
+    if fb_codec._is_fb(data):
+        return fb_codec.decode_fb_resp_ok(data)
     request_id = 0
     dec = PayloadDecoder(data)
     while dec.next():
@@ -530,6 +565,8 @@ def decode_resp_ok(data: bytes) -> int:
 
 def decode_evt_window_closed(data: bytes) -> Tuple[int, int, str]:
     """Returns (figure_id, window_id, reason)."""
+    if fb_codec._is_fb(data):
+        return fb_codec.decode_fb_evt_window_closed(data)
     figure_id = 0
     window_id = 0
     reason = ""
@@ -543,3 +580,36 @@ def decode_evt_window_closed(data: bytes) -> Tuple[int, int, str]:
         elif t == P.TAG_REASON:
             reason = dec.as_string()
     return figure_id, window_id, reason
+
+
+# ─── Topics ───────────────────────────────────────────────────────────────────
+
+def encode_req_declare_topic(name: str, kind: int = 0, unit: str = "",
+                             ring_capacity: int = 4096) -> bytes:
+    return fb_codec.encode_fb_req_declare_topic(name, kind, unit, ring_capacity)
+
+
+def encode_req_publish_topic_samples(name: str, samples: List[float]) -> bytes:
+    return fb_codec.encode_fb_req_publish_topic_samples(name, samples)
+
+
+def encode_req_subscribe_topic(name: str, figure_id: int, axes_index: int,
+                               series_index: int = 0xFFFFFFFF) -> bytes:
+    return fb_codec.encode_fb_req_subscribe_topic(name, figure_id, axes_index, series_index)
+
+
+def encode_req_unsubscribe_topic(name: str, figure_id: int, axes_index: int,
+                                 series_index: int) -> bytes:
+    return fb_codec.encode_fb_req_unsubscribe_topic(name, figure_id, axes_index, series_index)
+
+
+def encode_req_list_topics() -> bytes:
+    return fb_codec.encode_fb_req_list_topics()
+
+
+def decode_resp_topic_list(data: bytes):
+    return fb_codec.decode_fb_resp_topic_list(data)
+
+
+def decode_resp_subscribe_topic(data: bytes):
+    return fb_codec.decode_fb_resp_subscribe_topic(data)