openbacktesting 0.2.0__py3-none-any.whl

openbacktesting/indicators/runtime.py

@@ -0,0 +1,290 @@
+"""Built-in indicator catalog, pure computation entry points, and bounded computation reuse."""
+
+from __future__ import annotations
+
+import json
+from collections import OrderedDict
+from concurrent.futures import Future
+from contextlib import contextmanager
+from copy import deepcopy
+from hashlib import sha256
+from importlib.metadata import version
+from threading import RLock
+from uuid import uuid4
+
+import numpy as np
+import pandas as pd
+
+from .common import SPECS, to_arrays
+from .registry import execute, validate_backend
+from .types import IndicatorCursor, IndicatorError, IndicatorHandle
+
+DEFAULT_CACHE_BYTES = 64 * 1024 * 1024
+_CATALOG = {spec.id: spec for spec in SPECS}
+_COLUMNS = {"open_": "Open", "high": "High", "low": "Low", "close": "Close", "volume": "Volume"}
+
+
+def catalog():
+    """Return a tuple of all reviewed definitions, including deferred entries that cannot be called.
+
+    Returns:
+        tuple: Indicator definitions; check status before calling, and expect the count to vary with the reviewed catalog.
+    """
+    return tuple(_CATALOG.values())
+
+
+def describe(indicator):
+    """Look up an indicator definition by stable ID without computing it.
+
+    Args:
+        indicator: Full catalog ID, such as ta.ema.
+
+    Returns:
+        IndicatorSpec: Definition of parameter domains, outputs, status, and semantic version.
+
+    Raises:
+        IndicatorError: code is unknown-indicator when the ID does not exist.
+    """
+    try:
+        return _CATALOG[indicator]
+    except KeyError as error:
+        raise IndicatorError("unknown-indicator", indicator, "Unregistered indicator") from error
+
+
+class IndicatorCache:
+    """The budget limits cache retention; active strategies' holdings are not bounded by this budget."""
+
+    def __init__(self, budget=DEFAULT_CACHE_BYTES):
+        if isinstance(budget, bool) or not isinstance(budget, int) or budget < 0:
+            raise ValueError("Cache budget must be a nonnegative integer")
+        self.budget = budget
+        self.bytes = 0
+        self.hits = self.misses = 0
+        self._entries = OrderedDict()
+        self._pending = {}
+        self._lock = RLock()
+
+    def get(self, key, calculate):
+        """Look up key in the cache or run calculate; coalesce concurrent identical keys, do not cache failures, and return read-only templates."""
+        if not self.budget:
+            self.misses += 1
+            return calculate()
+        with self._lock:
+            if key in self._entries:
+                self.hits += 1
+                self._entries.move_to_end(key)
+                return self._entries[key][0]
+            if key in self._pending:
+                future = self._pending[key]
+                owner = False
+            else:
+                future = self._pending[key] = Future()
+                self.misses += 1
+                owner = True
+        if not owner:
+            return future.result()
+        try:
+            value = calculate()
+            size = (
+                value._values.nbytes
+                + value._valid.nbytes
+                + value._ready.nbytes
+                + value._gating.nbytes
+                + value._opts["index"].nbytes
+            )
+            with self._lock:
+                if self.budget and size <= self.budget:
+                    while self.bytes + size > self.budget:
+                        _, (_, removed) = self._entries.popitem(last=False)
+                        self.bytes -= removed
+                    self._entries[key] = (value, size)
+                    self.bytes += size
+                future.set_result(value)
+            return value
+        except BaseException as error:
+            future.set_exception(error)
+            raise
+        finally:
+            with self._lock:
+                del self._pending[key]
+
+    def clear(self):
+        """Clear retained entries and reset retained bytes to zero; do not revoke active result references."""
+        with self._lock:
+            self._entries.clear()
+            self.bytes = 0
+
+
+def _data_identity(frame):
+    digest = sha256(pd.util.hash_pandas_object(frame, index=True).values.tobytes())
+    digest.update(
+        repr(
+            (
+                tuple(frame.columns),
+                tuple(map(str, frame.dtypes)),
+                str(frame.index.dtype),
+                frame.index.name,
+            )
+        ).encode()
+    )
+    return digest.hexdigest()
+
+
+def _prepare_inputs(spec, frame, inputs, cursor):
+    if not isinstance(frame, pd.DataFrame) or not frame.index.is_unique:
+        raise IndicatorError("index-mismatch", spec.id, "Input must be a DataFrame with a unique index")
+    mapping = dict(inputs or {})
+    if mapping.keys() - set(spec.inputs):
+        raise IndicatorError("missing-input", spec.id, "Input mapping contains undeclared fields")
+    columns = {}
+    dtypes = {}
+    defaults = dict(spec.input_defaults)
+    for name in spec.inputs:
+        source = mapping.get(name, defaults.get(name, _COLUMNS.get(name, name)))
+        if isinstance(source, IndicatorHandle):
+            if cursor is None or source._cursor is not cursor or source.ndim != 1:
+                raise IndicatorError("index-mismatch", spec.id, "Indicator inputs must come from a single channel in this run")
+            series = source.s.where(source.valid)
+        else:
+            if not isinstance(source, str) or source not in frame:
+                raise IndicatorError("missing-input", spec.id, f"Missing input: {name}")
+            series = frame[source]
+        if not series.index.equals(frame.index):
+            raise IndicatorError("index-mismatch", spec.id, "Input index does not match")
+        if not pd.api.types.is_numeric_dtype(series.dtype):
+            raise IndicatorError("missing-input", spec.id, f"{name} must be numeric")
+        dtypes[name] = str(series.dtype)
+        columns[name] = series.to_numpy(dtype=float, copy=False)
+    prepared = pd.DataFrame(columns, index=frame.index, copy=True)
+    prepared.attrs["input_dtypes"] = dtypes
+    return prepared
+
+
+def compute(
+    indicator,
+    frame,
+    *,
+    parameters=None,
+    backend=None,
+    inputs=None,
+    cache=None,
+    cursor=None,
+    required_outputs=None,
+):
+    """Compute reviewed indicators in bulk on explicit market data and return read-only result handles.
+
+    Args:
+        indicator: Full catalog ID.
+        frame: pandas DataFrame; index and inputs must satisfy the indicator contract.
+        parameters: Parameter mapping; reject unknown keys, invalid types, and invalid relationships.
+        backend: Backend identifier; None uses the catalog default without silent fallback.
+        inputs: Mapping from indicator inputs to market-data column names or single channels from the same run.
+        cache: Optional IndicatorCache; None recomputes each time.
+        cursor: Internal framework run cursor; None for standalone computation.
+        required_outputs: Canonical required output names; an empty list disables warmup gating.
+
+    Returns:
+        IndicatorHandle: Single- or multi-channel handle with valid/ready masks and provenance metadata.
+
+    Raises:
+        IndicatorError: Failure in ID, parameters, backend, inputs, outputs, or computation.
+    """
+    spec = describe(indicator)
+    parameters = spec.normalize(dict(parameters or {}))
+    backend = spec.default_backend if backend is None else backend
+    binding = validate_backend(spec, backend)
+    if spec.status != "available":
+        raise IndicatorError("unavailable-indicator", indicator, spec.reason)
+    required = spec.outputs if spec.required is None else spec.required
+    required = tuple(required if required_outputs is None else required_outputs)
+    if not set(required) <= set(spec.outputs):
+        raise IndicatorError("output-contract", indicator, "Unknown required channel")
+    data = _prepare_inputs(spec, frame, inputs, cursor)
+    metadata = {
+        "id": indicator,
+        "semantic_version": spec.version,
+        "implementation_version": binding.implementation_version,
+        "parameters": parameters,
+        "data_identity": _data_identity(data),
+        "input_dtypes": data.attrs["input_dtypes"],
+        "backend": backend,
+        "versions": {name: version(name) for name in ("pandas-ta-classic", "pandas", "numpy")},
+        "dtype": spec.dtype,
+        "kind": spec.kind,
+        "validity": spec.validity,
+        "missing_policy": spec.missing_policy,
+        "readiness": "history-and-finite-v1",
+        "unit": spec.unit,
+        "engine_version": version("openbacktesting"),
+        "inputs": {
+            name: (source.metadata | {"channel": source.name})
+            if isinstance(source, IndicatorHandle)
+            else source
+            for name, source in (inputs or {}).items()
+        },
+        "fixed": dict(spec.fixed),
+    }
+    key = json.dumps(metadata, sort_keys=True)
+
+    def calculate():
+        try:
+            result = execute(spec, {name: data[name] for name in spec.inputs}, parameters, backend)
+        except IndicatorError:
+            raise
+        except Exception as error:
+            raise IndicatorError(
+                "calculation-failed", indicator, str(error), backend=backend
+            ) from error
+        values, valid = to_arrays(spec, result, data.index, parameters)
+        ready = np.arange(len(data)) >= spec.history_required(parameters) - 1
+        current_valid = np.isfinite(data.to_numpy()).all(axis=1)
+        valid &= ready
+        if spec.validity == "current-inputs":
+            valid &= current_valid
+        # Unready values are not used for trading; preserve native values for diagnostics rather than filling zeros to feign validity.
+        if spec.dtype != "float64":
+            values = np.nan_to_num(values).astype(spec.dtype)
+        if len(spec.outputs) == 1:
+            values, valid = values[0], valid[0]
+        return IndicatorHandle(
+            values,
+            name=spec.outputs[0] if len(spec.outputs) == 1 else spec.outputs,
+            index=data.index,
+            valid=valid,
+            metadata=metadata,
+            ready=ready,
+        )
+
+    template = calculate() if cache is None else cache.get(key, calculate)
+    handle = object.__new__(IndicatorHandle)
+    handle.__dict__ = template.__dict__.copy()
+    handle._metadata = deepcopy(template._metadata)
+    handle._cursor = cursor or IndicatorCursor(len(frame), "complete")
+    handle._set_required(spec.outputs.index(name) for name in required)
+    handle._opts = template._opts.copy()
+    handle._metadata["required_outputs"] = list(required)
+    return handle
+
+
+_OPTIMIZATION_CACHES = {}
+_OPTIMIZATION_LOCK = RLock()
+
+
+def optimization_cache(token, budget):
+    """Reuse within a process; token is serializable, while caches and locks are excluded from task messages."""
+    with _OPTIMIZATION_LOCK:
+        if token not in _OPTIMIZATION_CACHES:
+            _OPTIMIZATION_CACHES[token] = IndicatorCache(budget)
+        return _OPTIMIZATION_CACHES[token]
+
+
+@contextmanager
+def optimization_scope(budget):
+    """The parent process/thread releases in finally; child caches are released when the Pool owned by this run exits."""
+    token = uuid4().hex
+    optimization_cache(token, budget)
+    try:
+        yield token
+    finally:
+        with _OPTIMIZATION_LOCK:
+            _OPTIMIZATION_CACHES.pop(token).clear()

