topstep-backtest 0.1.0__py3-none-any.whl

topstep_backtest/strategy/symbol.py

@@ -0,0 +1,344 @@
+"""Single-contract ergonomic strategy base (the backtesting.py-style dialect).
+
+``SymbolStrategy`` narrows the raw ``Strategy`` seam to one contract: events
+for other instruments never reach the ``on_*`` hooks, ``use()``-registered
+indicators are auto-updated once per matching bar (registration order ==
+update order), and ``on_bar`` is gated until every indicator is ready. The
+position/working-order views fold ONLY the SDK models both brokers emit (plus
+a submit-time latch of each sugar-placed order id, superseded by its first
+real event), and the order sugar targets the ``ctx`` protocol surfaces with
+rejections routed to ``on_reject`` — a rejection is normal combine control
+flow (position cap,
+no-trade window), not an exception. The raw raising path remains
+``self.ctx.orders``.
+"""
+
+from __future__ import annotations
+
+from decimal import Decimal
+from typing import cast
+
+from topstep_sdk import (
+    APIError,
+    HalfTradeModel,
+    OrderModel,
+    OrderSide,
+    OrderStatus,
+    OrderType,
+    PositionModel,
+)
+
+from ..core.instruments import InstrumentSpec
+from ..indicators import Cross, Indicator, TalibLine, ValueSource
+from ..protocols import Bar
+from .base import Strategy
+from .tracker import NetPosition, OrderTracker
+
+__all__ = ["SymbolStrategy"]
+
+
+def _implied_type(limit_price: Decimal | None, stop_price: Decimal | None) -> OrderType:
+    """The order type the price kwargs imply.
+
+    Both together would imply STOP_LIMIT, which the Tier-0 sim rejects while
+    live places — a strategy validated in sim would carry a silently dead
+    branch — so the combination is refused loudly at the seam.
+    """
+    if limit_price is not None and stop_price is not None:
+        raise ValueError(
+            "limit_price and stop_price together imply STOP_LIMIT, which the "
+            "Tier-0 sim cannot fill (sim would reject what live would place); "
+            "place it explicitly via self.ctx.orders if you mean it"
+        )
+    if limit_price is not None:
+        return OrderType.LIMIT
+    if stop_price is not None:
+        return OrderType.STOP
+    return OrderType.MARKET
+
+
+def _owner_of(source: object) -> object:
+    """A ``Cross`` input's registerable identity: a line resolves to its owner."""
+    return source.owner if isinstance(source, TalibLine) else source
+
+
+def _check_cross_inputs(cross: Cross, registered_ids: set[int]) -> None:
+    """Both hazards a ``Cross`` can be wired into, refused at registration.
+
+    Inputs are viewed as plain objects because the checks exist for callers the
+    type system never saw — a ``Cross`` over another ``Cross`` type-checks (a
+    Cross has lookback/ready) but has no ``.value``, and would die with an
+    ``AttributeError`` only on the first bar both inner inputs happened to be
+    ready, potentially hours into a run.
+    """
+    for source in cast("tuple[object, object]", cross.inputs):
+        if not isinstance(source, ValueSource):
+            raise ValueError(
+                f"Cross input {source!r} exposes no `.value`, so the Cross would "
+                f"die mid-run on the first bar both inputs are ready"
+            )
+        if id(_owner_of(source)) not in registered_ids:
+            raise ValueError(
+                "Cross inputs must be use()-registered before the Cross "
+                "that reads them (update the Cross manually if an input "
+                "is maintained outside use())"
+            )
+
+
+def _require_indicator(candidate: object) -> None:
+    """Reject a non-``Indicator`` at registration rather than on the first bar.
+
+    Typed callers cannot reach this (``use`` is bound to ``Indicator``), but an
+    untyped one would otherwise get a bare ``AttributeError`` a bar later.
+    """
+    if not isinstance(candidate, Indicator):
+        raise TypeError(
+            f"{candidate!r} is not an Indicator (needs lookback/ready/update); "
+            f"registering it would fail on the first bar instead of here"
+        )
+
+
+class SymbolStrategy(Strategy):
+    """Base for strategies trading exactly one contract.
+
+    Subclasses register indicators with ``use()`` in ``__init__`` and override
+    ``on_bar`` — invoked only for ``contract_id``, only once every registered
+    indicator is ready (and, when ``warmup`` is explicitly overridden, at
+    least that many matching bars have been seen; an explicit ``warmup``
+    gates even under ``require_ready=False``), with every indicator already
+    updated for that bar. ``position`` and ``working_orders`` are folded from
+    the same user events live emits, and ``buy``/``sell`` latch the returned
+    order id into ``working_orders`` at submit time — so entry guards like
+    ``position.flat and not self.working_orders`` hold even when live hub
+    confirmations lag the REST return past the next bar.
+
+    One known hook-cadence gap: the sim emits no ``PositionModel`` event on a
+    full close (live sends a closed/size-0 snapshot), so detect flatness from
+    ``position.flat`` in ``on_fill`` — never by overriding ``on_position``.
+    The views themselves stay correct on both sides.
+    """
+
+    def __init__(
+        self,
+        contract_id: str,
+        *,
+        require_ready: bool = True,
+        warmup: int | None = None,
+    ) -> None:
+        self.contract_id = contract_id
+        self._require_ready = require_ready
+        self._warmup_override = warmup
+        self._indicators: list[Indicator] = []
+        self._position = NetPosition()
+        self._orders = OrderTracker()
+        self._bars_seen = 0
+        self._bars_gated = 0
+
+    def use[T: Indicator](self, indicator: T) -> T:
+        """Register an indicator: auto-updated on every matching bar and
+
+        counted toward the ready-gate. Registration order == update order —
+        ``use()`` a ``Cross``'s inputs BEFORE the ``Cross`` that reads them
+        (enforced: a ``Cross`` with unregistered inputs would read one-bar-
+        stale values with no error, so it is refused here instead). A
+        ``TalibLine`` input counts as registered once the indicator that OWNS
+        it is, since one owner computes all of its lines together.
+        """
+        if isinstance(indicator, TalibLine):
+            raise ValueError(
+                "a TalibLine cannot be use()-registered — it has no state of "
+                "its own and would never advance; register the indicator that "
+                "owns it and keep the line only as a Cross input"
+            )
+        _require_indicator(indicator)
+        if isinstance(indicator, Cross):
+            _check_cross_inputs(indicator, {id(known) for known in self._indicators})
+            indicator.mark_registered()
+        self._indicators.append(indicator)
+        return indicator
+
+    @property
+    def warmup(self) -> int:
+        """Declared warmup: the explicit override, else the max indicator lookback."""
+        if self._warmup_override is not None:
+            return self._warmup_override
+        return max((indicator.lookback for indicator in self._indicators), default=0)
+
+    @property
+    def position(self) -> NetPosition:
+        """This contract's net position, folded from fills and snapshots."""
+        return self._position
+
+    @property
+    def working_orders(self) -> tuple[OrderModel, ...]:
+        """Non-terminal orders on this contract, ascending order id."""
+        return self._orders.working_for(self.contract_id)
+
+    @property
+    def spec(self) -> InstrumentSpec:
+        """Instrument economics for this contract."""
+        return self.ctx.instrument(self.contract_id)
+
+    @property
+    def bars_gated(self) -> int:
+        """Matching bars swallowed by the ready-gate so far."""
+        return self._bars_gated
+
+    async def handle_bar(self, bar: Bar) -> None:
+        if bar.bar_type.contract_id != self.contract_id:
+            return
+        for indicator in self._indicators:
+            indicator.update(bar)
+        self._bars_seen += 1
+        if self._gated():
+            self._bars_gated += 1
+            return
+        await self.on_bar(bar)
+
+    def _gated(self) -> bool:
+        # An explicit warmup override gates even when require_ready is off —
+        # the declared warmup must never silently understate the actual gate.
+        if self._warmup_override is not None and self._bars_seen < self._warmup_override:
+            return True
+        return self._require_ready and any(not indicator.ready for indicator in self._indicators)
+
+    async def handle_order(self, order: OrderModel) -> None:
+        if order.contract_id != self.contract_id:
+            return
+        self._orders.apply(order)
+        await self.on_order(order)
+
+    async def handle_fill(self, trade: HalfTradeModel) -> None:
+        if trade.contract_id != self.contract_id:
+            return
+        self._position.apply_fill(trade)
+        await self.on_fill(trade)
+
+    async def handle_position(self, position: PositionModel) -> None:
+        if position.contract_id != self.contract_id:
+            return
+        self._position.apply_snapshot(position)
+        await self.on_position(position)
+
+    async def on_reject(self, error: APIError) -> None:
+        """Called with the ``APIError`` when a sugar order call is rejected.
+
+        Default: ignore (the sugar call returns ``None``).
+        """
+
+    async def buy(
+        self,
+        size: int,
+        *,
+        stop_loss_ticks: int | None = None,
+        take_profit_ticks: int | None = None,
+        limit_price: Decimal | None = None,
+        stop_price: Decimal | None = None,
+        custom_tag: str | None = None,
+    ) -> int | None:
+        """Buy this contract (market unless a price kwarg implies otherwise);
+
+        returns the order id — latched into ``working_orders`` at submit time —
+        or ``None`` on rejection (see ``on_reject``).
+        """
+        order_type = _implied_type(limit_price, stop_price)
+        try:
+            order_id = await self.ctx.orders.buy(
+                self.ctx.account_id,
+                self.contract_id,
+                size,
+                type=order_type,
+                limit_price=limit_price,
+                stop_price=stop_price,
+                custom_tag=custom_tag,
+                stop_loss_ticks=stop_loss_ticks,
+                take_profit_ticks=take_profit_ticks,
+            )
+        except APIError as error:
+            await self.on_reject(error)
+            return None
+        self._latch(order_id, OrderSide.BUY, order_type, size, limit_price, stop_price, custom_tag)
+        return order_id
+
+    async def sell(
+        self,
+        size: int,
+        *,
+        stop_loss_ticks: int | None = None,
+        take_profit_ticks: int | None = None,
+        limit_price: Decimal | None = None,
+        stop_price: Decimal | None = None,
+        custom_tag: str | None = None,
+    ) -> int | None:
+        """Sell this contract (market unless a price kwarg implies otherwise);
+
+        returns the order id — latched into ``working_orders`` at submit time —
+        or ``None`` on rejection (see ``on_reject``).
+        """
+        order_type = _implied_type(limit_price, stop_price)
+        try:
+            order_id = await self.ctx.orders.sell(
+                self.ctx.account_id,
+                self.contract_id,
+                size,
+                type=order_type,
+                limit_price=limit_price,
+                stop_price=stop_price,
+                custom_tag=custom_tag,
+                stop_loss_ticks=stop_loss_ticks,
+                take_profit_ticks=take_profit_ticks,
+            )
+        except APIError as error:
+            await self.on_reject(error)
+            return None
+        self._latch(order_id, OrderSide.SELL, order_type, size, limit_price, stop_price, custom_tag)
+        return order_id
+
+    def _latch(
+        self,
+        order_id: int,
+        side: OrderSide,
+        order_type: OrderType,
+        size: int,
+        limit_price: Decimal | None,
+        stop_price: Decimal | None,
+        custom_tag: str | None,
+    ) -> None:
+        """Fold a synthetic PENDING order for a just-submitted id, so the
+
+        working view is truthful the instant the REST call returns — live, the
+        hub ``OrderModel`` may lag past the next bar's ``on_bar``. The first
+        real event for the id supersedes (or, if terminal, pre-empts) it.
+        """
+        self._orders.latch(
+            OrderModel(
+                id=order_id,
+                account_id=self.ctx.account_id,
+                contract_id=self.contract_id,
+                status=OrderStatus.PENDING,
+                type=order_type,
+                side=side,
+                size=size,
+                limit_price=limit_price,
+                stop_price=stop_price,
+                custom_tag=custom_tag,
+            )
+        )
+
+    async def close(self) -> None:
+        """Flatten this contract's position; a rejection goes to ``on_reject``."""
+        try:
+            await self.ctx.positions.close(self.ctx.account_id, self.contract_id)
+        except APIError as error:
+            await self.on_reject(error)
+
+    async def cancel_working(self) -> None:
+        """Cancel every working order on this contract, one cancel per order;
+
+        each rejection goes to ``on_reject`` and the remaining cancels proceed.
+        """
+        for order in self.working_orders:
+            try:
+                await self.ctx.orders.cancel(self.ctx.account_id, order.id)
+            except APIError as error:
+                await self.on_reject(error)

