openbacktesting 0.2.0__py3-none-any.whl

openbacktesting/indicators/volume/pvt.py

@@ -0,0 +1,10 @@
+"""ta.pvt: Computation wrapper for the pinned dependency with canonical outputs."""
+
+from pandas_ta_classic.volume.pvt import pvt as _calculate
+
+from ..common import named_series
+
+
+def compute(*, close, volume, drift, talib):
+    result = _calculate(close=close, volume=volume, drift=drift, talib=talib)
+    return named_series(result, "ta.pvt", "pvt")

openbacktesting/indicators/volume/rvol.py

@@ -0,0 +1,8 @@
+"""ta.rvol: Independent formula with a fixed initialization contract."""
+
+from ..calculus import clean, ratio
+
+
+def compute(*, volume, length):
+    volume = clean(volume)
+    return ratio(volume, volume.shift(1).rolling(length).mean()).rename("rvol")

openbacktesting/indicators/volume/vfi.py

@@ -0,0 +1,18 @@
+"""ta.vfi: Computation wrapper for the pinned dependency with canonical outputs."""
+
+from pandas_ta_classic.volume.vfi import vfi as _calculate
+
+from ..common import named_series
+
+
+def compute(*, close, volume, length, coef, vcoef, mamode, talib):
+    result = _calculate(
+        close=close,
+        volume=volume,
+        length=length,
+        coef=coef,
+        vcoef=vcoef,
+        mamode=mamode,
+        talib=talib,
+    )
+    return named_series(result, "ta.vfi", "vfi")

openbacktesting/indicators/volume/vosc.py

@@ -0,0 +1,10 @@
+"""ta.vosc: Computation wrapper for the pinned dependency with canonical outputs."""
+
+from pandas_ta_classic.volume.vosc import vosc as _calculate
+
+from ..common import named_series
+
+
+def compute(*, volume, fast, slow, talib):
+    result = _calculate(volume=volume, fast=fast, slow=slow, talib=talib)
+    return named_series(result, "ta.vosc", "vosc")

openbacktesting/indicators/volume/wad.py

@@ -0,0 +1,10 @@
+"""ta.wad: Computation wrapper for the pinned dependency with canonical outputs."""
+
+from pandas_ta_classic.volume.wad import wad as _calculate
+
+from ..common import named_series
+
+
+def compute(*, high, low, close, talib):
+    result = _calculate(high=high, low=low, close=close, talib=talib)
+    return named_series(result, "ta.wad", "wad")

openbacktesting/indicators/volume/wvad.py

@@ -0,0 +1,9 @@
+"""ta.wvad: Independent formula with a fixed initialization contract."""
+
+from ..calculus import clean, ratio
+
+
+def compute(*, open_, high, low, close, volume):
+    return ratio(clean(volume) * (clean(close) - clean(open_)), clean(high) - clean(low)).rename(
+        "wvad"
+    )

openbacktesting/inputs.py

@@ -0,0 +1,51 @@
+"""Compatibility exports for the old inputs path; implemented in strategy.inputs."""
+
+from openbacktesting.strategy.inputs import (
+    _SAFE_INT,  # noqa: F401 — re-export the legacy entry point
+    _UNSET,  # noqa: F401 — re-export the legacy entry point
+    SCHEMA_VERSION,
+    InputError,
+    InputSpec,
+    ResolvedInputs,
+    _collect,  # noqa: F401 — re-export the legacy entry point
+    _definitions,  # noqa: F401 — re-export the legacy entry point
+    _fail,  # noqa: F401 — re-export the legacy entry point
+    _make,  # noqa: F401 — re-export the legacy entry point
+    _resolve,  # noqa: F401 — re-export the legacy entry point
+    _scalar,  # noqa: F401 — re-export the legacy entry point
+    _schema,  # noqa: F401 — re-export the legacy entry point
+    _session,  # noqa: F401 — re-export the legacy entry point
+    bool,
+    color,
+    describe,
+    enum,
+    float,
+    int,
+    price,
+    request_for,
+    resolve_native,
+    resolve_request,
+    session,
+    string,
+    time,
+)
+
+__all__ = [
+    "SCHEMA_VERSION",
+    "InputError",
+    "InputSpec",
+    "ResolvedInputs",
+    "bool",
+    "color",
+    "describe",
+    "enum",
+    "float",
+    "int",
+    "price",
+    "request_for",
+    "resolve_native",
+    "resolve_request",
+    "session",
+    "string",
+    "time",
+]

openbacktesting/lib.py

