pfund-plot 0.0.1__py3-none-any.whl

pfund_plot/plots/plotly.py

@@ -0,0 +1,32 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar, Literal
+
+if TYPE_CHECKING:
+    from plotly.graph_objects import Figure as PlotlyFigure
+
+from pfund_plot.enums import PlottingBackend
+from pfund_plot.plots.plot import BasePlot
+
+
+class Plotly(BasePlot):
+    SUPPORTED_BACKENDS: ClassVar[list[Literal[PlottingBackend.plotly]]] = [
+        PlottingBackend.plotly
+    ]
+    REQUIRED_DATA: ClassVar[bool] = False
+
+    def __init__(
+        self, fig: PlotlyFigure, sizing_mode: str | None = None, **pane_kwargs: Any
+    ):
+        """
+        Args:
+            fig: A Plotly Figure object.
+            sizing_mode: Panel sizing mode: e.g. "stretch_width", "stretch_height", or "stretch_both".
+            **pane_kwargs: Additional keyword arguments passed to pn.pane.Plotly,
+                e.g. height, width, max_width, margin.
+        """
+        super().__init__(data=None)
+        self._plot: PlotlyFigure = fig
+        self._pane_kwargs = pane_kwargs
+        if sizing_mode is not None:
+            self._pane_kwargs["sizing_mode"] = sizing_mode

pfund_plot/plots/scatter/__init__.py

@@ -0,0 +1,62 @@
+# pyright: reportArgumentType=false, reportOptionalMemberAccess=false, reportOptionalSubscript=false, reportCallIssue=false, reportUnknownMemberType=false, reportUnknownVariableType=false, reportUnknownArgumentType=false
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, ClassVar
+
+if TYPE_CHECKING:
+    from narwhals.typing import IntoFrame
+
+    from pfund_plot.widgets.base import BaseWidget
+
+from pfund_plot.enums import PlottingBackend
+from pfund_plot.plots.plot import BasePlot
+from pfund_plot.widgets.datetime_widget import DatetimeRangeWidget
+
+__all__ = ["Scatter"]
+
+
+class ScatterStyle:
+    from pfund_plot.plots.scatter.bokeh import style as bokeh_style
+
+    bokeh = bokeh_style
+
+
+class ScatterControl:
+    from pfund_plot.plots.scatter.bokeh import control as bokeh_control
+
+    bokeh = bokeh_control
+
+
+class Scatter(BasePlot):
+    """Generic scatter plot — renders points on a 2D plane.
+
+    Supports per-point styling via DataFrame columns or uniform styling via kwargs.
+    Works standalone or composed onto another plot via the * operator.
+
+    Args:
+        data: DataFrame with point positions
+        x: Column name for x-axis position
+        y: Column name for y-axis position
+
+    Example:
+        plt.scatter(df, x='x', y='y')
+        plt.ohlc(ohlc_df) * plt.scatter(df, x='date', y='price')
+    """
+
+    SUPPORTED_BACKENDS: ClassVar[list[PlottingBackend]] = [PlottingBackend.bokeh]
+    # TODO: support other streaming feeds like EngineFeed etc.
+    # SUPPORT_STREAMING: ClassVar[bool] = True
+    SUPPORTED_WIDGETS: ClassVar[list[type[BaseWidget]]] = [DatetimeRangeWidget]
+    style = ScatterStyle
+    control = ScatterControl
+
+    # TODO: add "by" parameter to group by, see https://hvplot.holoviz.org/en/docs/latest/ref/api/manual/hvplot.hvPlot.scatter.html
+    def __init__(
+        self,
+        data: IntoFrame,
+        x: str | None = None,
+        y: str | list[str] | None = None,
+        name: str | None = None,
+        **reactive_params: Any,
+    ):
+        super().__init__(data=data, x=x, y=y, name=name, **reactive_params)

pfund_plot/plots/scatter/bokeh.py

