Change Portfolio to PortfolioBase, add Portfolio as a union of actual portfolio types

rename CashPortfolio to Cash, add end-to-end testing in tests/e2e, move
unit tests into unit/ directory

fix doctest

Author: jathoms

src/backtest_lib/backtest/__init__.py

@@ -3,7 +3,7 @@
 import datetime as dt
 import logging
 import warnings
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, assert_never, overload
 
 from backtest_lib.backtest._helpers import _to_pydt
 from backtest_lib.backtest.results import BacktestResults
@@ -15,7 +15,13 @@
     PerfectWorldPlanGenerator,
 )
 from backtest_lib.market import MarketView, get_pastview_type_from_backend
-from backtest_lib.portfolio import CashPortfolio, Portfolio, WeightedPortfolio
+from backtest_lib.portfolio import (
+    Cash,
+    FractionalQuantityPortfolio,
+    Portfolio,
+    QuantityPortfolio,
+    WeightedPortfolio,
+)
 from backtest_lib.strategy import Strategy
 from backtest_lib.strategy.context import StrategyContext
 
@@ -105,14 +111,14 @@ class Backtest:
         >>> bt = btl.Backtest(hold_strategy, market, uniform_portfolio(universe))
         >>> results = bt.run()
         >>> results.annualized_return
