spectra-plot 0.2.0__tar.gz

spectra_plot-0.2.0/MANIFEST.in

@@ -0,0 +1 @@
+include VERSION

spectra_plot-0.2.0/PKG-INFO

@@ -0,0 +1,22 @@
+Metadata-Version: 2.4
+Name: spectra-plot
+Version: 0.2.0
+Summary: GPU-accelerated scientific plotting via IPC
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: numpy
+Requires-Dist: numpy>=1.20; extra == "numpy"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: numpy>=1.20; extra == "dev"

spectra_plot-0.2.0/VERSION

@@ -0,0 +1 @@
+0.2.0

spectra_plot-0.2.0/pyproject.toml

@@ -0,0 +1,34 @@
+[build-system]
+requires = ["setuptools>=68.0"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "spectra-plot"
+dynamic = ["version"]
+description = "GPU-accelerated scientific plotting via IPC"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Visualization",
+]
+
+[project.optional-dependencies]
+numpy = ["numpy>=1.20"]
+dev = ["pytest>=7.0", "numpy>=1.20"]
+
+[tool.setuptools.dynamic]
+version = {file = "VERSION"}
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["spectra*"]

spectra_plot-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

spectra_plot-0.2.0/spectra/__init__.py

@@ -0,0 +1,147 @@
+"""Spectra — GPU-accelerated scientific plotting via IPC.
+
+The easiest plotting library. One line to plot.
+
+Usage::
+
+    import spectra as sp
+
+    sp.plot([1, 4, 9, 16])                    # that's it. window opens.
+    sp.plot(x, y, color="red", label="data")   # with style
+    sp.scatter(x, y)                           # scatter plot
+    sp.hist(data, bins=50)                     # histogram
+    sp.plot3(x, y, z)                          # 3D line
+    sp.live(lambda t: math.sin(t))             # live streaming
+
+    sp.show()  # optional — block until windows closed
+
+Advanced usage (full control)::
+
+    s = sp.Session()
+    fig = s.figure("My Plot")
+    ax = fig.subplot(1, 1, 1)
+    line = ax.line(x, y, label="data")
+    fig.show()
+    s.show()
+"""
+
+from ._session import Session
+from ._figure import Figure
+from ._axes import Axes
+from ._series import Series
+from ._errors import (
+    SpectraError,
+    ConnectionError,
+    ProtocolError,
+    TimeoutError,
+    FigureNotFoundError,
+    BackendError,
+)
+from ._animation import ipc_sleep, FramePacer, BackendAnimator
+
+# ─── Easy API (one-liners, everything in background) ─────────────────────────
+from ._easy import (
+    plot,
+    scatter,
+    stem,
+    hist,
+    bar,
+    boxplot,
+    violin_plot,
+    hline,
+    vline,
+    plot3,
+    scatter3,
+    surf,
+    plotn,
+    subplots,
+    figure,
+    tab,
+    subplot,
+    subplot3d,
+    gcf,
+    gca,
+    title,
+    xlabel,
+    ylabel,
+    xlim,
+    ylim,
+    grid,
+    legend,
+    live,
+    stop_live,
+    append,
+    show,
+    close,
+    close_all,
+    clear,
+)
+
+# ─── Backward compatibility ───────────────────────────────────────────────────
+# Old API used sp.line(x, y) — keep as alias for sp.plot(x, y)
+line = plot
+
+# Old tests reference these module-level attributes
+_default_session = None
+_current_figure = None
+_current_axes = None
+
+try:
+    from importlib.metadata import version as _pkg_version
+    __version__ = _pkg_version("spectra-plot")
+except Exception:
+    __version__ = "0.1.0"
+
+__all__ = [
+    # Easy API — one-liners
+    "plot",
+    "scatter",
+    "stem",
+    "hist",
+    "bar",
+    "boxplot",
+    "violin_plot",
+    "hline",
+    "vline",
+    "plot3",
+    "scatter3",
+    "surf",
+    "plotn",
+    "subplots",
+    "figure",
+    "tab",
+    "subplot",
+    "subplot3d",
+    "gcf",
+    "gca",
+    "title",
+    "xlabel",
+    "ylabel",
+    "xlim",
+    "ylim",
+    "grid",
+    "legend",
+    "live",
+    "stop_live",
+    "append",
+    "show",
+    "close",
+    "close_all",
+    "clear",
+    # Backward compat
+    "line",
+    # Advanced API — full control
+    "Session",
+    "Figure",
+    "Axes",
+    "Series",
+    "SpectraError",
+    "ConnectionError",
+    "ProtocolError",
+    "TimeoutError",
+    "FigureNotFoundError",
+    "BackendError",
+    "ipc_sleep",
+    "FramePacer",
+    "BackendAnimator",
+]

spectra_plot-0.2.0/spectra/_animation.py