openbacktesting/indicators/statistics/beta.py

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

openbacktesting/indicators/statistics/correl.py

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

openbacktesting/indicators/statistics/entropy.py

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

openbacktesting/indicators/statistics/kurtosis.py

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

openbacktesting/indicators/statistics/mad.py

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

openbacktesting/indicators/statistics/md.py

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

openbacktesting/indicators/statistics/median.py

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

openbacktesting/indicators/statistics/mode.py

@@ -0,0 +1,48 @@
+"""Mode of the latest length finite observations; ties choose the smallest value, with state bounded by the window."""
+
+from collections import Counter, deque
+from heapq import heapify, heappop, heappush
+from math import isfinite
+
+import numpy as np
+import pandas as pd
+
+
+class _ModeWindow:
+    def __init__(self, length):
+        self.length = length
+        self.queue = deque()
+        self.counts = Counter()
+        self.heap = []
+
+    def _change(self, value, delta):
+        count = self.counts[value] + delta
+        if count:
+            self.counts[value] = count
+            heappush(self.heap, (-count, value))
+        else:
+            del self.counts[value]
+
+    def add(self, value):
+        self.queue.append(value)
+        self._change(value, 1)
+        if len(self.queue) > self.length:
+            self._change(self.queue.popleft(), -1)
+        if len(self.heap) > 4 * self.length:
+            self.heap = [(-count, value) for value, count in self.counts.items()]
+            heapify(self.heap)
+        while -self.heap[0][0] != self.counts.get(self.heap[0][1], 0):
+            heappop(self.heap)
+
+    def value(self):
+        return self.heap[0][1] if len(self.queue) == self.length else np.nan
+
+
+def compute(*, close, length):
+    window = _ModeWindow(length)
+    result = np.full(len(close), np.nan)
+    for i, value in enumerate(close):
+        if isfinite(value):
+            window.add(value)
+        result[i] = window.value()
+    return pd.Series(result, index=close.index, name="mode")

