back-trader-python 1.4.0__py3-none-any.whl

backtrader/bokeh/plot_adapter.py

@@ -0,0 +1,200 @@
+#!/usr/bin/env python
+"""Bokeh plotter adapter for Cerebro plotter contract."""
+
+from __future__ import annotations
+
+import bisect
+import datetime
+import sys
+
+from .. import date2num
+from ..utils.log_message import get_logger
+from .app import BOKEH_AVAILABLE, PANDAS_AVAILABLE, BacktraderBokeh
+
+try:
+    from bokeh.io import output_file, output_notebook, save
+    from bokeh.io import show as bokeh_show
+except ImportError:  # pragma: no cover - covered by feature flag above
+    output_notebook = None
+    output_file = None
+    save = None
+    bokeh_show = None
+
+logger = get_logger(__name__)
+
+_KNOWN_PLOTTER_KWARGS = {"style", "scheme", "use_default_tabs", "filter", "filename"}
+
+
+class BokehPlot:
+    """Adapter class exposing cerebro-compatible plotter contract.
+
+    It keeps `BacktraderBokeh` API unchanged and maps the existing `cerebro.plot()`
+    contract to a Plot/Plotly-compatible adapter interface:
+    ``plot -> show -> savefig``.
+    """
+
+    def __init__(self, **kwargs):
+        if not BOKEH_AVAILABLE:
+            raise ImportError("bokeh is required for backend='bokeh'; pip install bokeh")
+        if not PANDAS_AVAILABLE:
+            raise ImportError("pandas is required for backend='bokeh'; pip install pandas")
+
+        self._notebook_notified = False
+        self._iplot = True
+        self._filename = None
+        self._models = []
+        self._app_kwargs = {}
+
+        unknown_kwargs = [k for k in kwargs if k not in _KNOWN_PLOTTER_KWARGS]
+        if unknown_kwargs:
+            logger.warning(
+                "Ignoring unsupported BacktraderBokeh kwargs for adapter: %s",
+                ", ".join(sorted(unknown_kwargs)),
+            )
+
+        for key, value in kwargs.items():
+            if key == "filename":
+                self._filename = value
+            elif key in _KNOWN_PLOTTER_KWARGS:
+                self._app_kwargs[key] = value
+
+        self._app = BacktraderBokeh(**self._app_kwargs)
+
+    def plot(
+        self,
+        strategy,
+        figid=0,
+        numfigs=1,
+        iplot=True,
+        start=None,
+        end=None,
+        use=None,
+        **kwargs,
+    ):
+        """Collect a strategy figure for deferred rendering.
+
+        Args:
+            strategy: Strategy instance
+            figid: Unused in adapter, kept for compatibility.
+            numfigs: Reserved for compatibility.
+            iplot: Notebook display preference.
+            start: Start index or datetime for slicing.
+            end: End index or datetime for slicing.
+            use: Unused, matplotlib-only option kept for compatibility.
+
+        Returns:
+            Empty list, reserved for plotter contract consistency.
+        """
+        self._iplot = iplot
+
+        if use is not None:
+            logger.warning("bokeh backend ignores use parameter from cerebro.plot()")
+        if numfigs is not None and numfigs != 1:
+            logger.warning(
+                "bokeh backend uses one tab chart stack; numfigs=%s will be ignored",
+                numfigs,
+            )
+
+        if kwargs:
+            logger.warning("Unsupported plot() kwargs ignored: %s", ", ".join(sorted(kwargs)))
+
+        _ = iplot  # keep signature compatibility; actual display is deferred to show()
+
+        if strategy is None:
+            return []
+
+        start_i, end_i = self._resolve_range(strategy, start, end)
+        self._app.create_figurepage(strategy, filldata=True, start=start_i, end=end_i)
+        return []
+
+    def show(self):
+        """Build deferred models and render them.
+
+        Returns:
+            List of bokeh models.
+        """
+        # build_full_model (not build_model) so the extra tabs
+        # (Performance/Analyzer/Metadata/Config/Log/Source) are included,
+        # matching BacktraderBokeh.plot() - this is bokeh's value-add over a
+        # bare charts panel.
+        model = self._app.build_full_model()
+        if model is None:
+            return []
+
+        if self._iplot and self._should_use_notebook_output():
+            output_notebook()
+
+        if bokeh_show is not None and self._iplot:
+            bokeh_show(model)
+
+        if self._filename is not None:
+            self.savefig(model, self._filename)
+
+        self._models.append(model)
+        return [model]
+
+    def savefig(self, fig, filename, **kwargs):
+        """Save a bokeh model to disk.
+
+        Args:
+            fig: Bokeh model
+            filename: HTML file path
+            **kwargs: Unused compatibility args
+        """
+        if output_file is None or save is None:
+            raise ImportError("bokeh is required for backend='bokeh'; pip install bokeh")
+
+        output_file(filename)
+        save(fig)
+
+    def _should_use_notebook_output(self):
+        if self._notebook_notified:
+            return False
+
+        if "ipykernel" not in sys.modules:
+            return False
+
+        self._notebook_notified = True
+        return output_notebook is not None
+
+    def _resolve_range(self, strategy, start, end):
+        if strategy is None:
+            return 0, None
+
+        dtime = strategy.lines.datetime.plot()
+        total = len(dtime)
+        if total == 0:
+            return 0, 0
+
+        start_i = self._resolve_index(dtime, start, 0)
+        end_i = self._resolve_index(dtime, end, total, is_end=True)
+        return start_i, end_i
+
+    def _resolve_index(self, dtline, value, default, is_end=False):
+        if value is None:
+            return default
+
+        if isinstance(value, (datetime.date, datetime.datetime)):
+            return (
+                bisect.bisect_right(dtline, date2num(value))
+                if is_end
+                else bisect.bisect_left(dtline, date2num(value))
+            )
+
+        if isinstance(value, (int, float)):
+            value = int(value)
+            if value < 0:
+                value = len(dtline) + value
+            if is_end and value < 0:
+                value = len(dtline) + 1 + value
+            return max(0, value)
+
+        try:
+            return bisect.bisect_left(dtline, value)
+        except TypeError:
+            if is_end:
+                try:
+                    return bisect.bisect_right(dtline, value)
+                except TypeError:
+                    return default
+            return bisect.bisect_left(dtline, value)

