fix docs, add doctests and docs to pre-commit.

Author: jathoms

.pre-commit-config.yaml

@@ -35,5 +35,18 @@ repos:
         files: \.ipynb$
         language: system
 
+      - id: doctest
+        name: run doctests
+        files: ^docs/
+        entry: just doctest
+        language: system
+        pass_filenames: false
+
+      - id: docs
+        name: build docs
+        files: ^docs/
+        entry: just docs
+        language: system
+        pass_filenames: false
 
 

docs/open_docs.py

@@ -2,8 +2,8 @@
 import sys
 import webbrowser
 
-open_flag = sys.argv[1] == "--open"
-output_path = sys.argv[2]
+open_flag = len(sys.argv) > 1 and sys.argv[1] == "--open"
+output_path = sys.argv[2] if len(sys.argv) > 2 else ""
 
 if open_flag:
     webbrowser.open(pathlib.Path(output_path, "index.html").resolve().as_uri())

…s/source/reference/strategy/decision.rst …urce/reference/engine/decision/index.rstdocs/source/reference/strategy/decision.rst renamed to docs/source/reference/engine/decision/index.rst docs/source/reference/strategy/decision.rst renamed to docs/source/reference/engine/decision/index.rst

@@ -1,10 +1,8 @@
-
 ========
 Decision
 ========
 
-.. currentmodule:: backtest_lib
+.. currentmodule:: backtest_lib.engine.decision
 
 .. autoclass:: Decision
-   :members:
 

docs/source/reference/engine/execute/index.rst

@@ -0,0 +1,7 @@
+=======
+Execute
+=======
+
+.. currentmodule:: backtest_lib.engine.execute
+
+.. autoclass:: PlanExecutor

docs/source/reference/engine/index.rst

@@ -0,0 +1,15 @@
+======
+Engine
+======
+
+.. toctree::
+  :hidden:
+
+  decision/index
+  plan/index
+  execute/index
+
+.. currentmodule:: backtest_lib.engine
+
+.. autoclass:: Engine
+

docs/source/reference/engine/plan/index.rst

@@ -0,0 +1,7 @@
+====
+Plan
+====
+
+.. currentmodule:: backtest_lib.engine.plan
+
+.. autoclass:: PlanGenerator

docs/source/reference/index.rst

@@ -11,4 +11,5 @@ This is an overview of the public API of backtest-lib.
   market/index
   strategy/index
   portfolio/index
+  engine/index
   universe/index

docs/source/reference/strategy/index.rst

@@ -4,11 +4,6 @@ Strategy
 
 .. currentmodule:: backtest_lib
 
-.. toctree::
-   :hidden:
-
-   decision
-
 .. autoclass:: Strategy
    :members:
 

src/backtest_lib/backtest/__init__.py

@@ -101,13 +101,11 @@ class Backtest:
         >>> market = btl.MarketView(spot_prices)
         >>> universe = market.securities
         >>> def hold_strategy(universe, current_portfolio, market, ctx):
-        ...     return btl.Decision(current_portfolio)
-        >>> bt = btl.Backtest(
-        ...     hold_strategy, universe, market, uniform_portfolio(universe)
-        ... )
+        ...     return btl.hold()
+        >>> bt = btl.Backtest(hold_strategy, market, uniform_portfolio(universe))
         >>> results = bt.run()
         >>> results.annualized_return
-        -0.00022650...
+        -0.00553564...
     """
 
     strategy: Strategy
@@ -133,7 +131,7 @@ def __init__(
         backend="polars",
     ):
         self.strategy = strategy
-        self.universe = universe or tuple(market_view.securities)
+        self.universe = universe or market_view.securities
         self.market_view = market_view
         if isinstance(initial_portfolio, CashPortfolio):
             initial_portfolio = initial_portfolio.materialize(

src/backtest_lib/market/__init__.py

@@ -100,13 +100,13 @@ class PastView[ValueT: (float, int), Index: Comparable](ABC):
 
     @property
     @abstractmethod
-    def periods(self) -> Sequence[Index]:
+    def periods(self) -> tuple[Index, ...]:
         """PLACEHOLDER PROPERTY"""
         ...
 
     @property
     @abstractmethod
-    def securities(self) -> Sequence[str]:
+    def securities(self) -> tuple[str, ...]:
         """PLACEHOLDER PROPERTY"""
         ...
 
@@ -430,8 +430,8 @@ def __init__(
         periods = self._resolve_period_axis_spec(reference_view_for_axis_values)
         securities = self._resolve_security_axis_spec(reference_view_for_axis_values)
 
-        self._periods: Sequence[Index] = periods
-        self._securities: Sequence[str] = securities
+        self._periods: tuple[Index, ...] = periods
+        self._securities: tuple[str, ...] = securities
         self._security_policy: SecurityAxisPolicy = security_policy
         self._period_policy: PeriodAxisPolicy = period_policy
         self._backend: str = backend
@@ -443,11 +443,11 @@ def prices(self) -> PastUniversePrices[Index]:
         return self._prices
 
     @property
-    def periods(self) -> Sequence[Index]:
+    def periods(self) -> tuple[Index, ...]:
         return self._periods
 
     @property
-    def securities(self) -> Sequence[str]:
+    def securities(self) -> tuple[str, ...]:
         return self._securities
 
     @property
@@ -544,10 +544,10 @@ def _align(
         # TODO: Add a reindexing method to the PastView protocol in some way
         # return view.reindex(securities=new_sec, periods=new_per)
 
-    def _resolve_period_axis_spec(self, spec: str) -> Sequence[Index]:
+    def _resolve_period_axis_spec(self, spec: str) -> tuple[Index, ...]:
         return self._resolve_axis_spec(spec).periods
 
-    def _resolve_security_axis_spec(self, spec: str) -> Sequence[str]:
+    def _resolve_security_axis_spec(self, spec: str) -> tuple[str, ...]:
         return self._resolve_axis_spec(spec).securities
 
     def _resolve_axis_spec(self, spec: str) -> PastView: