pfund-plot 0.0.1__py3-none-any.whl

pfund_plot/plots/candlestick/__init__.py

@@ -0,0 +1,77 @@
+# 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, cast
+
+if TYPE_CHECKING:
+    from pfeed.requests.market_feed_stream_request import MarketFeedStreamRequest
+    from pfund.datas.resolution import Resolution
+
+    from pfund_plot.widgets.base import BaseStreamingWidget, BaseWidget
+
+from pfund_plot.enums import PlottingBackend
+from pfund_plot.mixins.streaming_market_feed_mixin import StreamingMarketFeedMixin
+from pfund_plot.plots.plot import BasePlot
+from pfund_plot.widgets.datetime_widget import DatetimeRangeWidget
+from pfund_plot.widgets.ticker_widget import TickerSelectWidget
+
+__all__ = ["Candlestick"]
+
+
+class CandlestickStyle:
+    from pfund_plot.plots.candlestick.bokeh import style as bokeh_style
+    from pfund_plot.plots.candlestick.svelte import style as svelte_style
+
+    bokeh = bokeh_style
+    svelte = svelte_style
+
+
+class CandlestickControl:
+    from pfund_plot.plots.candlestick.bokeh import control as bokeh_control
+    from pfund_plot.plots.candlestick.svelte import control as svelte_control
+
+    bokeh = bokeh_control
+    svelte = svelte_control
+
+
+class Candlestick(StreamingMarketFeedMixin, BasePlot):
+    REQUIRED_COLS: ClassVar[list[str]] = ["date", "open", "high", "low", "close"]
+    OPTIONAL_COLS: ClassVar[list[str]] = ["volume"]
+    SUPPORTED_BACKENDS: ClassVar[list[PlottingBackend]] = [
+        PlottingBackend.bokeh,
+        PlottingBackend.svelte,
+    ]
+    SUPPORT_STREAMING: ClassVar[bool] = True
+    SUPPORTED_WIDGETS: ClassVar[list[type[BaseWidget]]] = [DatetimeRangeWidget]
+    SUPPORTED_STREAMING_WIDGETS: ClassVar[list[type[BaseStreamingWidget]]] = [
+        TickerSelectWidget
+    ]
+    style = CandlestickStyle
+    control = CandlestickControl
+
+    def _create_component(self):
+        # NOTE: somehow data update on anywidget (svelte) in marimo notebook doesn't work using Panel
+        # (probably need a refresh of the marimo cell to reflect the changes), so use mo.vstack() as a workaround
+        if self._is_using_marimo_svelte_combo():
+            import marimo as mo
+            from pfund_kit.style import RichColor, TextStyle, cprint
+
+            # NOTE: self._style (a Panel-layer concern) is NOT applied in this case,
+            # since we bypass pn.Column. total_height is the only style with a visible
+            # effect here, so warn if it was set and is being silently dropped.
+            if self._style and self._style.get("total_height") is not None:
+                cprint(
+                    "total_height is not supported in the marimo + svelte combo and will be ignored.",
+                    style=TextStyle.BOLD + RichColor.YELLOW,
+                )
+            self._component = mo.vstack([self._anywidget])
+        else:
+            super()._create_component()
+
+    def _start_streaming(self):
+        requests = cast("list[MarketFeedStreamRequest]", self._feed._requests)
+        assert all(
+            cast("Resolution", request.target_resolution).is_bar()
+            for request in requests
+        ), "candlestick streaming only supports bar data"
+        super()._start_streaming()

pfund_plot/plots/candlestick/bokeh.py

