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

backtrader/signal.py

@@ -0,0 +1,118 @@
+#!/usr/bin/env python
+"""Signal Module - Signal indicator for trading strategies.
+
+This module provides the Signal indicator which wraps a data line
+to provide trading signal values for strategy execution.
+
+Constants:
+    SIGNAL_NONE: No signal.
+    SIGNAL_LONGSHORT: Both long and short signals.
+    SIGNAL_LONG: Long entry signal.
+    SIGNAL_LONG_INV: Inverted long signal.
+    SIGNAL_LONG_ANY: Any long signal variant.
+    SIGNAL_SHORT: Short entry signal.
+    SIGNAL_SHORT_INV: Inverted short signal.
+    SIGNAL_SHORT_ANY: Any short signal variant.
+    SIGNAL_LONGEXIT: Long exit signal.
+    SIGNAL_LONGEXIT_INV: Inverted long exit signal.
+    SIGNAL_LONGEXIT_ANY: Any long exit variant.
+    SIGNAL_SHORTEXIT: Short exit signal.
+    SIGNAL_SHORTEXIT_INV: Inverted short exit signal.
+    SIGNAL_SHORTEXIT_ANY: Any short exit variant.
+
+Classes:
+    Signal: Indicator that wraps a data line as a trading signal.
+
+Example:
+    >>> class MyStrategy(bt.Strategy):
+    ...     def __init__(self):
+    ...         # Create a signal indicator from a data line
+    ...         self.signal = bt.Signal(self.data.close)
+    ...         self.sma = bt.indicators.SMA(self.data.close, period=20)
+    ...
+    ...     def next(self):
+    ...         if self.signal[0] > 0:
+    ...             self.buy()
+    ...         elif self.signal[0] < 0:
+    ...             self.sell()
+"""
+
+from .indicator import Indicator
+
+# Create different SIGNAL types
+(
+    SIGNAL_NONE,
+    SIGNAL_LONGSHORT,
+    SIGNAL_LONG,
+    SIGNAL_LONG_INV,
+    SIGNAL_LONG_ANY,
+    SIGNAL_SHORT,
+    SIGNAL_SHORT_INV,
+    SIGNAL_SHORT_ANY,
+    SIGNAL_LONGEXIT,
+    SIGNAL_LONGEXIT_INV,
+    SIGNAL_LONGEXIT_ANY,
+    SIGNAL_SHORTEXIT,
+    SIGNAL_SHORTEXIT_INV,
+    SIGNAL_SHORTEXIT_ANY,
+) = range(14)
+
+# Different signal types
+SignalTypes = [
+    SIGNAL_NONE,
+    SIGNAL_LONGSHORT,
+    SIGNAL_LONG,
+    SIGNAL_LONG_INV,
+    SIGNAL_LONG_ANY,
+    SIGNAL_SHORT,
+    SIGNAL_SHORT_INV,
+    SIGNAL_SHORT_ANY,
+    SIGNAL_LONGEXIT,
+    SIGNAL_LONGEXIT_INV,
+    SIGNAL_LONGEXIT_ANY,
+    SIGNAL_SHORTEXIT,
+    SIGNAL_SHORTEXIT_INV,
+    SIGNAL_SHORTEXIT_ANY,
+]
+
+
+# Inherit from Indicator, create a signal indicator
+class Signal(Indicator):
+    """Signal indicator for trading strategies.
+
+    The Signal class wraps a data line to provide trading signal values
+    for strategy execution. It inherits from Indicator and exposes a
+    single signal line that can be used to generate long/short signals.
+
+    Attributes:
+        SignalTypes: List of available signal type constants.
+        lines: Tuple containing the signal line name.
+
+    Example:
+        >>> class MyStrategy(bt.Strategy):
+        ...     def __init__(self):
+        ...         # Create a signal indicator from a data line
+        ...         self.signal = bt.Signal(self.data.close)
+        ...         self.sma = bt.indicators.SMA(self.data.close, period=20)
+        ...
+        ...     def next(self):
+        ...         if self.signal[0] > 0:
+        ...             self.buy()
+        ...         elif self.signal[0] < 0:
+        ...             self.sell()
+    """
+
+    # Signal type
+    SignalTypes = SignalTypes
+    # Create a signal line
+    lines = ("signal",)
+
+    # Initialize
+    def __init__(self):
+        """Initialize the Signal indicator.
+
+        Wraps the first data line from data0 as the signal line and sets
+        up plotting information to use data0's clock as the plot master.
+        """
+        self.lines.signal = self.data0.lines[0]
+        self.plotinfo.plotmaster = getattr(self.data0, "_clock", self.data0)