openbacktesting/indicators/statistics/quantile.py

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

openbacktesting/indicators/statistics/skew.py

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

openbacktesting/indicators/statistics/stderr.py

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

openbacktesting/indicators/statistics/stdev.py

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

openbacktesting/indicators/statistics/variance.py

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

openbacktesting/indicators/statistics/zscore.py

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

openbacktesting/indicators/trend/adx.py

@@ -0,0 +1,28 @@
+"""ta.adx: Computation wrapper for the pinned dependency with canonical outputs."""
+
+from pandas_ta_classic.trend.adx import adx as _calculate
+
+from ..common import named_frame
+
+
+def compute(*, high, low, close, length, lensig, scalar, mamode, drift, talib):
+    result = _calculate(
+        high=high,
+        low=low,
+        close=close,
+        length=length,
+        lensig=lensig,
+        scalar=scalar,
+        mamode=mamode,
+        drift=drift,
+        talib=talib,
+    )
+    return named_frame(
+        result,
+        "ta.adx",
+        {
+            f"ADX_{lensig}": "adx",
+            f"DMP_{length}": "positive",
+            f"DMN_{length}": "negative",
+        },
+    )

openbacktesting/indicators/trend/adxr.py

@@ -0,0 +1,28 @@
+"""ta.adxr: Computation wrapper for the pinned dependency with canonical outputs."""
+
+from pandas_ta_classic.trend.adxr import adxr as _calculate
+
+from ..common import named_frame
+
+
+def compute(*, high, low, close, length, lensig, scalar, mamode, drift, talib):
+    result = _calculate(
+        high=high,
+        low=low,
+        close=close,
+        length=length,
+        lensig=lensig,
+        scalar=scalar,
+        mamode=mamode,
+        drift=drift,
+        talib=talib,
+    )
+    return named_frame(
+        result,
+        "ta.adxr",
+        {
+            f"ADXR_{lensig}": "adxr",
+            f"DMP_{length}": "positive",
+            f"DMN_{length}": "negative",
+        },
+    )

