pfund-plot 0.0.1__py3-none-any.whl

pfund_plot/plots/layout/layout.py

@@ -0,0 +1,116 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar, Literal
+
+if TYPE_CHECKING:
+    from pfund_plot.typing import RawFigure
+
+from pfund_kit.style import RichColor, TextStyle, cprint
+
+from pfund_plot.enums import PlottingBackend
+from pfund_plot.plots.lazy import LazyPlot
+from pfund_plot.plots.plot import BasePlot
+
+
+class BaseLayout(BasePlot):
+    SUPPORTED_BACKENDS: ClassVar[list[Literal[PlottingBackend.panel]]] = [
+        PlottingBackend.panel
+    ]
+    SUPPORT_STREAMING: ClassVar[bool] = True
+    REQUIRED_DATA: ClassVar[bool] = False
+
+    def __new__(cls, *plots: LazyPlot | RawFigure):
+        from pfund_plot.utils import convert_to_lazy_plot
+
+        # Convert any plotting library figures to LazyPlot instances
+        lazy_plots = tuple(
+            convert_to_lazy_plot(plot) if not isinstance(plot, LazyPlot) else plot
+            for plot in plots
+        )
+        # super().__new__ will call __init__ with converted_plots
+        return super().__new__(cls, *lazy_plots)
+
+    def __init__(self, *plots: LazyPlot):  # pyright: ignore[reportInconsistentConstructor]
+        self._plots: tuple[LazyPlot, ...] = plots
+        super().__init__(data=None)
+
+    def _add_plots_periodic_callbacks(self):
+        """Transfer child plots' periodic callbacks to Layout's renderer.
+
+        Child plots inside Layout are never rendered directly — only Layout's
+        renderer gets render() called. Without this, child streaming plots'
+        periodic callbacks (e.g. _refresh_streaming_ui) would never start.
+        """
+        assert self._renderer is not None, "renderer is not set"
+        for lazyplot in self._plots:
+            plot = lazyplot._plot
+            assert plot._renderer is not None, f"{plot.name} renderer is not set"
+            for cb in plot._renderer._periodic_callbacks:
+                self._renderer.add_periodic_callback(cb)
+
+    def is_streaming(self):
+        return any(lazyplot.is_streaming for lazyplot in self._plots)
+
+    def _start_streaming(self):
+        for lazyplot in self._plots:
+            plot = lazyplot._plot
+            if plot.is_streaming():
+                plot._start_streaming()
+
+    def _wait_for_streaming_ready(self):
+        for lazyplot in self._plots:
+            plot = lazyplot._plot
+            if plot.is_streaming():
+                plot._wait_for_streaming_ready()
+
+    def _apply_linked_axes(self):
+        """Apply layout-level linked_axes control to all child plots."""
+        if self._control is None:
+            return
+        linked_axes = self._control.get("linked_axes", True)
+        for lazyplot in self._plots:
+            plot = lazyplot._plot
+            if plot._control is not None:
+                plot._control["linked_axes"] = linked_axes
+            for overlay in plot._overlays:
+                if overlay._control is not None:
+                    overlay._control["linked_axes"] = linked_axes
+
+    def _warn_if_linked_axes_with_streaming(self):
+        """Warn if linked_axes is enabled when streaming and non-streaming plots coexist.
+
+        Streaming plots continuously update their x-axis range, which will drag
+        linked non-streaming plots to the same range — making their data invisible.
+        """
+        if self._control is None or not self._control.get("linked_axes", True):
+            return
+        has_streaming = any(lazyplot.is_streaming for lazyplot in self._plots)
+        has_non_streaming = any(not lazyplot.is_streaming for lazyplot in self._plots)
+        if has_streaming and has_non_streaming:
+            cprint(
+                "Streaming and non-streaming plots detected with linked_axes=True. "
+                + "Non-streaming plots may show empty data as their axes follow the streaming range. "
+                + "Use .control(linked_axes=False) to fix this.",
+                style=TextStyle.BOLD + RichColor.YELLOW,
+            )
+
+    def _create(self):
+        super()._create()
+        self._warn_if_linked_axes_with_streaming()
+
+    # no plot needed
+    def _create_plot(self):
+        pass
+
+    # no pane needed
+    def _create_pane(self):
+        pass
+
+    def _create_component(self):
+        self._apply_linked_axes()
+        self._component = self._plot_func(
+            *self._plots,
+            style=self._style,
+            control=self._control,  # pyright: ignore[reportCallIssue]
+        )
+        self._add_plots_periodic_callbacks()

