gstrat 1.9.0__tar.gz

gstrat-1.9.0/.gitignore

@@ -0,0 +1 @@
+__pycache__/

gstrat-1.9.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GStrat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

gstrat-1.9.0/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.5
+Name: gstrat
+Version: 1.9.0
+Summary: Reference backtest engine for GStrat-generated Python strategies.
+Project-URL: Homepage, https://gstrat.net
+Author: GStrat
+License-Expression: MIT
+License-File: LICENSE
+Keywords: backtest,quant,strategy,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.11
+Requires-Dist: numpy>=1.26
+Requires-Dist: pandas>=2.2.2
+Description-Content-Type: text/markdown
+
+# gstrat
+
+The reference backtest engine that [GStrat](https://gstrat.net) generates strategies against.
+
+A GStrat-generated strategy is a plain Python script: it builds indicator and signal columns on a
+`pandas` DataFrame, registers entry rules and their exits, and runs a bar-by-bar fill simulation over
+them. This package is that simulation — the same engine the generated script carries — so results are
+reproducible on your own machine, against your own data, with nothing executed server-side.
+
+## Install
+
+```bash
+pip install gstrat
+```
+
+Requires Python 3.11+, `pandas` 2.2.2+ and `numpy` 1.26+.
+
+## Quickstart
+
+```python
+import pandas as pd
+from gstrat import Strategy
+
+df = pd.DataFrame({
+    "Open":  [100.0, 101.0, 103.0, 102.0, 100.0],
+    "High":  [101.0, 103.5, 104.0, 103.0, 100.5],
+    "Low":   [ 99.5, 100.5, 101.5,  98.0,  99.0],
+    "Close": [100.5, 103.0, 102.0,  98.5, 100.0],
+})
+
+# Signals and exit distances are ordinary columns you compute yourself.
+df["go_long"] = df["Close"] > df["Open"]
+df["stop_distance"] = 2.0
+
+strategy = Strategy(df)
+position = strategy.entry("breakout", 1, df["go_long"], qty=10)
+position.exit_stop(df["stop_distance"])
+
+result = strategy.backtest(initial_equity=100_000, commission_pct=0.05, slippage_ticks=1)
+print(result)
+```
+
+`Strategy.entry(entry_id, direction, when, qty)` registers a rule — `direction` is `1` for long and
+`-1` for short, `when` is a boolean column, and `qty` is a number, a column, or a
+`Strategy.size_risk(risk, distance)` spec that sizes off running equity. The returned position takes
+`exit_stop`, `exit_profit` and `exit_trail` (each `mode="price"` or `mode="percent"`), plus
+`exit_signal(when)` to close at market on a condition.
+
+`backtest()` returns a result carrying the DataFrame and the list of trades. Printing it gives the
+run's span, its warm-up, the headline numbers and every trade with the reason it closed — `stop`,
+`target`, `trail`, `signal`, `reversal`, or `still open` for one still running (stored as `open`). Colour is used when the
+output is a terminal and is suppressed by `NO_COLOR`; `result.report(color=False)` is the explicit
+form. `.summary()` still returns the same five numbers as a dict, `.trades` the raw records, and
+`.warmup_bars` the bars before every numeric column beyond the prices held a value, not counting
+the columns a `per_bar` hook writes.
+
+## Fill model
+
+The engine is deliberately explicit about execution, and the module docstring is its specification —
+read it with `python -c "import gstrat; print(gstrat.__doc__)"`. In short: a signal on a bar's close
+fills at the next bar's open; stop and trailing fills take slippage while limit fills do not;
+commission is a percent of notional on each filled side; an order's size is resolved on the bar that
+placed it, not the bar that fills it; and the intrabar path checks the extreme nearer the open first.
+
+## Version
+
+The distribution version is the engine version — there is no second one. Both of these report it:
+
+```python
+import gstrat, importlib.metadata
+gstrat.ENGINE_VERSION                      # e.g. "1.9.0"
+importlib.metadata.version("gstrat")
+```
+
+Every release moves the version, and the component says what moved with it:
+
+- **major** — something you can observe changed: a signature, a number a previous release returned
+  for the same input, or a call that used to raise. Pin with `gstrat~=1.8` if you want to review
+  those before adopting them; a fill-model correction lands here, because two runs of the same
+  strategy giving different numbers is a break whatever caused it.
+- **minor** — a new capability. Nothing you already read changes value.
+- **patch** — no API change and no value changes anywhere.
+
+A generated script and the `gstrat` it runs against should carry the same version. The generated
+script names the version it was built for in its header.
+
+## License
+
+MIT.

gstrat-1.9.0/README.md

@@ -0,0 +1,89 @@
+# gstrat
+
+The reference backtest engine that [GStrat](https://gstrat.net) generates strategies against.
+
+A GStrat-generated strategy is a plain Python script: it builds indicator and signal columns on a
+`pandas` DataFrame, registers entry rules and their exits, and runs a bar-by-bar fill simulation over
+them. This package is that simulation — the same engine the generated script carries — so results are
+reproducible on your own machine, against your own data, with nothing executed server-side.
+
+## Install
+
+```bash
+pip install gstrat
+```
+
+Requires Python 3.11+, `pandas` 2.2.2+ and `numpy` 1.26+.
+
+## Quickstart
+
+```python
+import pandas as pd
+from gstrat import Strategy
+
+df = pd.DataFrame({
+    "Open":  [100.0, 101.0, 103.0, 102.0, 100.0],
+    "High":  [101.0, 103.5, 104.0, 103.0, 100.5],
+    "Low":   [ 99.5, 100.5, 101.5,  98.0,  99.0],
+    "Close": [100.5, 103.0, 102.0,  98.5, 100.0],
+})
+
+# Signals and exit distances are ordinary columns you compute yourself.
+df["go_long"] = df["Close"] > df["Open"]
+df["stop_distance"] = 2.0
+
+strategy = Strategy(df)
+position = strategy.entry("breakout", 1, df["go_long"], qty=10)
+position.exit_stop(df["stop_distance"])
+
+result = strategy.backtest(initial_equity=100_000, commission_pct=0.05, slippage_ticks=1)
+print(result)
+```
+
+`Strategy.entry(entry_id, direction, when, qty)` registers a rule — `direction` is `1` for long and
+`-1` for short, `when` is a boolean column, and `qty` is a number, a column, or a
+`Strategy.size_risk(risk, distance)` spec that sizes off running equity. The returned position takes
+`exit_stop`, `exit_profit` and `exit_trail` (each `mode="price"` or `mode="percent"`), plus
+`exit_signal(when)` to close at market on a condition.
+
+`backtest()` returns a result carrying the DataFrame and the list of trades. Printing it gives the
+run's span, its warm-up, the headline numbers and every trade with the reason it closed — `stop`,
+`target`, `trail`, `signal`, `reversal`, or `still open` for one still running (stored as `open`). Colour is used when the
+output is a terminal and is suppressed by `NO_COLOR`; `result.report(color=False)` is the explicit
+form. `.summary()` still returns the same five numbers as a dict, `.trades` the raw records, and
+`.warmup_bars` the bars before every numeric column beyond the prices held a value, not counting
+the columns a `per_bar` hook writes.
+
+## Fill model
+
+The engine is deliberately explicit about execution, and the module docstring is its specification —
+read it with `python -c "import gstrat; print(gstrat.__doc__)"`. In short: a signal on a bar's close
+fills at the next bar's open; stop and trailing fills take slippage while limit fills do not;
+commission is a percent of notional on each filled side; an order's size is resolved on the bar that
+placed it, not the bar that fills it; and the intrabar path checks the extreme nearer the open first.
+
+## Version
+
+The distribution version is the engine version — there is no second one. Both of these report it:
+
+```python
+import gstrat, importlib.metadata
+gstrat.ENGINE_VERSION                      # e.g. "1.9.0"
+importlib.metadata.version("gstrat")
+```
+
+Every release moves the version, and the component says what moved with it:
+
+- **major** — something you can observe changed: a signature, a number a previous release returned
+  for the same input, or a call that used to raise. Pin with `gstrat~=1.8` if you want to review
+  those before adopting them; a fill-model correction lands here, because two runs of the same
+  strategy giving different numbers is a break whatever caused it.
+- **minor** — a new capability. Nothing you already read changes value.
+- **patch** — no API change and no value changes anywhere.
+
+A generated script and the `gstrat` it runs against should carry the same version. The generated
+script names the version it was built for in its header.
+
+## License
+
+MIT.

gstrat-1.9.0/engine.py

@@ -0,0 +1,865 @@
+"""Backtest engine, consuming the signal and parameter columns
+already on the frame. `Strategy.backtest()` runs this fill model over a
+strategy's registered entry/exit rules and returns trade results the caller
+can use directly, with nothing computed remotely.
+
+Fill model:
+- entry signal on bar close -> market fill at next bar open
+- an opposite-direction entry signal while in a position REVERSES: the open
+  trade is closed at the next bar's open and the new trade opens at that same
+  price (one entry per direction, no adds: a same-direction signal while in
+  a position is ignored)
+- a rule's exitSignal column is a market exit to FLAT, not a reversal: true
+  on bar close -> the position closes at the next bar's open and nothing is
+  opened in its place. It is queued only while a position from that same
+  rule is open, so a signal with nothing to close is dropped rather than
+  held to flatten a later position; and because it fills at the open it
+  pre-empts every stop/limit/trail level that bar, which never becomes a
+  working order. It also pre-empts an opposite-direction entry filling at that
+  same open: the position is already flat when the entry arrives, so the trade
+  closes for reason "signal" rather than "reversal" and the new one opens
+  beside it. Both paths fill at the same price, so only the reason differs
+- exit orders are (re)placed at each bar CLOSE and govern the NEXT bar, so on
+  check bar B every parameter (stop distance, trail offset) is read at bar
+  B-1, and fraction-mode trail offsets multiply B-1's close
+- an order's qty is resolved on the bar that PLACED it, from that bar's
+  distance column and the equity as of its close (an open position marked to
+  that close), never from the fill bar, whose indicators need the whole bar to
+  close before they exist
+- a fixed stop-loss/take-profit level (re)placed on the bar a position is
+  entered is not yet a checkable working order against that same bar's
+  range (the earliest an order can fill is the next tick after it was
+  placed) — check_stop/check_limit never fire on position["entryBar"]; the
+  trail is exempt from this rule (see the arming bullet below)
+- stop/limit levels are rounded to the tick AWAY from the placement bar's
+  close; trailing levels are never tick-rounded
+- intrabar path: the extreme closer to the open trades first, then the other
+  extreme, then the close. Stops/limits fill at their level (at the open if
+  the bar opens beyond it); the trail updates its peak at the favorable
+  extreme's position in the path, fills at the level with NO open-gap fill,
+  and the close is a final trail checkpoint after a late peak update
+- check order follows the path: bars whose favorable extreme trades first
+  check limit -> stop -> trail; the others check stop -> trail -> limit
+- the trail arms on the entry bar with that bar's favorable extreme as the
+  initial peak; a trail whose offset column is not defined yet keeps tracking
+  that peak and only waits to check a level, so a distance with warm-up trails
+  from the entry bar rather than from wherever it first becomes readable
+- stop distances are absolute price by default; mode="percent" on
+  exit_stop / exit_profit / exit_trail (a rule's slStopMode / tpStopMode /
+  tslStopMode = "fraction") reads the column as a fraction of the
+  reference price instead (entry price for sl/tp, placement-bar close for the
+  trail), so a percent is written as the fraction it stands for: 2% is 0.02
+- slippage worsens every market, stop and trailing fill by slippage_ticks;
+  limit/take-profit fills are exempt, since a limit fills at its price or
+  better, and a slipped fill is not bounded into the bar's range
+- a stop that gaps through its level fills at the bar's open and is slipped
+  from there: the open models the trigger, and the fill follows it
+- stop/take-profit levels are measured from the FILLED entry price, so
+  slippage shifts them by the same amount and can change which bar an exit
+  lands on
+- commission is a percent of notional on each filled side, off the filled
+  price, and is deducted from the equity that drives risk-based sizing
+- a registered per-bar hook runs once per bar at the point signals are
+  evaluated — after this bar's fills and after its intrabar stop/target/trail
+  exits — so it sees the position as of this bar's close, and a column it
+  writes is readable by this same bar's exit and entry signals
+"""
+ENGINE_VERSION = "1.9.0"
+
+import math
+import os
+import sys
+
+import numpy as np
+
+INITIAL_EQUITY = 100_000.0
+
+# The frame's own price columns. Every other numeric column on the frame is
+# measured as the strategy's lookback.
+_PRICE_COLUMNS = ("Open", "High", "Low", "Close", "Volume")
+
+# numpy kind codes for bool/int/uint/float. A column outside them is not a value
+# a strategy waits for, and reading one would report warm-up wrongly in both
+# directions: a datetime column is finite at bar 0 under pandas' own coercion but
+# raises under float(), and a text column would call the entire run warm-up.
+_NUMERIC_KINDS = "biuf"
+
+
+def _raw(df, name, bar, store=None):
+    """Value of a signal or parameter column at `bar`, taken from the live
+    store when the column is one the per-bar hook writes. Those columns hold
+    NaN on the frame until the run ends, and a frame read here is not a stale
+    value but a silent no-op: the truthiness guards downstream read NaN as true
+    and NaN != NaN as false, so the rule never fires and the run ends with no
+    trades and no error."""
+    if store is not None:
+        column = store.get(name)
+        if column is not None:
+            return column[bar]
+    return df[name].iloc[bar]
+
+
+def _col(df, name, bar, store=None):
+    v = _raw(df, name, bar, store)
+    return None if v is None or v != v else float(v)  # NaN-safe
+
+
+def _resolve_qty(qty, df, bar, equity, store=None):
+    """Resolve a rule's `qty` from the bar that PLACED the order — the signal
+    bar — not the bar that fills it. `bar` is that placement index. Reading
+    the fill bar instead would size an order that executes at that bar's open
+    from indicators the whole bar has to close to produce. A risk-spec
+    dict (from Strategy.size_risk) sizes shares off equity and the distance
+    column at that bar, so per-bar volatility drives position size; a
+    scalar/Series qty is unchanged (fixed sizing)."""
+    if isinstance(qty, dict) and qty.get("__kind__") == "risk":
+        # _raw, not _col: a NaN distance must stay NaN and yield a NaN size.
+        # _col's None would raise TypeError on the division instead.
+        distance = _raw(df, qty["distance"], bar, store)
+        return (equity * qty["risk"] / 100.0) / distance
+    if hasattr(qty, "iloc"):
+        # A Series qty was captured at registration, so its only handle on the
+        # store is its own name; anything not a declared runtime column keeps
+        # reading the Series it was handed.
+        name = getattr(qty, "name", None)
+        if store is not None and name in store:
+            return float(store[name][bar])
+        return float(qty.iloc[bar])
+    return float(qty)
+
+
+def _tick_round(value, reference, tick):
+    """Rounds stop/limit prices to the tick AWAY from the reference
+    (the close of the bar that placed the order)."""
+    if not tick or tick <= 0 or not math.isfinite(value) or value == reference:
+        return value
+    ratio = value / tick
+    eps = 1e-9
+    steps = math.ceil(ratio - eps) if value > reference else math.floor(ratio + eps)
+    return steps * tick
+
+
+def _slipped(price, side, slip):
+    """Adverse fill adjustment. `side` is +1 when the fill buys and -1 when it
+    sells, so a buy fills higher and a sell fills lower. Deliberately not
+    bounded into the bar's range: a fill worse than the bar's extreme is the
+    honest model of an order that had to chase, and bounding it would silently
+    cancel the cost on exactly the gapping bars where it is largest."""
+    return price + side * slip if slip else price
+
+
+def _commission(price, size, rate):
+    """Cash charged on one filled side, computed off the price actually
+    filled at — that is the notional that changed hands."""
+    return abs(size) * price * rate if rate else 0.0
+
+
+def _first_finite_pos(values):
+    """Index of the first value a column actually holds, or len(values) when it
+    never holds one. float() is guarded rather than assumed total: a nullable
+    boolean column passes the dtype filter and still carries values that raise."""
+    for i, value in enumerate(values):
+        try:
+            if math.isfinite(float(value)):
+                return i
+        except (TypeError, ValueError):
+            pass
+    return len(values)
+
+
+def _warmup_bars(df, runtime_columns):
+    """Bars before EVERY numeric column beyond the prices holds a value — the
+    strategy's lookback, on a frame carrying only what it computed. Runtime
+    columns are excluded because they are outputs of the bar
+    loop rather than lookback: the ones a position defines stay NaN until the
+    first fill, which would report the first ENTRY bar as the strategy's
+    lookback, and the whole frame for a strategy that never trades."""
+    skip = set(_PRICE_COLUMNS) | set(runtime_columns)
+    # By position, not by name: a frame may carry two columns under one name,
+    # and df[name] then returns a frame, which has no single dtype.
+    return max(
+        (
+            _first_finite_pos(df.iloc[:, pos].tolist())
+            for pos, name in enumerate(df.columns)
+            if name not in skip
+            and getattr(df.iloc[:, pos].dtype, "kind", "O") in _NUMERIC_KINDS
+        ),
+        default=0,
+    )
+
+
+class _BarView:
+    """One bar of the frame, presented so that an expression written for a whole
+    column is correct unchanged for a single bar.
+
+    Columns materialise to a numpy array on first access rather than reading
+    `.iloc[bar]` each time: the positional pandas read is ~34x an array index,
+    which is the difference between a hook that disappears into the noise and
+    one that dominates the run.
+
+    An ARRAY rather than a list, and that is a correctness choice, not a
+    performance one. Indexing a list of Python floats hands back a Python
+    float, whose arithmetic differs from the column's on exactly the cases a
+    strategy meets first: `1.0 / 0.0` raises ZeroDivisionError where the column
+    yields `inf`, and a position is flat — size 0 — on every bar before the
+    first fill. Indexing the array hands back a numpy scalar, which divides,
+    compares and propagates NaN identically to the whole-column form. That
+    equivalence is what lets one expression serve both surfaces."""
+
+    def __init__(self, df, store):
+        self._df, self._store, self._cache, self._bar = df, store, {}, 0
+
+    def _seek(self, bar):
+        self._bar = bar
+
+    def __getitem__(self, name):
+        if name in self._store:
+            return self._store[name][self._bar]
+        column = self._cache.get(name)
+        if column is None:
+            column = self._df[name].to_numpy()
+            self._cache[name] = column
+        return column[self._bar]
+
+    def __setitem__(self, name, value):
+        if name not in self._store:
+            raise KeyError(
+                f"per_bar assigned '{name}', which was not declared a runtime "
+                f"column: its value would be discarded when the run ends"
+            )
+        self._store[name][self._bar] = value
+
+
+class _State:
+    """The live position and account as of this bar's close, after this bar's
+    fills and exits."""
+
+    __slots__ = (
+        "avg_price", "size", "bars_in_trade", "open_profit",
+        "equity", "net_profit", "win_trades", "loss_trades",
+    )
+
+
+def _refresh_state(st, position, close, bar, equity, initial_equity,
+                   wins, losses):
+    """`equity` in is the REALIZED running total. The published `st.equity`
+    adds the open position's mark to this bar's close, because that is the
+    number risk sizing is already fed (`placement_equity`) and the only one on
+    which two spellings of "risk 1% of equity" agree: `size_risk` and a per-bar
+    hook computing qty from `st.equity`. `st.net_profit` stays on the realized
+    total, which already carries the open trade's entry commission: an entry's
+    cost is charged when it fills, not held back until the trade closes."""
+    # numpy scalars, matching what the one-bar view hands back for a column:
+    # a value that reaches an expression from the state object and one that
+    # reaches it through a column have to divide and compare the same way.
+    f = np.float64
+    nan = f("nan")
+    if position is None:
+        st.avg_price = nan
+        st.size = f(0.0)
+        st.bars_in_trade = nan
+        st.open_profit = f(0.0)
+    else:
+        st.avg_price = f(position["entryPrice"])
+        st.size = f(position["size"])
+        st.bars_in_trade = f(bar - position["entryBar"])
+        st.open_profit = f(
+            (close - position["entryPrice"]) * position["size"]
+        )
+    st.equity = f(equity) + st.open_profit
+    st.net_profit = f(equity - initial_equity)
+    st.win_trades = f(wins)
+    st.loss_trades = f(losses)
+
+
+def simulate(df, rules, tick=0.01, initial_equity=INITIAL_EQUITY,
+             commission_pct=0.0, slippage_ticks=0,
+             per_bar=None, runtime_columns=()):
+    """rules: [{id, dir(+1/-1), entries, slStop?, tpStop?, tslStop?,
+    exitSignal?, qty?, slStopMode?, tpStopMode?, tslStopMode?}] — modes are
+    "price" (default) or "fraction". `tick` is the symbol's smallest price
+    increment (0.01 by default); pass 0 to disable price rounding, which
+    also disables slippage, since slippage is measured in ticks."""
+    trades = []
+    position = None  # {"rule", "entryBar", "entryPrice", "size", "peak",
+                      # "entryCommission", "slippageCost"}
+    equity = initial_equity  # tracked so risk-based qty specs can size off it
+    n = len(df)
+    opens = df["Open"].tolist()
+    highs = df["High"].tolist()
+    lows = df["Low"].tolist()
+    closes = df["Close"].tolist()
+    pending = None  # rule to fill at next open
+    pending_exit = False  # signal exit to fill flat at next open
+    slip = slippage_ticks * tick
+    commission_rate = commission_pct / 100.0
+    # Populated only with the hook: without one nothing can write these, and
+    # a store holding a name that is also a real frame column would shadow it
+    # with NaN at every read site below.
+    store = (
+        {name: [float("nan")] * n for name in runtime_columns}
+        if per_bar is not None
+        else {}
+    )
+    view = _BarView(df, store) if per_bar is not None else None
+    st = _State() if per_bar is not None else None
+    wins = losses = 0
+
+    def close_position(bar, exit_price, exit_slippage, reason):
+        nonlocal equity, wins, losses
+        exit_commission = _commission(exit_price, position["size"], commission_rate)
+        equity += (exit_price - position["entryPrice"]) * position["size"]
+        equity -= exit_commission
+        trades.append({
+            "entryId": position["rule"]["id"],
+            "entryBar": position["entryBar"],
+            "entryPrice": position["entryPrice"],
+            "exitBar": bar,
+            "exitPrice": exit_price,
+            "size": position["size"],
+            "entryCommission": position["entryCommission"],
+            "exitCommission": exit_commission,
+            "slippageCost": position["slippageCost"] + exit_slippage,
+            "reason": reason,
+        })
+        # Net of BOTH commissions, so a trade whose price moved in your favour
+        # counts as a loss when the two commissions exceed its gross profit.
+        # A trade netting exactly zero counts as neither.
+        net = ((exit_price - position["entryPrice"]) * position["size"]
+               - position["entryCommission"] - exit_commission)
+        if net > 0:
+            wins += 1
+        elif net < 0:
+            losses += 1
+
+    for bar in range(n):
+        # Equity as of the PREVIOUS bar's close — the moment an order filling
+        # at this bar's open was placed — carrying the then-open position's
+        # mark-to-market at that close. Captured before 1a/1b, which flatten
+        # that position and would leave only realized equity behind; on a
+        # reversal the two differ by the gap between the placing close and the
+        # fill open. Read only when `pending` is set, which cannot happen
+        # before bar 1.
+        placement_equity = equity
+        if pending is not None and position is not None:
+            placement_equity += (
+                closes[bar - 1] - position["entryPrice"]
+            ) * position["size"]
+
+        # 1a) a queued signal exit flattens at this bar's open, before any
+        #     intrabar order can be checked
+        if pending_exit:
+            if position is not None:
+                d_out = position["rule"]["dir"]
+                exit_fill = _slipped(opens[bar], -d_out, slip)
+                # Reported as "signal" even when an opposite entry fills at this
+                # same open and flips the position: 1a runs first and leaves
+                # nothing for 1b to close. The two produce byte-identical fills,
+                # so only the label is at stake, and the exit signal is the cause
+                # the trader wrote down.
+                close_position(
+                    bar, exit_fill,
+                    abs(exit_fill - opens[bar]) * abs(position["size"]),
+                    "signal",
+                )
+                position = None
+            pending_exit = False
+
+        # 1b) fill a pending entry at this bar's open; an opposite-direction
+        #    pending reverses (close at this open, then open the new trade)
+        if pending is not None:
+            if position is not None:
+                d_out = position["rule"]["dir"]
+                exit_fill = _slipped(opens[bar], -d_out, slip)
+                close_position(
+                    bar, exit_fill,
+                    abs(exit_fill - opens[bar]) * abs(position["size"]),
+                    "reversal",
+                )
+                position = None
+            rule = pending
+            # `pending` is only ever set in step 3 of an earlier bar, so the
+            # placement bar `bar - 1` always exists.
+            qty = _resolve_qty(
+                rule.get("qty", 1.0), df, bar - 1, placement_equity, store
+            )
+            entry_price = _slipped(opens[bar], rule["dir"], slip)
+            size = qty * rule["dir"]
+            entry_commission = _commission(entry_price, size, commission_rate)
+            equity -= entry_commission
+            position = {
+                "rule": rule,
+                "entryBar": bar,
+                "entryPrice": entry_price,
+                "size": size,
+                "peak": None,  # set when the trail arms (entry bar)
+                "entryCommission": entry_commission,
+                "slippageCost": abs(entry_price - opens[bar]) * abs(size),
+            }
+            pending = None
+
+        # 2) manage open position intrabar
+        if position is not None:
+            rule = position["rule"]
+            d = rule["dir"]
+            entry = position["entryPrice"]
+            o, h, lo, c = opens[bar], highs[bar], lows[bar], closes[bar]
+            placement = bar - 1  # the bar whose close (re)placed the orders
+            ref = closes[placement]
+            # Path order: the extreme closer to the open trades first;
+            # `favorable_first` is true when the position's favorable extreme
+            # (high for longs, low for shorts) comes first.
+            high_first = abs(h - o) <= abs(o - lo)
+            favorable_first = high_first if d == 1 else not high_first
+            exit_price = None
+            exit_slippage = 0.0
+            exit_reason = None
+
+            def fixed_level(col_name, mode_key, sign):
+                value = _col(df, rule[col_name], placement, store)
+                if value is None:
+                    return None
+                dist = (
+                    value * entry
+                    if rule.get(mode_key) == "fraction"
+                    else value
+                )
+                return _tick_round(entry + sign * d * dist, ref, tick)
+
+            def check_stop():
+                nonlocal exit_price, exit_slippage, exit_reason
+                if exit_price is not None or not rule.get("slStop"):
+                    return
+                if bar == position["entryBar"]:  # not yet a working order
+                    return
+                level = fixed_level("slStop", "slStopMode", -1)
+                if level is None:
+                    return
+                if (d == 1 and lo <= level) or (d == -1 and h >= level):
+                    beyond_at_open = o <= level if d == 1 else o >= level
+                    raw = o if beyond_at_open else level
+                    exit_price = _slipped(raw, -d, slip)
+                    exit_slippage = abs(exit_price - raw) * abs(position["size"])
+                    exit_reason = "stop"
+
+            def check_limit():
+                nonlocal exit_price, exit_reason
+                if exit_price is not None or not rule.get("tpStop"):
+                    return
+                if bar == position["entryBar"]:  # not yet a working order
+                    return
+                level = fixed_level("tpStop", "tpStopMode", +1)
+                if level is None:
+                    return
+                if (d == 1 and h >= level) or (d == -1 and lo <= level):
+                    beyond_at_open = o >= level if d == 1 else o <= level
+                    # Deliberately unslipped, unlike the stop and trail legs: a
+                    # resting limit fills at its own price or better.
+                    exit_price = o if beyond_at_open else level
+                    exit_reason = "target"
+
+            def check_trail():
+                nonlocal exit_price, exit_slippage, exit_reason
+                if not rule.get("tslStop"):
+                    return
+                favorable = h if d == 1 else lo
+                adverse = lo if d == 1 else h
+                arming = bar == position["entryBar"]
+                value = _col(df, rule["tslStop"], placement, store)
+                if value is None:
+                    # No offset yet, so no level to check — but the peak still
+                    # has to track. A distance with warm-up (ATR, stdev, a
+                    # rolling extreme) is undefined over its first bars, and
+                    # the arming bar reads bar-1. The peak accumulates from the
+                    # entry bar regardless of when the offset becomes readable;
+                    # restarting it there would trail from the wrong extreme.
+                    position["peak"] = favorable if arming else (
+                        max(position["peak"], favorable)
+                        if d == 1
+                        else min(position["peak"], favorable)
+                    )
+                    return
+                offset = (
+                    value * ref
+                    if rule.get("tslStopMode") == "fraction"
+                    else value
+                )
+
+                def level(peak):
+                    return peak - d * offset
+
+                def adverse_crosses(lvl):
+                    return adverse <= lvl if d == 1 else adverse >= lvl
+
+                def close_beyond(lvl):
+                    return c < lvl if d == 1 else c > lvl
+
+                def fill_at(lvl):
+                    nonlocal exit_price, exit_slippage, exit_reason
+                    exit_price = _slipped(lvl, -d, slip)
+                    exit_slippage = abs(exit_price - lvl) * abs(position["size"])
+                    exit_reason = "trail"
+
+                if arming:
+                    new_peak = favorable
+                    if exit_price is None:
+                        lvl = level(new_peak)
+                        fires = (
+                            adverse_crosses(lvl)
+                            if favorable_first
+                            else close_beyond(lvl)
+                        )
+                        if fires:
+                            fill_at(lvl)
+                    position["peak"] = new_peak
+                    return
+                peak = position["peak"]
+                if favorable_first:
+                    new_peak = max(peak, favorable) if d == 1 else min(peak, favorable)
+                    if exit_price is None and adverse_crosses(level(new_peak)):
+                        fill_at(level(new_peak))
+                    position["peak"] = new_peak
+                    return
+                if exit_price is None and adverse_crosses(level(peak)):
+                    fill_at(level(peak))
+                    return
+                new_peak = max(peak, favorable) if d == 1 else min(peak, favorable)
+                if exit_price is None and close_beyond(level(new_peak)):
+                    fill_at(level(new_peak))
+                position["peak"] = new_peak
+
+            if favorable_first:
+                check_limit()
+                check_stop()
+                check_trail()
+            else:
+                check_stop()
+                check_trail()
+                check_limit()
+
+            if exit_price is not None:
+                close_position(bar, exit_price, exit_slippage, exit_reason)
+                position = None
+
+        # 3) evaluate signals on this bar's close (fill next bar). Scoping
+        #    the exit signal to the rule that opened the position is what
+        #    makes a signal with nothing to close a no-op rather than an
+        #    order stored until some later position exists to flatten
+        #
+        #    The hook runs before both guards, so a column it writes is
+        #    readable by this same bar's exit and entry signals; after them it
+        #    would be a one-bar lag that raises nothing and still yields
+        #    plausible trades.
+        if per_bar is not None:
+            _refresh_state(st, position, closes[bar], bar, equity,
+                           initial_equity, wins, losses)
+            view._seek(bar)
+            per_bar(view, st)
+
+        if position is not None and position["rule"].get("exitSignal"):
+            v = _raw(df, position["rule"]["exitSignal"], bar, store)
+            if bool(v) and v == v:  # truthy and not NaN
+                pending_exit = True
+
+        # while in a position only an OPPOSITE-direction entry signal acts
+        # (as a reversal) — same-direction re-entry is ignored (one entry per
+        # direction, no adds)
+        if pending is None:
+            for rule in rules:
+                v = _raw(df, rule["entries"], bar, store)
+                if bool(v) and v == v:  # truthy and not NaN
+                    if position is None or rule["dir"] != position["rule"]["dir"]:
+                        pending = rule
+                        break
+
+    # The store is the frame's copy of these columns for the whole run; write
+    # it back so callers read those values off `result.df`.
+    for name, values in store.items():
+        df[name] = values
+
+    if position is not None:
+        trades.append({
+            "entryId": position["rule"]["id"],
+            "entryBar": position["entryBar"],
+            "entryPrice": position["entryPrice"],
+            "exitBar": None,
+            "exitPrice": None,
+            "size": position["size"],
+            "entryCommission": position["entryCommission"],
+            "exitCommission": None,
+            "slippageCost": position["slippageCost"],
+            "reason": "open",
+        })
+    return trades
+
+
+class _Position:
+    def __init__(self, strat, entry_id):
+        self._s, self._id = strat, entry_id
+
+    def exit_stop(self, distance, mode="price"):
+        self._set("slStop", "slStopMode", distance, mode)
+
+    def exit_profit(self, distance, mode="price"):
+        self._set("tpStop", "tpStopMode", distance, mode)
+
+    def exit_trail(self, distance, mode="price"):
+        self._set("tslStop", "tslStopMode", distance, mode)
+
+    def exit_signal(self, when):
+        """Close this position at market on the bar after `when` is true.
+        No mode argument: unlike the distance-driven exits there is no level
+        to interpret, and the exit is to flat, never a reversal."""
+        self._s._rules[self._id]["exitSignal"] = when.name
+
+    def _set(self, col_key, mode_key, distance, mode):
+        r = self._s._rules[self._id]
+        r[col_key] = distance.name
+        r[mode_key] = "fraction" if mode == "percent" else "price"
+
+
+_ANSI = {
+    "reset": "\033[0m",
+    "bold": "\033[1m",
+    "dim": "\033[2m",
+    "red": "\033[31m",
+    "green": "\033[32m",
+}
+
+# The six values a trade's "reason" can hold, and how each is shown. Only "open"
+# is renamed: on a line beside stop/target/trail, which are all level fills, the
+# bare word reads as "filled at the open" — the most overloaded word in this
+# file. The stored value keeps its own spelling for anything reading the trades.
+_REASON_LABELS = {
+    "signal": "signal",
+    "reversal": "reversal",
+    "stop": "stop",
+    "target": "target",
+    "trail": "trail",
+    "open": "still open",
+}
+
+
+def _color_enabled():
+    """Whether the report may carry ANSI codes. Terminal-only and opt-out: a
+    report piped to a file or read by another program has to be plain bytes, and
+    NO_COLOR is the convention a user already has for turning colour off."""
+    if os.environ.get("NO_COLOR"):  # set and non-empty, as no-color.org defines it
+        return False
+    if os.environ.get("TERM") == "dumb":
+        return False
+    try:
+        return bool(sys.stdout.isatty())
+    except (AttributeError, ValueError):  # detached or closed stdout
+        return False
+
+
+def _paint(text, key, on):
+    """Wrap ALREADY-PADDED text. Painting before padding would count the escape
+    bytes as width and skew every column in the table."""
+    return f"{_ANSI[key]}{text}{_ANSI['reset']}" if on else text
+
+
+def _quantity(size):
+    """Every digit a size carries, up to six decimals: a quantity sized by risk
+    is rarely whole, and significant-digit formats switch to exponent form at a
+    million."""
+    return f"{abs(size):.6f}".rstrip("0").rstrip(".")
+
+
+def _is_intraday(index):
+    """Whether any bar sits off midnight. Decided once for the whole run, so a
+    midnight bar inside an intraday run still prints its time."""
+    return any(
+        getattr(value, "hour", 0)
+        or getattr(value, "minute", 0)
+        or getattr(value, "second", 0)
+        for value in index
+    )
+
+
+def _stamp(value, intraday):
+    """A bar's label as the reader's own data has it: the date alone for a run
+    whose every bar sits at midnight, the minute too otherwise, so an intraday
+    run is not a column of identical dates. A frame not indexed by time falls
+    back to str()."""
+    strftime = getattr(value, "strftime", None)
+    if strftime is None:
+        return str(value)
+    return strftime("%Y-%m-%d %H:%M" if intraday else "%Y-%m-%d")
+
+
+class BacktestResult:
+    def __init__(self, df, trades, warmup_bars=0):
+        self.df, self.trades = df, trades
+        self.warmup_bars = warmup_bars
+
+    def summary(self):
+        closed = [t for t in self.trades if t["exitPrice"] is not None]
+
+        def net_of(t):
+            return ((t["exitPrice"] - t["entryPrice"]) * t["size"]
+                    - t["entryCommission"] - t["exitCommission"])
+
+        net = sum(net_of(t) for t in closed)
+        wins = sum(1 for t in closed if net_of(t) > 0)
+        # Spans EVERY trade, including one still open: its entry commission
+        # was paid. net_profit is closed-only, so the two sit on different
+        # populations by design.
+        costs = sum(
+            t["entryCommission"]
+            + (t["exitCommission"] if t["exitCommission"] is not None else 0.0)
+            + t["slippageCost"]
+            for t in self.trades
+        )
+        return {"trades": len(self.trades), "closed": len(closed),
+                "net_profit": round(net, 2),
+                "win_rate": round(wins / len(closed), 2) if closed else None,
+                "costs": round(costs, 2)}
+
+    def report(self, color=None):
+        """The whole run as text: the span it covered, the headline numbers, and
+        every trade with the reason it closed.
+
+        `color` defaults to auto-detection; pass False for plain bytes whatever
+        stdout is. The five headline numbers are taken from summary() rather than
+        recomputed, so the two can never disagree — but each trade's Net is
+        rounded for display, so that column will not always add up to Net Profit,
+        which summary() rounds once at the end. This is a report, not a ledger.
+        """
+        on = _color_enabled() if color is None else bool(color)
+        s = self.summary()
+        index = self.df.index
+        bars = len(index)
+        intraday = _is_intraday(index)
+        win_rate = s["win_rate"]
+        rows = [
+            ("Start", _stamp(index[0], intraday) if bars else "-"),
+            ("End", _stamp(index[-1], intraday) if bars else "-"),
+            ("Bars", str(bars)),
+            ("Warm-up bars", str(self.warmup_bars)),
+            ("Trades", str(s["trades"])),
+            ("Closed trades", str(s["closed"])),
+            # The unit brackets carry a qualifier rather than a currency: the
+            # engine is never told one, and every closed trade's costs are
+            # already inside Net Profit, so adjacent bare labels would invite
+            # subtracting one from the other. They are not even on the same
+            # population — costs spans the open trade, net profit is closed-only.
+            ("Net Profit [after costs]", f"{s['net_profit']:.2f}"),
+            # summary() rounds the rate to two places, so a whole percent is all
+            # the precision there is.
+            ("Win Rate [%]", "-" if win_rate is None else f"{win_rate * 100:.0f}"),
+            ("Costs [all trades]", f"{s['costs']:.2f}"),
+        ]
+        label_width = max(len(label) for label, _ in rows)
+        value_width = max(len(value) for _, value in rows)
+        lines = [
+            f"{label:<{label_width}}  {value:>{value_width}}" for label, value in rows
+        ]
+        if bars and self.warmup_bars >= bars:
+            # Bars and Warm-up bars would otherwise print the same number beside a
+            # non-zero trade count, three rows contradicting each other on sight.
+            lines.append(
+                "At least one column never held a value, so warm-up spans the"
+                " whole run."
+            )
+        return "\n".join(lines + [""] + self._trade_lines(on, intraday))
+
+    def _trade_lines(self, on, intraday):
+        heading = _paint("Trades", "bold", on)
+        if not self.trades:
+            return [heading, "  none"]
+        index = self.df.index
+        header = ("#", "Side", "Size", "Entry Date", "Entry Price",
+                  "Exit Date", "Exit Price", "Reason", "Net")
+        # True where the column reads as a quantity and should sit right-aligned.
+        numeric = (True, False, True, False, True, False, True, False, True)
+        body = [
+            self._trade_cells(i, t, index, intraday)
+            for i, t in enumerate(self.trades, 1)
+        ]
+        widths = [
+            max(len(row[c]) for row in [header, *body]) for c in range(len(header))
+        ]
+
+        def lay(cells):
+            return "  " + "  ".join(
+                cell.rjust(widths[c]) if numeric[c] else cell.ljust(widths[c])
+                for c, cell in enumerate(cells)
+            ).rstrip()
+
+        lines = [heading, _paint(lay(header), "bold", on)]
+        for row, trade in zip(body, self.trades):
+            line = lay(row)
+            if trade["exitPrice"] is None:
+                lines.append(_paint(line, "dim", on))
+                continue
+            net = self._net(trade)
+            if net > 0:
+                lines.append(_paint(line, "green", on))
+            elif net < 0:
+                lines.append(_paint(line, "red", on))
+            else:  # neither a win nor a loss, as summary() counts it
+                lines.append(line)
+        return lines
+
+    @staticmethod
+    def _net(trade):
+        return ((trade["exitPrice"] - trade["entryPrice"]) * trade["size"]
+                - trade["entryCommission"] - trade["exitCommission"])
+
+    def _trade_cells(self, number, trade, index, intraday):
+        closed = trade["exitPrice"] is not None
+        size = trade["size"]
+        # A NaN or zero size has no side; both comparisons are false for NaN.
+        side = "long" if size > 0 else "short" if size < 0 else "?"
+        return (
+            str(number),
+            side,
+            _quantity(size),
+            _stamp(index[trade["entryBar"]], intraday),
+            f"{trade['entryPrice']:.2f}",
+            _stamp(index[trade["exitBar"]], intraday) if closed else "-",
+            f"{trade['exitPrice']:.2f}" if closed else "-",
+            _REASON_LABELS.get(trade["reason"], trade["reason"]),
+            f"{self._net(trade):.2f}" if closed else "-",
+        )
+
+    def __str__(self):
+        return self.report()
+
+    # A REPL or a notebook cell echoing `result` calls __repr__, not __str__, and
+    # an object address is the exact thing this report exists to replace.
+    __repr__ = __str__
+
+
+class Strategy:
+    def __init__(self, df):
+        self.df, self._rules, self._per_bar = df, {}, None
+
+    def per_bar(self, fn, names):
+        """Register the per-bar hook and pre-create the columns it writes. The
+        columns have to exist before any rule is registered: a rule binds its
+        parameter by being handed the Series and keeping only its name."""
+        self._per_bar = (fn, list(names))
+        for name in names:
+            self.df[name] = float("nan")
+        return self
+
+    def entry(self, entry_id, direction, when, qty):
+        self._rules[entry_id] = {"id": entry_id, "dir": direction,
+                                 "entries": when.name, "qty": qty}
+        return _Position(self, entry_id)
+
+    def size_risk(self, risk, distance):
+        return {"__kind__": "risk", "risk": risk, "distance": distance.name}
+
+    def backtest(self, initial_equity=INITIAL_EQUITY, commission_pct=0.0,
+                 slippage_ticks=0):
+        fn, names = self._per_bar if self._per_bar is not None else (None, ())
+        trades = simulate(self.df, list(self._rules.values()),
+                          initial_equity=initial_equity,
+                          commission_pct=commission_pct,
+                          slippage_ticks=slippage_ticks,
+                          per_bar=fn, runtime_columns=names)
+        return BacktestResult(self.df, trades, _warmup_bars(self.df, names))

gstrat-1.9.0/pyproject.toml

@@ -0,0 +1,51 @@
+# Packaging for the `gstrat` PyPI distribution. The engine deliberately stays a
+# single flat module at `engine.py`: the wheel remaps it to `gstrat/__init__.py`
+# rather than the file moving, so the bake target, the version lock and the
+# unittest modules all keep the path they already use. See ../README.md.
+[build-system]
+requires = ["hatchling>=1.27"]
+build-backend = "hatchling.build"
+
+[project]
+name = "gstrat"
+description = "Reference backtest engine for GStrat-generated Python strategies."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "GStrat" }]
+keywords = ["backtest", "trading", "strategy", "quant"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Financial and Insurance Industry",
+  "Programming Language :: Python :: 3",
+  "Topic :: Office/Business :: Financial :: Investment",
+]
+# numpy is imported by engine.py. pandas is not, but it is the public API's
+# argument type — Strategy(df) and every column read go through a DataFrame —
+# so an install without it cannot be called. The pandas floor is 2.2.2, not
+# 2.0: earlier pandas is built against the NumPy 1 C ABI, so `pandas>=2.0` with
+# an unbounded numpy is a pip-resolvable pair that raises on `import pandas`.
+dependencies = ["numpy>=1.26", "pandas>=2.2.2"]
+dynamic = ["version"]
+
+[project.urls]
+# Homepage only: the GitHub repository is private, so a Source link would 404.
+Homepage = "https://gstrat.net"
+
+# The distribution version IS the engine version — there is no second place to
+# write one, so the two cannot drift.
+[tool.hatch.version]
+path = "engine.py"
+pattern = 'ENGINE_VERSION = "(?P<version>[^"]+)"'
+
+[tool.hatch.build.targets.wheel.force-include]
+"engine.py" = "gstrat/__init__.py"
+
+# force-include is scoped to the wheel target, so without this stanza the sdist
+# falls back to hatchling's sweep of the whole directory and publishes
+# engine.lock.json and the unittest modules. The tests are left out
+# deliberately: they import `engine`, which does not exist in an installed
+# gstrat.
+[tool.hatch.build.targets.sdist]
+include = ["engine.py", "pyproject.toml", "README.md", "LICENSE"]