bruedemo 0.1.0__py3-none-any.whl

brue/__init__.py

@@ -0,0 +1,65 @@
+"""brue: pure-Python implementation of the Brue trading-strategy language.
+
+Ported 1:1 from the Rust engine (src/lib.rs); the conformance harness in
+conformance/ verifies byte-identical output against it.
+"""
+from __future__ import annotations
+
+
+
+def run_script(source, bars):
+    from .runtime import ExternalData
+    return run_script_with_data(source, bars, ExternalData())
+
+
+def run_script_with_data(source, bars, external):
+    from .runtime import RunOptions
+    return run_script_full(source, bars, external, {}, RunOptions())
+
+
+def run_script_full(source, bars, external, input_overrides, options):
+    """tokenize + parse + execute, errors shaped exactly like the reference."""
+    from . import parser, tokenizer
+    from .errors import BrueError
+
+    # Windows editors and Python text-mode writes produce CRLF; the
+    # tokenizer speaks LF. Normalize at every entry point.
+    source = source.replace("\r\n", "\n").replace("\r", "\n")
+    try:
+        tokens = tokenizer.tokenize(source)
+    except BrueError as e:
+        return _error_output(e)
+    try:
+        program = parser.parse(tokens)
+    except BrueError as e:
+        return _error_output(e)
+    from .runtime import execute_with_options
+    return execute_with_options(program, bars, input_overrides, external, options)
+
+
+# parse_time_arg and parse_bars_csv live in data.py, ported with Rust-exact
+# parsing (float()/int() alone are looser than f64::from_str: underscores,
+# unicode digits); re-exported here for the lib.rs-shaped public API.
+from .data import parse_bars_csv, parse_time_arg  # noqa: E402,F401
+from .api import BacktestResult, BrueScriptError, backtest  # noqa: E402,F401
+
+
+def _error_output(e):
+    from .output import ErrorInfo, ExecOutput
+    from .value import Value
+    return ExecOutput(
+        success=False,
+        commands=[],
+        errors=[ErrorInfo(message=e.message, line=e.loc.line, col=e.loc.col,
+                          phase=e.phase, suggestion=e.suggestion)],
+        inputs=[],
+        live_orders=[],
+        live_closes=[],
+        decl_title=Value.Null,
+        decl_overlay=Value.Bool(True),
+        decl_symbol=None,
+        decl_timeframe=None,
+        strategy_result=None,
+    )
+
+

brue/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

brue/api.py