@@ -0,0 +1,31 @@
+"""Legacy entry point for convenience APIs; each domain directly re-exports the same objects."""
+
+from openbacktesting.data.aggregation import OHLCV_AGG, TRADES_AGG
+from openbacktesting.data.generators import random_ohlc_data
+from openbacktesting.portfolio.helpers import compute_stats
+from openbacktesting.simulation.core import Backtest  # noqa: F401
+from openbacktesting.simulation.variants import FractionalBacktest, MultiBacktest
+from openbacktesting.strategy.base import Strategy  # noqa: F401
+from openbacktesting.strategy.helpers import barssince, quantile, resample_apply
+from openbacktesting.strategy.templates import SignalStrategy, TrailingStrategy
+
+__pdoc__ = {
+    "Strategy.__init__": False,
+    "SignalStrategy.__init__": False,
+    "TrailingStrategy.__init__": False,
+}
+
+__all__ = [  # noqa: RUF022 — preserve existing export order
+    "OHLCV_AGG",
+    "TRADES_AGG",
+    "barssince",
+    "quantile",
+    "compute_stats",
+    "resample_apply",
+    "random_ohlc_data",
+    "SignalStrategy",
+    "TrailingStrategy",
+    "FractionalBacktest",
+    "FractionalBacktest",  # noqa: RUF068 — preserve existing duplicate exports
+    "MultiBacktest",
+]

openbacktesting/logs.py

@@ -0,0 +1,129 @@
+"""Independent strategy logs for each historical run; no connection to global Python logging or output streams."""
+
+from contextlib import contextmanager as _contextmanager
+from datetime import UTC
+from datetime import datetime as _datetime
+from inspect import currentframe as _currentframe
+from threading import Lock as _Lock
+from typing import NamedTuple as _NamedTuple
+
+
+class _Record(_NamedTuple):
+    sequence: int
+    level: str
+    message: str
+    phase: str
+    bar_index: int | None
+    bar_time: str | None
+    time_kind: str
+    recorded_at: str
+    source_file: str | None
+    source_line: int | None
+
+
+class _Collector:
+    def __init__(self, *, enabled=True):
+        self.enabled = enabled
+        self._records: list[_Record] = []
+        self._context = None
+        self._closed = False
+
+    @_contextmanager
+    def phase(self, phase, bar_index=None, bar_time=None, time_kind="none"):
+        if self._closed:
+            raise RuntimeError("Strategy log session has ended")
+        self._context = (phase, bar_index, bar_time, time_kind)
+        try:
+            yield
+        finally:
+            self._context = None
+
+    def close(self):
+        self._closed = True
+        self._context = None
+
+    def snapshot(self) -> list[dict[str, str | int | None]]:
+        return [record._asdict() for record in self._records]
+
+
+class StrategyLog:
+    """Read-only strategy log handle, accessed through self.log without author construction.
+
+    Record strings inside active author callbacks; error denotes only a level and does not stop the backtest.
+    Automatically record the actual calling file and line; calls after termination raise RuntimeError.
+    """
+
+    def __init__(self, collector: _Collector):
+        self._collector = collector
+
+    def info(self, message: str) -> None:
+        """Record informational messages, preserving empty strings, Chinese text, and newlines."""
+        self._write("info", message)
+
+    def warning(self, message: str) -> None:
+        """Record warning messages without changing strategy execution."""
+        self._write("warning", message)
+
+    def error(self, message: str) -> None:
+        """Record error-level messages; authors must explicitly raise to stop the strategy."""
+        self._write("error", message)
+
+    def _write(self, level, message):
+        if not isinstance(message, str):
+            raise TypeError("Strategy log message must be a string")
+        collector = self._collector
+        if collector._context is None:
+            raise RuntimeError("Strategy logs can only be written inside active author callbacks")
+        if not collector.enabled:
+            return
+        source_file, source_line = None, None
+        frame = _currentframe()
+        caller = None
+        try:
+            # Skip this function and the three public level methods explicitly; do not scan author helper functions.
+            caller = frame.f_back if frame is not None else None
+            caller = caller.f_back if caller is not None else None
+            if caller is not None:
+                filename, lineno = caller.f_code.co_filename, caller.f_lineno
+                if filename and lineno > 0:
+                    source_file, source_line = filename, lineno
+        finally:
+            del frame, caller
+        collector._records.append(
+            _Record(
+                len(collector._records) + 1,
+                level,
+                message,
+                *collector._context,
+                _datetime.now(UTC).isoformat(timespec="microseconds"),
+                source_file,
+                source_line,
+            )
+        )
+
+
+class RunLogs:
+    """Host-owned single-run log session, injected through runtime.run(..., logs=session).
+
+    Sequential reuse clears records before strategy discovery; a session cannot serve concurrent runs.
+    Queryable after success or exceptional exit; returns list and dictionary copies without holding author stack frames.
+    """
+
+    def __init__(self):
+        self._collector = _Collector()
+        self._lock = _Lock()
+
+    def get_logs(self) -> list[dict[str, str | int | None]]:
+        """Return an independent copy of all logs from this run; an empty list before the first run."""
+        return self._collector.snapshot()
+
+    @_contextmanager
+    def _capture(self):
+        if not self._lock.acquire(blocking=False):
+            raise RuntimeError("RunLogs is already occupied by another run")
+        try:
+            self._collector = _Collector()
+            yield
+        finally:
+            self._collector.close()
+            self._lock.release()

