openbacktesting 0.2.0__py3-none-any.whl

openbacktesting/broker/requests.py

@@ -0,0 +1,192 @@
+"""Author-supplied order descriptions and public argument validation without trading side effects."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Literal, cast, overload
+
+import pandas as pd
+
+from openbacktesting.broker.models import finite, freeze_tag
+from openbacktesting.broker.sizing import UNSET, _SizeIntent, select_size
+
+type _JsonValue = str | int | float | bool | None | list["_JsonValue"] | dict[str, "_JsonValue"]
+type _Expiry = datetime | pd.Timestamp | str
+
+
+def _normalize_conditions(
+    *,
+    limit=None,
+    stop=None,
+    sl=None,
+    tp=None,
+    tag=None,
+    reduce_only=False,
+    expires_at=None,
+    valid_bars=None,
+) -> dict:
+    """Normalize conditions requiring no account or instrument; do not modify caller data."""
+    if type(reduce_only) is not bool:
+        raise TypeError("reduce_only must be bool")
+    prices = {
+        name: None if value is None else finite(value, name, positive=True)
+        for name, value in (("limit", limit), ("stop", stop), ("sl", sl), ("tp", tp))
+    }
+    if expires_at is not None and valid_bars is not None:
+        raise ValueError("expires_at and valid_bars are mutually exclusive")
+    if valid_bars is not None and (
+        isinstance(valid_bars, bool) or not isinstance(valid_bars, int) or valid_bars <= 0
+    ):
+        raise ValueError("valid_bars must be a positive integer")
+    if expires_at is not None:
+        if not isinstance(expires_at, (datetime, pd.Timestamp, str)):
+            raise TypeError("expires_at must be a timezone-aware timestamp or string")
+        expires_at = pd.Timestamp(expires_at)
+        if pd.isna(expires_at):
+            raise ValueError("expires_at must not be NaT")
+        if expires_at.tzinfo is None:
+            raise ValueError("Absolute expiration must be timezone-aware")
+    return prices | {
+        "reduce_only": reduce_only,
+        "expires_at": expires_at,
+        "valid_bars": valid_bars,
+        "tag_json": freeze_tag(tag),
+    }
+
+
+@dataclass(frozen=True, init=False)
+class OrderRequest:
+    """Frozen entry request awaiting submission; construction does not register an order and is allowed during initialization.
+
+    All arguments must be supplied by name. Instrument precision, market-data timezone, and protection direction are validated at submission.
+    ``tag`` supports plain JSON values; it is frozen at construction, and reads return independent copies.
+
+    Args:
+        side: Buy (buy) or sell (sell).
+        qty: Finite positive asset quantity; choose exactly one of qty/amount/percent, without using a default budget.
+        amount: Finite positive notional amount, converted using Close at submission without reserving fees.
+        percent: Equity percentage in (0,100]; 20 means 20%, calculated at submission.
+        limit: Entry limit price; None means no limit condition.
+        stop: Entry trigger price, distinct from the post-entry sl.
+        sl: Absolute post-entry stop-loss price.
+        tp: Absolute post-entry take-profit price.
+        tag: Optional user tag, excluded from matching conditions.
+        expires_at: Timezone-aware absolute expiration, mutually exclusive with valid_bars.
+        valid_bars: Number of bars eligible for execution after submission; must be a positive integer.
+
+    Raises:
+        TypeError: Invalid argument types, names, or tag types.
+        ValueError: Invalid quantity, price, direction, or expiration values.
+    """
+
+    side: Literal["buy", "sell"]
+    _size: _SizeIntent
+    limit: float | None = None
+    stop: float | None = None
+    sl: float | None = None
+    tp: float | None = None
+    expires_at: pd.Timestamp | None = None
+    valid_bars: int | None = None
+    _tag_json: str = field(default="null", repr=False)
+
+    @overload
+    def __init__(
+        self,
+        *,
+        side: Literal["buy", "sell"],
+        qty: float,
+        limit: float | None = None,
+        stop: float | None = None,
+        sl: float | None = None,
+        tp: float | None = None,
+        tag: _JsonValue = None,
+        expires_at: _Expiry | None = None,
+        valid_bars: int | None = None,
+    ) -> None:
+        """Explicit asset-quantity intent."""
+
+    @overload
+    def __init__(
+        self,
+        *,
+        side: Literal["buy", "sell"],
+        amount: float,
+        limit: float | None = None,
+        stop: float | None = None,
+        sl: float | None = None,
+        tp: float | None = None,
+        tag: _JsonValue = None,
+        expires_at: _Expiry | None = None,
+        valid_bars: int | None = None,
+    ) -> None:
+        """Explicit notional-amount intent, converted at submission."""
+
+    @overload
+    def __init__(
+        self,
+        *,
+        side: Literal["buy", "sell"],
+        percent: float,
+        limit: float | None = None,
+        stop: float | None = None,
+        sl: float | None = None,
+        tp: float | None = None,
+        tag: _JsonValue = None,
+        expires_at: _Expiry | None = None,
+        valid_bars: int | None = None,
+    ) -> None:
+        """Explicit equity-percentage intent, converted at submission."""
+
+    def __init__(
+        self,
+        *,
+        side: Literal["buy", "sell"],
+        qty: float = cast(float, UNSET),
+        amount: float = cast(float, UNSET),
+        percent: float = cast(float, UNSET),
+        limit: float | None = None,
+        stop: float | None = None,
+        sl: float | None = None,
+        tp: float | None = None,
+        tag: _JsonValue = None,
+        expires_at: _Expiry | None = None,
+        valid_bars: int | None = None,
+    ) -> None:
+        if side not in ("buy", "sell"):
+            raise ValueError("side must be buy/sell")
+        size = select_size(qty=qty, amount=amount, percent=percent)
+        values = _normalize_conditions(
+            limit=limit,
+            stop=stop,
+            sl=sl,
+            tp=tp,
+            tag=tag,
+            expires_at=expires_at,
+            valid_bars=valid_bars,
+        )
+        values.pop("reduce_only")
+        values["_tag_json"] = values.pop("tag_json")
+        for name, value in (values | {"side": side, "_size": size}).items():
+            object.__setattr__(self, name, value)
+
+    @property
+    def qty(self) -> float | None:
+        """Explicit asset quantity; None in other modes."""
+        return self._size.value if self._size.mode == "qty" else None
+
+    @property
+    def amount(self) -> float | None:
+        """Explicit notional amount; converted at submission, None in other modes."""
+        return self._size.value if self._size.mode == "amount" else None
+
+    @property
+    def percent(self) -> float | None:
+        """Explicit equity percentage (20 means 20%); None in other modes."""
+        return self._size.value if self._size.mode == "percent" else None
+
+    @property
+    def tag(self) -> _JsonValue:
+        """Independent JSON tag copy; modifying it does not change the request."""
+        return json.loads(self._tag_json)

openbacktesting/broker/sizing.py

@@ -0,0 +1,76 @@
+"""Pure order-sizing resolution: intents are not bound to a run, and budgets use only explicit submission context."""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Literal
+
+from openbacktesting.broker.instrument import InstrumentSpec
+from openbacktesting.broker.models import AccountSnapshot, OrderSizingSnapshot, finite
+
+
+class _Unset(Enum):
+    VALUE = "omitted"
+
+
+UNSET = _Unset.VALUE
+
+
+@dataclass(frozen=True)
+class _SizeIntent:
+    mode: Literal["qty", "amount", "percent"]
+    value: float
+    source: Literal["explicit", "default"] = "explicit"
+
+
+def select_size(*, qty=UNSET, amount=UNSET, percent=UNSET, default=None, reduce_only=False):
+    """Validate sizing selection; None is explicitly invalid, and defaults apply only when all choices are omitted."""
+    if type(reduce_only) is not bool:
+        raise TypeError("reduce_only must be bool")
+    supplied = [
+        (mode, value)
+        for mode, value in (("qty", qty), ("amount", amount), ("percent", percent))
+        if value is not UNSET
+    ]
+    if len(supplied) > 1:
+        raise TypeError("qty, amount, and percent are mutually exclusive")
+    if reduce_only and (not supplied or supplied[0][0] != "qty"):
+        raise TypeError("Reduce-only orders require an explicit qty")
+    if not supplied:
+        if default is None:
+            raise TypeError("Supply one of qty, amount, or percent, or configure a default quantity")
+        return default
+    mode, value = supplied[0]
+    value = finite(value, mode, positive=True)
+    if mode == "percent" and value > 100:
+        raise ValueError("percent must be in (0,100]; 20 means 20%")
+    return _SizeIntent(mode, value)
+
+
+def resolve_size(
+    intent: _SizeIntent,
+    *,
+    account: AccountSnapshot,
+    reference_price: float,
+    instrument: InstrumentSpec,
+    reduce_only: bool = False,
+) -> OrderSizingSnapshot:
+    """Convert using the requested Close; validate explicit quantity strictly and round budgets toward zero without reserving fees."""
+    price = finite(reference_price, "reference_price", positive=True)
+    equity = finite(account.equity, "equity", positive=intent.mode == "percent")
+    budget = None
+    raw_qty = intent.value
+    if intent.mode != "qty":
+        budget = finite(
+            equity * (intent.value / 100) if intent.mode == "percent" else intent.value,
+            "budget",
+            positive=True,
+        )
+        raw_qty = finite(budget / price, "Budgeted quantity", positive=True)
+    floor = intent.mode != "qty" or intent.source == "default"
+    qty = instrument.quantity(raw_qty, floor=floor, opening=not reduce_only)
+    if floor:
+        if qty == 0:
+            raise ValueError("Quantity budget failed: below_min_quantity")
+        if finite(qty * price, "Budgeted notional amount") < instrument.min_notional:
+            raise ValueError("Quantity budget failed: below_min_notional")
+    return OrderSizingSnapshot(intent.mode, intent.source, intent.value, equity, price, budget, qty)

openbacktesting/colors.py

@@ -0,0 +1,175 @@
+"""Immutable RGBA color values and fixed presets independent of renderers and runtime context."""
+
+from __future__ import annotations
+
+import re as _re
+from dataclasses import dataclass as _dataclass
+from math import floor as _floor
+from math import isfinite as _isfinite
+
+
+def _alpha(transparency):
+    if type(transparency) not in (int, float):
+        raise TypeError("Transparency must be a Python int or float; bool is not accepted")
+    if not 0 <= transparency <= 100:
+        raise ValueError("Transparency must be a finite number from 0 to 100")
+    return _floor(255 * (100 - transparency) / 100 + 0.5)
+
+
+@_dataclass(frozen=True, slots=True)
+class Color:
+    """Immutable color compared by all four channels; alpha means opacity, with no implicit equality to strings.
+
+    Args:
+        red: Native Python int red component from 0 to 255.
+        green: Native Python int green component from 0 to 255.
+        blue: Native Python int blue component from 0 to 255.
+        alpha: Native Python int from 0 to 255; 0 is fully transparent, 255 is opaque.
+
+    Raises:
+        TypeError: A channel is not a native int, including bool.
+        ValueError: A channel is outside its range.
+    """
+
+    red: int
+    green: int
+    blue: int
+    alpha: int = 255
+
+    def __post_init__(self):
+        for value in (self.red, self.green, self.blue, self.alpha):
+            if type(value) is not int:
+                raise TypeError("Color channels must be Python int values; bool is not accepted")
+            if not 0 <= value <= 255:
+                raise ValueError("Color channels must be in 0–255")
+
+    @classmethod
+    def from_hex(cls, value: str) -> Color:
+        """Parse six- or eight-digit hexadecimal colors; append FF for six digits.
+
+        Args:
+            value: #RRGGBB or #RRGGBBAA without whitespace, in either case.
+
+        Returns:
+            The corresponding color value.
+
+        Raises:
+            TypeError: Input is not a native string.
+            ValueError: Invalid string format; CSS names and shorthand are not accepted.
+        """
+        if type(value) is not str:
+            raise TypeError("Color must be a hexadecimal string")
+        if _re.fullmatch(r"#[0-9a-fA-F]{6}(?:[0-9a-fA-F]{2})?", value) is None:
+            raise ValueError("Color must be #RRGGBB or #RRGGBBAA")
+        rgba = value[1:] + ("FF" if len(value) == 7 else "")
+        return cls(*(int(rgba[i : i + 2], 16) for i in (0, 2, 4, 6)))
+
+    @classmethod
+    def rgb(cls, red: int, green: int, blue: int, *, transparency: float = 0) -> Color:
+        """Construct from integer RGB and 0–100 transparency; 0 is opaque, 100 is fully transparent.
+
+        Transparency accepts only native finite int/float values; invalid types raise TypeError, out-of-range values raise ValueError.
+        Quantize alpha to the nearest byte, rounding half values upward without first rounding the percentage.
+        """
+        return cls(red, green, blue, _alpha(transparency))
+
+    def with_transparency(self, transparency: float) -> Color:
+        """Replace alpha using 0–100 transparency and return a new value; do not modify or multiply the original color.
+
+        Transparency uses the same range, quantization, and exception contract as rgb.
+        """
+        return Color(self.red, self.green, self.blue, _alpha(transparency))
+
+    @classmethod
+    def from_gradient(
+        cls,
+        value: float,
+        *,
+        lower: float,
+        upper: float,
+        lower_color: Color,
+        upper_color: Color,
+    ) -> Color:
+        """Linearly interpolate a scalar between unpremultiplied RGBA bytes at both endpoints; clamp outside the interval.
+
+        Args:
+            value: Finite native int/float; bool is not accepted.
+            lower: Finite lower bound, strictly below upper.
+            upper: Finite upper bound.
+            lower_color: Lower-bound Color; None and strings are not accepted.
+            upper_color: Upper-bound Color.
+
+        Returns:
+            Immutable Color, with each channel rounding half-byte values upward; neither endpoint is modified.
+
+        Raises:
+            TypeError: Invalid numeric or color types.
+            ValueError: Nonfinite values or invalid bound ordering.
+        """
+        for number in (value, lower, upper):
+            if type(number) not in (int, float):
+                raise TypeError("Gradient values and bounds must be Python int or float values")
+            try:
+                valid = _isfinite(number)
+            except OverflowError:
+                valid = False
+            if not valid:
+                raise ValueError("Gradient values and bounds must be finite numbers")
+        if lower >= upper:
+            raise ValueError("Gradient lower must be less than upper")
+        if not isinstance(lower_color, Color) or not isinstance(upper_color, Color):
+            raise TypeError("Gradient endpoints must be Color instances")
+        if value <= lower:
+            return lower_color
+        if value >= upper:
+            return upper_color
+        # upper-lower can overflow for extreme opposite signs; use the original difference for equal signs to avoid losing precision between nearby values.
+        if lower < 0 < upper:
+            scale = max(-lower, upper)
+            ratio = (value / scale - lower / scale) / (upper / scale - lower / scale)
+        else:
+            ratio = (value - lower) / (upper - lower)
+        return cls(
+            *(
+                _floor(a + (b - a) * ratio + 0.5)
+                for a, b in zip(
+                    (lower_color.red, lower_color.green, lower_color.blue, lower_color.alpha),
+                    (upper_color.red, upper_color.green, upper_color.blue, upper_color.alpha),
+                )
+            )
+        )
+
+    @property
+    def transparency(self) -> float:
+        """0–100 transparency derived from quantized alpha; it may differ from the original percentage."""
+        return 100 * (255 - self.alpha) / 255
+
+    def to_hex(self) -> str:
+        """Return uppercase #RRGGBBAA; fully transparent colors retain RGB and do not become None."""
+        return f"#{self.red:02X}{self.green:02X}{self.blue:02X}{self.alpha:02X}"
+
+    def __str__(self) -> str:
+        return self.to_hex()
+
+
+def _as_color(value):
+    return value if isinstance(value, Color) else Color.from_hex(value)
+
+
+AQUA = Color.from_hex("#00BCD4")
+BLACK = Color.from_hex("#363A45")
+BLUE = Color.from_hex("#2196F3")
+FUCHSIA = Color.from_hex("#E040FB")
+GRAY = Color.from_hex("#787B86")
+GREEN = Color.from_hex("#4CAF50")
+LIME = Color.from_hex("#00E676")
+MAROON = Color.from_hex("#880E4F")
+NAVY = Color.from_hex("#311B92")
+OLIVE = Color.from_hex("#808000")
+ORANGE = Color.from_hex("#FF9800")
+PURPLE = Color.from_hex("#9C27B0")
+RED = Color.from_hex("#F23645")
+SILVER = Color.from_hex("#B2B5BE")
+TEAL = Color.from_hex("#089981")
+WHITE = Color.from_hex("#FFFFFF")
+YELLOW = Color.from_hex("#FDD835")

