openbacktesting 0.2.0__py3-none-any.whl

openbacktesting/runtime.py

@@ -0,0 +1,330 @@
+"""Consume successfully loaded strategy modules; discovery needs no data, and the host injects chart context for execution."""
+
+from collections.abc import Mapping
+from dataclasses import asdict
+from importlib.metadata import version
+from inspect import isabstract
+
+import pandas as pd
+
+from openbacktesting.broker.instrument import InstrumentSpec
+from openbacktesting.data.context import DataContext
+from openbacktesting.indicators.runtime import DEFAULT_CACHE_BYTES
+from openbacktesting.logs import RunLogs
+from openbacktesting.optimizer.query import ExperimentResult
+from openbacktesting.plotting.types import PlottingLimits
+from openbacktesting.simulation.collection import DEFAULT_COLLECTION, CollectionPolicy
+from openbacktesting.simulation.core import Backtest
+from openbacktesting.strategy.base import Strategy
+from openbacktesting.strategy.declaration import declaration
+from openbacktesting.strategy.inputs import describe as describe_inputs
+from openbacktesting.strategy.inputs import resolve_request
+
+
+def discover(namespace: Mapping) -> type[Strategy]:
+    """Discover the single concrete strategy directly decorated in this module; deduplicate aliases and exclude imported and inherited entry points.
+
+    Args:
+        namespace: Successfully loaded module namespace containing a nonempty string __name__.
+
+    Returns:
+        type[Strategy]: Original strategy class, without instance construction.
+
+    Raises:
+        TypeError: Invalid namespace or declaration.
+        ValueError: No entry point or multiple entry points.
+    """
+    if not isinstance(namespace, Mapping):
+        raise TypeError("namespace must be a module mapping")
+    name = namespace.get("__name__")
+    if not isinstance(name, str) or not name:
+        raise TypeError("namespace must contain a nonempty __name__")
+    candidates = {}
+    for value in namespace.values():
+        if (
+            isinstance(value, type)
+            and issubclass(value, Strategy)
+            and value.__module__ == name
+            and not isabstract(value)
+            and declaration(value) is not None
+        ):
+            candidates[id(value)] = value
+    if len(candidates) != 1:
+        names = sorted(f"{cls.__module__}:{cls.__qualname__}" for cls in candidates.values())
+        raise ValueError(f"The module must contain exactly one @backtest strategy; candidates: {names}")
+    return next(iter(candidates.values()))
+
+
+def describe(namespace: Mapping) -> dict:
+    """Export inputs and complete default backtest settings without market data or executing the strategy lifecycle.
+
+    The returned backtest description is independent of input schemaHash; modifying copies does not alter class declarations.
+    """
+    cls = discover(namespace)
+    settings = declaration(cls)
+    return describe_inputs(cls) | {
+        "backtest": {"schemaVersion": 2, "settings": settings.snapshot()}
+    }
+
+
+def run(
+    namespace: Mapping,
+    request: Mapping | None = None,
+    *,
+    data: pd.DataFrame,
+    context: DataContext,
+    instrument: InstrumentSpec,
+    settings: Mapping | None = None,
+    options: Mapping | None = None,
+    logs: RunLogs | None = None,
+) -> pd.Series:
+    """Run a new session for this chart and return existing results plus backtest_snapshot.
+
+    Args:
+        namespace: Module successfully loaded by the host for this run; bt-only exports are no longer accepted.
+        request: Existing title-based input request; None uses defaults.
+        data: Current chart OHLC with a timezone-aware DatetimeIndex.
+        context: Actual timeframe and shared timezone for charts, strategy calendars, and statistics.
+            Convert the internal index before strategy construction, preserving inputs and absolute instants without resampling.
+            Changing timezone requires a new run; local-time conditions and statistics grouped by day may change.
+        instrument: Chart instrument specifications, without inference from market data.
+        settings: Sparse overrides of flat settings; enum fields accept corresponding members or exact strings.
+            Changing types requires supplying a value too; default_qty_value=None clears the default quantity.
+        options: cache budget, plotting, and plotting_limits are host runtime options.
+        logs: Optional host log session; get_logs works after success or exceptions, and sequential reuse clears old records.
+
+    No source loading, cached old instances, or declaration changes; exceptions propagate unchanged.
+    """
+    if logs is not None and not isinstance(logs, RunLogs):
+        raise TypeError("logs must be RunLogs or None")
+    session = RunLogs() if logs is None else logs
+    with session._capture():
+        return _run(namespace, request, data, context, instrument, settings, options, session)
+
+
+def _run(
+    namespace,
+    request,
+    data,
+    context,
+    instrument,
+    settings,
+    options,
+    session,
+    collection=DEFAULT_COLLECTION,
+):
+    cls = discover(namespace)
+    resolved = declaration(cls).resolve(settings)
+    if not isinstance(context, DataContext):
+        raise TypeError("context must be DataContext")
+    if not isinstance(instrument, InstrumentSpec):
+        raise TypeError("instrument must be InstrumentSpec")
+    if options is None:
+        options = {}
+    if not isinstance(options, Mapping):
+        raise TypeError("options must be a mapping or None")
+    defaults = {
+        "indicator_cache_bytes": DEFAULT_CACHE_BYTES,
+        "plotting": True,
+        "plotting_limits": PlottingLimits(),
+    }
+    unknown = set(options).difference(defaults)
+    if unknown:
+        raise ValueError(f"Unknown runtime option: {list(unknown)!r}")
+    effective_options = defaults | dict(options)
+    if effective_options["plotting_limits"] is None:
+        effective_options["plotting_limits"] = PlottingLimits()
+    # Digest and value errors must surface before constructing any strategy, preserving existing title-based entry semantics.
+    if request is not None:
+        resolve_request(cls, request)
+    bt = Backtest(
+        data,
+        cls,
+        context=context,
+        instrument=instrument,
+        _collection=collection,
+        **resolved.kwargs(),
+        **effective_options,
+    )
+    try:
+        result = bt.run() if request is None else bt.run_inputs(request)
+    finally:
+        session._collector = bt._log_collector
+    result.attrs["backtest_snapshot"] = {
+        "schemaVersion": 2,
+        "strategy": {"module": cls.__module__, "qualname": cls.__qualname__},
+        "settings": resolved.snapshot(),
+        "context": context.snapshot(),
+        "instrument": asdict(instrument),
+        "options": effective_options
+        | {"plotting_limits": asdict(effective_options["plotting_limits"])},
+        "engineVersion": version("openbacktesting"),
+    }
+    from openbacktesting.portfolio.snapshot import refresh_snapshot
+
+    refresh_snapshot(result)
+    return result
+
+
+def optimize(
+    namespace: Mapping,
+    search: Mapping,
+    *,
+    path,
+    identity,
+    data: pd.DataFrame,
+    context: DataContext,
+    instrument: InstrumentSpec,
+    request=None,
+    settings=None,
+    constraint=None,
+    constraint_id=None,
+    cancel=None,
+    on_progress=None,
+) -> ExperimentResult:
+    """Exhaustively search selected inputs sequentially, committing each complete Portfolio to a new local result database.
+
+    Unselected values come from the current request; retain only Portfolio without collecting logs/plotting.
+    identity is a host-supplied ExecutionIdentity; the framework computes data/configuration identities.
+    constraint uses complete wire values and requires constraint_id; cancel is a no-argument callable.
+    Return a read-only ExperimentResult; record strategy-trial failures and continue, but stop on storage failures.
+    """
+    return _optimize(
+        namespace,
+        search,
+        path,
+        identity,
+        data,
+        context,
+        instrument,
+        request,
+        settings,
+        constraint,
+        constraint_id,
+        cancel,
+        on_progress,
+        None,
+    )
+
+
+def resume_optimization(
+    namespace: Mapping,
+    *,
+    path,
+    experiment_id: str,
+    identity,
+    data: pd.DataFrame,
+    context: DataContext,
+    instrument: InstrumentSpec,
+    request=None,
+    settings=None,
+    constraint=None,
+    constraint_id=None,
+    cancel=None,
+    on_progress=None,
+) -> ExperimentResult:
+    """Resume unfinished trials after checking current declarations, inputs, and execution identity; failed trials are not automatically retried."""
+    from openbacktesting.optimizer.models import Range, Values
+    from openbacktesting.optimizer.query import open_result
+
+    source = open_result(path, experiment_id).info()["plan"]
+    search = {}
+    for dimension in source["dimensions"]:
+        expression = dimension["expression"]
+        search[dimension["title"]] = (
+            Range(**expression["range"]) if "range" in expression else Values(expression["values"])
+        )
+    return _optimize(
+        namespace,
+        search,
+        path,
+        identity,
+        data,
+        context,
+        instrument,
+        request,
+        settings,
+        constraint,
+        constraint_id,
+        cancel,
+        on_progress,
+        experiment_id,
+    )
+
+
+def _optimize(
+    namespace,
+    search,
+    path,
+    identity,
+    data,
+    context,
+    instrument,
+    request,
+    settings,
+    constraint,
+    constraint_id,
+    cancel,
+    on_progress,
+    experiment_id,
+):
+    from copy import deepcopy
+
+    from openbacktesting.optimizer.identity import execution_identity
+    from openbacktesting.optimizer.models import _ExportError
+    from openbacktesting.optimizer.plan import plan
+    from openbacktesting.optimizer.runner import execute
+    from openbacktesting.portfolio.snapshot import export_result
+
+    cls = discover(namespace)
+    resolved = declaration(cls).resolve(settings)
+    if not isinstance(context, DataContext) or not isinstance(instrument, InstrumentSpec):
+        raise TypeError("optimizer: DataContext and InstrumentSpec must be supplied")
+    frozen = data.copy(deep=True)
+    run_settings = resolved.snapshot()
+    backtest = {
+        "schemaVersion": 2,
+        "settings": run_settings,
+        "context": context.snapshot(),
+        "instrument": asdict(instrument),
+        "engineVersion": version("openbacktesting"),
+    }
+    execution = execution_identity(frozen, identity, backtest)
+    plan_value = plan(
+        cls, search, base_inputs=request, execution=execution, constraint_id=constraint_id
+    )
+    # Construction validation does not execute strategies; reject invalid market data before creating a database or running the first trial.
+    Backtest(
+        frozen, cls, context=context, instrument=instrument, **resolved.kwargs(), plotting=False
+    )
+    namespace = dict(namespace)
+    collection = CollectionPolicy(portfolio=True, logs=False, plotting=False)
+
+    def run_one(inputs_request):
+        session = RunLogs()
+        with session._capture():
+            result = _run(
+                namespace,
+                inputs_request,
+                frozen,
+                context,
+                instrument,
+                deepcopy(run_settings),
+                {"plotting": False},
+                session,
+                collection,
+            )
+        try:
+            return export_result(result)
+        except Exception as error:
+            raise _ExportError(str(error)) from error
+
+    return execute(
+        plan_value,
+        run_one,
+        path,
+        experiment_id=experiment_id,
+        constraint=constraint,
+        cancel=cancel,
+        on_progress=on_progress,
+    )