@@ -0,0 +1,158 @@
+# pyright: reportUnusedParameter=false
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from holoviews.core.overlay import Overlay
+
+import narwhals as nw
+
+from pfund_plot.enums import PlottingBackend
+
+__all__ = ["control", "plot", "style"]
+
+
+# Marker mapping from user-friendly names to Bokeh scatter types
+MARKER_MAP = {
+    "triangle_up": "triangle",
+    "triangle_down": "inverted_triangle",
+}
+
+DEFAULT_MARKER = "circle"
+DEFAULT_SIZE = 100  # hvplot takes sqrt(size), so 100 -> rendered size of 10
+DEFAULT_COLOR = "steelblue"
+DEFAULT_HEIGHT = 280
+
+
+def style(
+    title: str = "Scatter",
+    xlabel: str = "",
+    ylabel: str = "",
+    color: str = DEFAULT_COLOR,
+    marker: Literal[
+        "circle",
+        "square",
+        "triangle_up",
+        "triangle_down",
+        "diamond",
+        "cross",
+        "x",
+        "star",
+    ]
+    | str = DEFAULT_MARKER,
+    size: int | str = DEFAULT_SIZE,
+    opacity: float = 0.8,
+    grid: bool = False,
+    total_height: int | None = None,
+    height: int = DEFAULT_HEIGHT,
+    width: int | None = None,
+):
+    """
+    Args:
+        title: the title of the plot
+        xlabel: the label of the x-axis
+        ylabel: the label of the y-axis
+        color: Column name for per-point color, or a literal color string
+        marker: Column name for per-point marker, or a literal marker string.
+            Supported markers: circle, square, triangle_up, triangle_down,
+            diamond, cross, x, star
+        size: Point size. Either a fixed int (e.g. size=15) for uniform sizing,
+            or a column name (e.g. size='volume') for per-point sizing from data.
+        opacity: scatter opacity (0.0 to 1.0)
+        grid: whether to show the grid
+        total_height: the height of the component (including the figure + widgets).
+            Default is None, Panel will automatically adjust its height.
+        height: the height of the figure
+        width: the width of the plot, since the plot is responsive, this is only used in panel layout
+    """
+    return locals()
+
+
+def control(
+    num_data: int | None = None,
+    slider_step: int | None = None,
+    widgets: bool = True,
+    linked_axes: bool = True,
+    include_extra_cols: bool = False,
+):
+    """
+    Args:
+        num_data: (DatetimeRangeWidget) initial number of most recent data points to display.
+        slider_step: (DatetimeRangeWidget) step size in ms for the datetime range slider.
+            If None, derived from data resolution.
+        widgets: whether to show widgets. default is True.
+            For granular control, use remove_widgets() to remove specific widget classes.
+        linked_axes: whether to link axes across plots in a layout (plt.layout(...)).
+        include_extra_cols: whether to include extra columns in the hover tooltip.
+    """
+    return locals()
+
+
+def plot(
+    df: nw.DataFrame[Any],
+    style: dict[str, Any],
+    control: dict[str, Any],
+    x: str | None = None,
+    y: str | list[str] | None = None,
+    **kwargs: Any,
+) -> Overlay:
+    import hvplot
+
+    _ = hvplot.extension(PlottingBackend.bokeh)
+
+    color = style["color"]
+    marker = style["marker"]
+    size = style["size"]
+
+    columns = df.columns
+
+    if control["include_extra_cols"]:
+        exclude: set[str] = set()
+        if x:
+            exclude.add(x)
+        if isinstance(y, list):
+            exclude.update(y)
+        elif y:
+            exclude.add(y)
+        kwargs["hover_cols"] = [c for c in columns if c not in exclude]
+
+    color_is_col = isinstance(color, str) and color in columns
+    size_is_col = isinstance(size, str) and size in columns
+    marker_is_col = isinstance(marker, str) and marker in columns
+
+    if color_is_col:
+        kwargs["c"] = color
+    else:
+        kwargs["color"] = color
+
+    if size_is_col:
+        kwargs["s"] = size
+    else:
+        kwargs["size"] = size
+
+    if marker_is_col:
+        df = df.with_columns(
+            nw.col(marker).replace_strict(MARKER_MAP, default=nw.col(marker))
+        )
+        kwargs["marker"] = marker
+    else:
+        kwargs["marker"] = MARKER_MAP.get(marker, marker)
+
+    return (
+        df.to_native()
+        .hvplot.scatter(
+            x=x,
+            y=y,
+            responsive=True,
+            alpha=style["opacity"],
+            grid=style["grid"],
+            **kwargs,
+        )
+        .opts(
+            title=style["title"],
+            xlabel=style["xlabel"],
+            ylabel=style["ylabel"],
+            height=style["height"],
+        )
+    )

pfund_plot/plots/scatter/marker.py

