topstep-backtest 0.1.0__py3-none-any.whl

topstep_backtest/indicators/library.py

@@ -0,0 +1,303 @@
+"""Named indicators — typed spellings of the TA-Lib functions strategies reach
+for most, plus ``Cross``.
+
+Each class is a thin ``TalibIndicator`` subclass: it fixes the TA-Lib function
+and gives the parameters real names and types, so ``Ema(20)`` is autocompletable
+and pyright-checked while still being exactly ``TalibIndicator("EMA",
+timeperiod=20)``. Anything not named here is one line away —
+``TalibIndicator("CDLENGULFING")``, ``TalibIndicator("ULTOSC")`` — 152 of
+TA-Lib's 161 functions are reachable through the generic form (the other nine
+are refused at construction; see ``talib_adapter``).
+
+``lookback`` is TA-Lib's, so the warmup a strategy declares comes from the same
+authority that computes the values: ``Sma(3)`` and ``Ema(3)`` need 3 bars,
+``Rsi(3)`` and ``Atr(3)`` need 4 (their first delta/true-range consumes a bar).
+``lookback`` is where a value EXISTS; ``history_bars`` (``warm``) is where it
+stops depending on where the run started, which is where sim/live parity begins
+— see ``talib_adapter``'s module docstring.
+
+``Cross`` is not a TA-Lib function — it is a comparator over two value series
+and stays pure Python.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .talib_adapter import TalibIndicator
+
+if TYPE_CHECKING:
+    from ..protocols import Bar
+    from .base import ValueSource
+
+__all__ = [
+    "Adx",
+    "Atr",
+    "BBands",
+    "Cross",
+    "Ema",
+    "Highest",
+    "Lowest",
+    "Macd",
+    "Obv",
+    "Rsi",
+    "Sma",
+    "StdDev",
+    "Stoch",
+]
+
+
+def _check_period(period: int) -> None:
+    if period < 1:
+        raise ValueError(f"period must be >= 1, got {period}")
+
+
+# --------------------------------------------------------------------------- #
+# Single-output
+# --------------------------------------------------------------------------- #
+
+
+class Sma(TalibIndicator):
+    """Simple moving average of closes (TA-Lib ``SMA``)."""
+
+    def __init__(self, period: int, *, history: int | None = None) -> None:
+        _check_period(period)
+        super().__init__("SMA", history=history, timeperiod=period)
+
+
+class Ema(TalibIndicator):
+    """Exponential moving average of closes (TA-Lib ``EMA``).
+
+    Seeded with the SMA of the first ``period`` closes, then ``k = 2/(period+1)``
+    recursion — TA-Lib's convention.
+    """
+
+    def __init__(self, period: int, *, history: int | None = None) -> None:
+        _check_period(period)
+        super().__init__("EMA", history=history, timeperiod=period)
+
+
+class Rsi(TalibIndicator):
+    """Wilder's relative strength index (TA-Lib ``RSI``); ``lookback == period + 1``."""
+
+    def __init__(self, period: int, *, history: int | None = None) -> None:
+        _check_period(period)
+        super().__init__("RSI", history=history, timeperiod=period)
+
+
+class Atr(TalibIndicator):
+    """Wilder's average true range (TA-Lib ``ATR``); ``lookback == period + 1``."""
+
+    def __init__(self, period: int, *, history: int | None = None) -> None:
+        _check_period(period)
+        super().__init__("ATR", history=history, timeperiod=period)
+
+
+class StdDev(TalibIndicator):
+    """POPULATION standard deviation of closes (TA-Lib ``STDDEV``, ``nbdev=1``).
+
+    TA-Lib evaluates the NAIVE ``E[x^2] - E[x]^2`` form, which cancels badly
+    once the mean is large relative to the spread — at futures price levels the
+    relative error reaches ~2e-9 at 5,000 and ~7e-7 at 100,000. Harmless for a
+    threshold read; do not treat a value derived from it as exact.
+    """
+
+    def __init__(self, period: int, *, history: int | None = None) -> None:
+        _check_period(period)
+        super().__init__("STDDEV", history=history, timeperiod=period, nbdev=1.0)
+
+
+class Highest(TalibIndicator):
+    """Rolling maximum of ``bar.high`` (TA-Lib ``MAX`` redirected onto highs)."""
+
+    def __init__(self, period: int, *, history: int | None = None) -> None:
+        _check_period(period)
+        super().__init__("MAX", price="high", history=history, timeperiod=period)
+
+
+class Lowest(TalibIndicator):
+    """Rolling minimum of ``bar.low`` (TA-Lib ``MIN`` redirected onto lows)."""
+
+    def __init__(self, period: int, *, history: int | None = None) -> None:
+        _check_period(period)
+        super().__init__("MIN", price="low", history=history, timeperiod=period)
+
+
+class Adx(TalibIndicator):
+    """Average directional index (TA-Lib ``ADX``)."""
+
+    def __init__(self, period: int = 14, *, history: int | None = None) -> None:
+        _check_period(period)
+        super().__init__("ADX", history=history, timeperiod=period)
+
+
+class Obv(TalibIndicator):
+    """On-balance volume (TA-Lib ``OBV``).
+
+    OBV accumulates without decay, so — unlike every other indicator here — its
+    LEVEL depends on where accumulation started and is therefore windowed to
+    ``history_bars`` like everything else. Use its slope or divergence, never
+    the absolute level; an inception-anchored level could not be reproduced
+    live in any case.
+    """
+
+    def __init__(self, *, history: int | None = None) -> None:
+        super().__init__("OBV", history=history)
+
+
+# --------------------------------------------------------------------------- #
+# Multi-output — read individual lines with .get(...) / .line(...)
+# --------------------------------------------------------------------------- #
+
+
+class Macd(TalibIndicator):
+    """MACD (TA-Lib ``MACD``): outputs ``macd``, ``macdsignal``, ``macdhist``.
+
+    ``value`` is the MACD line; cross the lines with
+    ``Cross(macd.line("macd"), macd.line("macdsignal"))``.
+    """
+
+    def __init__(
+        self,
+        fast: int = 12,
+        slow: int = 26,
+        signal: int = 9,
+        *,
+        history: int | None = None,
+    ) -> None:
+        for period in (fast, slow, signal):
+            _check_period(period)
+        super().__init__(
+            "MACD", history=history, fastperiod=fast, slowperiod=slow, signalperiod=signal
+        )
+
+
+class BBands(TalibIndicator):
+    """Bollinger bands (TA-Lib ``BBANDS``): ``upperband``/``middleband``/``lowerband``.
+
+    The bands inherit ``StdDev``'s naive-variance error (~7e-7 relative at
+    100,000), so a band EDGE is not an exact number: a ``Cross`` against one can
+    flip on that noise, and a "touch" of a band is never exact. Use it as a
+    threshold, not as a price.
+    """
+
+    def __init__(
+        self,
+        period: int = 20,
+        *,
+        deviations: float = 2.0,
+        history: int | None = None,
+    ) -> None:
+        _check_period(period)
+        super().__init__(
+            "BBANDS",
+            history=history,
+            timeperiod=period,
+            nbdevup=deviations,
+            nbdevdn=deviations,
+        )
+
+
+class Stoch(TalibIndicator):
+    """Slow stochastic (TA-Lib ``STOCH``): outputs ``slowk`` and ``slowd``."""
+
+    def __init__(
+        self,
+        fastk: int = 5,
+        slowk: int = 3,
+        slowd: int = 3,
+        *,
+        history: int | None = None,
+    ) -> None:
+        for period in (fastk, slowk, slowd):
+            _check_period(period)
+        super().__init__(
+            "STOCH",
+            history=history,
+            fastk_period=fastk,
+            slowk_period=slowk,
+            slowd_period=slowd,
+        )
+
+
+# --------------------------------------------------------------------------- #
+# Cross
+# --------------------------------------------------------------------------- #
+
+
+class Cross:
+    """Crossover of two value series: ``up``/``down`` fire only on the crossing bar.
+
+    Tracks the sign of ``a.value - b.value`` per update: ``up`` when the sign
+    goes from <= 0 to > 0, ``down`` when it goes from >= 0 to < 0 — an exact
+    ``a == b`` touch therefore fires on the bar that resolves it, not on the
+    touch itself. Both are ``False`` until the detector holds a previous AND
+    a current comparison with both inputs ready, so
+    ``lookback = max(a.lookback, b.lookback) + 1``.
+
+    Note that TA-Lib values are float64, so an exact ``a == b`` touch is
+    vanishingly rare in practice — the zero-sign branch is a correctness
+    guarantee, not a common path.
+
+    ``update(bar)`` ignores the bar and reads ``a.value`` / ``b.value`` — it
+    REQUIRES both inputs to have been updated for the same bar first. Under
+    ``SymbolStrategy``'s registration-order update rule that means ``use()``
+    the inputs BEFORE the ``Cross`` that reads them (``use()`` enforces it via
+    ``inputs``, resolving a ``TalibLine`` to the indicator that owns it).
+    """
+
+    def __init__(self, a: ValueSource, b: ValueSource) -> None:
+        self._a = a
+        self._b = b
+        self._prev_sign: int | None = None
+        self._curr_sign: int | None = None
+        self._updates = 0
+        self._registered = False
+
+    @property
+    def inputs(self) -> tuple[ValueSource, ValueSource]:
+        """The ``(a, b)`` sources read on update, for registration-order checks."""
+        return (self._a, self._b)
+
+    def mark_registered(self) -> None:
+        """Called by ``use()``. A Cross nobody registered never updates, so its
+        ``up``/``down`` would read False forever and the strategy would take zero
+        trades in silence — ``up``/``down`` raise instead once that is provable."""
+        self._registered = True
+
+    def _check_driven(self) -> None:
+        if self._registered or self._updates:
+            return
+        if self._a.ready and self._b.ready:
+            raise RuntimeError(
+                "this Cross has never been updated although both inputs are "
+                "ready — it was never use()-registered, so it can never fire"
+            )
+
+    @property
+    def lookback(self) -> int:
+        return max(self._a.lookback, self._b.lookback) + 1
+
+    @property
+    def ready(self) -> bool:
+        return self._prev_sign is not None
+
+    @property
+    def up(self) -> bool:
+        self._check_driven()
+        prev, curr = self._prev_sign, self._curr_sign
+        return prev is not None and curr is not None and prev <= 0 and curr > 0
+
+    @property
+    def down(self) -> bool:
+        self._check_driven()
+        prev, curr = self._prev_sign, self._curr_sign
+        return prev is not None and curr is not None and prev >= 0 and curr < 0
+
+    def update(self, bar: Bar) -> None:
+        self._updates += 1
+        if not (self._a.ready and self._b.ready):
+            return
+        diff = self._a.value - self._b.value
+        self._prev_sign = self._curr_sign
+        self._curr_sign = 1 if diff > 0 else -1 if diff < 0 else 0