pfund_plot/plots/layout/panel.py

@@ -0,0 +1,51 @@
+# pyright: reportUnusedParameter=false, reportArgumentType=false
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from pfund_plot.plots.lazy import LazyPlot
+
+import panel as pn
+from panel.layout.gridstack import GridStack
+
+__all__ = ["control", "plot", "style"]
+DEFAULT_NUM_COLS = 3
+
+
+def style():
+    return locals()
+
+
+def control(
+    num_cols: int = DEFAULT_NUM_COLS,
+    allow_drag: bool = True,
+    allow_resize: bool = True,
+    linked_axes: bool = True,
+):
+    return locals()
+
+
+def plot(
+    *plots: LazyPlot, style: dict[str, Any], control: dict[str, Any], **kwargs: Any
+) -> GridStack:
+    pn.extension("gridstack")
+
+    gstack = GridStack(
+        sizing_mode="stretch_both",
+        allow_drag=control["allow_drag"],
+        allow_resize=control["allow_resize"],
+    )
+
+    grid_specs = [plot._grid_spec for plot in plots]
+    if all(grid_spec is not None for grid_spec in grid_specs):
+        for plot, grid_spec in zip(plots, grid_specs, strict=True):
+            row_slice, col_slice = grid_spec
+            gstack[row_slice, col_slice] = plot.component
+    else:
+        num_plots = len(plots)
+        num_cols = control["num_cols"]
+        # num_rows = math.ceil(num_plots / num_cols)
+        for i in range(num_plots):
+            gstack[i // num_cols, i % num_cols] = plots[i].component
+    return gstack

pfund_plot/plots/layout/tabs/__init__.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from panel import Tabs as PanelTabs
+
+import importlib
+
+from pfund_plot.plots.layout.layout import BaseLayout
+
+
+class TabsStyle:
+    from pfund_plot.plots.layout.tabs.panel import style as panel_style
+
+    panel = panel_style
+
+
+class TabsControl:
+    from pfund_plot.plots.layout.tabs.panel import control as panel_control
+
+    panel = panel_control
+
+
+class Tabs(BaseLayout):
+    style = TabsStyle
+    control = TabsControl
+
+    # tabs is not at the top level of plots, it's inside layout/tabs, so we need to override the _plot property
+    @property
+    def _plot_func(self) -> Callable[..., PanelTabs]:
+        """Runs the plot function for the current backend."""
+        module_path: str = f"pfund_plot.plots.layout.{self._class_name}.{self._backend}"
+        module = importlib.import_module(module_path)
+        return module.plot

pfund_plot/plots/layout/tabs/panel.py

@@ -0,0 +1,51 @@
+# pyright: reportUnusedParameter=false, reportArgumentType=false
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from pfund_plot.plots.lazy import LazyPlot
+    from pfund_plot.typing import RawFigure
+
+from panel import Tabs
+
+__all__ = ["control", "plot", "style"]
+
+
+def style(
+    height: int | None = None,
+    width: int | None = None,
+):
+    return locals()
+
+
+def control(
+    dynamic: bool = False,
+    closable: bool = False,
+    position: Literal["above", "below", "left", "right"] = "above",
+    linked_axes: bool = True,
+):
+    """
+    Args:
+        dynamic: Dynamically populate only the active tab.
+        closable: Whether it should be possible to close tabs.
+        position: The location of the tabs relative to the tab contents.
+        linked_axes: Whether to link axes across plots in different tabs.
+    """
+    return locals()
+
+
+def plot(
+    *plots: LazyPlot | RawFigure,
+    style: dict[str, Any],
+    control: dict[str, Any],
+    **kwargs: Any,
+) -> Tabs:
+    return Tabs(
+        *[plot.component for plot in plots],
+        height=style["height"],
+        width=style["width"],
+        dynamic=control["dynamic"],
+        closable=control["closable"],
+        tabs_location=control["position"],
+    )

pfund_plot/plots/lazy.py

@@ -0,0 +1,408 @@
+# pyright: reportUnknownMemberType=false, reportAttributeAccessIssue=false
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from narwhals.typing import IntoFrame
+    from panel.io.server import Server
+    from panel.pane import Pane
+    from panel.viewable import Viewable
+    from pfeed.feeds.market_feed import MarketFeed
+
+    from pfund_plot.enums import DisplayMode, PlottingBackend
+    from pfund_plot.plots.plot import BasePlot
+    from pfund_plot.typing import (
+        Component,
+        Figure,
+        Plot,
+        RenderedResult,
+    )
+    from pfund_plot.widgets.base import BaseWidget
+
+import panel as pn
+
+
+class LazyRow(pn.Row):
+    """A pn.Row subclass that supports + and | operators for chaining."""
+
+    def __add__(self, other: LazyPlot | Viewable) -> LazyRow:
+        right = other.component if isinstance(other, LazyPlot) else other
+        return LazyRow(*self.objects, right)
+
+    def __or__(self, other: LazyPlot | Viewable) -> LazyColumn:
+        right = other.component if isinstance(other, LazyPlot) else other
+        return LazyColumn(self, right)
+
+
+class LazyColumn(pn.Column):
+    """A pn.Column subclass that supports + and | operators for chaining."""
+
+    def __add__(self, other: LazyPlot | Viewable) -> LazyRow:
+        right = other.component if isinstance(other, LazyPlot) else other
+        return LazyRow(self, right)
+
+    def __or__(self, other: LazyPlot | Viewable) -> LazyColumn:
+        right = other.component if isinstance(other, LazyPlot) else other
+        return LazyColumn(*self.objects, right)
+
+
+class LazyPlot:
+    """Lazy plot builder that defers rendering until display.
+
+    Enables method chaining for configuring plots:
+        plt.ohlc(df).style(height=600, width=800).control(num_data=100)
+
+    Auto-renders when displayed in notebooks or at end of scripts.
+    """
+
+    def __init__(self, plot_instance: BasePlot):
+        self._plot = plot_instance
+        self._grid_spec: tuple[slice, slice] | None = None
+
+    def __getitem__(self, key: tuple[int | slice, int | slice]) -> LazyPlot:
+        """Set grid position for use with plt.layout (GridStack).
+
+        Args:
+            key: A tuple of two elements (row, col) specifying the grid position.
+                 Each element can be an int (single position) or slice (range).
+                 Examples: [1, 3], [1:2, 3:4], [1, 3:5]
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            plt.ohlc(df)[0, 0]         # single cell at row 0, col 0
+            plt.ohlc(df)[0:2, 0:6]     # spans rows 0-1, cols 0-5
+            plt.ohlc(df)[1, 0:3]       # row 1, cols 0-2
+            plt.layout(plot1[0:1, 0:2], plot2[0:1, 2:4])
+        """
+        if not isinstance(key, tuple) or len(key) != 2:
+            raise TypeError(
+                "Grid spec must be a tuple of two elements, e.g., [1, 3] or [1:2, 3:4]"
+            )
+        row_spec, col_spec = key
+        if not isinstance(row_spec, (int, slice)) or not isinstance(
+            col_spec, (int, slice)
+        ):
+            raise TypeError(
+                "Grid spec elements must be int or slice, e.g., [1, 3] or [1:2, 3:4]"
+            )
+
+        # Convert ints to slices for consistency
+        row_slice = (
+            slice(row_spec, row_spec + 1) if isinstance(row_spec, int) else row_spec
+        )
+        col_slice = (
+            slice(col_spec, col_spec + 1) if isinstance(col_spec, int) else col_spec
+        )
+
+        self._grid_spec = (row_slice, col_slice)
+        return self
+
+    @property
+    def name(self) -> str:
+        return self._plot.name
+
+    @property
+    def figure(self) -> Figure:
+        return self._plot.figure
+
+    @property
+    def plot(self) -> Plot:
+        if self._plot._plot is None:
+            self._plot._create_plot()
+        return self._plot._plot
+
+    @property
+    def is_streaming(self) -> bool:
+        return self._plot.is_streaming()
+
+    @property
+    def widgets(self) -> Any:
+        if not self._plot._widgets:
+            self._plot._create_widgets()
+        return self._plot._widgets
+
+    @property
+    def streaming_widgets(self) -> Any:
+        if self._plot.is_streaming() and not self._plot._streaming_widgets:
+            self._plot._create_widgets()
+        return self._plot._streaming_widgets
+
+    @property
+    def reactive_widgets(self) -> Any:
+        if self._plot._reactive_params and not self._plot._reactive_widgets:
+            self._plot._create_reactive_widgets()
+        return self._plot._reactive_widgets
+
+    def opts(self, *args: Any, **kwargs: Any) -> LazyPlot:
+        """Pass holoviews opts to the underlying plot.
+
+        Example:
+            candlestick.opts(multi_y=True)
+            (candlestick * volume).opts(multi_y=True)
+        """
+        self._plot._add_opts(args, kwargs)
+        return self
+
+    @property
+    def pane(self) -> Pane:
+        if self._plot._pane is None:
+            self._plot._create_pane()
+        return self._plot._pane
+
+    @property
+    def component(self) -> Component | None:
+        self._plot._create()  # create pane+widgets+component
+        return self._plot._component
+
+    @property
+    def df(self) -> IntoFrame | None:
+        if self._plot._df is None:
+            return None
+        return self._plot._df.to_native()
+
+    @property
+    def feed(self) -> MarketFeed | None:
+        return self._plot._feed
+
+    def style(self, **kwargs) -> LazyPlot:
+        """Configure style options.
+
+        Args:
+            **kwargs: Style parameters (e.g., height, width, colors, etc.)
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            plt.ohlc(df).style(height=600, width=800)
+        """
+        self._plot._set_style(kwargs)
+        return self
+
+    def get_style(self) -> dict:
+        return self._plot._style
+
+    def control(self, **kwargs) -> LazyPlot:
+        """Configure control options.
+
+        Args:
+            **kwargs: Control parameters (e.g., num_data, etc.)
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            plt.ohlc(df).control(num_data=100)
+        """
+        self._plot._set_control(kwargs)
+        return self
+
+    def get_control(self) -> dict:
+        return self._plot._control
+
+    def backend(self, backend: PlottingBackend | str) -> LazyPlot:
+        """Override backend for this plot only.
+
+        Args:
+            backend: Backend to use ('bokeh' or 'svelte')
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            plt.ohlc(df).backend('svelte').show()
+        """
+        self._plot._set_backend(backend)
+        return self
+
+    def get_backend(self) -> PlottingBackend:
+        return self._plot._backend
+
+    def mode(
+        self, mode: DisplayMode | Literal["notebook", "browser", "desktop"]
+    ) -> LazyPlot:
+        """Override display mode for this plot only.
+
+        Args:
+            mode: Display mode ('notebook', 'browser', or 'desktop')
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            plt.ohlc(df).mode('browser').show()
+        """
+        self._plot._set_mode(mode)
+        return self
+
+    def get_mode(self) -> DisplayMode:
+        return self._plot._mode
+
+    def remove_widgets(self, *WidgetClasses: type[BaseWidget]) -> LazyPlot:
+        """Remove widgets from the plot.
+
+        Args:
+            *WidgetClasses: The widget classes to remove.
+
+        Returns:
+            Self for method chaining
+        """
+        self._plot._remove_widgets(*WidgetClasses)
+        return self
+
+    def _get_existing_server(self) -> Server | None:
+        renderer = self._plot._renderer
+        server = renderer.server
+        # server is already running, return it
+        # happens when in notebook envs, somehow _repr_mimebundle_ and _repr_html_ are called multiple times automatically
+        # e.g. plt.ohlc(df).mode('browser')
+        if server is not None:
+            return server
+        return None
+
+    def show(self) -> Server | RenderedResult:
+        """Explicitly render and display the plot.
+
+        Returns:
+            The rendered plot output
+        """
+        if self._plot.is_streaming() and self._plot.is_in_notebook_mode():
+            raise RuntimeError(
+                "Cannot render streaming plot in synchronous mode, use show_async() instead."
+            )
+        if server := self._get_existing_server():
+            return server
+        return self._plot._render_sync()
+
+    async def show_async(self) -> Server | RenderedResult:
+        if server := self._get_existing_server():
+            return server
+        return await self._plot._render_async()
+
+    def servable(self, title: str | None = None) -> Component:
+        """Mark the plot as servable for use with `panel serve` CLI.
+
+        Use this when running with: panel serve myfile.py --show --autoreload
+
+        Args:
+            title: Optional title for the browser tab
+
+        Returns:
+            The servable component
+
+        Example:
+            fig = plt.ohlc(df).backend('bokeh')
+            fig.servable()
+        """
+        return self.component.servable(title=title)
+
+    def _repr_mimebundle_(self, include=None, exclude=None) -> dict[str, Any]:
+        """Auto-render in Jupyter/IPython notebooks.
+
+        This magic method is called when the object is the last expression
+        in a notebook cell, enabling auto-display without explicit render().
+        """
+        result = self.show()
+        if hasattr(result, "_repr_mimebundle_"):
+            return result._repr_mimebundle_(include, exclude)
+        return {}
+
+    def _repr_html_(self) -> str | None:
+        """Fallback HTML representation for notebooks."""
+        result = self.show()
+        if hasattr(result, "_repr_html_"):
+            return result._repr_html_()
+        return None
+
+    def __add__(self, other: LazyPlot | Viewable) -> LazyRow:
+        """Combine plots horizontally using + operator.
+
+        Args:
+            other: Another LazyPlot, Panel component, or any Panel-compatible object
+
+        Returns:
+            LazyRow containing the combined components
+
+        Example:
+            plot1 + plot2  # Side by side
+            plot1 + plot2 + plot3  # Three plots in a row
+            plot1 + some_widget  # LazyPlot with a widget
+        """
+        left = self.component
+        right = other.component if isinstance(other, LazyPlot) else other
+        return LazyRow(left, right)
+
+    def __radd__(self, other: Viewable) -> LazyRow:
+        """Support reverse addition (when left operand doesn't support +)."""
+        return LazyRow(other, self.component)
+
+    def __mul__(self, other: LazyPlot) -> LazyPlot:
+        """Overlay another plot or overlay layer onto this plot using * operator.
+
+        Returns a new LazyPlot with the overlay appended, leaving the original unchanged.
+        This allows reuse: plot * marker1 and plot * marker2 are independent.
+
+        Args:
+            other: A LazyPlot to composite onto this plot
+
+        Returns:
+            A new LazyPlot with the overlay added
+
+        Example:
+            candlestick * markers      # overlay markers on candlestick
+            candlestick * volume_bars  # overlay volume on candlestick
+        """
+        from copy import deepcopy
+
+        if not isinstance(other, LazyPlot):
+            raise TypeError(f"Cannot overlay {type(other).__name__} onto a plot.")
+
+        other_plot = other._plot
+        current_plot = self._plot
+        if other_plot.is_streaming() != current_plot.is_streaming():
+            raise RuntimeError(
+                "Cannot overlay a streaming plot with a non-streaming plot."
+            )
+        if other_plot._backend != current_plot._backend:
+            raise RuntimeError("Cannot overlay plots with different backends.")
+        if other_plot._mode != current_plot._mode:
+            raise RuntimeError("Cannot overlay plots with different modes.")
+        # NOTE: deepcopy both plots so the originals are not mutated —
+        # conceptually the result is a new plot instance that carries its own _overlays list.
+        # The overlay must also be cloned so that _parent_plot doesn't get shared
+        # when the same overlay is reused across multiple compositions.
+        try:
+            cloned_plot = deepcopy(self._plot)
+            cloned_plot._add_overlay(deepcopy(other._plot))
+        except (RuntimeError, AttributeError, TypeError) as e:
+            raise RuntimeError(
+                "Cannot overlay a plot that has already been rendered. "
+                + "Bokeh objects cannot be copied after rendering. "
+                + "Create fresh plots for the overlay instead, e.g. plt.ohlc(df) * plt.label(df, ...)"
+            ) from e
+        return LazyPlot(cloned_plot)
+
+    def __or__(self, other: LazyPlot | Viewable) -> LazyColumn:
+        """Stack plots vertically using | operator.
+
+        Args:
+            other: Another LazyPlot, Panel component, or any Panel-compatible object
+
+        Returns:
+            LazyColumn containing the stacked components
+
+        Example:
+            plot1 | plot2  # Vertically stacked
+            plot1 | plot2 | plot3  # Three plots stacked
+            plot1 | "Some text label"  # LazyPlot with text below
+        """
+        top = self.component
+        bottom = other.component if isinstance(other, LazyPlot) else other
+        return LazyColumn(top, bottom)
+
+    def __ror__(self, other: Viewable) -> LazyColumn:
+        """Support reverse or (when left operand doesn't support |)."""
+        return LazyColumn(other, self.component)

pfund_plot/plots/line/__init__.py

@@ -0,0 +1,37 @@
+# pyright: reportArgumentType=false, reportOptionalMemberAccess=false, reportOptionalSubscript=false, reportCallIssue=false, reportUnknownMemberType=false, reportUnknownVariableType=false, reportUnknownArgumentType=false
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar
+
+if TYPE_CHECKING:
+    from pfund_plot.widgets.base import BaseStreamingWidget, BaseWidget
+
+from pfund_plot.enums import PlottingBackend
+from pfund_plot.plots.plot import BasePlot
+from pfund_plot.widgets.datetime_widget import DatetimeRangeWidget
+from pfund_plot.widgets.ticker_widget import TickerSelectWidget
+
+__all__ = ["Line"]
+
+
+class LineStyle:
+    from pfund_plot.plots.line.bokeh import style as bokeh_style
+
+    bokeh = bokeh_style
+
+
+class LineControl:
+    from pfund_plot.plots.line.bokeh import control as bokeh_control
+
+    bokeh = bokeh_control
+
+
+class Line(BasePlot):
+    SUPPORTED_BACKENDS: ClassVar[list[PlottingBackend]] = [PlottingBackend.bokeh]
+    SUPPORT_STREAMING: ClassVar[bool] = True
+    SUPPORTED_WIDGETS: ClassVar[list[type[BaseWidget]]] = [DatetimeRangeWidget]
+    SUPPORTED_STREAMING_WIDGETS: ClassVar[list[type[BaseStreamingWidget]]] = [
+        TickerSelectWidget
+    ]
+    style = LineStyle
+    control = LineControl