openbacktesting/optimization.py

@@ -0,0 +1,8 @@
+"""Compatibility exports for the old optimization path; implemented in backtest.optimization."""
+
+from openbacktesting.simulation.optimization import (
+    _joined_pool,  # noqa: F401 — re-export the legacy entry point
+    _optimize,  # noqa: F401 — re-export the legacy entry point
+)
+
+__all__ = []

openbacktesting/optimizer/__init__.py

@@ -0,0 +1,25 @@
+"""Exhaustive parameter search, local storage of individual Portfolios, and subsequent queries."""
+
+from openbacktesting.optimizer import identity as identity
+from openbacktesting.optimizer.models import (
+    ExecutionIdentity,
+    OptimizationError,
+    Plan,
+    Range,
+    Values,
+)
+from openbacktesting.optimizer.plan import plan
+from openbacktesting.optimizer.query import ExperimentResult, open_result
+from openbacktesting.optimizer.runner import execute
+
+__all__ = [
+    "ExecutionIdentity",
+    "ExperimentResult",
+    "OptimizationError",
+    "Plan",
+    "Range",
+    "Values",
+    "execute",
+    "open_result",
+    "plan",
+]

openbacktesting/optimizer/_semantics.py

@@ -0,0 +1,155 @@
+# Generated by scripts/generate-contracts.mjs; do not edit manually.
+"""Cross-table Portfolio semantics; Schema ensures structure first, then this layer rejects inconsistent references."""
+
+import math
+
+
+def check_portfolio(p):
+    def require(ok, reason):
+        if not ok:
+            raise ValueError("portfolio-result: " + reason)
+
+    def unique(rows, key):
+        values = [r[key] for r in rows]
+        require(len(values) == len(set(values)), "duplicate_" + key)
+        return {r[key]: r for r in rows}
+
+    def close(a, b):
+        return math.isclose(a, b, rel_tol=1e-9, abs_tol=1e-8)
+
+    facts, trades, series = p["facts"], p["trades"], p["series"]
+    orders = unique(facts["orders"], "order_id")
+    fills = unique(facts["fills"], "fill_id")
+    allocations = unique(facts["allocations"], "allocation_id")
+    observations = unique(series["account"], "observationId")
+    fragments = unique(trades["closedFragments"], "fragmentId")
+    unique(trades["openLots"], "lotId")
+    require(bool(observations), "empty_observations")
+    require(
+        [r["observationSequence"] for r in observations.values()]
+        == list(range(1, len(observations) + 1)),
+        "observation_sequence",
+    )
+    require(
+        all(
+            a["barIndex"] <= b["barIndex"] for a, b in zip(series["account"], series["account"][1:])
+        ),
+        "bar_order",
+    )
+    require(series["account"][-1]["barIndex"] == p["run"]["processedThroughBar"], "executed_range")
+    for r in series["account"]:
+        require(0 <= r["barIndex"] <= p["run"]["processedThroughBar"], "bar_range")
+    for rows in (facts["orderSizing"], facts["orderEvents"], facts["fills"]):
+        require(all(r["order_id"] in orders for r in rows), "order_reference")
+    for table in (facts["fills"], facts["orderEvents"]):
+        seq = [r["sequence"] for r in table]
+        require(seq == sorted(set(seq)), "event_sequence")
+    require(
+        all(
+            r["fillSequence"] in {0} | {f["sequence"] for f in fills.values()}
+            for r in series["account"]
+        ),
+        "fill_sequence_reference",
+    )
+    for a in allocations.values():
+        require(a["fill_id"] in fills and a["entry_fill_id"] in fills, "fill_reference")
+    require(
+        set(fragments)
+        == {a["allocation_id"] for a in allocations.values() if a["kind"] == "close"},
+        "fragment_allocations",
+    )
+    require(
+        [t["displayOrdinal"] for t in fragments.values()] == list(range(1, len(fragments) + 1)),
+        "fragment_order",
+    )
+    for t in list(fragments.values()) + trades["openLots"]:
+        require(
+            t["entry"]["fillId"] in fills and t["entry"]["orderId"] in orders, "entry_reference"
+        )
+    for t in fragments.values():
+        require(t["exit"]["fillId"] in fills and t["exit"]["orderId"] in orders, "exit_reference")
+        require(allocations[t["fragmentId"]]["trade_id"] == t["lotId"], "lot_reference")
+        require(close(t["pnlNet"], t["pnlGross"] - t["feeTotal"]), "trade_accounting")
+    require(all(t["asOf"] in observations for t in trades["openLots"]), "open_asof")
+    for row in series["close"]:
+        require(row == observations.get(row["observationId"]), "close_reference")
+    require(len(series["margin"]) == len(observations), "margin_length")
+    for row, account in zip(series["margin"], series["account"]):
+        require(row["observationId"] == account["observationId"], "margin_axis")
+    for curve in series["directions"].values():
+        require(len(curve) == len(observations), "direction_length")
+        for row, account in zip(curve, series["account"]):
+            require(row["observationId"] == account["observationId"], "direction_axis")
+    initial = p["summary"]["all"]["initialCapital"]["value"]
+    for row, long, short in zip(
+        series["account"], series["directions"]["long"], series["directions"]["short"]
+    ):
+        require(
+            close(row["equity"] - initial, long["contribution"] + short["contribution"]),
+            "direction_accounting",
+        )
+    require(
+        close(sum(f["fee"] for f in fills.values()), sum(a["fee"] for a in allocations.values())),
+        "fee_conservation",
+    )
+    require(p["summary"]["all"]["closedFragmentCount"]["value"] == len(fragments), "closed_count")
+    require(p["summary"]["all"]["openLotCount"]["value"] == len(trades["openLots"]), "open_count")
+    for row in series["closedCumulative"]:
+        require(row["fragmentId"] in fragments, "cumulative_reference")
+    for bucket in p["analysis"]["distribution"]["histogram"]:
+        require(bucket["count"] == len(bucket["fragmentIds"]), "histogram_count")
+        require(all(ref in fragments for ref in bucket["fragmentIds"]), "histogram_reference")
+
+    histogram_ids = [
+        ref
+        for bucket in p["analysis"]["distribution"]["histogram"]
+        for ref in bucket["fragmentIds"]
+    ]
+    require(
+        len(histogram_ids) == len(fragments) and set(histogram_ids) == set(fragments),
+        "histogram_coverage",
+    )
+    for t in list(fragments.values()) + trades["openLots"]:
+        for leg in (t["entry"], t["exit"]):
+            if leg is not None:
+                fill = fills[leg["fillId"]]
+                require(
+                    leg["orderId"] == fill["order_id"]
+                    and leg["sequence"] == fill["sequence"]
+                    and leg["barIndex"] == fill["bar_index"]
+                    and leg["price"] == fill["price"],
+                    "leg_fill_consistency",
+                )
+    total = sum(t["pnlNet"] for t in fragments.values()) + sum(
+        t["openPnlNet"] for t in trades["openLots"]
+    )
+    require(close(total, series["account"][-1]["equity"] - initial), "portfolio_accounting")
+    for name in ("drawdowns", "alternating"):
+        for episode in p["analysis"]["growthAndDecline"][name]:
+            require(
+                all(episode[k] in observations for k in ("start", "end", "extreme")),
+                "episode_reference",
+            )
+    for ref in p["analysis"]["distribution"]["outliers"]["fragmentIds"]:
+        require(ref in fragments, "outlier_reference")
+    for streak in p["analysis"]["streaks"]["rows"]:
+        require(
+            streak["startFragmentId"] in fragments and streak["endFragmentId"] in fragments,
+            "streak_reference",
+        )
+
+    def metrics(value):
+        if isinstance(value, dict):
+            if "methodId" in value and "unit" in value and "status" in value:
+                missing = value["value"] is None
+                require((value["status"] in ("ok", "approximate")) != missing, "metric_status")
+                require(not missing or bool(value["reason"]), "metric_reason")
+            for item in value.values():
+                metrics(item)
+        elif isinstance(value, list):
+            for item in value:
+                metrics(item)
+
+    metrics(p["summary"])
+    metrics(p["analysis"])
+    metrics(p["extensions"])