backtrader/bokeh/schemes/__init__.py

@@ -0,0 +1,14 @@
+#!/usr/bin/env python
+"""
+Bokeh theme system.
+
+Provides multiple theme configurations:
+- Blackly: Dark theme
+- Tradimo: Light theme
+"""
+
+from .blackly import Blackly
+from .scheme import Scheme
+from .tradimo import Tradimo
+
+__all__ = ["Scheme", "Blackly", "Tradimo"]

backtrader/bokeh/schemes/blackly.py

@@ -0,0 +1,76 @@
+#!/usr/bin/env python
+"""
+Blackly dark theme.
+
+Plotting theme suitable for dark backgrounds.
+"""
+
+from .scheme import Scheme
+
+
+class Blackly(Scheme):
+    """Dark theme.
+
+    Dark background with light text, suitable for night use or dark interfaces.
+    """
+
+    def _set_params(self):
+        super()._set_params()
+
+        # ========== Candlestick color configuration ==========
+        self.barup = "#ff9896"  # Up candle color (light red)
+        self.bardown = "#98df8a"  # Down candle color (light green)
+        self.barup_wick = self.barup
+        self.bardown_wick = self.bardown
+        self.barup_outline = self.barup
+        self.bardown_outline = self.bardown
+
+        # ========== Volume color configuration ==========
+        self.volup = "#ff9896"
+        self.voldown = "#98df8a"
+
+        # ========== Background configuration ==========
+        self.background_fill = "#222222"  # Dark chart background
+        self.body_background_color = "#2B2B2B"  # Dark page background
+        self.border_fill = "#3C3F41"  # Dark border
+
+        # ========== Grid configuration ==========
+        self.grid_line_color = "#444444"
+
+        # ========== Axis configuration ==========
+        self.axis_line_color = "darkgrey"
+        self.tick_line_color = "darkgrey"
+        self.axis_text_color = "lightgrey"
+        self.axis_label_text_color = "darkgrey"
+
+        # ========== Title configuration ==========
+        self.plot_title_text_color = "darkgrey"
+
+        # ========== Legend configuration ==========
+        self.legend_background_color = "#3C3F41"
+        self.legend_text_color = "lightgrey"
+        self.legend_click = "hide"
+
+        # ========== Crosshair configuration ==========
+        self.crosshair_line_color = "#999999"
+
+        # ========== Tab configuration ==========
+        self.tab_active_background_color = "#666666"
+        self.tab_active_color = "#bbbbbb"
+
+        # ========== Table configuration ==========
+        self.table_color_even = "#404040"
+        self.table_color_odd = "#333333"
+        self.table_header_color = "#707070"
+
+        # ========== Tooltip configuration ==========
+        self.tooltip_background_color = "#4C4F51"
+        self.tooltip_text_label_color = "#848EFF"
+        self.tooltip_text_value_color = "#aaaaaa"
+
+        # ========== Code highlighting configuration ==========
+        self.tag_pre_background_color = "#222222"
+        self.tag_pre_text_color = "lightgrey"
+
+        # ========== Text configuration ==========
+        self.text_color = "lightgrey"