backtrader/signals/__init__.py

@@ -0,0 +1,17 @@
+#!/usr/bin/env python
+"""Signal Strategy Module - Trading signal based strategies.
+
+This module provides signal-based strategy implementations where trading
+decisions are driven by external signal sources rather than internal
+logic. Signals can be generated from indicators, machine learning models,
+or external data sources.
+
+Key Classes:
+    SignalStrategy: Base class for signal-based strategies.
+
+Example:
+    Creating a signal-based strategy:
+    >>> class MySignalStrategy(bt.SignalStrategy):
+    ...     def __init__(self):
+    ...         self.signal_add(bt.SIGNAL_LONG, self.data.close)
+"""

backtrader/sizer.py

@@ -0,0 +1,114 @@
+#!/usr/bin/env python
+"""Position Sizer Module - Position size calculation.
+
+This module provides the base class for position sizers, which determine
+the size of orders to place based on available cash, risk parameters,
+and other factors.
+
+Classes:
+    Sizer: Base class for position sizers.
+    FixedSize: Sizer that uses a fixed size.
+    FixedReverser: Sizer that reverses positions with fixed size.
+    PercentSizer: Sizer that uses a percentage of available cash.
+    AllInSizer: Sizer that uses all available cash.
+    RiskReturnSizer: Sizer that sizes based on risk/reward ratio.
+
+Example:
+    Creating a custom sizer:
+    >>> class MySizer(bt.Sizer):
+    ...     params = (('perc', 0.1),)
+    ...
+    ...     def _getsizing(self, comminfo, cash, data, isbuy):
+    ...         return int(cash * self.p.perc / data.close[0])
+"""
+
+from .parameters import ParameterizedBase
+
+
+# Sizer class - Refactored to use new parameter system
+class Sizer(ParameterizedBase):
+    """Base class for position sizers.
+
+    This is the base class for sizers. Any sizer should subclass this
+    and override the ``_getsizing`` method to provide custom position
+    sizing logic.
+
+    Attributes:
+        strategy: The strategy using this sizer.
+        broker: The broker instance for portfolio information.
+
+    Methods:
+        getsizing(data, isbuy): Get the position size for an order.
+        _getsizing(comminfo, cash, data, isbuy): Override to implement sizing logic.
+        set(strategy, broker): Set the strategy and broker references.
+
+    Example:
+        >>> cerebro.addsizer(bt.sizers.FixedSize, stake=100)
+    """
+
+    strategy = None
+    broker = None
+
+    def __init__(self, **kwargs):
+        """Initialize the Sizer with any provided parameters."""
+        super().__init__(**kwargs)
+
+    # Get the specific position size for order placement
+    def getsizing(self, data, isbuy):
+        """Get the position size for an order.
+
+        Args:
+            data: The target data for the order.
+            isbuy: True for buy operations, False for sell operations.
+
+        Returns:
+            int: The position size to use for the order, as determined
+                by the _getsizing method.
+        """
+        comminfo = self.broker.getcommissioninfo(data)
+        return self._getsizing(comminfo, self.broker.getcash(), data, isbuy)
+
+    def _getsizing(self, comminfo, cash, data, isbuy):
+        """This method has to be overriden by subclasses of Sizer to provide
+        the sizing functionality
+
+        Params:
+          - ``comminfo``: The CommissionInfo instance that contains
+            information about the commission for the data and allows
+            calculation of position value, operation cost, commission for the
+            operation
+
+          - ``cash``: current available cash in the *broker*
+
+          - ``data``: target of the operation
+
+          - ``isbuy``: will be ``True`` for *buy* operations and ``False``
+            for *sell* operations
+
+        The method has to return the actual size (an int) to be executed. If
+         `0` is returned, nothing will be executed.
+
+        The absolute value of the returned value will be used
+        # This method needs to be overridden when in use, takes four parameters:
+        # comminfo represents the commission instance, can be used to get commission etc.
+        # cash represents currently available cash
+        # data represents which data to trade on
+        # isbuy represents True for buy operations, False for sell operations
+
+        """
+        raise NotImplementedError
+
+    # Set strategy and broker
+    def set(self, strategy, broker):
+        """Set the strategy and broker references for this sizer.
+
+        Args:
+            strategy: The strategy instance using this sizer.
+            broker: The broker instance for portfolio information.
+        """
+        self.strategy = strategy
+        self.broker = broker
+
+
+# SizerBase class
+SizerBase = Sizer

