openscript 0.4.0__tar.gz

openscript-0.4.0/PKG-INFO

@@ -0,0 +1,82 @@
+Metadata-Version: 2.4
+Name: openscript
+Version: 0.4.0
+Summary: An open trading language: the engine that runs a compiled program.
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/marketcalls/openscript#readme
+Project-URL: Source, https://github.com/marketcalls/openscript
+Keywords: trading,language,interpreter,indicators,backtesting
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# openscript
+
+The engine that runs a compiled OpenScript program, in Python.
+
+OpenScript is an open trading language. A script is compiled to a **compiled
+program**: plain data, an instruction list, never generated code. This package
+runs one.
+
+It exists so that a platform can run a strategy where a JavaScript runtime is
+not available, which for a production trading server is the ordinary case. The
+compiler and the first engine are the `openalgo-script` package on npm; this is
+the second engine, and the two are held to each other by a conformance suite
+where any disagreement is a release blocker.
+
+## What it is
+
+- **No compiler.** This package is handed a compiled program and never a script.
+  The program arrives as canonical text, which is what a run's hash is taken
+  over, so an engine cannot quietly run something other than what was recorded.
+- **Nothing builds code out of text.** No string evaluator, no statement
+  executor, no import driven by hand, no object graph loaded out of bytes. That
+  is what lets a platform run many people's scripts in one process, and it is
+  enforced by a check rather than intended.
+- **Zero dependencies.** The standard library only, and not the parts of it that
+  stop a run being reproducible. Measured on every build against the module
+  names the running interpreter says are its own.
+
+## Installing
+
+```
+pip install openscript
+```
+
+Python 3.12 or newer. Nothing else.
+
+## Using it
+
+```python
+from openscript.run import load_text
+
+loaded = load_text(program_text, settings, library)
+if loaded.ok:
+    result = loaded.run.execute_bar(0, bar)
+```
+
+A host loads a program once and pushes bars at it one at a time, keeping a
+checkpoint so a bar that is still moving can be executed again and rolled back.
+The conformance adapter is the other way in:
+
+```
+python -m openscript --describe
+python -m openscript <case-directory>
+```
+
+## Where the documentation is
+
+The specification and the guides live in the repository:
+
+- `docs/integrating/the-python-engine.md` for what is in this package and what a
+  host needs.
+- `docs/integrating/running-a-strategy.md` for driving it bar by bar: the load,
+  the bar cycle, the rollback a moving bar rests on, and the order boundary.
+- `spec/` for the language, the compiled program format, the standard library
+  and the conformance suite.
+
+## Licence
+
+Apache-2.0.

openscript-0.4.0/README.md

@@ -0,0 +1,68 @@
+# openscript
+
+The engine that runs a compiled OpenScript program, in Python.
+
+OpenScript is an open trading language. A script is compiled to a **compiled
+program**: plain data, an instruction list, never generated code. This package
+runs one.
+
+It exists so that a platform can run a strategy where a JavaScript runtime is
+not available, which for a production trading server is the ordinary case. The
+compiler and the first engine are the `openalgo-script` package on npm; this is
+the second engine, and the two are held to each other by a conformance suite
+where any disagreement is a release blocker.
+
+## What it is
+
+- **No compiler.** This package is handed a compiled program and never a script.
+  The program arrives as canonical text, which is what a run's hash is taken
+  over, so an engine cannot quietly run something other than what was recorded.
+- **Nothing builds code out of text.** No string evaluator, no statement
+  executor, no import driven by hand, no object graph loaded out of bytes. That
+  is what lets a platform run many people's scripts in one process, and it is
+  enforced by a check rather than intended.
+- **Zero dependencies.** The standard library only, and not the parts of it that
+  stop a run being reproducible. Measured on every build against the module
+  names the running interpreter says are its own.
+
+## Installing
+
+```
+pip install openscript
+```
+
+Python 3.12 or newer. Nothing else.
+
+## Using it
+
+```python
+from openscript.run import load_text
+
+loaded = load_text(program_text, settings, library)
+if loaded.ok:
+    result = loaded.run.execute_bar(0, bar)
+```
+
+A host loads a program once and pushes bars at it one at a time, keeping a
+checkpoint so a bar that is still moving can be executed again and rolled back.
+The conformance adapter is the other way in:
+
+```
+python -m openscript --describe
+python -m openscript <case-directory>
+```
+
+## Where the documentation is
+
+The specification and the guides live in the repository:
+
+- `docs/integrating/the-python-engine.md` for what is in this package and what a
+  host needs.
+- `docs/integrating/running-a-strategy.md` for driving it bar by bar: the load,
+  the bar cycle, the rollback a moving bar rests on, and the order boundary.
+- `spec/` for the language, the compiled program format, the standard library
+  and the conformance suite.
+
+## Licence
+
+Apache-2.0.