backtrader/bokeh/schemes/scheme.py

@@ -0,0 +1,150 @@
+#!/usr/bin/env python
+"""Bokeh theme base class.
+
+Defines all plotting-related style parameters.
+"""
+
+
+class Scheme:
+    """Bokeh plotting theme base class.
+
+    Defines all plotting-related style parameters. Subclasses can customize
+    styles by overriding the _set_params method.
+
+    Attribute categories:
+    - Color configuration: barup, bardown, volup, voldown, etc.
+    - Background configuration: background_fill, body_background_color, etc.
+    - Grid configuration: grid_line_color, etc.
+    - Text configuration: axis_text_color, etc.
+    - Crosshair: crosshair_line_color, etc.
+    - Chart configuration: plot_sizing_mode, plot_height, etc.
+    """
+
+    def __init__(self):
+        """Initialize the scheme with default parameters."""
+        self._set_params()
+
+    def _set_params(self):
+        """Set default parameters.
+
+        Subclasses should call super()._set_params() first, then override specific parameters.
+        """
+        # ========== Candlestick color configuration ==========
+        self.barup = "#26a69a"  # Up candle color
+        self.bardown = "#ef5350"  # Down candle color
+        self.barup_wick = "#26a69a"  # Up candle wick color
+        self.bardown_wick = "#ef5350"  # Down candle wick color
+        self.barup_outline = "#26a69a"  # Up candle outline color
+        self.bardown_outline = "#ef5350"  # Down candle outline color
+
+        # ========== Volume color configuration ==========
+        self.volup = "#26a69a"  # Up volume color
+        self.voldown = "#ef5350"  # Down volume color
+
+        # ========== Background configuration ==========
+        self.background_fill = "#fafafa"  # Chart background color
+        self.body_background_color = "#ffffff"  # Page background color
+        self.border_fill = "#ffffff"  # Border fill color
+
+        # ========== Grid configuration ==========
+        self.grid_line_color = "#e0e0e0"  # Grid line color
+
+        # ========== Axis configuration ==========
+        self.axis_line_color = "#666666"  # Axis line color
+        self.tick_line_color = "#666666"  # Tick line color
+        self.axis_text_color = "#666666"  # Axis text color
+        self.axis_label_text_color = "#666666"  # Axis label color
+
+        # ========== Title configuration ==========
+        self.plot_title_text_color = "#333333"  # Chart title color
+
+        # ========== Legend configuration ==========
+        self.legend_background_color = "#ffffff"  # Legend background color
+        self.legend_text_color = "#333333"  # Legend text color
+        self.legend_click = "hide"  # Legend click behavior: 'hide' or 'mute'
+
+        # ========== Crosshair configuration ==========
+        self.crosshair_line_color = "#999999"  # Crosshair line color
+
+        # ========== Tab configuration ==========
+        self.tab_active_background_color = "#e0e0e0"  # Active tab background color
+        self.tab_active_color = "#333333"  # Active tab text color
+
+        # ========== Table configuration ==========
+        self.table_color_even = "#ffffff"  # Table even row color
+        self.table_color_odd = "#f5f5f5"  # Table odd row color
+        self.table_header_color = "#e0e0e0"  # Table header color
+
+        # ========== Tooltip configuration ==========
+        self.tooltip_background_color = "#ffffff"  # Tooltip background color
+        self.tooltip_text_label_color = "#666666"  # Tooltip label color
+        self.tooltip_text_value_color = "#333333"  # Tooltip value color
+
+        # ========== Code highlight configuration ==========
+        self.tag_pre_background_color = "#f5f5f5"  # Code block background color
+        self.tag_pre_text_color = "#333333"  # Code block text color
+
+        # ========== Text configuration ==========
+        self.text_color = "#333333"  # General text color
+
+        # ========== Chart layout configuration ==========
+        self.plot_sizing_mode = "stretch_width"  # Chart sizing mode
+        self.plot_height = 400  # Default chart height
+        self.plot_height_volume = 150  # Volume chart height
+        self.plot_height_indicator = 200  # Indicator chart height
+
+        # ========== Toolbar configuration ==========
+        self.toolbar_location = "right"  # Toolbar location
+
+        # ========== Line style configuration ==========
+        self.line_width = 1.5  # Default line width
+        self.line_alpha = 1.0  # Default line alpha
+
+        # ========== Marker configuration ==========
+        self.marker_size = 8  # Marker size
+        self.marker_buy_color = "#26a69a"  # Buy marker color
+        self.marker_sell_color = "#ef5350"  # Sell marker color
+
+        # ========== Data label configuration ==========
+        self.data_label_font_size = "10pt"  # Data label font size
+
+        # ========== Date format configuration ==========
+        self.date_format = "%Y-%m-%d"  # Date format
+        self.datetime_format = "%Y-%m-%d %H:%M"  # Datetime format
+
+        # ========== Axis format configuration ==========
+        self.xaxis_formatter = None  # X-axis formatter
+        self.yaxis_formatter = None  # Y-axis formatter
+
+    def get_color(self, name, default=None):
+        """Get color configuration.
+
+        Args:
+            name: Color name
+            default: Default value
+
+        Returns:
+            Color value
+        """
+        return getattr(self, name, default)
+
+    def set_color(self, name, value):
+        """Set color configuration.
+
+        Args:
+            name: Color name
+            value: Color value
+        """
+        setattr(self, name, value)
+
+    def copy(self):
+        """Create a copy of the theme.
+
+        Returns:
+            New theme instance
+        """
+        new_scheme = self.__class__()
+        for attr in dir(self):
+            if not attr.startswith("_") and not callable(getattr(self, attr)):
+                setattr(new_scheme, attr, getattr(self, attr))
+        return new_scheme