@@ -0,0 +1,107 @@
+# pyright: reportArgumentType=false, reportOptionalMemberAccess=false, reportOptionalSubscript=false, reportCallIssue=false, reportUnknownMemberType=false, reportUnknownVariableType=false, reportUnknownArgumentType=false
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Literal
+
+if TYPE_CHECKING:
+    from narwhals.typing import IntoFrame
+
+    from pfund_plot.typing import Control, Plot, Style
+
+import narwhals as nw
+
+from pfund_plot.plots.scatter import Scatter
+
+__all__ = ["Marker"]
+
+
+class Marker(Scatter):
+    """Marker plot that colors points by signal direction.
+
+    Positive signal values (>= 0) get one color/marker, negative values get another.
+
+    Args:
+        data: DataFrame with marker positions
+        x: Column name for x-axis position
+        y: Column name for y-axis position (e.g. 'close' price)
+        signal: Column whose sign determines positive/negative styling.
+            If None, defaults to the y column.
+        pos_color: Color for positive values (default: 'green')
+        neg_color: Color for negative values (default: 'red')
+        pos_marker: Marker shape for positive values (default: 'triangle_up')
+        neg_marker: Marker shape for negative values (default: 'triangle_down')
+
+    Example:
+        plt.marker(df, x='date', y='pnl')
+        plt.ohlc(df) * plt.marker(df, x='date', y='close', signal='trade')
+    """
+
+    def __init__(
+        self,
+        data: IntoFrame,
+        x: str | None = None,
+        y: str | list[str] | None = None,
+        signal: str | None = None,
+        pos_color: str = "green",
+        neg_color: str = "red",
+        pos_marker: Literal[
+            "circle",
+            "square",
+            "triangle_up",
+            "triangle_down",
+            "diamond",
+            "cross",
+            "x",
+            "star",
+        ] = "triangle_up",
+        neg_marker: Literal[
+            "circle",
+            "square",
+            "triangle_up",
+            "triangle_down",
+            "diamond",
+            "cross",
+            "x",
+            "star",
+        ] = "triangle_down",
+        name: str | None = None,
+        **reactive_params: Any,
+    ):
+        self._signal = signal
+        self._pos_color = pos_color
+        self._neg_color = neg_color
+        self._pos_marker = pos_marker
+        self._neg_marker = neg_marker
+        super().__init__(data=data, x=x, y=y, name=name, **reactive_params)
+
+    @property
+    def _plot_func(self) -> Callable[[nw.DataFrame[Any], Style, Control], Plot]:
+        """Runs the plot function for the current backend."""
+        import importlib
+
+        module_path = f"pfund_plot.plots.scatter.{self._backend}"
+        module = importlib.import_module(module_path)
+        return module.plot
+
+    def _standardize_df(self, df: IntoFrame) -> nw.DataFrame[Any]:
+        df: nw.DataFrame[Any] = super()._standardize_df(df)
+        signal_col = self._signal if self._signal else self._y
+        is_positive = nw.col(signal_col) >= 0
+        df = df.with_columns(
+            nw.when(is_positive)
+            .then(nw.lit(self._pos_color))
+            .otherwise(nw.lit(self._neg_color))
+            .alias("_color"),
+            nw.when(is_positive)
+            .then(nw.lit(self._pos_marker))
+            .otherwise(nw.lit(self._neg_marker))
+            .alias("_marker"),
+        )
+        return df
+
+    def _set_style(self, style: dict[str, Any] | None = None):
+        super()._set_style(style)
+        if self._style is not None:
+            self._style["color"] = "_color"
+            self._style["marker"] = "_marker"

pfund_plot/plots/ta.py

@@ -0,0 +1,6 @@
+# TODO: add technical analysis plots using talib?
+"""
+e.g. plt.sma(df, period=10)
+first convert it to plt.ta(df, indicator='sma', period=10)
+it will use sma from talib directly, and return a plot
+"""

