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

backtrader/mixins/__init__.py

@@ -0,0 +1,21 @@
+#!/usr/bin/env python
+
+"""Backtrader mixins module.
+
+This module provides mixin classes that can be used to add functionality
+to other classes without using metaclasses. These mixins are part of the
+effort to remove metaprogramming from backtrader while maintaining
+backward compatibility.
+"""
+
+from .singleton import (
+    ParameterizedSingletonMixin,
+    SingletonMixin,
+    StoreBase,
+)
+
+__all__ = [
+    "SingletonMixin",
+    "ParameterizedSingletonMixin",
+    "StoreBase",
+]

backtrader/mixins/singleton.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python
+"""Singleton Mixin Module - Singleton pattern implementation.
+
+This module provides the SingletonMixin class for implementing the
+singleton pattern without using metaclasses. This is part of the
+metaprogramming removal effort in backtrader.
+
+Classes:
+    SingletonMixin: Mixin class that implements the singleton pattern.
+    ParameterizedSingletonMixin: Singleton mixin with parameter support.
+    StoreBase: Base class for store singletons.
+
+Example:
+    Creating a singleton class:
+    >>> class MyClass(SingletonMixin):
+    ...     pass
+    >>> a = MyClass()
+    >>> b = MyClass()
+    >>> assert a is b  # True - same instance
+"""
+
+import threading
+import weakref
+from typing import Any, Dict, Optional
+
+
+class SingletonMixin:
+    """Mixin class to implement singleton pattern using __new__ method.
+
+    This replaces the MetaSingleton metaclass pattern, providing the same
+    functionality without using metaclasses. Each class that inherits from
+    this mixin will maintain exactly one instance per class.
+
+    Thread-safe implementation using threading.Lock.
+
+    Features:
+    - Thread-safe singleton creation
+    - Per-class singleton instances (subclasses get their own instances)
+    - Automatic cleanup when instances are garbage collected
+    - Maintains compatibility with existing parameter systems
+    """
+
+    # Class-level storage for singleton instances
+    # Using WeakValueDictionary for automatic cleanup
+    _instances: Dict[type, Any] = weakref.WeakValueDictionary()
+    _lock = threading.Lock()
+
+    def __new__(cls, *args, **kwargs):
+        """Create or return existing singleton instance for the class."""
+
+        # Check if instance already exists (fast path, no lock)
+        if cls in cls._instances:
+            return cls._instances[cls]
+
+        # Acquire lock for thread-safe creation
+        with cls._lock:
+            # Double-check pattern: instance might have been created
+            # by another thread while waiting for lock
+            if cls in cls._instances:
+                return cls._instances[cls]
+
+            # Create new instance using object.__new__ directly
+            # This avoids recursion issues with mixin inheritance
+            instance = object.__new__(cls)
+
+            # Store instance before calling __init__ to handle potential
+            # recursive calls during initialization
+            cls._instances[cls] = instance
+
+            return instance
+
+    @classmethod
+    def _reset_instance(cls):
+        """Reset the singleton instance for this class.
+
+        This is mainly for testing purposes and should be used with caution
+        in production code.
+        """
+        with cls._lock:
+            if cls in cls._instances:
+                del cls._instances[cls]
+
+    @classmethod
+    def _get_instance(cls) -> Optional[Any]:
+        """Get the current singleton instance if it exists.
+
+        Returns:
+            The singleton instance if it exists, None otherwise.
+        """
+        return cls._instances.get(cls)
+
+    @classmethod
+    def _has_instance(cls) -> bool:
+        """Check if a singleton instance exists for this class.
+
+        Returns:
+            True if instance exists, False otherwise.
+        """
+        return cls in cls._instances
+
+
+class ParameterizedSingletonMixin(SingletonMixin):
+    """Enhanced singleton mixin that integrates with parameter systems.
+
+    This version is specifically designed to work with backtrader's
+    parameter system, maintaining compatibility with MetaParams functionality.
+    """
+
+    def __init__(self, *args, **kwargs):
+        """Initialize singleton instance only once."""
+        if getattr(self, "_singleton_initialized", False):
+            return
+
+        self._singleton_initialized = True
+
+
+# Backward compatibility alias
+StoreBase = ParameterizedSingletonMixin

backtrader/observer.py