topstep_backtest/strategy/tracker.py

@@ -0,0 +1,151 @@
+"""Pure event-fold state trackers over the SDK's user-event models.
+
+Everything here folds ONLY ``topstep_sdk`` models (``HalfTradeModel``,
+``PositionModel``, ``OrderModel``) — the exact payloads BOTH the ``SimBroker``
+and the live user hub emit — so a strategy's view of its own position and
+working orders is built identically in sim and live. That is the parity
+argument: no broker internals, no engine imports, just event folding.
+"""
+
+from __future__ import annotations
+
+from topstep_sdk import (
+    HalfTradeModel,
+    OrderModel,
+    OrderSide,
+    OrderStatus,
+    PositionModel,
+    PositionType,
+)
+
+__all__ = [
+    "TERMINAL_ORDER_STATUSES",
+    "NetPosition",
+    "OrderTracker",
+    "PositionTracker",
+]
+
+TERMINAL_ORDER_STATUSES: frozenset[OrderStatus] = frozenset(
+    {
+        OrderStatus.FILLED,
+        OrderStatus.CANCELLED,
+        OrderStatus.EXPIRED,
+        OrderStatus.REJECTED,
+    }
+)
+"""Statuses after which an order can never execute again. Must match the sim
+broker's terminal set (asserted in tests) so ``OrderTracker.working`` mirrors
+``orders.search_open()`` in both sim and live."""
+
+
+class NetPosition:
+    """Signed net contracts for one instrument (positive = long).
+
+    ``apply_fill`` is the incremental path (one ``GatewayUserTrade`` at a
+    time); ``apply_snapshot`` is the authoritative reconcile — a broker
+    ``PositionModel`` overrides any fill-derived drift.
+
+    Folding assumes per-contract events arrive in execution order (each trade
+    before the snapshot that already includes it) — the sim guarantees this;
+    a live driver must serialize the trade/position hub callbacks per
+    contract. Neither model carries a sequence field, so a snapshot that
+    outruns its own trade double-counts that trade until the next snapshot
+    reconciles.
+    """
+
+    __slots__ = ("net",)
+
+    def __init__(self, net: int = 0) -> None:
+        self.net = net
+
+    @property
+    def is_long(self) -> bool:
+        return self.net > 0
+
+    @property
+    def is_short(self) -> bool:
+        return self.net < 0
+
+    @property
+    def flat(self) -> bool:
+        return self.net == 0
+
+    def __bool__(self) -> bool:
+        return self.net != 0
+
+    def __repr__(self) -> str:
+        return f"NetPosition(net={self.net})"
+
+    def apply_fill(self, trade: HalfTradeModel) -> None:
+        if trade.voided:  # a busted trade never changed the position
+            return
+        direction = 1 if trade.side == OrderSide.BID else -1  # BUY==BID==0
+        self.net += direction * trade.size
+
+    def apply_snapshot(self, position: PositionModel) -> None:
+        if position.type == PositionType.LONG:
+            self.net = position.size
+        elif position.type == PositionType.SHORT:
+            self.net = -position.size
+        else:  # closed/undefined snapshot: flat
+            self.net = 0
+
+
+class PositionTracker:
+    """Per-contract ``NetPosition``s, routed by ``contract_id``."""
+
+    __slots__ = ("_by_contract",)
+
+    def __init__(self) -> None:
+        self._by_contract: dict[str, NetPosition] = {}
+
+    def net(self, contract_id: str) -> NetPosition:
+        found = self._by_contract.get(contract_id)
+        if found is None:
+            found = NetPosition()
+            self._by_contract[contract_id] = found
+        return found
+
+    def apply_fill(self, trade: HalfTradeModel) -> None:
+        self.net(trade.contract_id).apply_fill(trade)
+
+    def apply_snapshot(self, position: PositionModel) -> None:
+        self.net(position.contract_id).apply_snapshot(position)
+
+
+class OrderTracker:
+    """Latest ``OrderModel`` per order id, folded from ``on_order`` events.
+
+    ``working`` mirrors what ``orders.search_open()`` would return once all
+    queued events are drained — without a broker round-trip. Terminal orders
+    are pruned on arrival (only their ids are retained), so a long live
+    session holds state proportional to its working orders, not its history.
+    """
+
+    __slots__ = ("_by_id", "_terminal_ids")
+
+    def __init__(self) -> None:
+        self._by_id: dict[int, OrderModel] = {}
+        self._terminal_ids: set[int] = set()
+
+    def apply(self, order: OrderModel) -> None:
+        if order.status in TERMINAL_ORDER_STATUSES:
+            self._by_id.pop(order.id, None)
+            self._terminal_ids.add(order.id)
+        elif order.id not in self._terminal_ids:  # reordered stale event: never resurrect
+            self._by_id[order.id] = order
+
+    def latch(self, order: OrderModel) -> None:
+        """Fold a submit-time synthetic order, closing the live window between
+        the REST return and the hub confirmation; any already-seen event for
+        the id (the hub can outrun the REST response) wins over the synthetic.
+        """
+        if order.id not in self._terminal_ids and order.id not in self._by_id:
+            self._by_id[order.id] = order
+
+    @property
+    def working(self) -> tuple[OrderModel, ...]:
+        return tuple(order for _, order in sorted(self._by_id.items()))
+
+    def working_for(self, contract_id: str) -> tuple[OrderModel, ...]:
+        return tuple(order for order in self.working if order.contract_id == contract_id)