openbacktesting/data/__init__.py

@@ -0,0 +1,20 @@
+"""Compatibility exports for the old data path; implemented in data.core."""
+
+from openbacktesting.data.core import (
+    _Array as _Array,
+)
+from openbacktesting.data.core import (
+    _Data as _Data,
+)
+from openbacktesting.data.core import (
+    _data_period as _data_period,
+)
+from openbacktesting.data.core import (
+    _Indicator as _Indicator,
+)
+from openbacktesting.data.core import (
+    _indicator_warmup_nbars as _indicator_warmup_nbars,
+)
+from openbacktesting.data.core import (
+    _strategy_indicators as _strategy_indicators,
+)

openbacktesting/data/aggregation.py

@@ -0,0 +1,39 @@
+"""Native resampling rules for market data and trades."""
+
+from collections import OrderedDict
+
+OHLCV_AGG = OrderedDict(
+    (
+        ("Open", "first"),
+        ("High", "max"),
+        ("Low", "min"),
+        ("Close", "last"),
+        ("Volume", "sum"),
+    )
+)
+"""Dictionary of rules for aggregating resampled OHLCV data frames,
+e.g.
+
+    df.resample('4H', label='right').agg(OHLCV_AGG).dropna()
+"""
+
+TRADES_AGG = OrderedDict(
+    (
+        ("Size", "sum"),
+        ("EntryBar", "first"),
+        ("ExitBar", "last"),
+        ("EntryPrice", "mean"),
+        ("ExitPrice", "mean"),
+        ("PnL", "sum"),
+        ("ReturnPct", "mean"),
+        ("EntryTime", "first"),
+        ("ExitTime", "last"),
+        ("Duration", "sum"),
+    )
+)
+"""Dictionary of rules for aggregating resampled trades data,
+e.g.
+
+    stats['_trades'].resample('1D', on='ExitTime',
+                              label='right').agg(TRADES_AGG)
+"""