@@ -0,0 +1,106 @@
+#!/usr/bin/env python
+"""Observer Module - Strategy monitoring and data collection.
+
+This module provides the Observer base class for monitoring strategy
+execution and collecting data during backtesting. Observers track metrics
+like cash, value, drawdown, and trade statistics.
+
+Observers are similar to indicators but are used primarily for monitoring
+and recording strategy state rather than generating trading signals.
+
+Key Classes:
+    Observer: Base class for all observers.
+
+Observers receive the same notifications as strategies:
+    - prenext/nextstart/next: Called during each bar
+    - start/stop: Called at the beginning and end of backtesting
+
+Example:
+    Creating a custom observer:
+    >>> class MyObserver(Observer):
+    ...     lines = ('custom_metric',)
+    ...
+    ...     def next(self):
+    ...         self.lines.custom_metric[0] = self.data.close[0] * 2
+"""
+
+from .lineiterator import LineIterator, ObserverBase, StrategyBase
+
+
+# Observer class - refactored to not use metaclass
+class Observer(ObserverBase):
+    """Base class for monitoring strategy execution.
+
+    Observers track and record strategy state during backtesting.
+    They can track metrics like cash, value, drawdown, positions, etc.
+
+    Attributes:
+        csv: Whether to save observer data to CSV (default: True).
+        plotinfo: Plotting configuration dictionary.
+
+    Example:
+        >>> observer = MyObserver()
+        >>> cerebro.addobserver(observer)
+    """
+
+    # Set _stclock to False
+    _stclock = False
+    # Owned instance
+    _OwnerCls = StrategyBase
+    # Line type
+    _ltype = LineIterator.ObsType
+    # Whether to save to csv and other files
+    csv = True
+    # Plot settings options
+    plotinfo = {"plot": False, "subplot": True}
+
+    def __init__(self, *args, **kwargs):
+        """
+        Initialize Observer with functionality previously in MetaObserver.dopreinit.
+
+        Note: __new__ removed - _analyzers initialization moved here.
+        """
+        # Initialize _analyzers list (moved from __new__)
+        self._analyzers = []  # keep children analyzers
+
+        # Initialize parent first
+        super().__init__(*args, **kwargs)
+
+        # Handle _stclock functionality (previously in MetaObserver.dopreinit)
+        if self._stclock:  # Change the clock if strategy wide observer
+            self._clock = self._owner
+
+    # An Observer is ideally always observing and that' why prenext calls next.
+    # The behavior can be overriden by subclasses
+    def prenext(self):
+        """Process bars before minimum period is reached.
+
+        By default, observers always process every bar by calling next()
+        even during the prenext phase. Subclasses can override this behavior.
+
+        Note:
+            This default implementation calls next() to ensure observers
+            track all bars from the beginning.
+        """
+        self.next()
+
+    # Register analyzer
+    def _register_analyzer(self, analyzer):
+        self._analyzers.append(analyzer)
+
+    def _start(self):
+        # PERFORMANCE FIX: Ensure _owner is set before calling start()
+        # This is a fallback for cases where findowner didn't find the strategy during __init__
+        if not hasattr(self, "_owner") or self._owner is None:
+            # Try to get owner from _parent (set by strategy when adding observer)
+            if hasattr(self, "_parent") and self._parent is not None:
+                self._owner = self._parent
+
+        self.start()
+
+    def start(self):
+        """Called at the start of the backtesting run.
+
+        This method can be overridden by subclasses to perform
+        initialization at the start of strategy execution.
+        """

backtrader/observers/__init__.py

@@ -0,0 +1,45 @@
+#!/usr/bin/env python
+"""Observers Module - Strategy monitoring observers.
+
+This module provides observers for monitoring and recording strategy
+execution. Observers track metrics like cash, value, drawdown, trades,
+and benchmark data during backtesting.
+
+Available Observers:
+    - Benchmark: Benchmark data (price) for comparison
+    - Broker: Cash and value tracking
+    - BuySell: Buy/sell signal visualization
+    - DrawDown: Drawdown tracking and visualization
+    - LogReturns: Log returns tracking
+    - TimeReturn: Returns by time period
+    - Trades: Trade tracking
+    - TradeLogger: Comprehensive logging (orders, trades, positions, indicators, signals)
+
+Example:
+    Adding observers to a strategy:
+    >>> cerebro.addobserver(bt.observers.DrawDown)
+    >>> cerebro.addobserver(bt.observers.Trades)
+    >>> cerebro.addobserver(bt.observers.TradeLogger, log_dir='./logs')
+"""
+
+import os as _os
+
+# The modules below should/must define __all__ with the Indicator objects
+# of prepend an "_" (underscore) to private classes/variables
+
+if _os.environ.get("BACKTRADER_LIGHT_IMPORT", "").strip().lower() in {
+    "1",
+    "true",
+    "yes",
+    "on",
+}:
+    from .trade_logger import TradeLogger as TradeLogger
+else:
+    from .benchmark import *
+    from .broker import *
+    from .buysell import *
+    from .drawdown import *
+    from .logreturns import *
+    from .timereturn import *
+    from .trade_logger import TradeLogger as TradeLogger
+    from .trades import *