backtrader/sizers/__init__.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python
+"""Position Sizers Module - Order size calculation strategies.
+
+This module provides position sizer implementations that determine
+the size of orders based on various strategies like fixed size,
+percentage of capital, risk/reward ratios, etc.
+
+Available Sizers:
+    - FixedSize: Always uses a fixed size for orders.
+    - FixedReverser: Reverses positions with fixed size.
+    - PercentSizer: Uses a percentage of available cash.
+    - AllInSizer: Uses all available cash for each order.
+    - RiskReturnSizer: Sizes based on risk/reward ratio.
+
+Example:
+    Using a sizer with cerebro:
+    >>> cerebro = bt.Cerebro()
+    >>> cerebro.addsizer(bt.sizers.FixedSize, stake=100)
+    >>> cerebro.addsizer(bt.sizers.PercentSizer, percents=10)
+"""
+
+# The modules below should/must define __all__ with the objects wishes
+# or prepend an "_" (underscore) to private classes/variables
+
+from .fixedsize import *
+from .percents_sizer import *

backtrader/sizers/fixedsize.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python
+"""Fixed Size Sizer Module - Fixed stake position sizing.
+
+This module provides the FixedSize sizer for using a fixed stake
+size in trading operations.
+
+Classes:
+    FixedSize: Returns a fixed stake size for orders.
+
+Example:
+    >>> cerebro.addsizer(bt.sizers.FixedSize, stake=10)
+"""
+
+from ..parameters import Int, ParameterDescriptor
+from ..sizer import Sizer
+
+
+class FixedSize(Sizer):
+    """
+    This sizer simply returns a fixed size for any operation.
+    Size can be controlled by the number of tranches that a system
+    wishes to use to scale into trades by specifying the ``tranches``
+    parameter.
+
+    This class has been refactored from legacy params tuple to the new
+    ParameterDescriptor system for Day 36-38 of the metaprogramming removal project.
+
+    Params:
+      - ``stake`` (default: ``1``)
+      - ``tranches`` (default: ``1``)
+    """
+
+    # Use new parameter descriptor system to define parameters
+    stake = ParameterDescriptor(
+        default=1, type_=int, validator=Int(min_val=1), doc="Fixed stake size for operations"
+    )
+    tranches = ParameterDescriptor(
+        default=1,
+        type_=int,
+        validator=Int(min_val=1),
+        doc="Number of tranches to divide stake into",
+    )
+
+    def __init__(self, **kwargs):
+        """Initialize the FixedSize sizer.
+
+        Args:
+            **kwargs: Keyword arguments for sizer configuration including
+                stake and tranches parameters.
+        """
+        super().__init__(**kwargs)
+
+    # Return specific stake size, if tranches > 1, will divide stake into tranches parts, otherwise return stake directly
+    def _getsizing(self, comminfo, cash, data, isbuy):
+        if self.get_param("tranches") > 1:
+            return abs(int(self.get_param("stake") / self.get_param("tranches")))
+        return self.get_param("stake")
+
+    # Set stake size
+    def setsizing(self, stake):
+        """Set the fixed stake size for operations.
+
+        Args:
+            stake (int): The stake size to set. If tranches > 1, this value
+                will be divided by tranches and stored as the internal stake.
+        """
+        if self.get_param("tranches") > 1:
+            self.set_param("stake", abs(int(stake / self.get_param("tranches"))))
+        else:
+            self.set_param("stake", stake)  # OLD METHOD FOR SAMPLE COMPATIBILITY
+
+
+# Another name for FixedSize
+SizerFix = FixedSize
+
+
+# If opening position, use stake, if reversing position, use double stake
+class FixedReverser(Sizer):
+    """This sizer returns the needes fixed size to reverse an open position or
+    the fixed size to open one
+
+      - To open a position: return the param ``stake``
+
+      - To reverse a position: return 2 * `stake`
+
+    Params:
+      - ``stake`` (default: ``1``)
+    """
+
+    stake = ParameterDescriptor(
+        default=1, type_=int, validator=Int(min_val=1), doc="Fixed stake size for operations"
+    )
+
+    def __init__(self, **kwargs):
+        """Initialize the FixedReverser sizer.
+
+        Args:
+            **kwargs: Keyword arguments for sizer configuration including
+                stake parameter.
+        """
+        super().__init__(**kwargs)
+
+    def _getsizing(self, comminfo, cash, data, isbuy):
+        position = self.strategy.getposition(data)
+        size = self.get_param("stake") * (1 + (position.size != 0))
+        return size
+
+
+# Fixed target stake size, if tranches > 1, first divide stake into tranches parts, then calculate current position and each part vs stake, choose smaller as order size
+# If tranches <= 1, directly use stake size
+class FixedSizeTarget(Sizer):
+    """
+    This sizer simply returns a fixed target size, useful when coupled
+    with Target Orders and specifically ``cerebro.target_order_size()``.
+    Size can be controlled by the number of tranches that a system
+    wishes to use to scale into trades by specifying the ``tranches``
+    parameter.
+
+    Params:
+      - ``stake`` (default: ``1``)
+      - ``tranches`` (default: ``1``)
+    """
+
+    stake = ParameterDescriptor(
+        default=1, type_=int, validator=Int(min_val=1), doc="Fixed target stake size"
+    )
+    tranches = ParameterDescriptor(
+        default=1,
+        type_=int,
+        validator=Int(min_val=1),
+        doc="Number of tranches to divide stake into",
+    )
+
+    def __init__(self, **kwargs):
+        """Initialize the FixedSizeTarget sizer.
+
+        Args:
+            **kwargs: Keyword arguments for sizer configuration including
+                stake and tranches parameters.
+        """
+        super().__init__(**kwargs)
+
+    def _getsizing(self, comminfo, cash, data, isbuy):
+        if self.get_param("tranches") > 1:
+            size = abs(int(self.get_param("stake") / self.get_param("tranches")))
+            return min((self.strategy.position.size + size), self.get_param("stake"))
+        return self.get_param("stake")
+
+    def setsizing(self, stake):
+        """Set the fixed target stake size for operations.
+
+        Args:
+            stake (int): The target stake size to set. If tranches > 1, this value
+                will be divided by tranches and adjusted based on current
+                position size to reach the target.
+        """
+        if self.get_param("tranches") > 1:
+            size = abs(int(stake / self.get_param("tranches")))
+            self.set_param("stake", min((self.strategy.position.size + size), stake))
+        else:
+            self.set_param("stake", stake)  # OLD METHOD FOR SAMPLE COMPATIBILITY