openscript-0.4.0/openscript/__init__.py

@@ -0,0 +1,40 @@
+"""The second engine: a compiled program, run in Python.
+
+The package is importable as one name, ``openscript``, and this module is its
+door. Nothing is exported through it: every caller, inside this package and
+outside it, names the module it wants, so the import that reaches a rule says
+where that rule lives.
+
+What is where, for somebody reading this engine rather than running it:
+
+- ``__main__.py``     the entry point the conformance adapter starts, as
+                      ``python -m openscript``, which is the command line half
+                      of the three invocations ``spec/conformance.md`` section
+                      9 gives an adapter.
+- the modules beside  the machine of ``spec/compiled-program.md`` sections 2 to
+  this one            11: the program read as data, the instruction set, the
+                      memory regions and their lifetimes, the values, the bars,
+                      the inputs, the verification done before the first bar,
+                      the execution budget, the canonical encoding, the
+                      diagnostics and the two version numbers.
+- ``library/``        the functions of ``spec/stdlib.md``, each accumulating in
+                      the order that page fixes, in the two halves that page
+                      divides them into: the calls that remember nothing and
+                      the calls that carry state from bar to bar.
+- ``strategy/``       what a strategy decided and what came back: the order
+                      calls, the intents a bar leaves behind, the frames a host
+                      folds in and the ledger of ``stdlib.md`` section 17.
+- ``accounting/``     what those fills came to: the charges, the trades, the
+                      equity a report is marked on, and the summary.
+- ``adapter/``        one conformance case, read from its files, run, and
+                      answered channel by channel.
+
+Two rules that are not this file's to relax, both from ``CLAUDE.md``:
+
+Nothing here builds code out of text. No string evaluator, no statement
+executor, no compiler, no import by a name computed at run time, no object
+graph loaded out of bytes. The compiled program is data, and an engine that
+reads data is why a host can run many people's scripts in one process.
+
+Nothing here imports anything but the standard library.
+"""

openscript-0.4.0/openscript/__main__.py

@@ -0,0 +1,62 @@
+"""The entry point the conformance adapter starts: ``python -m openscript``.
+
+``spec/conformance.md`` section 9 gives an adapter three invocations, each
+writing one JSON object to standard output and exiting 0, and this module is the
+command line half of all three. Everything about what the engine answers is next
+door in ``adapter/``.
+
+    python -m openscript --describe
+    python -m openscript <case-directory>
+    python -m openscript --actual <case-directory>
+
+**The compiled program arrives on standard input**, as one JSON object holding
+the canonical text of the program under ``program``, or holding ``diagnostics``
+when the case's script did not compile. This engine implements no compiler, which
+section 1 provides for: an implementation that only has an engine reads compiled
+programs produced elsewhere, runs the engine half and says so. The text goes to
+``load_text`` rather than to a parsed object, because canonical bytes are what a
+host sends in production and the hash it records a run against is taken over
+them.
+
+**Why it exits 0 on a failing case.** Section 9 puts the outcome inside the
+object, and the runner holds the clock and the child process, so a non-zero exit
+is the one thing left to mean a crash. An invocation that is not one of the three
+is refused with a non-zero exit, because nothing it could write would be a case
+result.
+
+**The output is the canonical encoding**, written by the same writer the compiled
+program's text boundary uses. One writer means a number in a report is spelled
+the way a number in a program is, which is ``language.md`` section 5.5 in both
+places rather than the interpreter's own rendering in one of them.
+"""
+
+import sys
+
+from .adapter.answers import invoke
+from .adapter.spellings import Malformed
+from .canonical import canonicalise
+
+_USAGE = (
+    "Usage: python -m openscript --describe | <case-directory> | --actual <case-directory>\n"
+    "conformance.md section 9 gives an adapter these three invocations and no other.\n"
+    "A case invocation is handed the compiled program on standard input, as one JSON\n"
+    "object holding the canonical program text under program, because this engine\n"
+    "implements no compiler and reads programs produced elsewhere (section 1)."
+)
+
+
+def main(arguments) -> int:
+    try:
+        answered = invoke(arguments)
+    except Malformed as reason:
+        sys.stderr.write(f"{reason}\n")
+        return 1
+    if answered is None:
+        sys.stderr.write(f"{_USAGE}\n")
+        return 1
+    sys.stdout.write(f"{canonicalise(answered)}\n")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

openscript-0.4.0/openscript/accounting/__init__.py