pfund_plot/renderers/base.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from panel.io.callbacks import PeriodicCallback
+    from panel.io.server import Server
+    from panel.io.threads import StoppableThread
+
+    from pfund_plot.enums import NotebookType
+    from pfund_plot.typing import Component, RenderedResult
+
+from abc import ABC, abstractmethod
+
+import panel as pn
+
+
+class BaseRenderer(ABC):
+    def __init__(self):
+        from pfund_kit.utils import get_notebook_type
+
+        self._periodic_callbacks: list[PeriodicCallback] = []
+        self._port: int | None = None
+        self._server: StoppableThread | Server | None = None
+        self._notebook_type: NotebookType | None = get_notebook_type()
+
+    def is_in_notebook_env(self) -> bool:
+        return self._notebook_type is not None
+
+    @property
+    def server(self) -> StoppableThread | Server | None:
+        return self._server
+
+    def add_periodic_callback(self, periodic_callback: PeriodicCallback):
+        from panel.io.callbacks import PeriodicCallback
+
+        if not isinstance(periodic_callback, PeriodicCallback):
+            raise ValueError(
+                "periodic_callback must be a panel.io.callbacks.PeriodicCallback instance"
+            )
+        self._periodic_callbacks.append(periodic_callback)
+
+    def run_periodic_callbacks(self):
+        for periodic_callback in self._periodic_callbacks:
+            periodic_callback.start()
+
+    def set_port_in_use(self, port: int):
+        self._port = port
+
+    @staticmethod
+    def _get_free_port() -> int:
+        from pfund_kit.utils import get_free_port
+
+        return get_free_port()
+
+    @abstractmethod
+    def render(self, component: Component, *args: Any, **kwargs: Any) -> RenderedResult:
+        pass
+
+    def serve(
+        self,
+        # component or factory function that returns a component
+        renderable: Component | Callable[[], Component],
+        show: bool = False,
+        threaded: bool = True,
+        port: int | None = None,
+    ) -> StoppableThread | Server:
+        from pfund_plot.config import get_config
+
+        if port is None:
+            port = self._get_free_port()
+        if self._server is not None:
+            raise ValueError("Server is already running")
+        config = get_config()
+        self.set_port_in_use(port)
+        self._server = pn.serve(  # pyright: ignore[reportUnknownMemberType]
+            renderable,  # pyright: ignore[reportArgumentType]
+            show=show,
+            threaded=threaded,
+            port=port,
+            static_dirs=config.static_dirs,
+        )
+        return self._server

pfund_plot/renderers/browser.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+if TYPE_CHECKING:
+    from panel.io.threads import StoppableThread
+
+    from pfund_plot.typing import Component
+
+from pfund_plot.renderers.base import BaseRenderer
+
+
+class BrowserRenderer(BaseRenderer):
+    def render(self, component: Component):
+        if self.is_in_notebook_env():  # run browser mode in a notebook environment
+            thread = cast(
+                "StoppableThread", self.serve(component, show=True, threaded=True)
+            )
+            self.run_periodic_callbacks()
+            return thread
+        else:  # run in a python script
+            # wrap component in a factory so periodic callbacks start inside the server's event loop
+            def _servable():
+                self.run_periodic_callbacks()
+                return component
+
+            # this will block the main thread
+            _ = self.serve(_servable, show=True, threaded=False)

pfund_plot/renderers/desktop.py

@@ -0,0 +1,109 @@
+# pyright: reportUnknownMemberType=false
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+if TYPE_CHECKING:
+    from panel.io.threads import StoppableThread
+
+    from pfund_plot.typing import Component
+
+from multiprocessing import Event as create_event
+from multiprocessing import Process
+from multiprocessing.synchronize import Event
+from threading import Thread
+
+from pfund_kit.style import RichColor, TextStyle, cprint
+
+from pfund_plot.renderers.browser import BrowserRenderer
+
+
+def _run_webview(title: str, port: int, window_ready: Event):
+    import webview as wv
+
+    _ = wv.create_window(
+        title,
+        url=f"http://localhost:{port}",
+        resizable=True,
+    )
+    window_ready.set()
+    wv.start()
+
+
+class DesktopRenderer(BrowserRenderer):
+    def render(self, component: Component):
+        port = self._get_free_port()
+        title = getattr(component, "name", "PFund Plot")
+        window_ready = create_event()
+        if self.is_in_notebook_env():
+            server = cast(
+                "StoppableThread",
+                self.serve(component, show=False, threaded=True, port=port),
+            )
+
+            def run_process():
+                try:
+                    process = Process(
+                        target=_run_webview,
+                        name=title,
+                        args=(
+                            title,
+                            port,
+                            window_ready,
+                        ),
+                        daemon=True,
+                    )
+                    process.start()
+                    process.join()
+                except Exception as e:
+                    cprint(
+                        f"An error occurred: {e}", style=TextStyle.BOLD + RichColor.RED
+                    )
+                finally:
+                    server.stop()
+
+            thread = Thread(target=run_process, daemon=True)
+            thread.start()
+            # wait for the window to be ready before starting the periodic callback to prevent data loss during streaming
+            _ = window_ready.wait()
+            self.run_periodic_callbacks()
+            return server
+        else:
+            process = Process(
+                target=_run_webview,
+                name=title,
+                args=(
+                    title,
+                    port,
+                    window_ready,
+                ),
+                daemon=True,
+            )
+            try:
+                process.start()
+            except RuntimeError as e:
+                if "freeze_support" in str(
+                    e
+                ) or "current process has finished its bootstrapping phase" in str(e):
+                    raise RuntimeError(
+                        "Failed to start desktop renderer process.\n"
+                        + "Please wrap your code with:\n\n"
+                        + "    if __name__ == '__main__':\n"
+                        + "        # your code here\n"
+                    ) from None
+                raise
+            _ = window_ready.wait()
+
+            def _servable():
+                self.run_periodic_callbacks()
+                return component
+
+            thread = Thread(
+                target=lambda: self.serve(
+                    _servable, show=False, threaded=False, port=port
+                ),
+                daemon=True,
+            )
+            thread.start()
+
+            process.join()