@@ -0,0 +1,124 @@
+# 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"]
+
+
+DEFAULT_HEIGHT = 280
+DEFAULT_NUM_DATA = 150
+
+
+def style(
+    title: str = "Candlestick",
+    xlabel: str = "date",
+    ylabel: str = "price",
+    pos_color: str = "green",
+    neg_color: str = "red",
+    bg_color: str = "",  # empty string by default because Panel will automatically use the theme color
+    grid: bool = True,
+    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
+        pos_color: the color of the upward candle, hex code is supported
+        neg_color: the color of the downward candle, hex code is supported
+        bg_color: the background color of the plot, hex code is supported
+        total_height: the height of the component (including the figure + widgets)
+            Default is None, when it 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
+        grid: whether to show the grid
+    """
+    return locals()
+
+
+def control(
+    num_data: int = DEFAULT_NUM_DATA,
+    max_data: int | None = None,
+    slider_step: int | None = None,
+    linked_axes: bool = True,
+    update_interval: int = 5000,  # ms
+    incremental_update: bool = True,
+    widgets: bool = True,
+    datetime_precision: Literal["d", "s", "ms"] = "s",
+):
+    """
+    Args:
+        num_data: (DatetimeRangeWidget) initial number of most recent data points to display.
+        max_data: (streaming) maximum number of data points kept in memory.
+            If None, data will continue to grow unbounded.
+        slider_step: (DatetimeRangeWidget) step size in ms for the datetime range slider.
+            If None, derived from data resolution.
+        linked_axes: whether to link axes across plots in a layout (plt.layout(...)).
+        update_interval: (streaming) interval in ms to update the plot. default is 5000 ms.
+        incremental_update: (streaming) whether to update even when the bar is incomplete. default is True.
+        widgets: whether to show widgets. default is True.
+            For granular control, use remove_widgets() to remove specific widget classes.
+        datetime_precision: the precision of datetime formatting on the hover tooltip.
+            "d" for days (%Y-%m-%d), "s" for seconds (default, %Y-%m-%d %H:%M:%S), "ms" for milliseconds (%Y-%m-%d %H:%M:%S.%3N).
+    """
+    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
+    from bokeh.models import CrosshairTool
+
+    from pfund_plot.plots.candlestick import Candlestick
+    from pfund_plot.utils.bokeh import create_bundled_hover_tool
+
+    _ = hvplot.extension(PlottingBackend.bokeh)
+
+    date_col = Candlestick.REQUIRED_COLS[0]
+    ohlc_cols = Candlestick.REQUIRED_COLS[1:]
+    # include optional cols (e.g. volume) only when present in the df
+    value_cols = ohlc_cols + [
+        col for col in Candlestick.OPTIONAL_COLS if col in df.columns
+    ]
+    return (
+        df.to_native()
+        .hvplot.ohlc(
+            date_col,
+            ohlc_cols,
+            hover_cols=[date_col, *value_cols],
+            tools=[
+                create_bundled_hover_tool(
+                    df, date_col, value_cols, control["datetime_precision"]
+                ),
+                CrosshairTool(dimensions="height", line_color="gray", line_alpha=0.3),
+            ],
+            responsive=True,
+            grid=style["grid"],
+            pos_color=style["pos_color"],
+            neg_color=style["neg_color"],
+            bgcolor=style["bg_color"],
+            **kwargs,
+        )
+        .opts(
+            title=style["title"],
+            xlabel=style["xlabel"],
+            ylabel=style["ylabel"],
+            height=style["height"],
+        )
+    )

pfund_plot/plots/candlestick/svelte.py

@@ -0,0 +1,161 @@
+# pyright: reportUnusedParameter=false
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Literal
+
+import narwhals as nw
+import traitlets
+from anywidget import AnyWidget
+
+__all__ = ["CandlestickWidget", "control", "plot", "style"]
+
+
+DEFAULT_HEIGHT = 280
+DEFAULT_WIDTH = 670
+DEFAULT_NUM_DATA = 150
+
+# Live build output in the repo, written by `pixi run js-watch`
+# (vite build --watch). Present only in a source checkout.
+_DEV_BUNDLE = (
+    Path(__file__).parents[3] / "js-tap" / "dist" / "components" / "candlestick.js"
+)
+# Packaged copy shipped inside the wheel (`pixi run js-package` copies dist ->
+# pfund_plot/js_tap/components/ before build; `dashboards/` will sit alongside).
+# parents[2] == the pfund_plot package root.
+_DIST_BUNDLE = Path(__file__).parents[2] / "js_tap" / "components" / "candlestick.js"
+
+# No PYTHON_ENV / VITE_PORT, no dev server, no port to detect: `_esm` is always a
+# built file. In a source checkout the repo build output exists, so we load that;
+# anywidget watches the file (with ANYWIDGET_HMR=1) and live-reloads on rebuild.
+# Installed from a wheel, only the packaged copy exists, so we load that.
+_ESM = _DEV_BUNDLE if _DEV_BUNDLE.exists() else _DIST_BUNDLE
+
+
+class CandlestickWidget(AnyWidget):
+    _esm = _ESM
+    # data plus the two config groups the frontend renders from: `style` (visual)
+    # and `control` (behavior). They mirror the Python-side style()/control() dicts,
+    # carrying only the keys the chart actually uses (e.g. total_height is a
+    # Panel-layer concern and stays out). All are set in __init__, so no
+    # default_value is needed.
+    data = traitlets.List().tag(sync=True)  # list of dicts with OHLC + time
+    style = traitlets.Dict().tag(sync=True)
+    control = traitlets.Dict().tag(sync=True)
+
+    def __init__(
+        self,
+        df: nw.DataFrame[Any],
+        style: dict[str, Any],
+        control: dict[str, Any],
+    ) -> None:
+        super().__init__()
+        self.style = {
+            "height": style["height"],
+            "width": style["width"],
+            "title": style["title"],
+            "xlabel": style["xlabel"],
+            "ylabel": style["ylabel"],
+            "pos_color": style["pos_color"],
+            "neg_color": style["neg_color"],
+            "bg_color": style["bg_color"],
+            "grid": style["grid"],
+        }
+        self.control = {"datetime_precision": control["datetime_precision"]}
+        self.update_data(df)
+
+    @staticmethod
+    def _format_data(df: nw.DataFrame[Any]) -> list[dict[str, Any]]:
+        """
+        Convert dataframe to format supported by lightweight-charts,
+        e.g. [ { "open": 10, "high": 10.63, "low": 9.49, "close": 9.55, "time": 1642377600 } ]
+
+        `time` is sent as a UNIX timestamp in seconds (UTCTimestamp). Stringifying
+        the datetime instead (e.g. '2025-01-01 09:00:00') is NOT a format
+        lightweight-charts parses for intraday: it collapses every bar within a day
+        onto a single point. Epoch seconds keep hourly/minute bars distinct and work
+        for daily bars too. `dt.timestamp` yields the UTC epoch (naive datetimes are
+        read as UTC wall-clock), which lightweight-charts renders back in UTC, so
+        input time == displayed time.
+        """
+        if "date" in df.columns:
+            # narwhals' dt.timestamp only goes down to milliseconds; floor to seconds.
+            df = df.with_columns(time=nw.col("date").dt.timestamp("ms") // 1_000).drop(
+                "date"
+            )
+        return df.rows(named=True)
+
+    def update_data(self, df: nw.DataFrame[Any]):
+        """Update the widget's data from a DataFrame"""
+        self.data = self._format_data(df)
+
+    def append_data(self, new_df: nw.DataFrame[Any]):
+        """Append new data points for streaming"""
+        self.data += self._format_data(new_df)
+
+
+def style(
+    title: str = "Candlestick",
+    xlabel: str = "date",
+    ylabel: str = "price",
+    pos_color: str = "#26a69a",
+    neg_color: str = "#ef5350",
+    bg_color: str = "white",
+    grid: bool = True,
+    total_height: int | None = None,
+    height: int = DEFAULT_HEIGHT,
+    width: int = DEFAULT_WIDTH,
+):
+    """
+    Args:
+        title: the title shown above the plot. Pass an empty string to hide it.
+            (lightweight-charts has no native title, so it's rendered as HTML.)
+        xlabel: the x-axis label shown below the plot. Empty string to hide.
+            (lightweight-charts has no axis titles, so it's rendered as HTML.)
+        ylabel: the y-axis label shown left of the plot. Empty string to hide.
+            (lightweight-charts has no axis titles, so it's rendered as HTML.)
+        pos_color: the color of the upward candle, hex code is supported
+        neg_color: the color of the downward candle, hex code is supported
+        bg_color: the background color of the plot, hex code is supported
+        grid: whether to show the grid
+        total_height: the height of the component (including the figure + widgets)
+        height: the height of the figure
+        width: the width of the plot
+    """
+    return locals()
+
+
+def control(
+    num_data: int = DEFAULT_NUM_DATA,
+    max_data: int | None = None,
+    slider_step: int | None = None,
+    update_interval: int = 5000,  # ms
+    incremental_update: bool = True,
+    widgets: bool = True,
+    datetime_precision: Literal["d", "s"] = "s",
+):
+    """
+    Args:
+        num_data: (DatetimeRangeWidget) initial number of most recent data points to display.
+        max_data: (streaming) maximum number of data points kept in memory.
+            If None, data will continue to grow unbounded.
+        slider_step: (DatetimeRangeWidget) step size in ms for the datetime range slider.
+            If None, derived from data resolution.
+        update_interval: (streaming) interval in ms to update the plot. default is 5000 ms.
+        incremental_update: (streaming) whether to update even when the bar is incomplete. default is True.
+        widgets: whether to show widgets. default is True.
+            For granular control, use remove_widgets() to remove specific widget classes.
+        datetime_precision: the precision of datetime shown on the time axis / crosshair.
+            "d" for days (date only), "s" for seconds (default, %H:%M:%S). Sub-second
+            ("ms") is not supported: the time field is a UTCTimestamp (second-resolution).
+    """
+    return locals()
+
+
+def plot(
+    df: nw.DataFrame[Any],
+    style: dict[str, Any],
+    control: dict[str, Any],
+    **kwargs: Any,
+) -> CandlestickWidget:
+    return CandlestickWidget(df, style, control)

pfund_plot/plots/holoviews.py

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

pfund_plot/plots/label/__init__.py

@@ -0,0 +1,43 @@
+# 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.enums import PlottingBackend
+from pfund_plot.plots.plot import BasePlot
+
+__all__ = ["Label"]
+
+
+class LabelStyle:
+    from pfund_plot.plots.label.bokeh import style as bokeh_style
+
+    bokeh = bokeh_style
+
+
+class LabelControl:
+    from pfund_plot.plots.label.bokeh import control as bokeh_control
+
+    bokeh = bokeh_control
+
+
+class Label(BasePlot):
+    SUPPORTED_BACKENDS: ClassVar[list[PlottingBackend]] = [PlottingBackend.bokeh]
+    style = LabelStyle
+    control = LabelControl
+
+    def __init__(
+        self,
+        data: IntoFrame,
+        text: str,
+        x: str | None = None,
+        y: str | list[str] | None = None,
+        name: str | None = None,
+        **reactive_params: Any,
+    ):
+        self._text = text
+        super().__init__(data=data, x=x, y=y, name=name, **reactive_params)
+        self._plot_kwargs["text"] = text

pfund_plot/plots/label/bokeh.py

@@ -0,0 +1,89 @@
+# 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"]
+
+
+DEFAULT_COLOR = "black"
+DEFAULT_FONT_SIZE = "10pt"
+DEFAULT_HEIGHT = 280
+
+
+def style(
+    title: str = "Label",
+    xlabel: str = "",
+    ylabel: str = "",
+    color: str = DEFAULT_COLOR,
+    font_size: str = DEFAULT_FONT_SIZE,
+    text_align: Literal["left", "center", "right"] = "center",
+    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: text color
+        font_size: text font size (e.g. '10pt', '12px')
+        text_align: horizontal text alignment ('left', 'center', 'right')
+        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(
+    widgets: bool = True,
+    linked_axes: bool = True,
+):
+    """
+    Args:
+        widgets: whether to show widgets. default is True.
+        linked_axes: whether to link axes across plots in a layout (plt.layout(...)).
+    """
+    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)
+
+    return (
+        df.to_native()
+        .hvplot.labels(
+            x=x,
+            y=y,
+            responsive=True,
+            **kwargs,
+        )
+        .opts(
+            title=style["title"],
+            xlabel=style["xlabel"],
+            ylabel=style["ylabel"],
+            height=style["height"],
+            text_color=style["color"],
+            text_font_size=style["font_size"],
+            text_align=style["text_align"],
+        )
+    )

pfund_plot/plots/layout/__init__.py

@@ -0,0 +1,98 @@
+from pfund_kit.style import RichColor, TextStyle, cprint
+
+from pfund_plot.enums import DisplayMode
+from pfund_plot.plots.layout.layout import BaseLayout
+from pfund_plot.plots.lazy import LazyPlot
+
+
+class LayoutStyle:
+    from pfund_plot.plots.layout.panel import style as panel_style
+
+    panel = panel_style
+
+
+class LayoutControl:
+    from pfund_plot.plots.layout.panel import control as panel_control
+
+    panel = panel_control
+
+
+class Layout(BaseLayout):
+    _MAX_COLS = 12  # maximum number of columns in a grid when using GridStack
+
+    style = LayoutStyle
+    control = LayoutControl
+
+    def __init__(self, *plots: LazyPlot):  # pyright: ignore[reportInconsistentConstructor]
+        super().__init__(*plots)
+        default_mode = DisplayMode.browser
+        self._set_mode(default_mode)
+
+    def _render(self):
+        if self._mode == DisplayMode.desktop:
+            cprint(
+                "There is a known issue in resizing when using plt.layout (GridStack) in desktop mode. Please consider switching to browser mode instead.",
+                style=TextStyle.BOLD + RichColor.YELLOW,
+            )
+        return super()._render()
+
+    def _validate_grid_specs(self):
+        # Check grid_spec consistency: either all plots have it or none do
+        grid_specs = [plot._grid_spec for plot in self._plots]
+        has_grid_spec = [grid_spec is not None for grid_spec in grid_specs]
+        all_has_grid_spec = all(has_grid_spec)
+        if any(has_grid_spec):
+            if not all_has_grid_spec:
+                raise ValueError("All plots must have grid_spec defined if any do.")
+            else:
+                # REVIEW: somehow when column index exceeds 12, GridStack doesn't work, columns must be within 0-12
+                if any(
+                    grid_spec[1].stop is not None and grid_spec[1].stop > self._MAX_COLS
+                    for grid_spec in grid_specs
+                ):
+                    raise ValueError(
+                        f"Column index exceeds maximum of {self._MAX_COLS}. Grid uses a {self._MAX_COLS}-column system."
+                    )
+        assert self._control is not None, "control is not set"
+        assert self._control["num_cols"] <= self._MAX_COLS, (
+            f"'num_cols' must be less than or equal to {self._MAX_COLS}"
+        )
+
+    def _warn_if_widgets_with_drag(self):
+        """Warn if child plots have widgets and GridStack drag is enabled.
+
+        GridStack's drag handler intercepts pointer events, which prevents
+        click-based widgets (e.g. Select dropdowns, buttons) from working.
+        Drag-based widgets (e.g. sliders) are unaffected.
+        """
+        if self._control is None or not self._control.get("allow_drag", True):
+            return
+        for lazyplot in self._plots:
+            plot = lazyplot._plot
+            has_widgets = (
+                plot._widgets or plot._streaming_widgets or plot._reactive_widgets
+            )
+            if not has_widgets:
+                for overlay in plot._overlays:
+                    has_widgets = (
+                        overlay._widgets
+                        or overlay._streaming_widgets
+                        or overlay._reactive_widgets
+                    )
+                    if has_widgets:
+                        break
+            if has_widgets:
+                cprint(
+                    "Widgets detected inside Layout with allow_drag=True. Click-based widgets (e.g. dropdowns, buttons) may not work. "
+                    + "Use plt.layout(...).control(allow_drag=False) to fix this.",
+                    style=TextStyle.BOLD + RichColor.YELLOW,
+                )
+                break
+
+    def _create_component(self):
+        self._validate_grid_specs()
+        super()._create_component()
+
+    def _create(self):
+        super()._create()
+        self._warn_if_widgets_with_drag()