openbacktesting/simulation/__init__.py

@@ -0,0 +1,17 @@
+"""Lazy class exports for the simulation package; implemented in simulation.core."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from openbacktesting.simulation.core import Backtest as Backtest
+
+__all__ = ["Backtest"]
+
+
+def __getattr__(name):
+    if name == "Backtest":
+        from openbacktesting.simulation.core import Backtest
+
+        globals()[name] = Backtest
+        return Backtest
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

openbacktesting/simulation/collection.py

@@ -0,0 +1,13 @@
+"""Internal run-collection policy; defaults match ordinary backtest behavior."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CollectionPolicy:
+    portfolio: bool = True
+    logs: bool = True
+    plotting: bool = True
+
+
+DEFAULT_COLLECTION = CollectionPolicy()

openbacktesting/simulation/config.py

@@ -0,0 +1,241 @@
+"""Exportable default backtest settings independent of strategies, hosts, and execution lifecycles."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass, fields, replace
+from enum import Enum
+
+from openbacktesting.broker.commission import Commission
+from openbacktesting.broker.execution import Slippage
+from openbacktesting.broker.models import finite
+from openbacktesting.portfolio.rates import validate_risk_free_rate
+
+
+class CommissionType(Enum):
+    """Author-facing commission type; PERCENT uses percentage points, and other members use account amounts."""
+
+    PERCENT = "percent"
+    CASH_PER_ORDER = "cash_per_order"
+    CASH_PER_CONTRACT = "cash_per_contract"
+
+
+class QuantityType(Enum):
+    """Default order size: Fixed asset quantity or a percentage of equity at request time."""
+
+    FIXED = "fixed"
+    PERCENT_OF_EQUITY = "percent_of_equity"
+
+
+class SlippageType(Enum):
+    """Slippage distance: Fixed price units or basis points of price."""
+
+    FIXED = "fixed"
+    BPS = "bps"
+
+
+class ExecutionTiming(Enum):
+    """Execution timing: Process no earlier than the next bar, or process new unconditional market orders at this bar's close."""
+
+    NEXT_OPEN = "next_open"
+    SAME_CLOSE = "same_close"
+
+
+class EndPolicy(Enum):
+    """End policy: Retain marked positions or liquidate actual positions at the final close."""
+
+    MARK_TO_MARKET = "mark_to_market"
+    CLOSE_AT_LAST_CLOSE = "close_at_last_close"
+
+
+_ENUM_FIELDS = {
+    "commission_type": CommissionType,
+    "default_qty_type": QuantityType,
+    "slippage_type": SlippageType,
+    "execution_timing": ExecutionTiming,
+    "end_policy": EndPolicy,
+}
+_PAIRED_FIELDS = (
+    ("commission_type", "commission_value"),
+    ("default_qty_type", "default_qty_value"),
+    ("slippage_type", "slippage_value"),
+)
+
+
+def _decode_enums(values: Mapping) -> dict:
+    """Convert exact strings to corresponding enum members only at the host boundary."""
+    result = dict(values)
+    for name, kind in _ENUM_FIELDS.items():
+        if name not in result:
+            continue
+        value = result[name]
+        if type(value) is str:
+            try:
+                result[name] = kind(value)
+            except ValueError:
+                choices = ", ".join(member.value for member in kind)
+                raise ValueError(f"{name} must be one of: {choices}") from None
+        elif not isinstance(value, kind):
+            raise TypeError(f"{name} must be {kind.__name__} member or corresponding string")
+    return result
+
+
+@dataclass(frozen=True)
+class DefaultOrderSize:
+    """Request budget when ordinary orders omit qty; does not represent a target position or filled notional."""
+
+    mode: str
+    value: float
+
+    def __post_init__(self):
+        if self.mode not in ("fixed", "equity_fraction"):
+            raise ValueError("mode must be fixed or equity_fraction")
+        object.__setattr__(self, "value", finite(self.value, "value", positive=True))
+        if self.mode == "equity_fraction" and self.value > 1:
+            raise ValueError("equity_fraction must be in (0, 1]")
+
+    def snapshot(self) -> dict:
+        """Export independent mode and value."""
+        return {"mode": self.mode, "value": self.value}
+
+    @classmethod
+    def from_snapshot(cls, value: Mapping) -> "DefaultOrderSize":
+        """Strictly restore complete configuration without filling missing fields."""
+        if not isinstance(value, Mapping):
+            raise TypeError("DefaultOrderSize snapshot must be a mapping")
+        if set(value) != {"mode", "value"}:
+            raise ValueError("DefaultOrderSize snapshot has missing or unknown fields")
+        return cls(value["mode"], value["value"])
+
+
+def validate_order_size(value: DefaultOrderSize | None) -> DefaultOrderSize | None:
+    """Accept only validated immutable models or explicit clearing."""
+    if value is not None and not isinstance(value, DefaultOrderSize):
+        raise TypeError("default_order_size must be DefaultOrderSize or None")
+    return value
+
+
+@dataclass(frozen=True)
+class BacktestSettings:
+    """Flat immutable author-facing settings; validate enums and numbers after decoding at the host boundary."""
+
+    cash: float = 10_000
+    spread: float = 0.0
+    commission_type: CommissionType = CommissionType.PERCENT
+    commission_value: float = 0.0
+    risk_free_rate: float = 0.0
+    default_qty_type: QuantityType = QuantityType.FIXED
+    default_qty_value: float | None = None
+    margin: float = 1.0
+    execution_timing: ExecutionTiming = ExecutionTiming.NEXT_OPEN
+    slippage_type: SlippageType = SlippageType.BPS
+    slippage_value: float = 0.0
+    allow_short: bool = True
+    max_gross_exposure: float | None = None
+    hedging: bool = False
+    exclusive_orders: bool = False
+    end_policy: EndPolicy = EndPolicy.MARK_TO_MARKET
+
+    def __post_init__(self):
+        for name, kind in _ENUM_FIELDS.items():
+            if not isinstance(getattr(self, name), kind):
+                raise TypeError(f"{name} must be {kind.__name__} member")
+        object.__setattr__(self, "risk_free_rate", validate_risk_free_rate(self.risk_free_rate))
+        for name in ("cash", "margin"):
+            object.__setattr__(self, name, finite(getattr(self, name), name, positive=True))
+        spread = finite(self.spread, "spread")
+        object.__setattr__(self, "spread", spread)
+        if self.margin > 1:
+            raise ValueError("margin must be in (0,1]")
+        if not 0 <= spread < 1:
+            raise ValueError("spread must be in [0,1)")
+        if self.max_gross_exposure is not None:
+            object.__setattr__(
+                self,
+                "max_gross_exposure",
+                finite(self.max_gross_exposure, "max_gross_exposure", positive=True),
+            )
+        for name in ("allow_short", "hedging", "exclusive_orders"):
+            if type(getattr(self, name)) is not bool:
+                raise TypeError(f"{name} must be bool")
+        value = finite(self.commission_value, "commission_value")
+        if self.commission_type is CommissionType.PERCENT:
+            if not -10 <= value < 10:
+                raise ValueError("commission_value percentage must be in [-10,10)")
+        elif value < 0:
+            raise ValueError("commission_value amount must not be negative")
+        object.__setattr__(self, "commission_value", value)
+        if self.default_qty_value is not None:
+            value = finite(self.default_qty_value, "default_qty_value", positive=True)
+            if self.default_qty_type is QuantityType.PERCENT_OF_EQUITY and value > 100:
+                raise ValueError("default_qty_value equity percentage must be in (0,100]")
+            object.__setattr__(self, "default_qty_value", value)
+        value = finite(self.slippage_value, "slippage_value")
+        if value < 0:
+            raise ValueError("slippage_value must not be negative")
+        object.__setattr__(self, "slippage_value", value)
+
+    def _values(self) -> dict:
+        return {field.name: getattr(self, field.name) for field in fields(self)}
+
+    def kwargs(self) -> dict:
+        """Adapt to low-level Backtest arguments, separately from flat snapshots and the override allowlist."""
+        result = self._values()
+        for type_name, value_name in _PAIRED_FIELDS:
+            del result[type_name], result[value_name]
+        if self.commission_type is CommissionType.PERCENT:
+            commission = Commission(relative=self.commission_value / 100)
+        elif self.commission_type is CommissionType.CASH_PER_ORDER:
+            commission = Commission(fixed=self.commission_value)
+        else:
+            commission = Commission(per_unit=self.commission_value)
+        size = None
+        if self.default_qty_value is not None:
+            size = (
+                DefaultOrderSize("fixed", self.default_qty_value)
+                if self.default_qty_type is QuantityType.FIXED
+                else DefaultOrderSize("equity_fraction", self.default_qty_value / 100)
+            )
+        return result | {
+            "commission": commission,
+            "default_order_size": size,
+            "slippage": Slippage(self.slippage_type.value, self.slippage_value),
+            "execution_timing": self.execution_timing.value,
+            "end_policy": self.end_policy.value,
+        }
+
+    def resolve(self, overrides: Mapping | None) -> "BacktestSettings":
+        """Decode sparse host overrides; a changed type must be supplied together with a new value."""
+        if overrides is None:
+            overrides = {}
+        if not isinstance(overrides, Mapping):
+            raise TypeError("settings must be a mapping or None")
+        unknown = set(overrides).difference(self._values())
+        if unknown:
+            raise ValueError(f"Unknown backtest setting: {list(unknown)!r}")
+        values = _decode_enums(overrides)
+        for type_name, value_name in _PAIRED_FIELDS:
+            if (
+                type_name in values
+                and values[type_name] is not getattr(self, type_name)
+                and value_name not in values
+            ):
+                raise ValueError(f"Changing {type_name} requires also supplying {value_name}")
+        return replace(self, **values)
+
+    def snapshot(self) -> dict:
+        """Export all flat fields; enums become strings and percentages retain author units."""
+        return {
+            name: value.value if isinstance(value, Enum) else value
+            for name, value in self._values().items()
+        }
+
+    @classmethod
+    def from_snapshot(cls, value: Mapping) -> "BacktestSettings":
+        """Strictly restore complete JSON settings; sparse fields and Python enums are not accepted."""
+        if not isinstance(value, Mapping):
+            raise TypeError("Backtest settings snapshot must be a mapping")
+        if set(value) != {field.name for field in fields(cls)}:
+            raise ValueError("Backtest settings snapshot has missing or unknown fields")
+        for name, item in value.items():
+            if type(item) not in (str, int, float, bool, type(None)):
+                raise TypeError(f"{name} must be a JSON primitive")
+        return cls(**_decode_enums(value))