backtrader/observers/benchmark.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python
+"""Benchmark Observer Module - Strategy vs benchmark comparison.
+
+This module provides the Benchmark observer for tracking strategy returns
+against a reference asset (benchmark).
+
+Classes:
+    Benchmark: Observer that compares strategy performance to a benchmark.
+
+Example:
+    >>> cerebro = bt.Cerebro()
+    >>> data = bt.feeds.GenericCSVData(dataname='benchmark.csv')
+    >>> cerebro.adddata(data)
+    >>> cerebro.addobserver(bt.observers.Benchmark, data=data)
+"""
+
+from ..analyzers.timereturn import TimeReturn as TimeReturnAnalyzer
+from .timereturn import TimeReturn
+
+
+# Benchmark
+class Benchmark(TimeReturn):
+    """This observer stores the *returns* of the strategy and the *return* of a
+    reference asset which is one of the datas passed to the system.
+
+    Params:
+
+      - ``timeframe`` (default: ``None``)
+        If ``None`` then the complete return over the entire backtested period
+        will be reported
+
+      - ``compression`` (default: ``None``)
+
+        Only used for sub-day timeframes to, for example, work on an hourly
+        timeframe by specifying "TimeFrame.Minutes" and 60 as compression
+
+      - ``data`` (default: ``None``)
+
+        Reference asset to track to allow for comparison.
+
+        :note:: this data must have been added to a ``cerebro`` instance with
+                  ``addata``, ``resampledata`` or ``replaydata``.
+
+
+      - ``_doprenext`` (default: ``False``)
+
+        Benchmarking will take place from the point at which the strategy kicks
+        in (i.e.: when the minimum period of the strategy has been met).
+
+        Setting this to ``True`` will record benchmarking values from the
+        starting point of the data feeds
+
+      - ``firstopen`` (default: ``False``)
+
+        Keepint it as ``False`` ensures that the 1st comparison point between
+        the value and the benchmark starts at 0%, because the benchmark will
+        not use its opening price.
+
+        See the ``TimeReturn`` analyzer reference for a full explanation of the
+        meaning of the parameter
+
+      - ``fund`` (default: ``None``)
+
+        If `None`, the actual mode of the broker (fundmode - True/False) will
+        be autodetected to decide if the returns are based on the total net
+        asset value or on the fund value. See ``set_fundmode`` in the broker
+        documentation
+
+        Set it to ``True`` or ``False`` for a specific behavior
+
+    Remember that at any moment of a `run` the current values can be checked
+    by looking at the *lines* by name at index ``0``.
+
+    """
+
+    _stclock = True
+
+    lines = ("benchmark",)
+    plotlines = {"benchmark": {"_name": "Benchmark"}}
+
+    params = (
+        ("data", None),
+        ("_doprenext", False),
+        # Set to False, to ensure the asset is measured at 0% in the 1st tick
+        ("firstopen", False),
+        ("fund", None),
+    )
+
+    def _plotlabel(self):
+        labels = super()._plotlabel()
+        labels.append(self.p.data._name)
+        return labels
+
+    def __init__(self):
+        """Initialize the Benchmark observer.
+
+        Sets up data reference and benchmark analyzer.
+        """
+        if self.p.data is None:  # use the 1st data in the system if none given
+            self.p.data = self.data0
+
+        super().__init__()  # treturn including data parameter
+        # Create a time return object without the data
+        kwargs = self.p._getkwargs()
+        kwargs.update(data=None)  # to create a return for the strategy
+        # Get return rate
+        t = self._owner._addanalyzer_slave(TimeReturnAnalyzer, **kwargs)
+
+        # swap for consistency
+        self.treturn, self.tbench = t, self.treturn
+
+    def next(self):
+        """Update benchmark value for the current period.
+
+        Gets the benchmark return from the analyzer.
+        """
+        super().next()
+        self.lines.benchmark[0] = self.tbench.rets.get(self.tbench.dtkey, float("NaN"))
+
+    def prenext(self):
+        """Process bars before minimum period is reached.
+
+        Handles prenext phase for time tracking.
+        """
+        if self.p._doprenext:
+            super(TimeReturn, self).prenext()

backtrader/observers/broker.py

