openbacktesting 0.2.0__py3-none-any.whl

openbacktesting/broker/execution.py

@@ -0,0 +1,62 @@
+"""Independent deterministic OHLC fill-price policy."""
+
+from dataclasses import dataclass
+
+from openbacktesting.broker.models import finite
+
+
+@dataclass(frozen=True)
+class Slippage:
+    """No slippage, fixed-price slippage, or basis-point slippage; apply once per fill."""
+
+    mode: str = "none"
+    value: float = 0
+
+    def __post_init__(self):
+        if self.mode not in ("none", "fixed", "bps"):
+            raise ValueError("slippage mode must be none/fixed/bps")
+        object.__setattr__(self, "value", finite(self.value, "slippage"))
+        if self.value < 0 or (self.mode == "none" and self.value != 0):
+            raise ValueError("Invalid slippage value")
+
+    def cost(self, price: float) -> float:
+        """Return a nonnegative slippage distance per unit."""
+        if self.mode == "fixed":
+            return self.value
+        return price * self.value / 10000 if self.mode == "bps" else 0.0
+
+
+def match_price(request, *, triggered, open_, high, low):
+    """Return the candidate reference price and trigger state without modifying the request."""
+    buy = request.side == "buy"
+    stop = request.stop if not triggered else None
+    if stop is not None:
+        if not (high >= stop if buy else low <= stop):
+            return None, False
+        triggered = True
+    if request.limit is not None:
+        limit = request.limit
+        if not (low <= limit if buy else high >= limit):
+            return None, triggered
+        if stop is not None and (limit <= stop if buy else limit >= stop):
+            return None, triggered
+        return (min(stop or open_, limit) if buy else max(stop or open_, limit)), triggered
+    return ((max(open_, stop) if buy else min(open_, stop)) if stop else open_), triggered
+
+
+def execution_price(base, side, *, spread, slippage, instrument, limit, bounds=None):
+    """Apply costs and the grid before checking the limit; ordinary execution is constrained to the OHLC range."""
+    sign = 1 if side == "buy" else -1
+    price = base * (1 + sign * spread) + sign * slippage.cost(base)
+    price = instrument.price(price, side=side)
+    if limit is not None and (price > limit if side == "buy" else price < limit):
+        return None
+    if bounds is not None:
+        low, high = bounds
+        price = min(max(price, low), high)
+        price = instrument.price(price, side=side)
+        if not low <= price <= high:
+            return None
+    if limit is not None and (price > limit if side == "buy" else price < limit):
+        return None
+    return price

openbacktesting/broker/instrument.py