backtrader/bokeh/schemes/tradimo.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python
+"""
+Tradimo light theme.
+
+Plotting theme suitable for light backgrounds.
+"""
+
+from .blackly import Blackly
+
+
+class Tradimo(Blackly):
+    """Light theme.
+
+    Light background with dark text, suitable for daytime use or light interfaces.
+    Inherits from Blackly to maintain consistent parameter structure.
+    """
+
+    def _set_params(self):
+        super()._set_params()
+
+        dark_text = "#333333"
+
+        # ========== Candlestick color configuration ==========
+        self.barup = "#e6550d"  # Up candle color (orange)
+        self.bardown = "#31a354"  # Down candle color (green)
+        self.barup_wick = self.barup
+        self.bardown_wick = self.bardown
+        self.barup_outline = self.barup
+        self.bardown_outline = self.bardown
+
+        # ========== Volume color configuration ==========
+        self.volup = "#ff9896"
+        self.voldown = "#98df8a"
+
+        # ========== Background configuration ==========
+        self.background_fill = "white"
+        self.body_background_color = "white"
+        self.border_fill = "white"
+
+        # ========== Grid configuration ==========
+        self.grid_line_color = "#eeeeee"
+
+        # ========== Axis configuration ==========
+        self.axis_line_color = "#222222"
+        self.tick_line_color = "#222222"
+        self.axis_text_color = dark_text
+        self.axis_label_text_color = dark_text
+
+        # ========== Title configuration ==========
+        self.plot_title_text_color = dark_text
+
+        # ========== Legend configuration ==========
+        self.legend_background_color = "#f5f5f5"
+        self.legend_text_color = dark_text
+        self.legend_click = "hide"
+
+        # ========== Crosshair configuration ==========
+        self.crosshair_line_color = "#000000"
+
+        # ========== Tab configuration ==========
+        self.tab_active_background_color = "#dddddd"
+        self.tab_active_color = "#111111"
+
+        # ========== Table configuration ==========
+        self.table_color_even = "#fefefe"
+        self.table_color_odd = "#eeeeee"
+        self.table_header_color = "#cccccc"
+
+        # ========== Tooltip configuration ==========
+        self.tooltip_background_color = "#f5f5f5"
+        self.tooltip_text_label_color = "#848EFF"
+        self.tooltip_text_value_color = "#5c5c5c"
+
+        # ========== Code highlighting configuration ==========
+        self.tag_pre_background_color = "#f5f5f5"
+        self.tag_pre_text_color = dark_text
+
+        # ========== Text configuration ==========
+        self.text_color = "#222222"
+
+        # ========== Special configuration ==========
+        self.loc = "#265371"  # Location line color