openbacktesting/indicators/trend/amat.py

@@ -0,0 +1,19 @@
+"""ta.amat: Computation wrapper for the pinned dependency with canonical outputs."""
+
+from pandas_ta_classic.trend.amat import amat as _calculate
+
+from ..common import named_frame
+
+
+def compute(*, close, fast, slow, lookback, mamode, talib):
+    result = _calculate(
+        close=close, fast=fast, slow=slow, lookback=lookback, mamode=mamode, talib=talib
+    )
+    return named_frame(
+        result,
+        "ta.amat",
+        {
+            f"AMAT{mamode[0]}_LR_{fast}_{slow}_{lookback}": "long",
+            f"AMAT{mamode[0]}_SR_{fast}_{slow}_{lookback}": "short",
+        },
+    )

openbacktesting/indicators/trend/aroon.py

@@ -0,0 +1,18 @@
+"""ta.aroon: Computation wrapper for the pinned dependency with canonical outputs."""
+
+from pandas_ta_classic.trend.aroon import aroon as _calculate
+
+from ..common import named_frame
+
+
+def compute(*, high, low, length, scalar, talib):
+    result = _calculate(high=high, low=low, length=length, scalar=scalar, talib=talib)
+    return named_frame(
+        result,
+        "ta.aroon",
+        {
+            f"AROOND_{length}": "down",
+            f"AROONU_{length}": "up",
+            f"AROONOSC_{length}": "oscillator",
+        },
+    )