pfund_plot/renderers/notebook.py

@@ -0,0 +1,92 @@
+# pyright: reportUnknownMemberType=false, reportOptionalMemberAccess=false, reportCallIssue=false, reportUnusedVariable=false, reportOperatorIssue=false, reportUnknownArgumentType=false
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from pfund_plot.typing import Component
+
+try:
+    import marimo as mo
+except ImportError:
+    mo = None
+
+from pfund_plot.enums import NotebookType
+from pfund_plot.renderers.base import BaseRenderer
+
+
+class NotebookRenderer(BaseRenderer):
+    # REVIEW: if want more control of the callback thread in marimo, add it back
+    # def run_periodic_callbacks(self):
+    #     if self._notebook_type != NotebookType.marimo:
+    #         super().run_periodic_callbacks()
+    #         return
+    #     # Don't use the thread created by periodic_callback.start(),
+    #     # instead create a marimo thread to stream updates.
+    #     def stream_updates(_periodic_callback: PeriodicCallback):
+    #         thread = mo.current_thread()
+    #         time.sleep(1)  # HACK: wait some time to avoid data loss during streaming
+    #         while not thread.should_exit:
+    #             _periodic_callback.callback()
+    #             time.sleep(_periodic_callback.period / 1000)
+
+    #     for periodic_callback in self._periodic_callbacks:
+    #         stream_thread = mo.Thread(target=stream_updates, args=(periodic_callback,), daemon=True)
+    #         stream_thread.start()
+
+    def render(
+        self,
+        component: Component,
+        use_iframe: bool = False,
+        iframe_style: str | None = None,
+    ):
+        """
+        Args:
+            use_iframe: if True, use an iframe to display the plot in a notebook.
+                It is a workaround when the plot can't be displayed in a notebook.
+            iframe_style: the style of the iframe when use_iframe is True.
+        """
+        if not self.is_in_notebook_env():
+            raise ValueError("Not in a notebook environment")
+
+        if not use_iframe:
+            self.run_periodic_callbacks()
+            if self._notebook_type == NotebookType.marimo:
+                return mo.as_html(component)
+            else:
+                return component
+        else:
+            raise NotImplementedError("Iframe is not supported in notebook mode yet")
+            # if iframe_style is None:
+            #     cprint(
+            #         "No iframe_style is provided for iframe in notebook",
+            #         style=TextStyle.BOLD + RichColor.YELLOW
+            #     )
+            # port = self._get_free_port()
+            # if self._notebook_type == NotebookType.jupyter:
+            #     cprint(
+            #         f"If the plot can't be displayed, try to use 'from IPython.display import IFrame' and 'IFrame(src='http://localhost:{port}', width=..., height=...)'",
+            #         style=TextStyle.BOLD + RichColor.YELLOW
+            #     )
+            # html_pane: Pane = pn.pane.HTML(
+            #     f'''
+            #     <iframe
+            #         src="http://localhost:{port}"
+            #         style="{iframe_style}"
+            #     </iframe>
+            #     ''',
+            # )
+            # # let pane HTML inherit the height, width and sizing_mode from the figure, useful in layout_plot()
+            # html_pane.param.update(
+            #     height=component.height,
+            #     width=component.width,
+            #     sizing_mode=component.sizing_mode,
+            # )
+            # thread: StoppableThread = self.serve(component, show=False, threaded=True, port=port)
+            # self.run_periodic_callbacks()
+            # return thread
+            # FIXME: should return html_pane instead of thread?
+            # if self._notebook_type == NotebookType.marimo:
+            #     return mo.as_html(html_pane)
+            # else:
+            #     return html_pane