@@ -0,0 +1,74 @@
+"""The money: what a run made, what it cost, and what that is worth knowing.
+
+**This package imports no interpreter and no ledger, and it never will.** It is
+arithmetic over portable data: a list of settled fills, a list of bar closes, a
+charge schedule and the contract the run was carried out under. Two things follow
+from that and both of them are the reason for it.
+
+A stored record can be reported again with no engine present, which is what makes
+a run record a conformance case rather than a souvenir. And the engine can call
+this, when the day comes that a script may read its own equity, without a cycle
+and without a second implementation of any of these formulas sitting inside the
+execution path disagreeing with this one.
+
+What is here:
+
+- ``shapes``      the atoms: a fill, a contract and a bar's close
+- ``charges``     what one fill cost, in the order the lines are declared
+- ``trades``      the round trips, one per position reference
+- ``equity``      one point per report bar, marked to the close
+- ``statistics``  the summary, and which half of the trade list each figure counts
+- ``report``      the one pass, in the one order, that is the result
+
+**What none of these is, is specified.** ``conformance.md`` section 4 makes
+``performance`` a channel a case asserts and ``stdlib.md`` 17.4 leaves every
+figure in it planned, so the formulas below are read from the first engine rather
+than from a page. That is a defect of the specification and not of either engine,
+and it is recorded where a reader of this package will meet it rather than only in
+a report nobody keeps.
+"""
+
+from .analysis import SideAnalysis, TradeAnalysis, analysis_of
+from .charges import (
+    ChargeBreakdown,
+    ChargeLine,
+    ChargeSchedule,
+    charge_for,
+    round_money,
+    schedule_from_declaration,
+    schedule_problem,
+)
+from .equity import EquityPoint, bars_in_market_over, equity_over, open_on_bar, ratio_of
+from .report import Report, report_of
+from .shapes import BarMark, Contract, RecordedFill
+from .statistics import Summary, summary_of
+from .trades import Trade, closed_by, opened_by, trades_of
+
+__all__ = [
+    "BarMark",
+    "ChargeBreakdown",
+    "ChargeLine",
+    "ChargeSchedule",
+    "Contract",
+    "EquityPoint",
+    "RecordedFill",
+    "Report",
+    "SideAnalysis",
+    "Summary",
+    "Trade",
+    "TradeAnalysis",
+    "analysis_of",
+    "bars_in_market_over",
+    "charge_for",
+    "closed_by",
+    "equity_over",
+    "open_on_bar",
+    "opened_by",
+    "ratio_of",
+    "report_of",
+    "round_money",
+    "schedule_from_declaration",
+    "schedule_problem",
+    "summary_of",
+    "trades_of",
+]

openscript-0.4.0/openscript/accounting/analysis.py