@@ -0,0 +1,180 @@
+"""Animation utilities for the Spectra Python client.
+
+Provides IPC-aware sleep and frame pacing helpers that drain events
+while waiting, preventing the backend from stalling on a blocked client.
+
+Two animation modes:
+  1. Python-driven: Python controls the loop with FramePacer
+  2. Backend-driven: Backend sends ANIM_TICK at fixed rate, Python responds
+"""
+
+import time
+from typing import TYPE_CHECKING, Callable, Optional
+
+if TYPE_CHECKING:
+    from ._session import Session
+
+
+def ipc_sleep(session: "Session", duration: float) -> None:
+    """Sleep for `duration` seconds while draining IPC events.
+
+    Unlike time.sleep(), this keeps the IPC connection alive by
+    processing incoming events (e.g. EVT_WINDOW_CLOSED) during the wait.
+
+    Thread-safe: acquires the session lock before reading from the socket.
+    Falls back to plain sleep if the lock is held by another thread
+    (e.g. the main thread doing a _request() or show() recv).
+    """
+    import select
+
+    if session._transport is None or not session._transport.is_open:
+        time.sleep(duration)
+        return
+
+    deadline = time.monotonic() + duration
+    while True:
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            break
+
+        timeout = min(remaining, 0.05)  # poll at 20 Hz
+        try:
+            ready, _, _ = select.select([session._transport.fileno()], [], [], timeout)
+        except (ValueError, OSError):
+            break
+
+        if ready:
+            # Try to acquire the lock without blocking — if another thread
+            # is doing a _request() send+recv, just skip this read.
+            acquired = session._lock.acquire(blocking=False)
+            if not acquired:
+                time.sleep(min(remaining, 0.01))
+                continue
+            try:
+                msg = session._transport.recv()
+            finally:
+                session._lock.release()
+            if msg is None:
+                break
+            session._handle_event(msg)
+
+
+class FramePacer:
+    """Simple frame pacer for Python-driven animation loops.
+
+    Usage::
+
+        pacer = FramePacer(fps=30)
+        while running:
+            update_data()
+            series.set_data(x, y)
+            pacer.pace(session)
+    """
+
+    __slots__ = ("_interval", "_last_time")
+
+    def __init__(self, fps: float = 30.0) -> None:
+        self._interval = 1.0 / max(fps, 1.0)
+        self._last_time = time.monotonic()
+
+    @property
+    def fps(self) -> float:
+        return 1.0 / self._interval
+
+    @fps.setter
+    def fps(self, value: float) -> None:
+        self._interval = 1.0 / max(value, 1.0)
+
+    def pace(self, session: "Session") -> float:
+        """Wait until the next frame time, draining events. Returns dt since last call."""
+        now = time.monotonic()
+        elapsed = now - self._last_time
+        remaining = self._interval - elapsed
+        if remaining > 0:
+            ipc_sleep(session, remaining)
+        now = time.monotonic()
+        dt = now - self._last_time
+        self._last_time = now
+        return dt
+
+
+class BackendAnimator:
+    """Backend-driven animation: the backend controls the clock and sends
+    ANIM_TICK events at a fixed rate. Python registers a callback that
+    receives (t, dt, frame_num) and updates data accordingly.
+
+    Usage::
+
+        def on_tick(t, dt, frame_num):
+            y = [math.sin(x_i + t) for x_i in x]
+            series.set_data(x, y)
+
+        animator = BackendAnimator(session, figure, fps=60)
+        animator.on_tick = on_tick
+        animator.start()
+        session.show()  # blocks until windows closed
+        animator.stop()
+    """
+
+    __slots__ = (
+        "_session", "_figure_id", "_fps", "_duration",
+        "_running", "_on_tick",
+    )
+
+    def __init__(
+        self,
+        session: "Session",
+        figure_id: int,
+        fps: float = 60.0,
+        duration: float = 0.0,
+    ) -> None:
+        self._session = session
+        self._figure_id = figure_id
+        self._fps = fps
+        self._duration = duration
+        self._running = False
+        self._on_tick: Optional[Callable[[float, float, int], None]] = None
+
+    @property
+    def on_tick(self) -> Optional[Callable[[float, float, int], None]]:
+        return self._on_tick
+
+    @on_tick.setter
+    def on_tick(self, callback: Optional[Callable[[float, float, int], None]]) -> None:
+        self._on_tick = callback
+
+    @property
+    def is_running(self) -> bool:
+        return self._running
+
+    def start(self) -> None:
+        """Request the backend to start sending ANIM_TICK events."""
+        from . import _protocol as P
+        from . import _codec as codec
+
+        if self._running:
+            return
+        payload = codec.encode_req_anim_start(
+            self._figure_id, self._fps, self._duration
+        )
+        self._session._request(P.REQ_ANIM_START, payload)
+        self._running = True
+        # Register this animator with the session for tick dispatch
+        self._session._register_animator(self)
+
+    def stop(self) -> None:
+        """Request the backend to stop sending ANIM_TICK events."""
+        from . import _protocol as P
+        from . import _codec as codec
+
+        if not self._running:
+            return
+        payload = codec.encode_req_anim_stop(self._figure_id)
+        self._session._request(P.REQ_ANIM_STOP, payload)
+        self._running = False
+        self._session._unregister_animator(self)
+
+    def handle_tick(self, t: float, dt: float, frame_num: int) -> None:
+        """Called by Session when an ANIM_TICK is received for this figure."""
+        if self._on_tick is not None:
+            self._on_tick(t, dt, frame_num)