@@ -0,0 +1,182 @@
+"""The Python-native front door for the brue package.
+
+The engine internals speak BarData lists and ExecOutput (ported 1:1 from
+the reference engine; conformance-locked, do not touch). This module is the
+convenience layer a Python user actually calls:
+
+    import brue
+
+    result = brue.backtest(script, df)        # df: pandas or rows
+    result.stats["netProfit"], result.trades, result.equity_curve
+
+Accepted data shapes: a pandas DataFrame (any case-insensitive subset of
+time/open/high/low/close/volume columns, time in epoch s, epoch ms, or
+datetimes), a list of dicts with those keys, a list of [t,o,h,l,c,v] rows,
+or a path to a csv. pandas is NOT a dependency: it is duck-typed, so the
+package installs clean without it.
+"""
+from __future__ import annotations
+
+import json
+
+
+class BrueScriptError(Exception):
+    """The script failed to tokenize/parse/run; message is user-facing."""
+
+    def __init__(self, errors):
+        self.errors = errors
+        first = errors[0] if errors else {}
+        super().__init__(first.get("message", "script error"))
+
+
+class BacktestResult:
+    """Friendly view over the engine's canonical output."""
+
+    def __init__(self, raw: dict, bar_times=None):
+        self.raw = raw
+        sr = raw.get("strategyResult") or {}
+        self.stats = {k: v for k, v in sr.items()
+                      if k not in ("trades", "equityCurve")}
+        self.trades = sr.get("trades", [])
+        # The engine emits one equity value per bar, no timestamps; the
+        # caller's bar times restore the x axis.
+        self.equity_curve = sr.get("equityCurve", [])
+        self.bar_times = bar_times or []
+
+    def trades_frame(self):
+        """The trade ledger as a pandas DataFrame (pandas required here)."""
+        import pandas as pd
+        return pd.DataFrame(self.trades)
+
+    def equity_frame(self):
+        import pandas as pd
+        df = pd.DataFrame({"equity": self.equity_curve})
+        if len(self.bar_times) == len(df):
+            df.insert(0, "time", pd.to_datetime(self.bar_times, unit="ms"))
+        return df
+
+    def __repr__(self):
+        s = self.stats
+        return (f"BacktestResult(trades={s.get('totalTrades')}, "
+                f"netProfit={s.get('netProfit')}, "
+                f"winRate={s.get('winRate')}, "
+                f"profitFactor={s.get('profitFactor')})")
+
+
+def _to_ms(t) -> float:
+    """Epoch seconds, epoch ms, or datetime-like -> epoch ms."""
+    if hasattr(t, "timestamp"):
+        return float(t.timestamp() * 1000.0)
+    x = float(t)
+    # Heuristic shared with the userdata importer: values before the year
+    # 5138 in seconds are seconds; anything bigger is already ms.
+    return x * 1000.0 if x < 1e11 else x
+
+
+def _bars_from_any(data):
+    from .runtime import BarData
+
+    if isinstance(data, str):
+        from . import parse_bars_csv
+        with open(data, encoding="utf-8") as f:
+            return parse_bars_csv(f.read())
+
+    # pandas DataFrame, duck-typed so pandas stays optional.
+    if hasattr(data, "columns") and hasattr(data, "itertuples"):
+        cols = {str(c).strip().lower(): c for c in data.columns}
+        tcol = next((cols[k] for k in ("time", "ts", "timestamp", "date",
+                                       "datetime") if k in cols), None)
+        need = [k for k in ("open", "high", "low", "close") if k not in cols]
+        if tcol is None or need:
+            missing = (["time"] if tcol is None else []) + need
+            raise ValueError(f"data is missing columns: {', '.join(missing)}")
+        # Follow the index when there is no time column? No: explicit only,
+        # a wrong guess silently shifts every fill.
+        out = []
+        vol = cols.get("volume")
+        for row in data.itertuples(index=False):
+            d = dict(zip(data.columns, row))
+            out.append(BarData(
+                time=_to_ms(d[tcol]),
+                open=float(d[cols["open"]]), high=float(d[cols["high"]]),
+                low=float(d[cols["low"]]), close=float(d[cols["close"]]),
+                volume=float(d[vol]) if vol is not None else 0.0))
+        return out
+
+    if isinstance(data, (list, tuple)) and data:
+        first = data[0]
+        if isinstance(first, dict):
+            return [BarData(time=_to_ms(r.get("time", r.get("ts", r.get("timestamp")))),
+                            open=float(r["open"]), high=float(r["high"]),
+                            low=float(r["low"]), close=float(r["close"]),
+                            volume=float(r.get("volume", 0.0)))
+                    for r in data]
+        if isinstance(first, (list, tuple)) and len(first) >= 5:
+            return [BarData(time=_to_ms(r[0]), open=float(r[1]), high=float(r[2]),
+                            low=float(r[3]), close=float(r[4]),
+                            volume=float(r[5]) if len(r) > 5 else 0.0)
+                    for r in data]
+    raise ValueError("unsupported data shape: pass a DataFrame, list of "
+                     "dicts, list of [t,o,h,l,c,v] rows, or a csv path")
+
+
+def indicator_series(script: str, data, inputs: dict | None = None) -> dict:
+    """
+    Run a Brue script as a chart INDICATOR: every plot() call becomes a
+    named series aligned to the bars. This is how hosts (the LSE Terminal,
+    notebooks) draw Brue-written indicators on live charts.
+
+    Returns {"plots": {name: [float per bar]}, "meta": {name: kwargs},
+             "overlay": bool, "inputs": [declared input() specs],
+             "times": [epoch ms per bar]}.
+    Raises BrueScriptError on script errors.
+    """
+    from . import run_script_full
+    from .runtime import ExternalData, RunOptions
+    from .value import Value
+
+    bars = _bars_from_any(data)
+    options = RunOptions()
+    options.collect_plots = True
+    overrides = {}
+    for k, v in (inputs or {}).items():
+        overrides[str(k)] = (Value.Bool(v) if isinstance(v, bool)
+                             else Value.Num(v) if isinstance(v, (int, float))
+                             else Value.Str(str(v)))
+    out = run_script_full(script, bars, ExternalData(), overrides, options)
+    raw = json.loads(out.to_json())
+    if not raw.get("success"):
+        raise BrueScriptError(raw.get("errors", []))
+    n = len(bars)
+    plots = {}
+    for name, points in getattr(out, "plots", {}).items():
+        col = [float("nan")] * n
+        for bar_i, v in points:
+            if 0 <= bar_i < n:
+                col[bar_i] = v
+        plots[name] = col
+    return {"plots": plots,
+            "meta": getattr(out, "plot_meta", {}),
+            "overlay": bool((raw.get("declaration") or {}).get("overlay", True)),
+            "inputs": raw.get("inputs", []),
+            "times": [b.time for b in bars]}
+
+
+def backtest(script: str, data, extended_stats: bool = False,
+             trade_from=None, trade_to=None) -> BacktestResult:
+    """Run a Brue strategy over the given bars, entirely in-process."""
+    from . import run_script_full
+    from .runtime import ExternalData, RunOptions
+
+    bars = _bars_from_any(data)
+    options = RunOptions()
+    options.extended_stats = bool(extended_stats)
+    if trade_from is not None:
+        options.trade_from = _to_ms(trade_from)
+    if trade_to is not None:
+        options.trade_to = _to_ms(trade_to)
+    out = run_script_full(script, bars, ExternalData(), {}, options)
+    raw = json.loads(out.to_json())
+    if not raw.get("success"):
+        raise BrueScriptError(raw.get("errors", []))
+    return BacktestResult(raw, bar_times=[b.time for b in bars])