@@ -0,0 +1,106 @@
+"""Explicit asset units; trading rules are not inferred from market-data decimal places."""
+
+from dataclasses import dataclass
+from decimal import ROUND_CEILING, ROUND_DOWN, ROUND_FLOOR, ROUND_HALF_UP, Decimal, localcontext
+
+import numpy as np
+
+from openbacktesting.broker.models import finite
+
+
+@dataclass(frozen=True)
+class InstrumentSpec:
+    """Actual asset quantity and price grids; currency is only a label."""
+
+    symbol: str = "asset"
+    quantity_step: float = 1
+    min_quantity: float | None = None
+    price_tick: float | None = None
+    min_notional: float = 0
+    currency: str | None = None
+
+    def __post_init__(self):
+        if not isinstance(self.symbol, str) or not self.symbol:
+            raise ValueError("symbol must be a nonempty string")
+        if self.currency is not None and not isinstance(self.currency, str):
+            raise TypeError("currency must be a string or None")
+        step = finite(self.quantity_step, "quantity_step", positive=True)
+        minimum = (
+            step
+            if self.min_quantity is None
+            else finite(self.min_quantity, "min_quantity", positive=True)
+        )
+        object.__setattr__(self, "quantity_step", step)
+        object.__setattr__(self, "min_quantity", minimum)
+        if self.price_tick is not None:
+            object.__setattr__(
+                self, "price_tick", finite(self.price_tick, "price_tick", positive=True)
+            )
+        object.__setattr__(self, "min_notional", finite(self.min_notional, "min_notional"))
+        if self.min_notional < 0:
+            raise ValueError("min_notional must not be negative")
+
+    def quantity(self, value, *, floor=False, opening=True) -> float:
+        """Direct requests must lie on the grid; budgeted quantities may round toward zero."""
+        value = finite(value, "qty")
+        if value < 0:
+            raise ValueError("qty must not be negative")
+        lots = Decimal(str(value)) / Decimal(str(self.quantity_step))
+        whole = lots.to_integral_value(rounding=ROUND_DOWN)
+        if not floor and lots != whole:
+            raise ValueError("qty is not on the quantity_step grid")
+        result = float(whole * Decimal(str(self.quantity_step)))
+        if opening and result < self.min_quantity:
+            if floor:
+                return 0.0
+            raise ValueError("qty is below min_quantity")
+        return result
+
+    def price(self, value, *, side=None) -> float:
+        """Validate requested prices strictly; normalize execution prices in the adverse direction."""
+        value = finite(value, "price", positive=True)
+        if self.price_tick is None:
+            return value
+        ticks = Decimal(str(value)) / Decimal(str(self.price_tick))
+        rounded = ticks.to_integral_value(rounding=ROUND_CEILING if side == "buy" else ROUND_FLOOR)
+        if side is None and ticks != rounded:
+            raise ValueError("price is not on the price_tick grid")
+        return float(rounded * Decimal(str(self.price_tick)))
+
+    def validate_data(self, frame):
+        """Trading market data must be ordered, unique, and have valid prices; explicit ticks must not be silently corrected."""
+        if not frame.index.is_monotonic_increasing or not frame.index.is_unique:
+            raise ValueError("Market-data index must be increasing and unique")
+        values = frame[["Open", "High", "Low", "Close"]].to_numpy(dtype=float)
+        if not np.isfinite(values).all() or (values <= 0).any():
+            raise ValueError("OHLC must contain finite positive prices")
+        if self.price_tick is not None:
+            for price in np.unique(values):
+                self.price(float(price))
+
+    def round_price_to_tick(self, value: float) -> float:
+        """Round prices to the nearest explicit tick; half ticks round to the higher price.
+
+        Args:
+            value: Finite positive price; booleans are not accepted.
+
+        Returns:
+            Finite positive float passing this instrument's strict grid validation; does not change matching-rounding policy.
+
+        Raises:
+            TypeError: value is nonnumeric or a boolean.
+            ValueError: Missing tick, invalid input, zero result, or a valid grid value cannot be represented as a float.
+        """
+        value = finite(value, "price", positive=True)
+        if self.price_tick is None:
+            raise ValueError("round_price_to_tick requires an explicit price_tick")
+        # Decimal exponents of two finite floats can differ by more than 600; prevent default precision from losing half ticks.
+        with localcontext() as context:
+            context.prec = 700
+            tick = Decimal(str(self.price_tick))
+            ticks = (Decimal(str(value)) / tick).to_integral_value(rounding=ROUND_HALF_UP)
+            exact = ticks * tick
+            result = float(exact)
+            if Decimal(str(result)) != exact:
+                raise ValueError("Rounded price cannot represent the grid exactly as a float")
+            return self.price(result)

openbacktesting/broker/ledger.py

