anyplotlib 0.1.0b1__py3-none-any.whl

anyplotlib/callbacks.py

@@ -0,0 +1,328 @@
+"""
+callbacks.py
+============
+
+Event system used by all plot objects and widgets.
+
+:class:`Event`
+    Flat dataclass carrying all event fields as typed top-level attributes.
+
+:class:`CallbackRegistry`
+    Per-object handler store. (Full implementation added in Tasks 2-3.)
+
+:class:`_EventMixin`
+    Mixin added to every plot class and widget. (Added in Task 4.)
+"""
+from __future__ import annotations
+
+import time
+from collections import defaultdict, deque
+from contextlib import contextmanager
+from dataclasses import dataclass, field
+from typing import Any, Callable
+
+VALID_EVENT_TYPES = frozenset({
+    "pointer_down", "pointer_up", "pointer_move", "pointer_settled",
+    "pointer_enter", "pointer_leave", "double_click", "wheel",
+    "key_down", "key_up", "close", "*",
+})
+
+
+@dataclass
+class Event:
+    """A single interactive event with all payload fields as typed attributes.
+
+    Universal fields (every event):
+        event_type, source, time_stamp, modifiers
+
+    Pointer fields (pointer_* and double_click events):
+        x, y           — canvas coordinates within the panel (float pixels)
+        button         — 0=left 1=middle 2=right; None on move/enter/leave/settled
+        buttons        — bitmask of currently held buttons
+        xdata, ydata   — data-space coordinates (None for Plot3D)
+        ray            — Plot3D only: {"origin": [...], "direction": [...]}
+        line_id        — Plot1D only: set when pointer is over a line
+        dwell_ms       — pointer_settled only: actual dwell time
+
+    PlotBar extra fields (pointer_down only):
+        bar_index, value, x_label, group_index
+
+    Wheel fields:
+        dx, dy         — scroll deltas
+
+    Key fields:
+        key            — key name e.g. "q", "Enter", "ArrowLeft"
+        last_widget_id — id of the last widget the user clicked, or None
+
+    Propagation:
+        stop_propagation — set True inside a handler to halt remaining handlers
+    """
+    event_type: str
+    source: Any = None
+    time_stamp: float = field(default_factory=time.perf_counter)
+    modifiers: list[str] = field(default_factory=list)
+    # Pointer
+    x: float | None = None
+    y: float | None = None
+    button: int | None = None
+    buttons: int = 0
+    xdata: float | None = None
+    ydata: float | None = None
+    ray: dict | None = None
+    line_id: str | None = None
+    dwell_ms: float | None = None
+    # PlotBar
+    bar_index: int | None = None
+    value: float | None = None
+    x_label: str | None = None
+    group_index: int | None = None
+    # Wheel
+    dx: float | None = None
+    dy: float | None = None
+    # Key
+    key: str | None = None
+    last_widget_id: str | None = None
+    # Propagation (not repr'd)
+    stop_propagation: bool = field(default=False, repr=False)
+
+    def __repr__(self) -> str:
+        src = type(self.source).__name__ if self.source is not None else "None"
+        parts = [f"event_type={self.event_type!r}", f"source={src}"]
+        for fname in ("x", "y", "xdata", "ydata", "button", "key",
+                      "line_id", "bar_index", "dwell_ms"):
+            v = getattr(self, fname)
+            if v is not None:
+                parts.append(f"{fname}={v!r}")
+        if self.modifiers:
+            parts.append(f"modifiers={self.modifiers!r}")
+        return "Event(" + ", ".join(parts) + ")"
+
+
+class CallbackRegistry:
+    """Per-object handler store.
+
+    Supports:
+    - Priority ordering (``order`` kwarg — lower fires first)
+    - Wildcard ``"*"`` type receives every dispatched event
+    - ``stop_propagation`` on the event halts remaining handlers
+    - ``disconnect_fn(fn, *types)`` removes by callback reference
+    - ``pause_events`` / ``hold_events`` context managers (added in Task 3)
+    """
+
+    def __init__(self) -> None:
+        # {event_type: [(order, cid, fn), ...]} — sorted by order
+        self._handlers: dict[str, list[tuple[float, int, Callable]]] = defaultdict(list)
+        self._next_cid: int = 1
+        # {cid: set[str]} — which types this cid is registered under
+        self._cid_map: dict[int, set[str]] = {}
+        # {id(fn): set[int]} — which cids this fn owns
+        self._fn_map: dict[int, set[int]] = defaultdict(set)
+        # pause/hold state (populated in Task 3)
+        self._pause_counts: dict[str, int] = {}
+        self._hold_counts: dict[str, int] = {}
+        self._held: deque[Event] = deque()
+
+    # ── registration ─────────────────────────────────────────────────────
+
+    def connect(self, event_type: str, fn: Callable, *, order: float = 0) -> int:
+        """Register fn for event_type. Returns integer CID."""
+        if event_type not in VALID_EVENT_TYPES:
+            raise ValueError(
+                f"Invalid event_type {event_type!r}. "
+                f"Valid types: {sorted(t for t in VALID_EVENT_TYPES if t != '*')} or '*'"
+            )
+        cid = self._next_cid
+        self._next_cid += 1
+        self._handlers[event_type].append((order, cid, fn))
+        self._handlers[event_type].sort(key=lambda t: t[0])
+        self._cid_map.setdefault(cid, set()).add(event_type)
+        self._fn_map[id(fn)].add(cid)
+        return cid
+
+    def disconnect(self, cid: int) -> None:
+        """Remove handler by CID. Silent if not found."""
+        types = self._cid_map.pop(cid, set())
+        for et in types:
+            self._handlers[et] = [
+                (o, c, f) for o, c, f in self._handlers[et] if c != cid
+            ]
+        for fn_cids in self._fn_map.values():
+            fn_cids.discard(cid)
+
+    def disconnect_fn(self, fn: Callable, *types: str) -> None:
+        """Remove fn from the given types (all types if none given)."""
+        for cid in list(self._fn_map.get(id(fn), set())):
+            cid_types = self._cid_map.get(cid, set())
+            if not types or cid_types & set(types):
+                self.disconnect(cid)
+
+    # ── dispatch ─────────────────────────────────────────────────────────
+
+    def fire(self, event: Event) -> None:
+        """Dispatch event to matching handlers (respects pause/hold)."""
+        et = event.event_type
+        if self._pause_counts.get(et, 0) > 0 or self._pause_counts.get("*", 0) > 0:
+            return
+        if self._hold_counts.get(et, 0) > 0 or self._hold_counts.get("*", 0) > 0:
+            self._held.append(event)
+            return
+        self._dispatch(event)
+
+    def _dispatch(self, event: Event) -> None:
+        et = event.event_type
+        specific = list(self._handlers.get(et, []))
+        wildcard = list(self._handlers.get("*", []))
+        merged = sorted(specific + wildcard, key=lambda t: t[0])
+        for _order, _cid, fn in merged:
+            if event.stop_propagation:
+                break
+            fn(event)
+
+    def _flush(self) -> None:
+        while self._held:
+            self._dispatch(self._held.popleft())
+
+    @contextmanager
+    def pause_events(self, *types: str):
+        """Suppress events of the given types while inside this context.
+        All types are paused when called with no arguments.
+        Pause wins over hold for the same type."""
+        target = types if types else ("*",)
+        for t in target:
+            self._pause_counts[t] = self._pause_counts.get(t, 0) + 1
+        try:
+            yield
+        finally:
+            for t in target:
+                self._pause_counts[t] -= 1
+                if self._pause_counts[t] == 0:
+                    del self._pause_counts[t]
+
+    @contextmanager
+    def hold_events(self, *types: str):
+        """Buffer events of the given types; flush when the outermost hold exits.
+        All types are held when called with no arguments."""
+        target = types if types else ("*",)
+        for t in target:
+            self._hold_counts[t] = self._hold_counts.get(t, 0) + 1
+        try:
+            yield
+        finally:
+            for t in target:
+                self._hold_counts[t] -= 1
+                if self._hold_counts[t] == 0:
+                    del self._hold_counts[t]
+            if not self._hold_counts:
+                self._flush()
+
+    def __bool__(self) -> bool:
+        return any(bool(v) for v in self._handlers.values())
+
+
+class _EventMixin:
+    """Mixin for plot classes and widgets.
+
+    Provides ``add_event_handler`` / ``remove_handler`` / ``pause_events`` /
+    ``hold_events``.  The host class must set ``self.callbacks = CallbackRegistry()``
+    in its ``__init__``.
+    """
+
+    callbacks: CallbackRegistry
+
+    def add_event_handler(
+        self,
+        fn_or_type,
+        *args,
+        order: float = 0,
+        ms: int = 300,
+        delta: float = 4,
+    ):
+        """Register an event handler. Works as a direct call or decorator.
+
+        Direct call::
+
+            plot.add_event_handler(fn, "pointer_down")
+            plot.add_event_handler(fn, "pointer_down", "pointer_up")
+
+        Decorator::
+
+            @plot.add_event_handler("pointer_down")
+            def handler(event): ...
+
+            @plot.add_event_handler("pointer_settled", ms=400, delta=5)
+            def on_settle(event): ...
+
+        Parameters
+        ----------
+        fn_or_type : callable or str
+            Handler function (direct call) or first event type string (decorator).
+        *args : str
+            Remaining event type strings.
+        order : float
+            Priority. Lower fires first. Default 0.
+        ms : int
+            ``pointer_settled`` dwell threshold in milliseconds. Default 300.
+            Raises ``ValueError`` if provided without ``"pointer_settled"`` in types.
+        delta : float
+            ``pointer_settled`` pixel radius. Default 4.
+            Raises ``ValueError`` if provided without ``"pointer_settled"`` in types.
+        """
+        if callable(fn_or_type):
+            return self._register(fn_or_type, args, order=order, ms=ms, delta=delta)
+        else:
+            all_types = (fn_or_type,) + args
+            def _decorator(fn: Callable) -> Callable:
+                self._register(fn, all_types, order=order, ms=ms, delta=delta)
+                return fn
+            return _decorator
+
+    def _register(
+        self, fn: Callable, types: tuple, *, order: float, ms: int, delta: float
+    ) -> Callable:
+        has_settled = "pointer_settled" in types
+        _ms_changed = ms != 300
+        _delta_changed = delta != 4
+        if (_ms_changed or _delta_changed) and not has_settled:
+            raise ValueError(
+                "ms/delta kwargs are only valid when 'pointer_settled' is in the event types"
+            )
+        for event_type in types:
+            self.callbacks.connect(event_type, fn, order=order)
+        if has_settled:
+            self._configure_pointer_settled(ms, delta)
+        fn._event_types = getattr(fn, "_event_types", set()) | set(types)
+        return fn
+
+    def remove_handler(self, cid_or_fn, *types: str) -> None:
+        """Remove a registered handler.
+
+        Parameters
+        ----------
+        cid_or_fn : int or callable
+            CID returned by ``callbacks.connect()`` or the handler function.
+        *types : str
+            If given, only remove from these types. If omitted, remove from all.
+        """
+        had_settled = bool(self.callbacks._handlers.get("pointer_settled"))
+        if isinstance(cid_or_fn, int):
+            self.callbacks.disconnect(cid_or_fn)
+        else:
+            self.callbacks.disconnect_fn(cid_or_fn, *types)
+        if had_settled and not self.callbacks._handlers.get("pointer_settled"):
+            self._configure_pointer_settled(0, 0)
+
+    def _configure_pointer_settled(self, ms: int, delta: float) -> None:
+        """Override in plot subclasses to push thresholds to JS."""
+        pass
+
+    @contextmanager
+    def pause_events(self, *types: str):
+        """Suppress events of the given types (all types if none given)."""
+        with self.callbacks.pause_events(*types):
+            yield
+
+    @contextmanager
+    def hold_events(self, *types: str):
+        """Buffer events of the given types; flush when context exits."""
+        with self.callbacks.hold_events(*types):
+            yield