openbacktesting/data/context.py

@@ -0,0 +1,30 @@
+"""Host-provided chart context; instrument specifications are bound separately."""
+
+from dataclasses import dataclass
+from zoneinfo import ZoneInfo
+
+from openbacktesting.data.timeframe import Timeframe
+
+
+@dataclass(frozen=True)
+class DataContext:
+    """Describe the existing market-data timeframe and shared timezone for charts, strategy calendars, and statistics.
+
+    Timezone-aware market data is converted to this timezone before strategy construction; absolute instants and original data remain unchanged.
+    Statistics group by local day boundaries; changing timezone requires a new run, and annualized metrics may differ.
+    Provides no downloading, resampling, or exchange-calendar capability.
+    """
+
+    timeframe: Timeframe
+    timezone: str
+
+    def __post_init__(self):
+        if not isinstance(self.timeframe, Timeframe):
+            raise TypeError("timeframe must be a Timeframe")
+        if not isinstance(self.timezone, str) or not self.timezone:
+            raise TypeError("timezone must be a nonempty IANA timezone string")
+        ZoneInfo(self.timezone)
+
+    def snapshot(self) -> dict:
+        """Return independent plain values without reusing mutable request objects."""
+        return {"timeframe": self.timeframe.snapshot(), "timezone": self.timezone}