@@ -0,0 +1,60 @@
+"""Balance, actual fees, and position snapshots independent of strategies and result tables."""
+
+from openbacktesting.broker.models import AccountSnapshot, PositionSnapshot
+
+
+class TradingLedger:
+    """Record only actual executions; candidate calculations must not call apply."""
+
+    def __init__(self, balance):
+        self.initial_balance = float(balance)
+        self.balance = float(balance)
+        self.realized_pnl_gross = 0.0
+        self.fees_paid = 0.0
+
+    def apply(self, realized_pnl_gross, fee):
+        self.realized_pnl_gross += realized_pnl_gross
+        self.fees_paid += fee
+        self.balance = self.initial_balance + self.realized_pnl_gross - self.fees_paid
+
+    def position(self, trades, price):
+        long_qty = sum(t.size for t in trades if t.size > 0)
+        short_qty = sum(-t.size for t in trades if t.size < 0)
+        long_cost = sum(t.size * t.entry_price for t in trades if t.size > 0)
+        short_cost = sum(-t.size * t.entry_price for t in trades if t.size < 0)
+        long_avg = long_cost / long_qty if long_qty else None
+        short_avg = short_cost / short_qty if short_qty else None
+        average = None if long_qty and short_qty else long_avg or short_avg
+        gross_pl = sum(t.size * (price - t.entry_price) for t in trades)
+        fees = sum(t._entry_commission for t in trades)
+        cost = long_cost + short_cost
+        return PositionSnapshot(
+            long_qty - short_qty,
+            long_qty + short_qty,
+            long_qty,
+            short_qty,
+            long_avg,
+            short_avg,
+            average,
+            (long_qty + short_qty) * price,
+            (long_qty - short_qty) * price,
+            gross_pl,
+            gross_pl - fees,
+            fees,
+            (gross_pl - fees) / cost if cost and average is not None else None,
+        )
+
+    def account(self, position, margin):
+        equity = self.balance + position.unrealized_pnl_gross
+        used = position.gross_notional * margin
+        return AccountSnapshot(
+            self.balance,
+            equity,
+            self.realized_pnl_gross,
+            position.unrealized_pnl_gross,
+            self.fees_paid,
+            used,
+            max(0.0, equity - used),
+            position.gross_notional,
+            position.net_notional,
+        )

openbacktesting/broker/models.py