anyplotlib/embed.py

@@ -0,0 +1,194 @@
+"""
+embed.py
+========
+
+Use anyplotlib figures **outside Jupyter** — in Electron apps, MDI
+sub-windows, kiosk dashboards, or any plain web page.  No kernel, no
+ipywidgets, no anywidget runtime in the page.
+
+Three levels of integration
+---------------------------
+
+**1. Static / self-contained (no Python at runtime)** — export a fully
+self-contained HTML page (renderer + data inlined) and load it anywhere a
+browser engine runs, e.g. an Electron ``BrowserWindow`` or ``<webview>``::
+
+    import anyplotlib as apl
+    fig, ax = apl.subplots(1, 1)
+    ax.imshow(data)
+    fig.save_html("plot.html")          # win.loadFile('plot.html')
+
+All client-side interactivity (pan, zoom, widgets, markers) works; Python
+callbacks obviously do not.
+
+**2. JS-driven (your app owns the data)** — ship ``figure_esm.js`` with your
+app and mount figures from JavaScript using the exported ``mount()``::
+
+    import { mount } from './figure_esm.js';
+    const handle = mount(container, state, { onEvent: ev => ... });
+    handle.setPanelState(panelId, newPanelState);   // live updates
+    handle.resize(w, h);  handle.dispose();
+
+``state`` is the JSON dict produced by :func:`figure_state` — generate it
+once from Python (build time, or a one-shot script) or construct it in JS.
+Each ``mount()`` is fully self-contained, so one window can host many
+figures (MDI-style) by mounting into separate containers.
+
+**3. Live Python backend** — run Python alongside your app (sidecar process,
+local WebSocket server, …) and keep figures fully interactive with Python
+callbacks via :class:`FigureBridge`, which is transport-agnostic::
+
+    # Python side (e.g. behind a websocket)
+    bridge = FigureBridge(fig, send=lambda key, value: ws.send(
+        json.dumps({"key": key, "value": value})))
+    ws.on_message = lambda m: bridge.receive(**json.loads(m))
+
+    // JS side
+    const handle = mount(el, snapshot, {
+      onSync: (key, value) => ws.send(JSON.stringify({key, value})),
+    });
+    ws.onmessage = (m) => { const u = JSON.parse(m.data);
+                            handle.applyUpdate(u.key, u.value); };
+
+See ``docs/embedding.rst`` for a complete Electron walkthrough.
+"""
+
+from __future__ import annotations
+
+import pathlib
+
+from anyplotlib._repr_utils import build_standalone_html, _widget_state
+
+__all__ = ["figure_state", "to_html", "save_html", "esm_path", "FigureBridge"]
+
+
+def figure_state(fig) -> dict:
+    """Return the figure's full serialised state as a plain JSON-safe dict.
+
+    The dict contains every synced trait — ``layout_json``, ``fig_width``,
+    ``fig_height``, ``event_json``, and one ``panel_<id>_json`` entry per
+    panel — and is exactly what the JS ``mount(el, state)`` entry point
+    expects.
+
+    Parameters
+    ----------
+    fig : Figure
+
+    Returns
+    -------
+    dict
+    """
+    # _widget_state also picks up ipywidgets infrastructure traits (layout,
+    # tabbable, …) whose values aren't JSON.  The renderer only reads scalar
+    # traits, so keep exactly those.
+    return {k: v for k, v in _widget_state(fig).items()
+            if isinstance(v, (str, int, float, bool)) or v is None}
+
+
+def to_html(fig, *, resizable: bool = True) -> str:
+    """Return a fully self-contained HTML page rendering *fig*.
+
+    The page inlines the renderer and all figure data; it needs no network,
+    kernel, or Python at view time.  Client-side interactivity (pan, zoom,
+    overlay widgets) is preserved.
+
+    Parameters
+    ----------
+    fig : Figure
+    resizable : bool, optional
+        Keep the figure's drag-to-resize handle.  Default ``True``.
+    """
+    return build_standalone_html(fig, resizable=resizable)
+
+
+def save_html(fig, path, *, resizable: bool = True) -> pathlib.Path:
+    """Write :func:`to_html` output to *path* and return it as a ``Path``."""
+    p = pathlib.Path(path)
+    p.write_text(to_html(fig, resizable=resizable), encoding="utf-8")
+    return p
+
+
+def esm_path() -> pathlib.Path:
+    """Return the path to ``figure_esm.js`` for bundling into a JS app.
+
+    Copy (or import) this file into your Electron / web build; it exports
+    ``mount`` and ``createLocalModel`` alongside the anywidget ``render``.
+    """
+    return pathlib.Path(__file__).parent / "figure_esm.js"
+
+
+class FigureBridge:
+    """Transport-agnostic two-way sync between a live ``Figure`` and a
+    remote JS view mounted with ``mount(el, state, {onSync})``.
+
+    You supply the pipe (WebSocket, Electron IPC via a sidecar, stdio, …);
+    the bridge supplies the protocol: plain ``(key, value)`` pairs.
+
+    Parameters
+    ----------
+    fig : Figure
+        The live figure.  All Python-side mutations (``plot.set_data(...)``,
+        marker/widget updates, layout changes) are forwarded automatically.
+    send : callable(key: str, value) -> None
+        Called for every outbound state change.  Wire it to your transport.
+
+    Notes
+    -----
+    * **Python → JS**: any synced trait change triggers ``send(key, value)``;
+      deliver it to ``handle.applyUpdate(key, value)`` in JS.
+    * **JS → Python**: deliver each JS ``onSync(key, value)`` message to
+      :meth:`receive`.  Interaction events (``event_json``) are dispatched to
+      the figure's callback registries exactly as in Jupyter, so
+      ``@plot.add_event_handler(...)`` handlers fire unchanged.
+    * Echo is suppressed in both directions.
+    """
+
+    def __init__(self, fig, send) -> None:
+        self._fig = fig
+        self._send = send
+        self._applying = False
+        # names=traitlets.All: also covers panel traits added dynamically
+        # after the bridge is created (Figure.add_traits on new panels).
+        import traitlets
+        fig.observe(self._on_trait_change, names=traitlets.All)
+
+    # ── outbound (Python → JS) ────────────────────────────────────────────
+    def _on_trait_change(self, change) -> None:
+        if self._applying:
+            return
+        name = change["name"]
+        trait = self._fig.traits().get(name)
+        if trait is None or not trait.metadata.get("sync") or name.startswith("_"):
+            return
+        self._send(name, change["new"])
+
+    def snapshot(self) -> dict:
+        """Full state dict for the initial ``mount()`` on the JS side."""
+        return figure_state(self._fig)
+
+    # ── inbound (JS → Python) ─────────────────────────────────────────────
+    def receive(self, key: str, value) -> None:
+        """Apply one inbound ``(key, value)`` message from the JS view.
+
+        ``event_json`` messages are dispatched to plot/widget callbacks;
+        other keys (e.g. a panel's view state after a JS-side 3D rotate)
+        are stored on the figure without echoing back.
+        """
+        if key == "event_json":
+            self._fig._dispatch_event(value)
+            return
+        if not self._fig.has_trait(key):
+            return
+        self._applying = True
+        try:
+            setattr(self._fig, key, value)
+        finally:
+            self._applying = False
+
+    def close(self) -> None:
+        """Stop forwarding (unobserve the figure)."""
+        import traitlets
+        try:
+            self._fig.unobserve(self._on_trait_change, names=traitlets.All)
+        except ValueError:
+            pass

anyplotlib/figure/__init__.py

@@ -0,0 +1,7 @@
+"""anyplotlib.figure — Figure widget, grid spec, and subplots factory."""
+
+from anyplotlib.figure._figure import Figure
+from anyplotlib.figure._gridspec import GridSpec, SubplotSpec
+from anyplotlib.figure._subplots import subplots
+
+__all__ = ["Figure", "GridSpec", "SubplotSpec", "subplots"]