.github/ISSUE_TEMPLATE/1-bug.yml

@@ -0,0 +1,98 @@
+name: Bug report
+description: File a new bug report. Please use the search
+title: "Short title loaded with keywords"
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for putting in the effort to submit this bug report! Note, the
+        best bug reports are accompanied with fixing patches / pull-requests. 🙏
+
+  - type: checkboxes
+    attributes:
+      label: Contributing guidelines
+      description: |
+        Please kindly follow this project's
+        [Contributing Guidelines](https://github.com/kernc/backtesting.py/blob/master/CONTRIBUTING.md).
+        The guidelines contain short technical notes on how to best contribute to this project.
+      options:
+        - label: |
+            I agree to follow this project's
+            [Contributing Guidelines](https://github.com/kernc/backtesting.py/blob/master/CONTRIBUTING.md)
+            which, I understand, contain short technical notes on how to best contribute to this project.
+          required: true
+
+  - type: checkboxes
+    attributes:
+      label: Own due diligence
+      options:
+        - label: |
+            I verify my due dilligence—I have went through the **tutorials** and the **API docs** and
+            have used the **search** on **Issues** and GitHub **Disucussions**, as well all Google,
+            with all the relevant search keywords.
+          required: true
+
+  - type: textarea
+    id: expected
+    validations:
+      required: true
+    attributes:
+      label: Expected behavior
+      description: You run the code below and expect what to happen?
+      placeholder: When I run this code ... the program should ...
+
+  - type: textarea
+    id: code
+    validations:
+      required: false
+    attributes:
+      label: Code sample
+      description: Code snippet that clearly reproduces the issue
+      render: python
+      placeholder: |
+        from backtesting import Backtest, Strategy
+        from backtesting.test import GOOG
+
+        class Example(Strategy):
+            ...
+
+        bt = Backtest(GOOG, Example)
+        ...
+
+  - type: textarea
+    id: actual
+    validations:
+      required: true
+    attributes:
+      label: Actual behavior
+      description: What happened unexpectedly when you ran the code above?
+      placeholder: When I ran the code above ... the program did ...
+
+  - type: textarea
+    id: steps
+    validations:
+      required: false
+    attributes:
+      label: Additional info, steps to reproduce, full crash traceback, screenshots
+      description: |
+        Attach any additional info you think might be helpful and
+        result in quicker resolution of your bug.
+      placeholder: |
+        1. Do ...
+        2. ...
+        3. Boom.
+        4. See attached screenshots where I highlight the relevant parts.
+
+  - type: textarea
+    id: versions
+    validations:
+      required: false
+    attributes:
+      label: Software versions
+      description: |
+        Versions of the relevant software / packages.
+      value: |
+        <!-- From `backtesting.__version__`. If git, use commit hash -->
+        - Backtesting version: 0.?.?
+        - `bokeh.__version__`:
+        - OS:

.github/ISSUE_TEMPLATE/2-enh.yml

@@ -0,0 +1,60 @@
+name: Enhancement proposal
+description: Describe the enhancement you'd like to see
+title: "Short title loaded with keywords"
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to give feedback on this software!
+
+  - type: checkboxes
+    attributes:
+      label: Contributing guidelines
+      description: |
+        Please kindly follow this project's
+        [Contributing Guidelines](https://github.com/kernc/backtesting.py/blob/master/CONTRIBUTING.md).
+        The guidelines contain short technical notes on how to best contribute to this project.
+      options:
+        - label: |
+            I agree to follow this project's
+            [Contributing Guidelines](https://github.com/kernc/backtesting.py/blob/master/CONTRIBUTING.md)
+            which, I understand, contain short technical notes on how to best contribute to this project.
+          required: true
+
+  - type: checkboxes
+    attributes:
+      label: Own due diligence
+      options:
+        - label: |
+            I verify my due dilligence—I have went through the **tutorials** and the **API docs** and
+            have used the **search** on **Issues** and GitHub **Disucussions**, as well all Google,
+            with all the relevant search keywords.
+          required: true
+
+  - type: textarea
+    id: expected
+    validations:
+      required: true
+    attributes:
+      label: Enhancement description
+      description: What would you want to see in the software that doesn't appear to be presently included?
+      placeholder: I absolutely love your software, but I'm missing a way to ...
+
+  - type: textarea
+    id: code
+    validations:
+      required: false
+    attributes:
+      label: Code sample
+      description: Code snippet relevant to the new feature
+      render: python
+
+  - type: textarea
+    id: steps
+    validations:
+      required: false
+    attributes:
+      label: Additional info, images
+      description: |
+        Extra information you think might be helpful or interesting.

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Reference documentation
+    url: https://kernc.github.io/backtesting.py/doc/backtesting/
+    about: Please confirm you've checked here first.
+  - name: FAQ
+    url: https://github.com/kernc/backtesting.py/issues?q=label%3Aquestion%20
+    about: Frequently asked questions. Use search with potential keywords.
+  - name: Discussion forum
+    url: https://github.com/kernc/backtesting.py/discussions
+    about: Other discussions. Make sure you've seen this too.

.github/issue_template.md

@@ -1,11 +1,13 @@
 ### Expected Behavior
 
+...
 
 ### Actual Behavior
 
-<!-- In case of a bug, attach full exception traceback. Please
-     wrap verbatim code/output in Markdown fenced code blocks:
-     https://bit.ly/3nEvlHP -->
+<!-- 
+    In case of a bug, attach full exception traceback.
+    Please wrap verbatim code/output in Markdown fenced code blocks.
+-->
 
 
 ### Steps to Reproduce
@@ -25,8 +27,4 @@ python code goes here
 
 ### Additional info
 
-<!-- screenshots, code snippets, ... -->
-
-- Backtesting version: 0.?.?   <!-- From backtesting.__version__ -->
-- `bokeh.__version__`:
-- OS:
+<!-- screenshots, code snippets, versions ... -->

.gitignore

@@ -13,6 +13,7 @@ dist/*
 htmlcov/*
 
 doc/build/*
+build/*
 
 .idea/*
 .vscode/

CHANGELOG.md

@@ -5,6 +5,28 @@ These were the major changes contributing to each release:
 
 ### 0.x.x
 
+### 0.6.0
+(2025-02-04)
+
+* Enhancements:
+  * Add `Backtest(spread=)`; change `Backtest(commission=)` to apply twice per trade
+  * Show paid "Commissions [$]" key in trade stats
+  * Allow multiple names for vector indicators (#980)
+  * Add columns SL and TP to `stats['trades']` (#1039)
+  * Add entry/exit indicator values to `stats['trades']` (#1116)
+  * Optionally finalize trades at the end of backtest run (#393)
+* Bug fixes, including for some long-standing bugs:
+  * Fix bug in Sharpe ratio with non-zero risk-free rate (#904)
+  * Change price comparisons to lte/gte to align with TradingView
+  * Reduce optimization memory footprint (#884)
+  * Fix annualized stats with weekly/monthly data
+  * Fix `AssertionError` on `for o in self.orders: o.cancel()`
+  * Fix plot not shown in VSCode Jupyter
+  * Buy&Hold duration now matches trading duration
+  * Fix `bt.plot(resample=True)` with categorical indicators
+* Several other small bug fixes, deprecations and docs updates.
+
+
 ### 0.5.0
 (2025-01-21)
 

CONTRIBUTING.md

@@ -9,26 +9,40 @@ have been fixed already.
 
 To have your issue dealt with promptly, it's best to construct a
 [minimal working example] that exposes the issue in a clear and
-reproducible manner. Make sure to understand
-[how to report bugs effectively][bugs] and how to
+reproducible manner. Review [how to report bugs effectively][bugs]
+and, particularly, how to
 [craft useful bug reports][bugs2] in Python.
 
-In case of bugs, please submit full tracebacks
+In case of bugs, please submit **full** tracebacks.
 
-Wrap verbatim example code/traceback in [fenced code blocks],
-and use the preview function!
+Remember that GitHub Issues supports [markdown] syntax, so
+please **wrap verbatim example code**/traceback in
+triple-backtick-[fenced code blocks],
+such as:
+~~~markdown
+```python
+def foo():
+    ...
+```
+~~~
+and use the post preview function before posting!
 
 Many thanks from the maintainers!
 
+Note, In most cases, the issues are most readily dealt with when
+accompanied by [respective fixes/PRs].
+
 [minimal working example]: https://en.wikipedia.org/wiki/Minimal_working_example
 [bugs]: https://www.chiark.greenend.org.uk/~sgtatham/bugs.html
 [bugs2]: https://matthewrocklin.com/blog/work/2018/02/28/minimal-bug-reports
-[fenced code blocks]: https://www.markdownguide.org/extended-syntax/#fenced-code-blocks
+[markdown]: https://www.markdownguide.org/cheat-sheet/
+[fenced code blocks]: https://www.markdownguide.org/extended-syntax/#syntax-highlighting
+[respective fixes/PRs]: https://github.com/kernc/backtesting.py/blob/master/CONTRIBUTING.md#pull-requests
 
 
 Installation
 ------------
-To install a developmental version of the project,
+To install a _developmental_ version of the project,
 first [fork the project]. Then:
 
     git clone git@github.com:YOUR_USERNAME/backtesting.py
@@ -48,14 +62,14 @@ Before submitting a PR, ensure the tests pass:
 
 Also ensure that idiomatic code style is respected by running:
 
-    flake8  
+    flake8 backtesting
     mypy backtesting
 
 
 Documentation
 -------------
 See _doc/README.md_. Besides Jupyter Notebook examples, all documentation
-is generated from [pdoc]-compatible docstrings in code.
+is generated from [pdoc]-compatible markdown docstrings in code.
 
 [pdoc]: https://pdoc3.github.io/pdoc
 
@@ -67,5 +81,8 @@ A general recommended reading:
 Please use explicit commit messages. See [NumPy's development workflow]
 for inspiration.
 
+Please help review [existing PRs] you wish to see included.
+
 [code-review]: https://mtlynch.io/code-review-love/
 [NumPy's development workflow]: https://numpy.org/doc/stable/dev/development_workflow.html
+[existing PRs]: https://github.com/kernc/backtesting.py/pulls

backtesting/__init__.py

@@ -8,6 +8,9 @@
 
 ## Tutorials
 
+The tutorials encompass most framework features, so it's important
+and advisable to go through all of them. They are short.
+
 * [Library of Utilities and Composable Base Strategies](../examples/Strategies Library.html)
 * [Multiple Time Frames](../examples/Multiple Time Frames.html)
 * [**Parameter Heatmap & Optimization**](../examples/Parameter Heatmap & Optimization.html)

backtesting/_plotting.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import os
 import re
 import sys
@@ -38,13 +40,14 @@
 from bokeh.palettes import Category10
 from bokeh.transform import factor_cmap
 
-from backtesting._util import _data_period, _as_list, _Indicator
+from backtesting._util import _data_period, _as_list, _Indicator, try_
 
 with open(os.path.join(os.path.dirname(__file__), 'autoscale_cb.js'),
           encoding='utf-8') as _f:
     _AUTOSCALE_JS_CALLBACK = _f.read()
 
-IS_JUPYTER_NOTEBOOK = 'JPY_PARENT_PID' in os.environ
+IS_JUPYTER_NOTEBOOK = ('JPY_PARENT_PID' in os.environ or
+                       'inline' in os.environ.get('MPLBACKEND', ''))
 
 if IS_JUPYTER_NOTEBOOK:
     warnings.warn('Jupyter Notebook detected. '
@@ -88,7 +91,7 @@ def colorgen():
 def lightness(color, lightness=.94):
     rgb = np.array([color.r, color.g, color.b]) / 255
     h, _, s = rgb_to_hls(*rgb)
-    rgb = np.array(hls_to_rgb(h, lightness, s)) * 255.
+    rgb = (np.array(hls_to_rgb(h, lightness, s)) * 255).astype(int)
     return RGB(*rgb)
 
 
@@ -103,18 +106,18 @@ def _maybe_resample_data(resample_rule, df, indicators, equity_data, trades):
             return df, indicators, equity_data, trades
 
         freq_minutes = pd.Series({
-            "1T": 1,
-            "5T": 5,
-            "10T": 10,
-            "15T": 15,
-            "30T": 30,
-            "1H": 60,
-            "2H": 60*2,
-            "4H": 60*4,
-            "8H": 60*8,
+            "1min": 1,
+            "5min": 5,
+            "10min": 10,
+            "15min": 15,
+            "30min": 30,
+            "1h": 60,
+            "2h": 60*2,
+            "4h": 60*4,
+            "8h": 60*8,
             "1D": 60*24,
             "1W": 60*24*7,
-            "1M": np.inf,
+            "1ME": np.inf,
         })
         timespan = df.index[-1] - df.index[0]
         require_minutes = (timespan / _MAX_CANDLES).total_seconds() // 60
@@ -125,8 +128,15 @@ def _maybe_resample_data(resample_rule, df, indicators, equity_data, trades):
     from .lib import OHLCV_AGG, TRADES_AGG, _EQUITY_AGG
     df = df.resample(freq, label='right').agg(OHLCV_AGG).dropna()
 
-    indicators = [_Indicator(i.df.resample(freq, label='right').mean()
-                             .dropna().reindex(df.index).values.T,
+    def try_mean_first(indicator):
+        nonlocal freq
+        resampled = indicator.df.fillna(np.nan).resample(freq, label='right')
+        try:
+            return resampled.mean()
+        except Exception:
+            return resampled.first()
+
+    indicators = [_Indicator(try_mean_first(i).dropna().reindex(df.index).values.T,
                              **dict(i._opts, name=i.name,
                                     # Replace saved index with the resampled one
                                     index=df.index))
@@ -141,7 +151,7 @@ def _weighted_returns(s, trades=trades):
         return ((df['Size'].abs() * df['ReturnPct']) / df['Size'].abs().sum()).sum()
 
     def _group_trades(column):
-        def f(s, new_index=pd.Index(df.index.view(int)), bars=trades[column]):
+        def f(s, new_index=pd.Index(df.index.astype(int)), bars=trades[column]):
             if s.size:
                 # Via int64 because on pandas recently broken datetime
                 mean_time = int(bars.loc[s.index].astype(int).mean())
@@ -537,10 +547,23 @@ def __eq__(self, other):
             colors = value._opts['color']
             colors = colors and cycle(_as_list(colors)) or (
                 cycle([next(ohlc_colors)]) if is_overlay else colorgen())
-            legend_label = LegendStr(value.name)
-            for j, arr in enumerate(value, 1):
+
+            if isinstance(value.name, str):
+                tooltip_label = value.name
+                if len(value) == 1:
+                    legend_labels = [LegendStr(value.name)]
+                else:
+                    legend_labels = [
+                        LegendStr(f"{value.name}[{i}]")
+                        for i in range(len(value))
+                    ]
+            else:
+                tooltip_label = ", ".join(value.name)
+                legend_labels = [LegendStr(item) for item in value.name]
+
+            for j, arr in enumerate(value):
                 color = next(colors)
-                source_name = f'{legend_label}_{i}_{j}'
+                source_name = f'{legend_labels[j]}_{i}_{j}'
                 if arr.dtype == bool:
                     arr = arr.astype(int)
                 source.add(arr, source_name)
@@ -550,37 +573,37 @@ def __eq__(self, other):
                     if is_scatter:
                         fig.circle(
                             'index', source_name, source=source,
-                            legend_label=legend_label, color=color,
+                            legend_label=legend_labels[j], color=color,
                             line_color='black', fill_alpha=.8,
                             radius=BAR_WIDTH / 2 * .9)
                     else:
                         fig.line(
                             'index', source_name, source=source,
-                            legend_label=legend_label, line_color=color,
+                            legend_label=legend_labels[j], line_color=color,
                             line_width=1.3)
                 else:
                     if is_scatter:
                         r = fig.circle(
                             'index', source_name, source=source,
-                            legend_label=LegendStr(legend_label), color=color,
+                            legend_label=legend_labels[j], color=color,
                             radius=BAR_WIDTH / 2 * .6)
                     else:
                         r = fig.line(
                             'index', source_name, source=source,
-                            legend_label=LegendStr(legend_label), line_color=color,
+                            legend_label=legend_labels[j], line_color=color,
                             line_width=1.3)
                     # Add dashed centerline just because
-                    mean = float(pd.Series(arr).mean())
+                    mean = try_(lambda: float(pd.Series(arr).mean()), default=np.nan)
                     if not np.isnan(mean) and (abs(mean) < .1 or
                                                round(abs(mean), 1) == .5 or
                                                round(abs(mean), -1) in (50, 100, 200)):
                         fig.add_layout(Span(location=float(mean), dimension='width',
                                             line_color='#666666', line_dash='dashed',
                                             line_width=.5))
             if is_overlay:
-                ohlc_tooltips.append((legend_label, NBSP.join(tooltips)))
+                ohlc_tooltips.append((tooltip_label, NBSP.join(tooltips)))
             else:
-                set_tooltips(fig, [(legend_label, NBSP.join(tooltips))], vline=True, renderers=[r])
+                set_tooltips(fig, [(tooltip_label, NBSP.join(tooltips))], vline=True, renderers=[r])
                 # If the sole indicator line on this figure,
                 # have the legend only contain text without the glyph
                 if len(value) == 1:

backtesting/_stats.py

@@ -1,9 +1,11 @@
-from typing import TYPE_CHECKING, List, Union
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, List, Union, cast
 
 import numpy as np
 import pandas as pd
 
-from ._util import _data_period
+from ._util import _data_period, _indicator_warmup_nbars
 
 if TYPE_CHECKING:
     from .backtesting import Strategy, Trade
@@ -36,7 +38,7 @@ def compute_stats(
         trades: Union[List['Trade'], pd.DataFrame],
         equity: np.ndarray,
         ohlc_data: pd.DataFrame,
-        strategy_instance: 'Strategy',
+        strategy_instance: Strategy | None,
         risk_free_rate: float = 0,
 ) -> pd.Series:
     assert -1 < risk_free_rate < 1
@@ -53,6 +55,7 @@ def compute_stats(
 
     if isinstance(trades, pd.DataFrame):
         trades_df: pd.DataFrame = trades
+        commissions = None  # Not shown
     else:
         # Came straight from Backtest.run()
         trades_df = pd.DataFrame({
@@ -61,13 +64,26 @@ def compute_stats(
             'ExitBar': [t.exit_bar for t in trades],
             'EntryPrice': [t.entry_price for t in trades],
             'ExitPrice': [t.exit_price for t in trades],
+            'SL': [t.sl for t in trades],
+            'TP': [t.tp for t in trades],
             'PnL': [t.pl for t in trades],
             'ReturnPct': [t.pl_pct for t in trades],
             'EntryTime': [t.entry_time for t in trades],
             'ExitTime': [t.exit_time for t in trades],
-            'Tag': [t.tag for t in trades],
         })
         trades_df['Duration'] = trades_df['ExitTime'] - trades_df['EntryTime']
+        trades_df['Tag'] = [t.tag for t in trades]
+
+        # Add indicator values
+        if len(trades_df) and strategy_instance:
+            for ind in strategy_instance._indicators:
+                ind = np.atleast_2d(ind)
+                for i, values in enumerate(ind):  # multi-d indicators
+                    suffix = f'_{i}' if len(ind) > 1 else ''
+                    trades_df[f'Entry_{ind.name}{suffix}'] = values[trades_df['EntryBar'].values]
+                    trades_df[f'Exit_{ind.name}{suffix}'] = values[trades_df['ExitBar'].values]
+
+        commissions = sum(t._commissions for t in trades)
     del trades
 
     pl = trades_df['PnL']
@@ -92,20 +108,28 @@ def _round_timedelta(value, _period=_data_period(index)):
     s.loc['Exposure Time [%]'] = have_position.mean() * 100  # In "n bars" time, not index time
     s.loc['Equity Final [$]'] = equity[-1]
     s.loc['Equity Peak [$]'] = equity.max()
+    if commissions:
+        s.loc['Commissions [$]'] = commissions
     s.loc['Return [%]'] = (equity[-1] - equity[0]) / equity[0] * 100
+    first_trading_bar = _indicator_warmup_nbars(strategy_instance)
     c = ohlc_data.Close.values
-    s.loc['Buy & Hold Return [%]'] = (c[-1] - c[0]) / c[0] * 100  # long-only return
+    s.loc['Buy & Hold Return [%]'] = (c[-1] - c[first_trading_bar]) / c[first_trading_bar] * 100  # long-only return
 
     gmean_day_return: float = 0
     day_returns = np.array(np.nan)
     annual_trading_days = np.nan
     is_datetime_index = isinstance(index, pd.DatetimeIndex)
     if is_datetime_index:
-        day_returns = equity_df['Equity'].resample('D').last().dropna().pct_change()
+        freq_days = cast(pd.Timedelta, _data_period(index)).days
+        have_weekends = index.dayofweek.to_series().between(5, 6).mean() > 2 / 7 * .6
+        annual_trading_days = (
+            52 if freq_days == 7 else
+            12 if freq_days == 31 else
+            1 if freq_days == 365 else
+            (365 if have_weekends else 252))
+        freq = {7: 'W', 31: 'ME', 365: 'YE'}.get(freq_days, 'D')
+        day_returns = equity_df['Equity'].resample(freq).last().dropna().pct_change()
         gmean_day_return = geometric_mean(day_returns)
-        annual_trading_days = float(
-            365 if index.dayofweek.to_series().between(5, 6).mean() > 2/7 * .6 else
-            252)
 
     # Annualized return and risk metrics are computed based on the (mostly correct)
     # assumption that the returns are compounded. See: https://dx.doi.org/10.2139/ssrn.3054517
@@ -122,9 +146,10 @@ def _round_timedelta(value, _period=_data_period(index)):
 
     # Our Sharpe mismatches `empyrical.sharpe_ratio()` because they use arithmetic mean return
     # and simple standard deviation
-    s.loc['Sharpe Ratio'] = (s.loc['Return (Ann.) [%]'] - risk_free_rate) / (s.loc['Volatility (Ann.) [%]'] or np.nan)  # noqa: E501
+    s.loc['Sharpe Ratio'] = (s.loc['Return (Ann.) [%]'] - risk_free_rate * 100) / (s.loc['Volatility (Ann.) [%]'] or np.nan)  # noqa: E501
     # Our Sortino mismatches `empyrical.sortino_ratio()` because they use arithmetic mean return
-    s.loc['Sortino Ratio'] = (annualized_return - risk_free_rate) / (np.sqrt(np.mean(day_returns.clip(-np.inf, 0)**2)) * np.sqrt(annual_trading_days))  # noqa: E501
+    with np.errstate(divide='ignore'):
+        s.loc['Sortino Ratio'] = (annualized_return - risk_free_rate) / (np.sqrt(np.mean(day_returns.clip(-np.inf, 0)**2)) * np.sqrt(annual_trading_days))  # noqa: E501
     max_dd = -np.nan_to_num(dd.max())
     s.loc['Calmar Ratio'] = annualized_return / (-max_dd or np.nan)
     s.loc['Max. Drawdown [%]'] = max_dd * 100

backtesting/_util.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 import warnings
 from numbers import Number
 from typing import Dict, List, Optional, Sequence, Union, cast
@@ -40,6 +42,21 @@ def _data_period(index) -> Union[pd.Timedelta, Number]:
     return values.diff().dropna().median()
 
 
+def _strategy_indicators(strategy):
+    return {attr: indicator
+            for attr, indicator in strategy.__dict__.items()
+            if isinstance(indicator, _Indicator)}.items()
+
+
+def _indicator_warmup_nbars(strategy):
+    if strategy is None:
+        return 0
+    nbars = max((np.isnan(indicator.astype(float)).argmin(axis=-1).max()
+                 for _, indicator in _strategy_indicators(strategy)
+                 if not indicator._opts['scatter']), default=0)
+    return nbars
+
+
 class _Array(np.ndarray):
     """
     ndarray extended to supply .name and other arbitrary properties

backtesting/lib.py

@@ -11,11 +11,13 @@
 [issue tracker]: https://github.com/kernc/backtesting.py
 """
 
+from __future__ import annotations
+
 from collections import OrderedDict
 from inspect import currentframe
 from itertools import compress
 from numbers import Number
-from typing import Callable, Optional, Sequence, Union
+from typing import Callable, Generator, Optional, Sequence, Union
 
 import numpy as np
 import pandas as pd
@@ -330,7 +332,7 @@ def wrap_func(resampled, *args, **kwargs):
 
 
 def random_ohlc_data(example_data: pd.DataFrame, *,
-                     frac=1., random_state: Optional[int] = None) -> pd.DataFrame:
+                     frac=1., random_state: Optional[int] = None) -> Generator[pd.DataFrame, None, None]:
     """
     OHLC data generator. The generated OHLC data has basic
     [descriptive statistics](https://en.wikipedia.org/wiki/Descriptive_statistics)

backtesting/test/__init__.py

@@ -1,4 +1,7 @@
 """Data and utilities for testing."""
+
+from __future__ import annotations
+
 import pandas as pd
 
 

backtesting/test/__main__.py

@@ -1,8 +1,8 @@
-import sys
 import unittest
 
 suite = unittest.defaultTestLoader.discover('backtesting.test',
                                             pattern='_test*.py')
+unittest.defaultTestLoader.suiteClass = lambda _: suite
+
 if __name__ == '__main__':
-    result = unittest.TextTestRunner(verbosity=2).run(suite)
-    sys.exit(not result.wasSuccessful())
+    unittest.main(verbosity=2)

backtesting/test/_test.py

@@ -218,13 +218,44 @@ def next(self, _FEW_DAYS=pd.Timedelta('3 days')):  # noqa: N803
         bt = Backtest(GOOG, Assertive)
         with self.assertWarns(UserWarning):
             stats = bt.run()
-        self.assertEqual(stats['# Trades'], 145)
+        self.assertEqual(stats['# Trades'], 131)
 
     def test_broker_params(self):
         bt = Backtest(GOOG.iloc[:100], SmaCross,
-                      cash=1000, commission=.01, margin=.1, trade_on_close=True)
+                      cash=1000, spread=.01, margin=.1, trade_on_close=True)
         bt.run()
 
+    def test_spread_commission(self):
+        class S(Strategy):
+            def init(self):
+                self.done = False
+
+            def next(self):
+                if not self.position:
+                    self.buy()
+                else:
+                    self.position.close()
+                    self.next = lambda: None  # Done
+
+        SPREAD = .01
+        COMMISSION = .01
+        CASH = 10_000
+        ORDER_BAR = 2
+        stats = Backtest(SHORT_DATA, S, cash=CASH, spread=SPREAD, commission=COMMISSION).run()
+        trade_open_price = SHORT_DATA['Open'].iloc[ORDER_BAR]
+        self.assertEqual(stats['_trades']['EntryPrice'].iloc[0], trade_open_price * (1 + SPREAD))
+        self.assertEqual(stats['_equity_curve']['Equity'].iloc[2:4].round(2).tolist(),
+                         [9685.31, 9749.33])
+
+        stats = Backtest(SHORT_DATA, S, cash=CASH, commission=(100, COMMISSION)).run()
+        self.assertEqual(stats['_equity_curve']['Equity'].iloc[2:4].round(2).tolist(),
+                         [9784.50, 9718.69])
+
+        commission_func = lambda size, price: size * price * COMMISSION  # noqa: E731
+        stats = Backtest(SHORT_DATA, S, cash=CASH, commission=commission_func).run()
+        self.assertEqual(stats['_equity_curve']['Equity'].iloc[2:4].round(2).tolist(),
+                         [9781.28, 9846.04])
+
     def test_dont_overwrite_data(self):
         df = EURUSD.copy()
         bt = Backtest(df, SmaCross)
@@ -251,7 +282,7 @@ def test_compute_drawdown(self):
         np.testing.assert_array_equal(peaks, pd.Series([7, 4], index=[3, 5]).reindex(dd.index))
 
     def test_compute_stats(self):
-        stats = Backtest(GOOG, SmaCross).run()
+        stats = Backtest(GOOG, SmaCross, finalize_trades=True).run()
         expected = pd.Series({
                 # NOTE: These values are also used on the website!
                 '# Trades': 66,
@@ -260,7 +291,7 @@ def test_compute_stats(self):
                 'Avg. Trade Duration': pd.Timedelta('46 days 00:00:00'),
                 'Avg. Trade [%]': 2.531715975158555,
                 'Best Trade [%]': 53.59595229490424,
-                'Buy & Hold Return [%]': 703.4582419772772,
+                'Buy & Hold Return [%]': 522.0601851851852,
                 'Calmar Ratio': 0.4414380935608377,
                 'Duration': pd.Timedelta('3116 days 00:00:00'),
                 'End': pd.Timestamp('2013-03-01 00:00:00'),
@@ -302,10 +333,15 @@ def almost_equal(a, b):
 
         self.assertEqual(len(stats['_trades']), 66)
 
+        indicator_columns = [
+            f'{entry}_SMA(C,{n})'
+            for entry in ('Entry', 'Exit')
+            for n in (SmaCross.fast, SmaCross.slow)]
         self.assertSequenceEqual(
             sorted(stats['_trades'].columns),
-            sorted(['Size', 'EntryBar', 'ExitBar', 'EntryPrice', 'ExitPrice',
-                    'PnL', 'ReturnPct', 'EntryTime', 'ExitTime', 'Duration', 'Tag']))
+            sorted(['Size', 'EntryBar', 'ExitBar', 'EntryPrice', 'ExitPrice', 'SL', 'TP',
+                    'PnL', 'ReturnPct', 'EntryTime', 'ExitTime', 'Duration', 'Tag',
+                    *indicator_columns]))
 
     def test_compute_stats_bordercase(self):
 
@@ -389,7 +425,7 @@ def next(self):
                 if self.position and crossover(self.sma2, self.sma1):
                     self.position.close(portion=.5)
 
-        bt = Backtest(GOOG, SmaCross, commission=.002)
+        bt = Backtest(GOOG, SmaCross, spread=.002)
         bt.run()
 
     def test_close_orders_from_last_strategy_iteration(self):
@@ -402,7 +438,8 @@ def next(self):
                 elif len(self.data) == len(SHORT_DATA):
                     self.position.close()
 
-        self.assertFalse(Backtest(SHORT_DATA, S).run()._trades.empty)
+        self.assertTrue(Backtest(SHORT_DATA, S, finalize_trades=False).run()._trades.empty)
+        self.assertFalse(Backtest(SHORT_DATA, S, finalize_trades=True).run()._trades.empty)
 
     def test_check_adjusted_price_when_placing_order(self):
         class S(Strategy):
@@ -411,7 +448,7 @@ def init(self): pass
             def next(self):
                 self.buy(tp=self.data.Close * 1.01)
 
-        self.assertRaises(ValueError, Backtest(SHORT_DATA, S, commission=.02).run)
+        self.assertRaises(ValueError, Backtest(SHORT_DATA, S, spread=.02).run)
 
 
 class TestStrategy(TestCase):
@@ -504,7 +541,7 @@ def test_autoclose_trades_on_finish(self):
         def coroutine(self):
             yield self.buy()
 
-        stats = self._Backtest(coroutine).run()
+        stats = self._Backtest(coroutine, finalize_trades=True).run()
         self.assertEqual(len(stats._trades), 1)
 
     def test_order_tag(self):
@@ -551,7 +588,7 @@ def test_optimize(self):
             bt.plot(filename=f, open_browser=False)
 
     def test_method_sambo(self):
-        bt = Backtest(GOOG.iloc[:100], SmaCross)
+        bt = Backtest(GOOG.iloc[:100], SmaCross, finalize_trades=True)
         res, heatmap, sambo_results = bt.optimize(
             fast=range(2, 20), slow=np.arange(2, 20, dtype=object),
             constraint=lambda p: p.fast < p.slow,
@@ -730,7 +767,12 @@ def next(self):
             time.sleep(1)
 
     def test_resample(self):
-        bt = Backtest(GOOG, SmaCross)
+        class S(SmaCross):
+            def init(self):
+                self.I(lambda: ['x'] * len(self.data))  # categorical indicator, GH-309
+                super().init()
+
+        bt = Backtest(GOOG, S)
         bt.run()
         import backtesting._plotting
         with _tempfile() as f, \
@@ -740,6 +782,37 @@ def test_resample(self):
             # Give browser time to open before tempfile is removed
             time.sleep(1)
 
+    def test_indicator_name(self):
+        test_self = self
+
+        class S(Strategy):
+            def init(self):
+                def _SMA():
+                    return SMA(self.data.Close, 5), SMA(self.data.Close, 10)
+
+                test_self.assertRaises(TypeError, self.I, _SMA, name=42)
+                test_self.assertRaises(ValueError, self.I, _SMA, name=("SMA One", ))
+                test_self.assertRaises(
+                    ValueError, self.I, _SMA, name=("SMA One", "SMA Two", "SMA Three"))
+
+                for overlay in (True, False):
+                    self.I(SMA, self.data.Close, 5, overlay=overlay)
+                    self.I(SMA, self.data.Close, 5, name="My SMA", overlay=overlay)
+                    self.I(SMA, self.data.Close, 5, name=("My SMA", ), overlay=overlay)
+                    self.I(_SMA, overlay=overlay)
+                    self.I(_SMA, name="My SMA", overlay=overlay)
+                    self.I(_SMA, name=("SMA One", "SMA Two"), overlay=overlay)
+
+            def next(self):
+                pass
+
+        bt = Backtest(GOOG, S)
+        bt.run()
+        with _tempfile() as f:
+            bt.plot(filename=f,
+                    plot_drawdown=False, plot_equity=False, plot_pl=False, plot_volume=False,
+                    open_browser=False)
+
     def test_indicator_color(self):
         class S(Strategy):
             def init(self):
@@ -858,7 +931,7 @@ def init(self):
                                 self.data.Close < sma)
 
         stats = Backtest(GOOG, S).run()
-        self.assertIn(stats['# Trades'], (1181, 1182))  # varies on different archs?
+        self.assertIn(stats['# Trades'], (1179, 1180))  # varies on different archs?
 
     def test_TrailingStrategy(self):
         class S(TrailingStrategy):
@@ -874,7 +947,7 @@ def next(self):
                     self.buy()
 
         stats = Backtest(GOOG, S).run()
-        self.assertEqual(stats['# Trades'], 57)
+        self.assertEqual(stats['# Trades'], 56)
 
 
 class TestUtil(TestCase):
@@ -967,6 +1040,24 @@ def next(self):
             bt = Backtest(df, S, cash=100, trade_on_close=True)
         self.assertEqual(bt.run()._trades['ExitPrice'][0], 50)
 
+    def test_stats_annualized(self):
+        stats = Backtest(GOOG.resample('W').agg(OHLCV_AGG), SmaCross).run()
+        self.assertFalse(np.isnan(stats['Return (Ann.) [%]']))
+        self.assertEqual(round(stats['Return (Ann.) [%]']), -3)
+
+    def test_cancel_orders(self):
+        class S(Strategy):
+            def init(self): pass
+
+            def next(self):
+                self.buy(sl=1, tp=1e3)
+                if self.position:
+                    self.position.close()
+                    for order in self.orders:
+                        order.cancel()
+
+        Backtest(SHORT_DATA, S).run()
+
 
 if __name__ == '__main__':
     warnings.filterwarnings('error')

doc/alternatives.md

@@ -10,6 +10,9 @@ If after reviewing the docs and examples perchance you find
 [_Backtesting.py_](https://kernc.github.io/backtesting.py) not your cup of tea,
 kindly have a look at some similar alternative Python backtesting frameworks:
 
+-  [AutoTrader](https://github.com/kieran-mackle/AutoTrader) -
+  an automated trading framework with an emphasis on cryptocurrency markets
+  that includes a [robust backtesting API](https://github.com/kieran-mackle/AutoTrader/blob/main/docs/source/tutorials/backtesting.md)
 - [bt](http://pmorissette.github.io/bt/) -
   a framework based on reusable and flexible blocks of
   strategy logic that support multiple instruments and
@@ -54,6 +57,13 @@ kindly have a look at some similar alternative Python backtesting frameworks:
   stock picking, backtesting, and unified visualization. Documentation in Chinese.
 - [AwesomeQuant](https://github.com/wilsonfreitas/awesome-quant#trading--backtesting) -
   A somewhat curated list of libraries, packages, and resources for quants.
+- [Nautilus Trader](https://github.com/nautechsystems/nautilus_trader) -
+  high-performance, production-grade algorithmic trading platform written in Rust/Python,
+  with event-driven engine to backtest portfolios of automated trading strategies,
+  and also deploy those same strategies live, with no code changes.
+- [LiuAlgoTrader](https://amor71.github.io/LiuAlgoTrader/) -
+  A scalable, multi-process ML-ready framework for effective algorithmic trading.
+
 
 #### Obsolete / Unmaintained
 

setup.py

@@ -9,7 +9,7 @@
     from setuptools import setup, find_packages
 
     setup(
-        name='Backtesting',
+        name='backtesting',
         description="Backtest trading strategies in Python",
         license='AGPL-3.0',
         url='https://kernc.github.io/backtesting.py/',