backtrader/sizers/percents_sizer.py

@@ -0,0 +1,119 @@
+#!/usr/bin/env python
+"""Percent Sizer Module - Percentage-based position sizing.
+
+This module provides sizers that calculate position size based on
+a percentage of available cash.
+
+Classes:
+    PercentSizer: Uses percentage of cash for sizing.
+    AllInSizer: Uses 100% of available cash.
+    PercentSizerInt: PercentSizer returning int values.
+    AllInSizerInt: AllInSizer returning int values.
+
+Example:
+    >>> cerebro.addsizer(bt.sizers.PercentSizer, percents=20)
+"""
+
+from ..parameters import Float, ParameterDescriptor
+from ..sizer import Sizer
+
+__all__ = ["PercentSizer", "AllInSizer", "PercentSizerInt", "AllInSizerInt"]
+
+
+class PercentSizer(Sizer):
+    """This sizer return percentages of available cash
+
+    This class has been refactored from legacy params tuple to the new
+    ParameterDescriptor system for Day 36-38 of the metaprogramming removal project.
+
+    Params:
+      - ``percents`` (default: ``20``)
+      - ``retint`` (default: ``False``) return an int size or rather the float value
+    """
+
+    # Use new parameter descriptor system to define parameters
+    percents = ParameterDescriptor(
+        default=20,
+        type_=float,
+        validator=Float(min_val=0.0, max_val=100.0),
+        doc="Percentage of available cash to use",
+    )
+    retint = ParameterDescriptor(
+        default=False, type_=bool, doc="Return an int size or rather the float value"
+    )
+
+    def __init__(self, **kwargs):
+        """Initialize the PercentSizer sizer.
+
+        Args:
+            **kwargs: Keyword arguments for sizer configuration.
+        """
+        super().__init__(**kwargs)
+
+    # If no current position, calculate orderable quantity based on cash percentage
+    # If current position exists, directly use position size as order stake
+    # If need to convert to int, then convert to int
+    def _getsizing(self, comminfo, cash, data, isbuy):
+        position = self.broker.getposition(data)
+        if not position:
+            close_price = data.close[0]
+            if not close_price or close_price != close_price:
+                return 0
+            size = cash / close_price * (self.get_param("percents") / 100)
+        else:
+            size = position.size
+
+        if self.get_param("retint"):
+            size = int(size)
+
+        return size
+
+
+# Use all available cash to place order
+class AllInSizer(PercentSizer):
+    """This sizer return all available cash of broker
+
+    Params:
+      - ``percents`` (default: ``100``)
+    """
+
+    # Redefine default value of percents parameter
+    percents = ParameterDescriptor(
+        default=100,
+        type_=float,
+        validator=Float(min_val=0.0, max_val=100.0),
+        doc="Percentage of available cash to use (100% for all-in)",
+    )
+
+
+# Calculate order stake by percentage, then round to integer
+class PercentSizerInt(PercentSizer):
+    """This sizer return percentages of available cash in the form of size truncated
+    to an int
+
+    Params:
+      - ``percents`` (default: ``20``)
+    """
+
+    # Redefine default value of retint parameter
+    retint = ParameterDescriptor(
+        default=True, type_=bool, doc="Return an int size or rather the float value (True for int)"
+    )
+
+
+# Place order based on all available cash, stake must be rounded
+class AllInSizerInt(PercentSizerInt):
+    """This sizer returns all available cash of broker with the
+    size truncated to an int
+
+     Params:
+       - ``percents`` (default: ``100``)
+    """
+
+    # Redefine default value of percents parameter
+    percents = ParameterDescriptor(
+        default=100,
+        type_=float,
+        validator=Float(min_val=0.0, max_val=100.0),
+        doc="Percentage of available cash to use (100% for all-in)",
+    )