brue/ast.py

@@ -0,0 +1,319 @@
+# AST node types, mirroring src/brue/ast.ts one-for-one (ported from
+# brue-rust src/ast.rs). The kind_str names must match the TS `kind` strings
+# exactly: the runtime's expression fingerprint falls back to
+# "{kind}_{line}_{col}" and those keys decide series-cache identity.
+from dataclasses import dataclass
+from typing import List, Optional, Tuple
+
+
+@dataclass
+class Loc:
+    line: int
+    col: int
+
+
+class Expr:
+    """Base class for all expression nodes (the Rust Expr enum)."""
+
+    # The TS `kind` string (used by the fingerprint fallback). Each subclass
+    # sets _KIND; kind_str() keeps the Rust method name.
+    _KIND = ""
+
+    def kind_str(self) -> str:
+        return self._KIND
+
+
+@dataclass
+class KeywordArg:
+    name: str
+    value: Expr
+
+
+@dataclass
+class NumberLiteral(Expr):
+    value: float
+    loc: Loc
+    _KIND = "NumberLiteral"
+
+
+@dataclass
+class StringLiteral(Expr):
+    value: str
+    loc: Loc
+    _KIND = "StringLiteral"
+
+
+@dataclass
+class BoolLiteral(Expr):
+    value: bool
+    loc: Loc
+    _KIND = "BoolLiteral"
+
+
+@dataclass
+class NaLiteral(Expr):
+    loc: Loc
+    _KIND = "NaLiteral"
+
+
+@dataclass
+class ColorLiteral(Expr):
+    r: float
+    g: float
+    b: float
+    a: float
+    loc: Loc
+    _KIND = "ColorLiteral"
+
+
+@dataclass
+class Identifier(Expr):
+    name: str
+    loc: Loc
+    _KIND = "Identifier"
+
+
+@dataclass
+class Binary(Expr):
+    op: str
+    left: Expr
+    right: Expr
+    loc: Loc
+    _KIND = "BinaryExpr"
+
+
+@dataclass
+class Unary(Expr):
+    op: str
+    operand: Expr
+    loc: Loc
+    _KIND = "UnaryExpr"
+
+
+@dataclass
+class Call(Expr):
+    callee: str
+    args: List[Expr]
+    kwargs: List[KeywordArg]
+    loc: Loc
+    _KIND = "CallExpr"
+
+
+@dataclass
+class History(Expr):
+    source: Expr
+    offset: Expr
+    loc: Loc
+    _KIND = "HistoryExpr"
+
+
+@dataclass
+class Ternary(Expr):
+    condition: Expr
+    if_true: Expr
+    if_false: Expr
+    loc: Loc
+    _KIND = "TernaryExpr"
+
+
+@dataclass
+class ArrayLiteral(Expr):
+    elements: List[Expr]
+    loc: Loc
+    _KIND = "ArrayLiteral"
+
+
+@dataclass
+class MapLiteral(Expr):
+    entries: List[Tuple[Expr, Expr]]
+    loc: Loc
+    _KIND = "MapLiteral"
+
+
+@dataclass
+class Member(Expr):
+    object: Expr
+    member: str
+    loc: Loc
+    _KIND = "MemberExpr"
+
+
+@dataclass
+class MethodCall(Expr):
+    object: Expr
+    method: str
+    args: List[Expr]
+    loc: Loc
+    _KIND = "MethodCallExpr"
+
+
+class FmtPart:
+    """The Rust FmtPart enum; variants are the nested classes
+    FmtPart.Text / FmtPart.Expr so call sites keep the Rust paths."""
+
+    @dataclass
+    class Text:
+        value: str
+
+    @dataclass
+    class Expr:
+        expr: "Expr"
+
+
+@dataclass
+class FormatString(Expr):
+    parts: List[object]  # FmtPart.Text | FmtPart.Expr
+    specs: List[Optional[str]]
+    loc: Loc
+    _KIND = "FormatStringExpr"
+
+
+@dataclass
+class FunctionParam:
+    name: str
+    default_value: Optional[Expr]
+
+
+@dataclass
+class TypeField:
+    name: str
+    field_type: str
+    default_value: Optional[Expr]
+
+
+@dataclass
+class DeclarationStmt:
+    args: List[Expr]
+    kwargs: List[KeywordArg]
+    symbol: Optional[str]
+    timeframe: Optional[str]
+    execution_mode: str  # "backtest" | "execute"
+    broker: Optional[str]
+    account: Optional[str]
+    password: Optional[str]
+    loc: Loc
+
+
+@dataclass
+class UseStmt:
+    canonical: str
+    timeframe: Optional[str]
+    alias: str
+    alias_explicit: bool
+    is_dataset: bool
+    loc: Loc
+
+
+class Stmt:
+    """Base class for all statement nodes (the Rust Stmt enum)."""
+
+
+@dataclass
+class Assign(Stmt):
+    target: str
+    op: str
+    value: Expr
+    loc: Loc
+
+
+@dataclass
+class Persist(Stmt):
+    target: str
+    value: Expr
+    loc: Loc
+
+
+@dataclass
+class Const(Stmt):
+    target: str
+    value: Expr
+    loc: Loc
+
+
+@dataclass
+class If(Stmt):
+    condition: Expr
+    body: List[Stmt]
+    elifs: List[Tuple[Expr, List[Stmt]]]
+    else_body: List[Stmt]
+    loc: Loc
+
+
+@dataclass
+class For(Stmt):
+    variable: str
+    iterable: Expr
+    body: List[Stmt]
+    loc: Loc
+
+
+@dataclass
+class While(Stmt):
+    condition: Expr
+    body: List[Stmt]
+    loc: Loc
+
+
+@dataclass
+class Break(Stmt):
+    loc: Loc
+
+
+@dataclass
+class Continue(Stmt):
+    loc: Loc
+
+
+@dataclass
+class FunctionDef(Stmt):
+    name: str
+    params: List[FunctionParam]
+    body: List[Stmt]
+    loc: Loc
+
+
+@dataclass
+class Return(Stmt):
+    value: Optional[Expr]
+    loc: Loc
+
+
+@dataclass
+class ExprStmt(Stmt):
+    expr: Expr
+    loc: Loc
+
+
+@dataclass
+class MemberAssign(Stmt):
+    target: Expr
+    value: Expr
+    loc: Loc
+
+
+@dataclass
+class MultiAssign(Stmt):
+    targets: List[str]
+    value: Expr
+    loc: Loc
+
+
+@dataclass
+class TypeDef(Stmt):
+    name: str
+    fields: List[TypeField]
+    loc: Loc
+
+
+@dataclass
+class EnumDef(Stmt):
+    name: str
+    members: List[Tuple[str, Optional[str]]]
+    loc: Loc
+
+
+@dataclass
+class Program:
+    declaration: DeclarationStmt
+    uses: List[UseStmt]
+    body: List[Stmt]