@@ -0,0 +1,236 @@
+"""Trade requests, events, and accounting snapshots independent of strategies and execution loops."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, fields
+from enum import StrEnum
+from functools import cache
+from math import isfinite
+from numbers import Real
+from typing import Literal
+
+
+def finite(value, name: str, *, positive=False) -> float:
+    """Reject booleans, nonnumeric values, and nonfinite values; return a normalized number."""
+    if isinstance(value, bool) or not isinstance(value, Real):
+        raise TypeError(f"{name} must be a finite number")
+    value = float(value)
+    if not isfinite(value) or (positive and value <= 0):
+        raise ValueError(f"{name} must be a {'positive ' if positive else ''}finite number")
+    return value
+
+
+class OrderStatus(StrEnum):
+    """Observable order states; terminal states cannot reopen."""
+
+    SUBMITTED = "Submitted"
+    ACCEPTED = "Accepted"
+    PARTIALLY_FILLED = "PartiallyFilled"
+    FILLED = "Filled"
+    CANCELED = "Canceled"
+    EXPIRED = "Expired"
+    REJECTED = "Rejected"
+
+    @property
+    def terminal(self) -> bool:
+        """Whether the state is terminal."""
+        return self in (self.FILLED, self.CANCELED, self.EXPIRED, self.REJECTED)
+
+
+@dataclass(frozen=True)
+class ClosedTradeStats:
+    """Cumulative closed portions as of the read; fees are allocated, and unrealized profit or loss is excluded.
+
+    Count closed portions rather than trade_id values; classify wins and losses by strictly positive or negative net profit or loss.
+    losing_amount is a nonnegative loss amount; average net profit or loss and the 0–1 win rate are None for empty records.
+    Values contain no runtime objects; saved snapshots are unaffected by later fills.
+    """
+
+    closed_count: int = 0
+    win_count: int = 0
+    loss_count: int = 0
+    even_count: int = 0
+    winning_profit: float = 0.0
+    losing_amount: float = 0.0
+    net_profit: float = 0.0
+    average_profit: float | None = None
+    win_rate: float | None = None
+
+
+@dataclass(frozen=True)
+class OrderSizingSnapshot:
+    """Sizing basis frozen at submission; budgets do not guarantee actual fill notional or fees.
+
+    mode is qty/amount/percent, source is explicit/default; percent value
+    uses percentage points (20 means 20%), and budget is None in qty mode.
+    """
+
+    mode: Literal["qty", "amount", "percent"]
+    source: Literal["explicit", "default"]
+    value: float
+    equity: float
+    reference_price: float
+    budget: float | None
+    qty: float
+
+
+@dataclass(frozen=True)
+class NormalizedOrderRequest:
+    """Immutable normalized request; tag is stored as JSON text, and reads return independent plain values."""
+
+    side: str
+    qty: float
+    limit: float | None = None
+    stop: float | None = None
+    sl: float | None = None
+    tp: float | None = None
+    reduce_only: bool = False
+    trade_id: str | None = None
+    expires_at: object = None
+    valid_bars: int | None = None
+    tag_json: str = "null"
+
+    @property
+    def tag(self):
+        """Return an independent tag copy; modifying it does not change the request."""
+        return json.loads(self.tag_json)
+
+
+@dataclass(frozen=True)
+class OrderSnapshot:
+    """Frozen order values at a state transition."""
+
+    order_id: str
+    status: OrderStatus
+    filled_qty: float
+    remaining_qty: float
+    avg_fill_price: float | None
+    reason: str | None
+    triggered: bool
+
+
+@dataclass(frozen=True)
+class OrderEvent:
+    """Immutable order event with time and phase."""
+
+    sequence: int
+    bar_index: int
+    timestamp: object
+    phase: str
+    snapshot: OrderSnapshot
+
+
+@dataclass(frozen=True)
+class Fill:
+    """An actual execution; fees are recorded exactly once here."""
+
+    fill_id: str
+    order_id: str
+    sequence: int
+    side: str
+    qty: float
+    price: float
+    fee: float
+    bar_index: int
+    timestamp: object
+    phase: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class TradeAllocation:
+    """Allocation of an execution quantity to entry lots or closed portions."""
+
+    allocation_id: str
+    fill_id: str
+    trade_id: str
+    entry_fill_id: str
+    kind: str
+    qty: float
+    fee: float
+    entry_fee: float
+    realized_pnl_gross: float
+
+
+@dataclass(frozen=True)
+class AccountSnapshot:
+    """Single-currency linear margin account; balance is not securities settlement cash."""
+
+    balance: float
+    equity: float
+    realized_pnl_gross: float
+    unrealized_pnl_gross: float
+    fees_paid: float
+    margin_used: float
+    margin_available: float
+    gross_notional: float
+    net_notional: float
+
+
+@dataclass(frozen=True)
+class PositionSnapshot:
+    """Net position, two-sided gross exposure, and explicit gross and net profit or loss."""
+
+    net_qty: float
+    gross_qty: float
+    long_qty: float
+    short_qty: float
+    long_avg_price: float | None
+    short_avg_price: float | None
+    avg_price: float | None
+    gross_notional: float
+    net_notional: float
+    unrealized_pnl_gross: float
+    unrealized_pnl_net: float
+    entry_fees_remaining: float
+    return_fraction: float | None
+
+    @property
+    def has_exposure(self) -> bool:
+        """A two-sided net-zero position still has gross exposure."""
+        return self.gross_qty > 0
+
+
+@dataclass(frozen=True)
+class RunSummary:
+    """Frozen summary for the finish hook; error text does not replace the original exception."""
+
+    reason: str
+    account: AccountSnapshot
+    error: str | None = None
+
+
+def record(value) -> dict:
+    """Produce a value-only dictionary without exposing live trading objects."""
+    names = _field_names(type(value))
+    return dict(zip(names, map(value.__dict__.__getitem__, names)))
+
+
+def columns(model) -> list[str]:
+    """Empty result tables retain model fields."""
+    return list(_field_names(model))
+
+
+@cache
+def _field_names(model):
+    return tuple(item.name for item in fields(model))
+
+
+def freeze_tag(value) -> str:
+    """Freeze JSON-safe tags as text; reject nonstring keys and nonfinite numbers."""
+
+    def validate(item):
+        if isinstance(item, dict):
+            if not all(isinstance(key, str) for key in item):
+                raise TypeError("tag mapping keys must be strings")
+            for child in item.values():
+                validate(child)
+        elif isinstance(item, list):
+            for child in item:
+                validate(child)
+        elif item is not None and not isinstance(item, (str, bool, int, float)):
+            raise TypeError("tag supports only plain JSON values")
+
+    validate(value)
+    return json.dumps(value, ensure_ascii=False, allow_nan=False, sort_keys=True)

openbacktesting/broker/observations.py

@@ -0,0 +1,99 @@
+"""Read-only execution observations: independent sequence, effective price ranges, and lot extrema."""
+
+from openbacktesting.broker.models import record
+
+
+def _update_extrema(state, bar_index, favorable, adverse):
+    # Initialize at zero; strict comparisons exclude negative magnitudes and preserve the first position of tied extrema.
+    if favorable > state["mfe"]:
+        state["mfe"], state["mfeBar"] = favorable, bar_index
+    if adverse > state["mae"]:
+        state["mae"], state["maeBar"] = adverse, bar_index
+
+
+class Observations:
+    def __init__(self):
+        self.rows = []
+        self.lots = {}
+        self.closed = {}
+        self.changed_bar = -1
+
+    def sample(
+        self,
+        broker,
+        price,
+        phase,
+        *,
+        ordered=True,
+        coverage="complete_under_bar_model",
+        facts=None,
+        range_eligible=False,
+    ):
+        if facts is None:
+            position = broker.ledger.position(broker.trades, price)
+            facts = record(broker.ledger.account(position, broker.margin)) | record(position)
+        row = {
+            "observationId": f"observation-{len(self.rows) + 1}",
+            "observationSequence": len(self.rows) + 1,
+            "barIndex": broker._i,
+            "phase": phase,
+            "price": price,
+            "fillSequence": broker.fills[-1].sequence if broker.fills else 0,
+            "ordered": ordered,
+            "coverage": coverage,
+            "rangeEligible": range_eligible,
+            **facts,
+        }
+        self.rows.append(row)
+        return row
+
+    def mark(self, broker, trade, price, *, partial=False):
+        state = self.lots[trade.trade_id]
+        value = (price - trade.entry_price) * (1 if trade.size > 0 else -1)
+        _update_extrema(state, broker._i, value, -value)
+        state["partial"] |= partial
+
+    def before(self, broker, price, phase, conditional):
+        self.sample(
+            broker,
+            price,
+            "before_" + phase,
+            coverage="partial" if conditional else "complete_under_bar_model",
+        )
+        for trade in broker.trades:
+            self.mark(broker, trade, price, partial=conditional)
+        if conditional or phase == "close":
+            self.changed_bar = broker._i
+
+    def opened(self, broker, trade, conditional, phase):
+        self.lots[trade.trade_id] = {
+            "mfe": 0.0,
+            "mae": 0.0,
+            "mfeBar": broker._i,
+            "maeBar": broker._i,
+            "partial": conditional,
+            "firstFullBar": broker._i + int(conditional or phase != "execute"),
+        }
+
+    def close(self, trade, allocation_id):
+        self.closed[allocation_id] = self.lots[trade.trade_id].copy()
+
+    def mark_bar(self, broker):
+        high, low = (broker._data._current_value(n) for n in ("High", "Low"))
+        if high < low:
+            high, low = low, high
+        for trade in broker.trades:
+            state = self.lots[trade.trade_id]
+            if state["firstFullBar"] <= broker._i:
+                entry = trade.entry_price
+                if trade.size > 0:
+                    favorable, adverse = high - entry, entry - low
+                else:
+                    favorable, adverse = entry - low, high - entry
+                _update_extrema(state, broker._i, favorable, adverse)
+            else:
+                self.mark(broker, trade, broker.last_price)
+
+    def bar(self, broker):
+        self.mark_bar(broker)
+        self.sample(broker, broker.last_price, "bar", range_eligible=self.changed_bar != broker._i)