backtrader/bokeh/tab.py

@@ -0,0 +1,125 @@
+#!/usr/bin/env python
+"""
+Tab base class.
+
+Provides extensible tab architecture for creating custom tabs.
+"""
+
+from typing import Any
+
+Panel: Any = None
+BOKEH_AVAILABLE = False
+
+try:
+    # Bokeh 3.x
+    from bokeh.models import TabPanel as _Panel
+
+    Panel = _Panel
+    BOKEH_AVAILABLE = True
+except ImportError:
+    try:
+        # Bokeh 2.x
+        from bokeh.models.widgets import Panel as _Panel
+
+        Panel = _Panel
+        BOKEH_AVAILABLE = True
+    except ImportError:
+        try:
+            from bokeh.models import Panel as _Panel
+
+            Panel = _Panel
+            BOKEH_AVAILABLE = True
+        except ImportError:
+            # Bokeh not installed (optional dependency); BOKEH_AVAILABLE stays False.
+            pass
+
+
+class BokehTab:
+    """Tab base class.
+
+    Abstract base class for creating custom tabs.
+    Subclasses must implement _is_useable and _get_panel methods.
+
+    Attributes:
+        _app: BacktraderBokeh application instance
+        _figurepage: Figure page instance
+        _client: Client instance (optional, for live mode)
+        _panel: Bokeh Panel instance
+
+    Example:
+        class MyCustomTab(BokehTab):
+            def _is_useable(self):
+                return True
+
+            def _get_panel(self):
+                from bokeh.models import Div
+                div = Div(text='<h1>My Content</h1>')
+                return div, 'My Tab'
+    """
+
+    def __init__(self, app, figurepage, client=None):
+        """Initialize tab.
+
+        Args:
+            app: BacktraderBokeh application instance
+            figurepage: Figure page instance
+            client: Client instance (optional)
+        """
+        self._app = app
+        self._figurepage = figurepage
+        self._client = client
+        self._panel = None
+
+    def _is_useable(self):
+        """Check if tab is useable.
+
+        Subclasses must implement this method.
+
+        Returns:
+            bool: Whether tab is useable
+        """
+        raise NotImplementedError("_is_useable needs to be implemented.")
+
+    def _get_panel(self):
+        """Get tab content.
+
+        Subclasses must implement this method.
+
+        Returns:
+            tuple: (child_widget, title) - Child widget and title
+        """
+        raise NotImplementedError("_get_panel needs to be implemented.")
+
+    def is_useable(self):
+        """Public interface: Check if tab is useable.
+
+        Returns:
+            bool: Whether tab is useable
+        """
+        return self._is_useable()
+
+    def get_panel(self):
+        """Public interface: Get Bokeh Panel.
+
+        Returns:
+            Panel: Bokeh Panel instance
+        """
+        if not BOKEH_AVAILABLE or Panel is None:
+            return None
+        child, title = self._get_panel()
+        self._panel = Panel(child=child, title=title)
+        return self._panel
+
+    @property
+    def strategy(self):
+        """Get strategy instance."""
+        if self._figurepage is not None:
+            return getattr(self._figurepage, "strategy", None)
+        return None
+
+    @property
+    def scheme(self):
+        """Get theme instance."""
+        if self._app is not None:
+            return getattr(self._app, "scheme", None)
+        return None

backtrader/bokeh/tabs/__init__.py

@@ -0,0 +1,30 @@
+#!/usr/bin/env python
+"""
+Built-in tabs module.
+
+Provides the following built-in tabs:
+- AnalyzerTab: Analyzer results display
+- ConfigTab: Configuration info display
+- LogTab: Log display
+- MetadataTab: Metadata display
+- SourceTab: Source code display
+- LiveTab: Live configuration tab
+"""
+
+from .analyzer import AnalyzerTab
+from .config import ConfigTab
+from .live import LiveTab
+from .log import LogTab
+from .metadata import MetadataTab
+from .performance import PerformanceTab
+from .source import SourceTab
+
+__all__ = [
+    "AnalyzerTab",
+    "ConfigTab",
+    "LogTab",
+    "MetadataTab",
+    "SourceTab",
+    "LiveTab",
+    "PerformanceTab",
+]