openbacktesting/optimizer/identity.py

@@ -0,0 +1,45 @@
+"""Calculate experiment identity only for stably encodable market data and host declarations."""
+
+import hashlib
+import platform
+from importlib.metadata import version
+
+import pandas as pd
+
+from openbacktesting.optimizer.models import ExecutionIdentity, digest
+
+
+def execution_identity(data, identity, backtest):
+    if not isinstance(identity, ExecutionIdentity):
+        raise TypeError("optimizer: identity must be an ExecutionIdentity")
+    if not isinstance(data, pd.DataFrame) or not isinstance(data.index, pd.DatetimeIndex):
+        raise TypeError("optimizer: data must be a DataFrame with a datetime index")
+    if not data.columns.is_unique or any(type(c) is not str for c in data.columns):
+        raise ValueError("optimizer: market-data column names must be unique strings")
+    for dtype in data.dtypes:
+        if dtype.kind not in "biufMm" or str(dtype) == "object":
+            raise TypeError("optimizer: market data may contain only numeric, boolean, and datetime columns")
+    hashes = pd.util.hash_pandas_object(data, index=True).to_numpy().astype("<u8").tobytes()
+    data_hash = hashlib.sha256(hashes).hexdigest()
+    return {
+        "identityVersion": 1,
+        "source": identity.strategy_sha256,
+        "dependencies": identity.dependencies_sha256,
+        "data": digest(
+            {
+                "hash": data_hash,
+                "columns": list(data.columns),
+                "dtypes": list(map(str, data.dtypes)),
+                "index": str(data.index.dtype),
+                "indexName": data.index.name,
+            }
+        ),
+        "environment": {
+            "python": platform.python_version(),
+            **{
+                name: version(name)
+                for name in ("openbacktesting", "numpy", "pandas", "pandas-ta-classic")
+            },
+        },
+        "backtest": backtest,
+    }