-        -0.00553564...
+        -0.00035649...
     """
 
     strategy: Strategy
     universe: Universe
     market_view: MarketView
-    initial_portfolio: WeightedPortfolio
-    _current_portfolio: WeightedPortfolio
+    initial_portfolio: Portfolio
+    _current_portfolio: Portfolio
     settings: BacktestSettings
     _schedule: DecisionSchedule
     _backend: type[PastView]
@@ -122,7 +128,7 @@ def __init__(
         self,
         strategy: Strategy,
         market_view: MarketView,
-        initial_portfolio: WeightedPortfolio,
+        initial_portfolio: Portfolio | Cash,
         universe: Universe | None = None,
         settings: BacktestSettings = _DEFAULT_BACKTEST_SETTINGS,
         *,
@@ -133,7 +139,7 @@ def __init__(
         self.strategy = strategy
         self.universe = universe or market_view.securities
         self.market_view = market_view
-        if isinstance(initial_portfolio, CashPortfolio):
+        if isinstance(initial_portfolio, Cash):
             initial_portfolio = initial_portfolio.materialize(
                 universe=self.universe, backend=backend
             )
@@ -160,6 +166,7 @@ def __init__(
     def run(self, ctx: StrategyContext | None = None) -> BacktestResults:
         schedule_it = iter(self._schedule)
         next_decision_period = next(schedule_it)
+        advance_schedule = False
         if ctx is None:
             ctx = StrategyContext()
         output_holdings: list[VectorMapping[str, float]] = []
@@ -176,15 +183,7 @@ def run(self, ctx: StrategyContext | None = None) -> BacktestResults:
                 f" {self._current_portfolio.total_value}",
             )
             if ctx.now >= _to_pydt(next_decision_period):
-                try:
-                    next_decision_period = next(schedule_it)
-                except StopIteration:
-                    logger.debug(
-                        "Reached end of decision schedule, breaking from backtest loop"
-                        f" at {ctx.now} (period {i}).",
-                    )
-                    break
-
+                advance_schedule = True
                 # NOTE: we are using close prices here. this is an implicit assumption.
                 # the user may want to use (low+high)/2, mid price, VWAP/TWAP.
                 result = self._engine.execute_strategy(
@@ -195,15 +194,7 @@ def run(self, ctx: StrategyContext | None = None) -> BacktestResults:
                     prices=yesterday_prices,
                 )
 
-                # problem: we convert into quantities a lot even when we may not have
-                # to. i.e when the user is using a PerfectWorldGenerator/Executor and
-                # only wants to pass target weights.
-                # idea: allow a decorator or something on the user's strategy to say:
-                # @weight_based or @quantity_based or something else so we can optimize
-                # our backtesting behaviour due to not neeeding constant conversions.
-                portfolio_after_decision = result.after.into_quantities(
-                    yesterday_prices
-                )
+                portfolio_after_decision = result.after
                 logger.debug(
                     f"engine output for {ctx.now}: {result.after.holdings}, "
                     f"cash: {result.after.cash}"
@@ -216,9 +207,7 @@ def run(self, ctx: StrategyContext | None = None) -> BacktestResults:
                         ctx.now,
                     )
             else:
-                portfolio_after_decision = self._current_portfolio.into_quantities(
-                    yesterday_prices
-                )
+                portfolio_after_decision = self._current_portfolio
             # TODO: the weights can be calculated as part of the results calculation,
             pf_as_weights = portfolio_after_decision.into_weighted(
                 prices=yesterday_prices
@@ -234,43 +223,93 @@ def run(self, ctx: StrategyContext | None = None) -> BacktestResults:
 
             self._current_portfolio = inter_day_adjusted_portfolio
             yesterday_prices = today_prices
+            if advance_schedule:
+                try:
+                    next_decision_period = next(schedule_it)
+                    advance_schedule = False
+                except StopIteration:
+                    logger.debug(
+                        "Reached end of decision schedule, breaking from backtest loop"
+                        f" at {ctx.now} (period {i}).",
+                    )
+                    break
 
         allocation_history: PastView = self._backend.from_security_mappings(
             output_holdings,
-            self.market_view.periods[: i - 1],
+            self.market_view.periods[:i],
         )
         results = BacktestResults.from_weights_market_initial_capital(
             weights=allocation_history,
-            market=self.market_view.truncated_to(i - 1),
+            market=self.market_view.truncated_to(i),
             backend=self._backend,
         )
         return results
 
 
+@overload
 def _apply_inter_period_price_changes(
     portfolio: WeightedPortfolio,
     pct_change: UniverseMapping[float],
-) -> WeightedPortfolio:
-    prev_cash = portfolio.cash
-    prev_hold = portfolio.holdings
-    # logger.debug(
-    #     f"Holdings length: {len(prev_hold)}, pct_change length: {len(pct_change)}, "
-    #     f"hold: {prev_hold}, pct_change: {pct_change}"
-    # )
-
-    new_total_holdings_weight = prev_hold * pct_change
-    new_total_weight = prev_cash + new_total_holdings_weight.sum()
-
-    new_cash = prev_cash / new_total_weight
-    new_holdings = new_total_holdings_weight / new_total_weight
-
-    return WeightedPortfolio(
-        cash=new_cash,
-        holdings=new_holdings,
-        universe=new_holdings.keys(),  # brittle, review this
-        total_value=portfolio.total_value * new_total_weight,
-        constructor_backend=portfolio._backend,
-    )
+) -> WeightedPortfolio: ...
+
+
+@overload
+def _apply_inter_period_price_changes(
+    portfolio: QuantityPortfolio,
+    pct_change: UniverseMapping[float],
+) -> QuantityPortfolio: ...
+
+
+@overload
+def _apply_inter_period_price_changes(
+    portfolio: FractionalQuantityPortfolio,
+    pct_change: UniverseMapping[float],
+) -> FractionalQuantityPortfolio: ...
+
+
+def _apply_inter_period_price_changes(
+    portfolio: Portfolio,
+    pct_change: UniverseMapping[float],
+) -> Portfolio:
+    if isinstance(portfolio, WeightedPortfolio):
+        prev_cash = portfolio.cash
+        prev_hold = portfolio.holdings
+
+        new_total_holdings_weight = prev_hold * pct_change
+        new_total_weight = prev_cash + new_total_holdings_weight.sum()
+
+        new_cash = prev_cash / new_total_weight
+        new_holdings = new_total_holdings_weight / new_total_weight
+
+        return WeightedPortfolio(
+            cash=new_cash,
+            holdings=new_holdings,
+            universe=new_holdings.keys(),  # brittle, review this
+            total_value=portfolio.total_value * new_total_weight,
+            constructor_backend=portfolio._backend,
+        )
+    elif isinstance(portfolio, QuantityPortfolio):
+        value_changes = portfolio.holdings * pct_change
+        new_total_value = value_changes.sum()
+        return QuantityPortfolio(
+            universe=portfolio.universe,
+            holdings=portfolio.holdings,
+            cash=portfolio.cash,
+            total_value=new_total_value,
+            constructor_backend=portfolio._backend,
+        )
+    elif isinstance(portfolio, FractionalQuantityPortfolio):
+        value_changes = portfolio.holdings * pct_change
+        new_total_value = value_changes.sum()
+        return FractionalQuantityPortfolio(
+            universe=portfolio.universe,
+            holdings=portfolio.holdings,
+            cash=portfolio.cash,
+            total_value=new_total_value,
+            constructor_backend=portfolio._backend,
+        )
+    else:
+        assert_never(portfolio)
 
 
 def _check_tradable(

src/backtest_lib/engine/execute/perfect_world.py

@@ -338,11 +338,13 @@ def _normalize_ops(
             assert_never(compiled_targetting_op)
 
         if trades:
-            yield Trades(
+            batched_trades = Trades(
                 trades=tuple(trades),
                 security_alignment=self._security_alignment,
                 backend_mapping_type=self._backend_mapping_type,
             )
+            if batched_trades.position_delta.abs().sum() != 0:
+                yield batched_trades
 
     def execute_plan(
         self,

src/backtest_lib/portfolio/__init__.py

@@ -20,7 +20,7 @@
 logger = logging.getLogger(__name__)
 
 
-class Portfolio[H: (float, int)]:
+class PortfolioBase[H: (float, int)]:
     """PLACEHOLDER"""
 
     holdings: UniverseMapping[H]
@@ -35,7 +35,7 @@ def __init__(
         holdings: UniverseMapping[H] | Mapping[str, H],
         cash: float,
         total_value: float,
-        constructor_backend: str,
+        constructor_backend: str = "polars",
     ):
         universe_tup = tuple(universe)
         self.holdings = make_universe_mapping(
@@ -64,7 +64,7 @@ def into_quantities_fractional(
     ) -> FractionalQuantityPortfolio: ...
 
 
-class QuantityPortfolio(Portfolio[Quantity]):
+class QuantityPortfolio(PortfolioBase[Quantity]):
     """PLACEHOLDER"""
 
     def into_weighted(
@@ -102,7 +102,7 @@ def into_quantities_fractional(self, prices=None) -> FractionalQuantityPortfolio
         )
 
 
-class FractionalQuantityPortfolio(Portfolio[FractionalQuantity]):
+class FractionalQuantityPortfolio(PortfolioBase[FractionalQuantity]):
     """PLACEHOLDER"""
 
     def into_weighted(self, prices: UniverseMapping | None = None) -> WeightedPortfolio:
@@ -138,7 +138,7 @@ def into_quantities_fractional(self, prices=None) -> FractionalQuantityPortfolio
         return self
 
 
-class WeightedPortfolio(Portfolio[Weight]):
+class WeightedPortfolio(PortfolioBase[Weight]):
     """PLACEHOLDER"""
 
     def into_weighted(self, prices=None) -> WeightedPortfolio:
@@ -254,7 +254,7 @@ def uniform_portfolio(
 
 
 @dataclass(frozen=True, slots=True)
-class CashPortfolio:
+class Cash:
     value: float
 
     def materialize(self, universe: Iterable[str], backend: str) -> WeightedPortfolio:
@@ -272,4 +272,7 @@ def materialize(self, universe: Iterable[str], backend: str) -> WeightedPortfoli
 
 
 def cash(value: float):
-    return CashPortfolio(value=value)
+    return Cash(value=value)
+
+
+Portfolio = WeightedPortfolio | QuantityPortfolio | FractionalQuantityPortfolio

tests/conftest.py

@@ -0,0 +1,18 @@
+from pathlib import Path
+
+import pytest
+from polars import read_csv
+
+from backtest_lib import MarketView
+
+
+@pytest.fixture(scope="session")
+def test_data_dir() -> Path:
+    return Path(__file__).resolve().parent / "data"
+
+
+@pytest.fixture(scope="session")
+def single_security_market(test_data_dir) -> MarketView:
+    data = read_csv(test_data_dir / "single_security.csv")
+    market = MarketView(data)
+    return market