@@ -0,0 +1,184 @@
+#!/usr/bin/env python
+"""Broker Observer Module - Cash and value tracking.
+
+This module provides observers for tracking broker cash and portfolio value.
+
+Classes:
+    Cash: Observer that tracks current cash level.
+    Value: Observer that tracks portfolio value.
+
+Example:
+    >>> cerebro = bt.Cerebro()
+    >>> cerebro.addobserver(bt.observers.Broker)
+"""
+
+from ..observer import Observer
+
+
+# Get cash
+class Cash(Observer):
+    """This observer keeps track the current amount of cash in the broker
+
+    Params: None
+    """
+
+    _stclock = True
+
+    lines = ("cash",)
+
+    plotinfo = {"plot": True, "subplot": True}
+
+    def next(self):
+        """Update the cash value for the current period.
+
+        Gets current cash amount from the broker.
+        """
+        self.lines[0][0] = self._owner.broker.getcash()
+
+
+# Get value
+class Value(Observer):
+    """This observer keeps track of the current portfolio value in the broker
+    including the cash
+
+    Params:
+
+      - ``fund`` (default: ``None``)
+
+        If `None`, the actual mode of the broker (fundmode - True/False) will
+        be autodetected to decide if the returns are based on the total net
+        asset value or on the fund value. See ``set_fundmode`` in the broker
+        documentation
+
+        Set it to ``True`` or ``False`` for a specific behavior
+
+    """
+
+    _stclock = True
+
+    params = (("fund", None),)
+
+    lines = ("value",)
+
+    plotinfo = {"plot": True, "subplot": True}
+
+    def __init__(self):
+        """Initialize the Value observer.
+
+        Sets up fund mode tracking variable.
+        """
+        self._fundmode = None
+
+    def start(self):
+        """Start the Value observer and determine fund mode.
+
+        Detects or sets fund mode for value calculation.
+        """
+        if self.p.fund is None:
+            self._fundmode = self._owner.broker.fundmode
+        else:
+            self._fundmode = self.p.fund
+
+    def next(self):
+        """Update the portfolio value for the current period.
+
+        Gets value from broker based on fund mode setting.
+        """
+        if not self._fundmode:
+            self.lines[0][0] = self._owner.broker.getvalue()
+        else:
+            self.lines[0][0] = self._owner.broker.fundvalue
+
+
+# Get both cash and value
+class Broker(Observer):
+    """This observer keeps track of the current cash amount and portfolio value in
+    the broker (including the cash)
+
+    Params: None
+    """
+
+    _stclock = True
+
+    params = (("fund", None),)
+
+    alias = ("CashValue",)
+    lines = ("cash", "value")
+
+    plotinfo = {"plot": True, "subplot": True}
+
+    def __init__(self):
+        """Initialize the Broker observer.
+
+        Sets up fund mode tracking variable.
+        """
+        self._fundmode = None
+
+    def start(self):
+        """Start the Broker observer and configure plotting.
+
+        Determines fund mode and configures plot settings.
+        """
+        if self.p.fund is None:
+            self._fundmode = self._owner.broker.fundmode
+        else:
+            self._fundmode = self.p.fund
+
+        if self._fundmode:
+            self.plotlines.cash._plotskip = True
+            self.plotlines.value._name = "FundValue"
+
+    def next(self):
+        """Update cash and value for the current period.
+
+        Gets current cash and portfolio value from the broker.
+        """
+        if not self._fundmode:
+            self.lines.value[0] = self._owner.broker.getvalue()
+            self.lines.cash[0] = self._owner.broker.getcash()
+        else:
+            self.lines.value[0] = self._owner.broker.fundvalue
+            self.lines.cash[0] = self._owner.broker.getcash()
+
+
+# fundvalue
+class FundValue(Observer):
+    """This observer keeps track of the current fund-like value
+
+    Params: None
+    """
+
+    _stclock = True
+
+    alias = ("FundShareValue", "FundVal")
+    lines = ("fundval",)
+
+    plotinfo = {"plot": True, "subplot": True}
+
+    def next(self):
+        """Update the fund value for the current period.
+
+        Gets current fund value from the broker.
+        """
+        self.lines.fundval[0] = self._owner.broker.fundvalue
+
+
+# Fund shares
+class FundShares(Observer):
+    """This observer keeps track of the current fund-like shares
+
+    Params: None
+    """
+
+    _stclock = True
+
+    lines = ("fundshares",)
+
+    plotinfo = {"plot": True, "subplot": True}
+
+    def next(self):
+        """Update the fund shares for the current period.
+
+        Gets current fund shares from the broker.
+        """
+        self.lines.fundshares[0] = self._owner.broker.fundshares