openbacktesting/optimizer/models.py

@@ -0,0 +1,92 @@
+"""Plain-value types and canonical encoding for parameter experiments."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from dataclasses import dataclass
+
+
+def encode(value) -> str:
+    """Canonical JSON; reject nonfinite numbers and nonstring keys."""
+
+    def check(item):
+        if isinstance(item, dict):
+            if any(type(k) is not str for k in item):
+                raise ValueError("optimizer: JSON keys must be strings")
+            for child in item.values():
+                check(child)
+        elif isinstance(item, (list, tuple)):
+            for child in item:
+                check(child)
+
+    check(value)
+    return json.dumps(
+        value, ensure_ascii=False, sort_keys=True, separators=(",", ":"), allow_nan=False
+    )
+
+
+def digest(value) -> str:
+    return hashlib.sha256(encode(value).encode()).hexdigest()
+
+
+@dataclass(frozen=True)
+class Values:
+    """Finite candidate values; plan validates against the corresponding input declaration."""
+
+    values: tuple | list
+
+
+@dataclass(frozen=True)
+class Range:
+    """Ascending grid range; int uses integers, float/price uses decimal strings or integers."""
+
+    start: int | str
+    stop: int | str
+    step: int | str
+
+
+@dataclass(frozen=True)
+class ExecutionIdentity:
+    """Host declaration of SHA256 digests for loaded source and local dependencies; no files are loaded or executed."""
+
+    strategy_sha256: str
+    dependencies_sha256: str
+
+    def __post_init__(self):
+        for value in (self.strategy_sha256, self.dependencies_sha256):
+            if not isinstance(value, str) or re.fullmatch("[0-9a-f]{64}", value) is None:
+                raise ValueError("optimizer: execution identity must be a lowercase SHA256 digest")
+
+
+@dataclass(frozen=True)
+class Plan:
+    """Immutable canonical text; snapshot returns an independent copy, and combinations are generated incrementally at runtime."""
+
+    _json: str
+
+    def snapshot(self) -> dict:
+        """Return an independent JSON copy of the complete plan."""
+        return json.loads(self._json)
+
+    @property
+    def total(self) -> int:
+        """Raw Cartesian-product count, without deducting constraints not yet checked."""
+        return self.snapshot()["total"]
+
+
+class OptimizationError(RuntimeError):
+    """Experiment infrastructure error preserving result location, identity, and last known committed count."""
+
+    def __init__(self, message, path, experiment_id, committed):
+        self.path = str(path)
+        self.experiment_id = experiment_id
+        self.committed = committed
+        super().__init__(
+            f"{message}; path={path}; experiment={experiment_id}; committed={committed}"
+        )
+
+
+class _ExportError(ValueError):
+    """A backtest returned, but complete Portfolio export failed."""