@@ -0,0 +1,174 @@
+"""The trades taken apart: by direction, by extreme, and by run.
+
+The summary answers what the whole run did. Three questions it cannot answer are
+asked here, and each of them is a question about whether the summary means what
+it looks like it means.
+
+**Which side made the money.** A run whose long trades paid for its short ones
+reports a healthy net and is two strategies, one of which is losing. The summary
+cannot show that, because every figure in it is folded over both sides at once.
+Splitting it is not a refinement of the headline number, it is the first thing
+that can contradict it.
+
+**Whether one trade is the result.** A hundred trades and a profit factor of two
+reads as an edge until the largest win is the whole of the net. The expectancy's
+standard error already says how wide the spread is; the largest win and the
+largest loss say where the width came from, which is the part a reader can act
+on.
+
+**What the run of losses was.** The deepest drawdown is a money figure and the
+longest one is a bar count, and neither is the number that actually stops
+somebody trading a strategy. That number is how many times in a row it was
+wrong, and it is not derivable from anything in the summary: the same win rate
+over the same trades gives a streak of two or a streak of eleven depending on an
+ordering the summary folds away.
+
+**Every figure here is over closed trades, and that is the whole rule.** An open
+trade has no net to win or lose by, so it is in none of these counts, in no
+streak and in no extreme. The consequence worth stating: ``long.count`` plus
+``short.count`` is the summary's ``trade_count`` and not the length of the list
+folded, and the summary's ``open_trade_count`` is where the difference goes.
+
+This is the first engine's ``src/core/accounting/analysis.ts`` in this language's
+spellings. The two are one algorithm and the conformance suite is what holds
+them to it.
+"""
+
+from dataclasses import dataclass
+from typing import List, Optional, Sequence
+
+from .trades import Trade
+
+
+@dataclass(frozen=True)
+class SideAnalysis:
+    """One direction's own figures, folded over that side's closed trades."""
+
+    count: int
+    wins: int
+    losses: int
+    #: Exactly zero net, counted in neither half, as in the summary.
+    scratches: int
+    #: Net after charges, which is the figure the sides are compared on.
+    net_profit: float
+    #: ``wins / (wins + losses)``, ``None`` where this side decided nothing.
+    win_rate: Optional[float]
+
+
+@dataclass(frozen=True)
+class TradeAnalysis:
+    """The trades by direction, by extreme and by run.
+
+    ``long`` and ``short`` partition the closed trades, so their counts sum to
+    the summary's ``trade_count`` and their nets sum to its ``net_profit``.
+    """
+
+    long: SideAnalysis
+    short: SideAnalysis
+    #: The best closed trade's net, zero where none closed and zero where every
+    #: closed trade lost. Zero rather than ``None``, because the figure is read
+    #: beside ``largest_loss`` and against the net, and a ``None`` in a column
+    #: of money makes every reader handle a case that means "nothing won",
+    #: which is what zero already means in this column.
+    largest_win: float
+    #: The worst closed trade's net as a positive magnitude, zero where none lost.
+    largest_loss: float
+    #: The longest run of consecutive winning closed trades, in the order they
+    #: closed, and not the order they opened: that is the order the account
+    #: experienced them in. The two differ whenever a trade is held across
+    #: another one's whole life, which is every scaling strategy.
+    max_consecutive_wins: int
+    #: The same, for losses.
+    max_consecutive_losses: int
+
+
+@dataclass
+class _SideTally:
+    """A side's figures under construction, before the rates are taken."""
+
+    count: int = 0
+    wins: int = 0
+    losses: int = 0
+    scratches: int = 0
+    net_profit: float = 0.0
+
+
+def _side_of(tally: _SideTally) -> SideAnalysis:
+    decided = tally.wins + tally.losses
+    return SideAnalysis(
+        count=tally.count,
+        wins=tally.wins,
+        losses=tally.losses,
+        scratches=tally.scratches,
+        net_profit=tally.net_profit,
+        win_rate=None if decided == 0 else tally.wins / decided,
+    )
+
+
+def analysis_of(trades: Sequence[Trade]) -> TradeAnalysis:
+    """One pass over the closed trades, in closing order.
+
+    The list arrives in opening order, which is what the equity fold needs. The
+    streaks need closing order, so the closed trades are ordered here rather
+    than anywhere else: reordering the list the caller holds would change the
+    equity curve.
+
+    A trade whose net is exactly zero is a scratch, which is the summary's rule.
+    A scratch **breaks** a streak without extending either one: a strategy that
+    went right, flat, right was not right twice running, and counting the flat
+    trade as either would make the streak a figure that depends on a rounding at
+    the last digit.
+    """
+    long = _SideTally()
+    short = _SideTally()
+    largest_win = 0.0
+    largest_loss = 0.0
+    max_consecutive_wins = 0
+    max_consecutive_losses = 0
+    win_streak = 0
+    loss_streak = 0
+
+    closed: List[Trade] = [trade for trade in trades if not trade.is_open]
+    # A trade closes on a bar, and two can close on the same one. The opening
+    # order breaks the tie, because it is the order the list arrived in and the
+    # only other fact available: a sort that is not total gives two engines two
+    # different streaks from one list of trades.
+    closed.sort(key=lambda trade: (
+            0 if trade.closed_on_bar is None else trade.closed_on_bar,
+            trade.index,
+        ))
+
+    for trade in closed:
+        side = long if trade.side == "long" else short
+        side.count += 1
+        side.net_profit += trade.net_profit
+
+        if trade.net_profit > 0:
+            side.wins += 1
+            if trade.net_profit > largest_win:
+                largest_win = trade.net_profit
+            win_streak += 1
+            loss_streak = 0
+            if win_streak > max_consecutive_wins:
+                max_consecutive_wins = win_streak
+        elif trade.net_profit < 0:
+            side.losses += 1
+            if -trade.net_profit > largest_loss:
+                largest_loss = -trade.net_profit
+            loss_streak += 1
+            win_streak = 0
+            if loss_streak > max_consecutive_losses:
+                max_consecutive_losses = loss_streak
+        else:
+            side.scratches += 1
+            win_streak = 0
+            loss_streak = 0
+
+    return TradeAnalysis(
+        long=_side_of(long),
+        short=_side_of(short),
+        largest_win=largest_win,
+        largest_loss=largest_loss,
+        max_consecutive_wins=max_consecutive_wins,
+        max_consecutive_losses=max_consecutive_losses,
+    )