spectra_plot-0.2.0/spectra/_axes.py

@@ -0,0 +1,275 @@
+"""Axes proxy — lightweight handle to axes within a figure."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List, Union
+
+from . import _protocol as P
+from . import _codec as codec
+
+if TYPE_CHECKING:
+    from ._session import Session
+    from ._series import Series
+
+
+class Axes:
+    """Proxy for an axes object within a figure.
+
+    All mutations are sent to the backend via IPC.
+    """
+
+    __slots__ = ("_session", "_figure_id", "_index", "_series_list", "_is_3d")
+
+    def __init__(self, session: Session, figure_id: int, axes_index: int, is_3d: bool = False) -> None:
+        self._session = session
+        self._figure_id = figure_id
+        self._index = axes_index
+        self._series_list: List[Series] = []
+        self._is_3d = is_3d
+
+    @property
+    def index(self) -> int:
+        return self._index
+
+    @property
+    def figure_id(self) -> int:
+        return self._figure_id
+
+    def line(
+        self,
+        x: Union[List[float], "object"],
+        y: Union[List[float], "object"],
+        label: str = "",
+    ) -> Series:
+        """Add a line series to this axes."""
+        return self._add_series("line", x, y, label)
+
+    def scatter(
+        self,
+        x: Union[List[float], "object"],
+        y: Union[List[float], "object"],
+        label: str = "",
+    ) -> Series:
+        """Add a scatter series to this axes."""
+        return self._add_series("scatter", x, y, label)
+
+    def _add_series(
+        self,
+        series_type: str,
+        x: Union[List[float], "object"],
+        y: Union[List[float], "object"],
+        label: str = "",
+    ) -> Series:
+        from ._series import Series
+
+        # Request series creation
+        payload = codec.encode_req_add_series(
+            figure_id=self._figure_id,
+            axes_index=self._index,
+            series_type=series_type,
+            label=label,
+        )
+        resp = self._session._request(P.REQ_ADD_SERIES, payload)
+        _, series_index = codec.decode_resp_series_added(resp["payload"])
+
+        series = Series(self._session, self._figure_id, series_index, series_type, label)
+        self._series_list.append(series)
+
+        # Set initial data
+        series.set_data(x, y)
+
+        return series
+
+    def _add_series_3d(
+        self,
+        series_type: str,
+        x: Union[List[float], "object"],
+        y: Union[List[float], "object"],
+        z: Union[List[float], "object"],
+        label: str = "",
+    ) -> Series:
+        """Add a 3D series and set XYZ data."""
+        from ._series import Series
+
+        payload = codec.encode_req_add_series(
+            figure_id=self._figure_id,
+            axes_index=self._index,
+            series_type=series_type,
+            label=label,
+        )
+        resp = self._session._request(P.REQ_ADD_SERIES, payload)
+        _, series_index = codec.decode_resp_series_added(resp["payload"])
+
+        series = Series(self._session, self._figure_id, series_index, series_type, label)
+        self._series_list.append(series)
+
+        series.set_data_xyz(x, y, z)
+
+        return series
+
+    @property
+    def series(self) -> List[Series]:
+        return list(self._series_list)
+
+    def set_xlim(self, xmin: float, xmax: float) -> None:
+        payload = codec.encode_req_update_property(
+            figure_id=self._figure_id,
+            axes_index=self._index,
+            prop="xlim",
+            f1=xmin,
+            f2=xmax,
+        )
+        self._session._request(P.REQ_UPDATE_PROPERTY, payload)
+
+    def set_ylim(self, ymin: float, ymax: float) -> None:
+        payload = codec.encode_req_update_property(
+            figure_id=self._figure_id,
+            axes_index=self._index,
+            prop="ylim",
+            f1=ymin,
+            f2=ymax,
+        )
+        self._session._request(P.REQ_UPDATE_PROPERTY, payload)
+
+    def set_zlim(self, zmin: float, zmax: float) -> None:
+        payload = codec.encode_req_update_property(
+            figure_id=self._figure_id,
+            axes_index=self._index,
+            prop="zlim",
+            f1=zmin,
+            f2=zmax,
+        )
+        self._session._request(P.REQ_UPDATE_PROPERTY, payload)
+
+    def set_xlabel(self, label: str) -> None:
+        payload = codec.encode_req_update_property(
+            figure_id=self._figure_id,
+            axes_index=self._index,
+            prop="xlabel",
+            str_val=label,
+        )
+        self._session._request(P.REQ_UPDATE_PROPERTY, payload)
+
+    def set_ylabel(self, label: str) -> None:
+        payload = codec.encode_req_update_property(
+            figure_id=self._figure_id,
+            axes_index=self._index,
+            prop="ylabel",
+            str_val=label,
+        )
+        self._session._request(P.REQ_UPDATE_PROPERTY, payload)
+
+    def set_title(self, title: str) -> None:
+        payload = codec.encode_req_update_property(
+            figure_id=self._figure_id,
+            axes_index=self._index,
+            prop="axes_title",
+            str_val=title,
+        )
+        self._session._request(P.REQ_UPDATE_PROPERTY, payload)
+
+    def grid(self, visible: bool = True) -> None:
+        payload = codec.encode_req_update_property(
+            figure_id=self._figure_id,
+            axes_index=self._index,
+            prop="grid",
+            bool_val=visible,
+        )
+        self._session._request(P.REQ_UPDATE_PROPERTY, payload)
+
+    def legend(self, visible: bool = True) -> None:
+        """Toggle legend visibility on this axes."""
+        payload = codec.encode_req_update_property(
+            figure_id=self._figure_id,
+            axes_index=self._index,
+            prop="legend",
+            bool_val=visible,
+        )
+        self._session._request(P.REQ_UPDATE_PROPERTY, payload)
+
+    def remove_series(self, index: int) -> None:
+        """Remove a series by index from this axes."""
+        payload = codec.encode_req_remove_series(
+            figure_id=self._figure_id,
+            series_index=index,
+        )
+        self._session._request(P.REQ_REMOVE_SERIES, payload)
+        self._series_list = [s for s in self._series_list if s._index != index]
+
+    def clear(self) -> None:
+        """Remove all series from this axes."""
+        # Remove in reverse order so indices stay valid
+        for s in reversed(list(self._series_list)):
+            payload = codec.encode_req_remove_series(
+                figure_id=self._figure_id,
+                series_index=s._index,
+            )
+            self._session._request(P.REQ_REMOVE_SERIES, payload)
+        self._series_list.clear()
+
+    def batch(self) -> "_AxesBatchContext":
+        """Context manager for batching multiple property updates into one IPC call.
+
+        Usage::
+
+            with ax.batch() as b:
+                b.set_xlim(0, 10)
+                b.set_ylim(-1, 1)
+                b.set_xlabel("Time")
+                b.set_ylabel("Value")
+                b.grid(True)
+        """
+        return _AxesBatchContext(self)
+
+    @property
+    def is_3d(self) -> bool:
+        return getattr(self, "_is_3d", False)
+
+    def __repr__(self) -> str:
+        is_3d = getattr(self, "_is_3d", False)
+        return f"Axes(figure_id={self._figure_id}, index={self._index}, is_3d={is_3d})"
+
+
+
+class _AxesBatchContext:
+    """Collects property updates and sends them as a single REQ_UPDATE_BATCH."""
+
+    __slots__ = ("_axes", "_updates")
+
+    def __init__(self, axes: Axes) -> None:
+        self._axes = axes
+        self._updates: list = []
+
+    def __enter__(self) -> "_AxesBatchContext":
+        return self
+
+    def __exit__(self, *args) -> None:
+        if self._updates:
+            self._axes._session.batch_update(self._updates)
+        self._updates.clear()
+
+    def _add(self, **kwargs) -> None:
+        kwargs.setdefault("figure_id", self._axes._figure_id)
+        kwargs.setdefault("axes_index", self._axes._index)
+        self._updates.append(kwargs)
+
+    def set_xlim(self, xmin: float, xmax: float) -> None:
+        self._add(prop="xlim", f1=xmin, f2=xmax)
+
+    def set_ylim(self, ymin: float, ymax: float) -> None:
+        self._add(prop="ylim", f1=ymin, f2=ymax)
+
+    def set_xlabel(self, label: str) -> None:
+        self._add(prop="xlabel", str_val=label)
+
+    def set_ylabel(self, label: str) -> None:
+        self._add(prop="ylabel", str_val=label)
+
+    def set_title(self, title: str) -> None:
+        self._add(prop="axes_title", str_val=title)
+
+    def grid(self, visible: bool = True) -> None:
+        self._add(prop="grid", bool_val=visible)
+
+    def legend(self, visible: bool = True) -> None:
+        self._add(prop="legend", bool_val=visible)