openbacktesting/indicators/trend/atr_stop.py

@@ -0,0 +1,33 @@
+"""ta.atr_stop: Independent formula with a fixed initialization contract."""
+
+import numpy as np
+import pandas as pd
+
+from ..calculus import atr, clean
+
+
+def compute(*, high, low, close, length, multiplier, end_type):
+    high, low, close = clean(high), clean(low), clean(close)
+    width = atr(high, low, close, length).to_numpy() * multiplier
+    prices, highs, lows = close.to_numpy(), high.to_numpy(), low.to_numpy()
+    stop = np.full(len(close), np.nan)
+    direction = stop.copy()
+    upper = lower = np.nan
+    bullish = True
+    for i in range(1, len(close)):
+        if not np.isfinite(width[i]) or not np.isfinite(prices[i]):
+            upper = lower = np.nan
+            continue
+        hi = (prices[i] if end_type == "close" else highs[i]) + width[i]
+        lo = (prices[i] if end_type == "close" else lows[i]) - width[i]
+        if not np.isfinite(upper):
+            bullish = prices[i] >= prices[i - 1]
+            upper, lower = hi, lo
+        if hi < upper or prices[i - 1] > upper:
+            upper = hi
+        if lo > lower or prices[i - 1] < lower:
+            lower = lo
+        bullish = prices[i] > (lower if bullish else upper)
+        stop[i] = lower if bullish else upper
+        direction[i] = 1 if bullish else -1
+    return pd.DataFrame({"stop": stop, "direction": direction}, index=close.index)

openbacktesting/indicators/trend/chop.py

@@ -0,0 +1,20 @@
+"""ta.chop: Computation wrapper for the pinned dependency with canonical outputs."""
+
+from pandas_ta_classic.trend.chop import chop as _calculate
+
+from ..common import named_series
+
+
+def compute(*, high, low, close, length, atr_length, ln, scalar, drift, talib):
+    result = _calculate(
+        high=high,
+        low=low,
+        close=close,
+        length=length,
+        atr_length=atr_length,
+        ln=ln,
+        scalar=scalar,
+        drift=drift,
+        talib=talib,
+    )
+    return named_series(result, "ta.chop", "chop")

openbacktesting/indicators/trend/cksp.py

@@ -0,0 +1,17 @@
+"""ta.cksp: Computation wrapper for the pinned dependency with canonical outputs."""
+
+from pandas_ta_classic.trend.cksp import cksp as _calculate
+
+from ..common import named_frame
+
+
+def compute(*, high, low, close, p, x, q, tvmode, talib):
+    result = _calculate(high=high, low=low, close=close, p=p, x=x, q=q, tvmode=tvmode, talib=talib)
+    return named_frame(
+        result,
+        "ta.cksp",
+        {
+            f"CKSPl_{p}_{float(x)}_{q}": "long",
+            f"CKSPs_{p}_{float(x)}_{q}": "short",
+        },
+    )