openscript 0.4.0__py3-none-any.whl

openscript/strategy/__init__.py

@@ -0,0 +1,78 @@
+"""Orders, frames, fills and the ledger: ``stdlib.md`` section 17, in Python.
+
+What a strategy decided, what the destination said became of it, and the position
+every figure in the language is folded from. Nothing here decides where an order
+goes: a destination is the host's, and the minute on it in ``spec/decisions.md``
+says the engine learns nothing about it.
+
+What is here, by the page it is written from:
+
+- ``statuses``   17.7's vocabulary: the seven words, the four that end an order
+- ``intents``    ``host-interface.md`` 7.1 and 7.2, the two shapes that cross over
+- ``rows``       17.7's row and 17.8's fold, which is where double counting happens
+- ``positions``  the position book: what settled, per reference, and at what price
+- ``holdings``   17.1, which position an order is sent against
+- ``closable``   17.1 and 17.2, what is left to reduce and which side reduces it
+- ``calls``      17.2 and 17.3's signatures, read once into named fields
+- ``sizing``     how much each order sends, and the split that crosses no zero
+- ``placing``    what each of the nine calls means
+- ``refusals``   OS7002 to OS7013 and OS7017, asked before anything is sent
+- ``ledger``     the run's own record, and the one way a frame gets in
+- ``fills``      what settled, and the ordinal a case names an intent by
+
+**Two things this package will not do.** It reaches no destination: an intent
+leaves through the caller, and a frame arrives through ``Ledger.deliver``, which
+is the only way in (``host-interface.md`` 7.4). And it holds no money. What a run
+made is ``accounting``'s, computed after the fact from the fills, and the two are
+separate so that a stored record can be reported again with no engine present.
+"""
+
+from .calls import ORDER_CALLS, OrderCall, call_of
+from .closable import Closable, closable, closable_units, closing_for, closing_side
+from .fills import Fills, Intents
+from .holdings import Holding, holdings, joining, opposing, outgoing_for, protecting
+from .intents import Identity, IntentBar, OrderFrame, OrderIntent, Placement
+from .ledger import Ledger, LedgerOptions, PlacedCall
+from .positions import Positions
+from .rows import FrameOutcome, LedgerRow, Reduction, fold_frame, working_units
+from .sizing import MappedOrder
+from .statuses import HOST_SENDABLE, STATUSES, TERMINAL, is_terminal, status_from
+
+__all__ = [
+    "Closable",
+    "Fills",
+    "HOST_SENDABLE",
+    "Holding",
+    "Identity",
+    "IntentBar",
+    "Intents",
+    "Ledger",
+    "LedgerOptions",
+    "LedgerRow",
+    "MappedOrder",
+    "ORDER_CALLS",
+    "OrderCall",
+    "OrderFrame",
+    "OrderIntent",
+    "Placement",
+    "PlacedCall",
+    "Positions",
+    "Reduction",
+    "FrameOutcome",
+    "STATUSES",
+    "TERMINAL",
+    "call_of",
+    "closable",
+    "closable_units",
+    "closing_for",
+    "closing_side",
+    "fold_frame",
+    "holdings",
+    "is_terminal",
+    "joining",
+    "opposing",
+    "outgoing_for",
+    "protecting",
+    "status_from",
+    "working_units",
+]

openscript/strategy/calls.py

@@ -0,0 +1,201 @@
+"""One order call, read once into the fields ``stdlib.md`` 17.2 and 17.3 name.
+
+**The positions the arguments arrive in are read here and nowhere else.** Which
+slot holds a quantity and which holds a trigger is a fact about the library
+surface, and a fact read in two places is one that has to be corrected in two
+places. The mapping to orders and the refusals both read this record, so neither
+of them counts arguments.
+
+**An argument the script left out and an argument it wrote as absent are not the
+same thing, and an order is where the difference matters most.** ``buy()`` means
+"use the size I declared" and takes the declaration's own quantity.
+``buy(qty = none)`` means "I computed a size and it came out absent", which is a
+sizing calculation that has not warmed up or a divisor that was zero, and it is
+OS7002: an order is the one place in the language where doing nothing quietly is
+worse than stopping loudly (``language.md`` 6.8).
+
+``compiled-program.md`` 4.10 is what makes the two readable apart. An order call
+carries one argument more than the language surface shows, and it is the last
+one: the names of the arguments the script wrote, in parameter order, separated
+by single spaces. Everything the script did not write takes the default the page
+documents, which the mapping applies.
+
+The parameter names below are those two sections' signatures, which is the one
+fact this file copies out of the page, and ``tests/test_calls_surface.py`` reads
+them back out of it. The engine reads no page, so the alternative to a copy held
+by a test is a copy held by nobody.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Dict, Optional, Sequence, Tuple
+
+from .intents import SIDES, TYPES
+
+#: The parameters of each order call, in signature order, without the extra
+#: argument 4.10 adds. A call's arity is one more than the length of its row.
+PARAMETERS: Dict[str, Tuple[str, ...]] = {
+    "buy": ("qty", "limit", "stop", "tag", "leg"),
+    "sell": ("qty", "limit", "stop", "tag", "leg"),
+    "close": ("tag", "qty", "leg"),
+    "exit": ("tag", "qty", "limit", "stop", "profit", "loss", "leg"),
+    "cancel": ("tag",),
+    "cancelAll": (),
+    "order.place": ("side", "qty", "type", "price", "trigger", "tag", "leg"),
+    "order.reverse": ("qty", "tag", "leg"),
+    "order.bracket": ("tag", "profit", "loss", "leg"),
+}
+
+#: The nine calls that place, cancel or protect, which is what a ledger reads.
+ORDER_CALLS: Tuple[str, ...] = tuple(PARAMETERS)
+
+
+@dataclass(frozen=True)
+class OrderCall:
+    """An order call, with every argument under the name its signature gives it.
+
+    ``trigger`` is an order's stop price, which ``buy`` and ``sell`` spell
+    ``stop`` and ``order.place`` spells ``trigger``. ``stop`` and ``target`` are
+    a bracket's two levels, which ``exit`` spells ``stop`` and ``limit``. The two
+    are separate fields because they are separate things: one rests at a venue
+    and one is a level the strategy holds.
+    """
+
+    name: str
+    position: Any
+    #: Arguments the script wrote that came out absent, in signature order.
+    absent: Tuple[str, ...] = ()
+    side: Optional[str] = None
+    qty: Optional[float] = None
+    order_type: Optional[str] = None
+    limit: Optional[float] = None
+    trigger: Optional[float] = None
+    target: Optional[float] = None
+    stop: Optional[float] = None
+    profit: Optional[float] = None
+    loss: Optional[float] = None
+    tag: Optional[str] = None
+
+
+def _number(args: Sequence[Any], index: int) -> Optional[float]:
+    """A number the script stated, or nothing where it stated none.
+
+    A boolean is not a number here, as it is not anywhere else in this engine:
+    this interpreter's own ``True`` equals ``1``, and an order sized from one
+    would be an order nobody wrote.
+    """
+    if index >= len(args):
+        return None
+    value = args[index]
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    return float(value) if value == value and abs(value) != float("inf") else None
+
+
+def _text(args: Sequence[Any], index: int) -> Optional[str]:
+    if index >= len(args):
+        return None
+    value = args[index]
+    return value if isinstance(value, str) else None
+
+
+def _one_of(words: Sequence[str], word: Optional[str]) -> Optional[str]:
+    return word if word in words else None
+
+
+def _absent_of(name: str, args: Sequence[Any]) -> Tuple[str, ...]:
+    """The arguments the script wrote that came out absent, in signature order.
+
+    Read from the names 4.10 puts in the last argument rather than from a list of
+    this file's own, because the signature is the library's and a second copy
+    here is one more thing to correct when a signature changes.
+    """
+    params = PARAMETERS.get(name, ())
+    written = _text(args, len(params))
+    named = set(written.split(" ")) if written else set()
+    found = []
+    for at, one in enumerate(params):
+        if one in named and at < len(args) and args[at] is None:
+            found.append(one)
+    return tuple(found)
+
+
+def _placing(side: str, args: Sequence[Any], position: Any) -> OrderCall:
+    """``buy`` and ``sell``, whose name is their side."""
+    return OrderCall(
+        name=side,
+        position=position,
+        side=side,
+        qty=_number(args, 0),
+        limit=_number(args, 1),
+        trigger=_number(args, 2),
+        tag=_text(args, 3),
+    )
+
+
+def _read(name: str, args: Sequence[Any], position: Any) -> OrderCall:
+    if name in ("buy", "sell"):
+        return _placing(name, args, position)
+    if name == "close":
+        # The tag defaults to absence rather than to the empty string, because a
+        # call that names none flattens the whole leg and the empty string is a
+        # tag an order can carry.
+        return OrderCall(name=name, position=position, qty=_number(args, 1), tag=_text(args, 0))
+    if name == "exit":
+        return OrderCall(
+            name=name,
+            position=position,
+            qty=_number(args, 1),
+            target=_number(args, 2),
+            stop=_number(args, 3),
+            profit=_number(args, 4),
+            loss=_number(args, 5),
+            tag=_text(args, 0),
+        )
+    if name == "cancel":
+        return OrderCall(name=name, position=position, tag=_text(args, 0))
+    if name == "order.place":
+        return OrderCall(
+            name=name,
+            position=position,
+            side=_one_of(SIDES, _text(args, 0)),
+            qty=_number(args, 1),
+            order_type=_one_of(TYPES, _text(args, 2)),
+            limit=_number(args, 3),
+            trigger=_number(args, 4),
+            tag=_text(args, 5),
+        )
+    if name == "order.reverse":
+        return OrderCall(name=name, position=position, qty=_number(args, 0), tag=_text(args, 1))
+    if name == "order.bracket":
+        # Distances only, which is the whole of this spelling.
+        return OrderCall(
+            name=name,
+            position=position,
+            profit=_number(args, 1),
+            loss=_number(args, 2),
+            tag=_text(args, 0),
+        )
+    return OrderCall(name=name, position=position)
+
+
+def call_of(name: str, args: Sequence[Any], position: Any) -> OrderCall:
+    """Reads one call, whichever of the nine it is."""
+    read = _read(name, args, position)
+    absent = _absent_of(name, args)
+    if not absent:
+        return read
+    return OrderCall(
+        name=read.name,
+        position=read.position,
+        absent=absent,
+        side=read.side,
+        qty=read.qty,
+        order_type=read.order_type,
+        limit=read.limit,
+        trigger=read.trigger,
+        target=read.target,
+        stop=read.stop,
+        profit=read.profit,
+        loss=read.loss,
+        tag=read.tag,
+    )

openscript/strategy/closable.py

@@ -0,0 +1,182 @@
+"""What is left to reduce and which side reduces it, ``stdlib.md`` 17.1 and 17.2.
+
+**Both questions are about a part rather than about the leg**, and the leg is the
+case of a part that no tag names. A leg can be long under one tag and short under
+another, and then its net answers neither question for either of them: a close
+taking its side from the net sent an order that added to the part it was told to
+flatten, and a count taken from the net did not see the close already on its way
+to that part.
+
+**What is available to reduce is the settled position less everything already
+working against it.** A position is folded from settled fills and from nothing
+else (17.8), which is right and is what makes this file necessary: an order the
+destination has not answered has filled nothing, so the leg still reads what it
+held before that order left, and measured against that alone every reducing order
+sends the whole position again.
+
+**The scope is the run and the position, not the bar.** Counted over one call,
+two bare closes on one bar took a leg holding three long to three short. Counted
+over one bar, the same two closes one bar apart did the same thing, because the
+bar's own record is emptied when the bar index changes. So the record is the
+ledger's, which is the run's: an order the destination still has is exactly a row
+that is neither terminal nor fully filled.
+
+**In units, because a position is.** A quantity the script stated is in the
+declaration's own unit (``host-interface.md`` 7.1), so it is a number this file
+can read only where that unit is units. What is done with an order it cannot read
+is the only reading that cannot cross zero: that the order took the whole of the
+part. So what is left carries whether it was counted or assumed. The mapping
+reads the number, because sending nothing is safe either way; the refusal reads
+both, because a refusal may only name a number it measured.
+"""
+
+from dataclasses import dataclass
+from typing import Optional, Protocol, Sequence
+
+from .positions import sign
+from .rows import LedgerRow, working_units
+from .statuses import is_terminal
+
+
+class Closing(Protocol):
+    """What the arithmetic below needs: the leg and the rows of its own ledger."""
+
+    def size(self) -> float:
+        """The leg's net position in units, folded from settled fills."""
+
+    def rows(self) -> Sequence[LedgerRow]:
+        """The rows this strategy placed, newest last."""
+
+
+@dataclass(frozen=True)
+class Closable:
+    """What one part of the leg can still close, and whether that was measured."""
+
+    #: The units a close may still send against it.
+    units: float
+    #: Whether every order counted against it stated a quantity in units.
+    counted: bool
+
+
+def closing_side(size: float) -> Optional[str]:
+    """The side that reduces a position, or nothing when there is none to reduce.
+
+    One fact with two readers: the mapping gives a close its direction with it,
+    and the arithmetic below tells an order on its way out of the position from
+    one on its way in, which is the difference between a reduction that is still
+    working and an entry that holds nothing.
+    """
+    if size > 0:
+        return "sell"
+    if size < 0:
+        return "buy"
+    return None
+
+
+def held_under(ctx: Closing, tag: str) -> float:
+    """The settled units held under one tag, signed the way a position is."""
+    held = 0.0
+    for row in ctx.rows():
+        if row.tag != tag:
+            continue
+        held += row.filled_qty if row.side == "buy" else -row.filled_qty
+    return held
+
+
+def _holding_of(ctx: Closing, tag: Optional[str]) -> float:
+    """What the part a call names holds, signed the way a position is.
+
+    The leg where the call names no tag, and the settled quantity of that tag's
+    own rows where it names one. One function because it is one question, and
+    every number this file produces about a part is taken from it.
+    """
+    return ctx.size() if tag is None else held_under(ctx, tag)
+
+
+def closing_for(ctx: Closing, tag: Optional[str]) -> Optional[str]:
+    """The side that reduces the part a call names, or nothing where it holds none.
+
+    Taken from the leg instead, a call named ``close`` opened a position: a leg
+    holding ten long under one tag and four short under another nets six long, so
+    closing the short part was answered with a sell, which took that part to eight
+    short and cut the other one to six. A part whose own rows have netted to
+    nothing has no side and the call sends nothing, which is 17.2's idempotence.
+    """
+    return closing_side(_holding_of(ctx, tag))
+
+
+def _committed(ctx: Closing, tag: Optional[str]) -> Closable:
+    """The units already working against the position, across the whole run.
+
+    Only an order on the side that reduces what the leg holds now, and every
+    order on that side. A row records what it reduced at the moment it was sent,
+    and a leg that has changed sign since is being reduced from the other side:
+    an order still working on the old side is adding to the leg rather than
+    taking from it, and an order recorded as adding is a reduction now whatever
+    it was then. The side is the part's own, which is the leg's where no tag
+    names one.
+    """
+    held = _holding_of(ctx, tag)
+    side = closing_side(held)
+    if side is None:
+        return Closable(units=0.0, counted=True)
+    units = 0.0
+    counted = True
+    for row in ctx.rows():
+        if row.side != side or is_terminal(row.status):
+            continue
+        reduces = row.reduces
+        if reduces is not None:
+            if tag is not None and reduces.part != tag:
+                continue
+            working = working_units(row)
+            if working == 0:
+                continue
+            units += working
+            counted = counted and reduces.counted
+            continue
+        # An order that was an entry when it left. Its own tag is what names it,
+        # because a reduction's part is the tag a close named and an entry named
+        # no part of anything.
+        if tag is not None and row.tag != tag:
+            continue
+        if row.units is None:
+            # A quantity in the declaration's own unit, working against this part
+            # and unreadable as a number of units. Taken to cover the whole of
+            # what is there, which is the reading 17.1 already makes for the
+            # other order it cannot read.
+            units += abs(held)
+            counted = False
+            continue
+        units += max(0.0, row.units - row.filled_qty)
+    return Closable(units=units, counted=counted)
+
+
+def closable(ctx: Closing, tag: Optional[str]) -> Closable:
+    """What a ``close`` can still close, in units, whether or not it names a quantity.
+
+    A part on the leg's own side is bounded by the leg, so that closing a part can
+    never take the leg through zero. A part on the other side is not: closing a
+    short part under a long leg is a buy, which moves the leg away from zero
+    rather than towards it, so there is nothing for the leg's own number to bound.
+    What that order may actually send is still bounded per position by what has
+    settled there, so a part whose reference has already returned to zero sends
+    nothing rather than opening it again.
+    """
+    spent = _committed(ctx, None)
+    leg = max(0.0, abs(ctx.size()) - spent.units)
+    if tag is None:
+        return Closable(units=leg, counted=spent.counted)
+    held = held_under(ctx, tag)
+    own = _committed(ctx, tag)
+    part = max(0.0, abs(held) - own.units)
+    if sign(held) != sign(ctx.size()):
+        return Closable(units=part, counted=own.counted)
+    if part <= leg:
+        return Closable(units=part, counted=own.counted)
+    return Closable(units=leg, counted=spent.counted)
+
+
+def closable_units(ctx: Closing, tag: Optional[str]) -> float:
+    """What a close can still close, for the mapping, which sends a number."""
+    return closable(ctx, tag).units

openscript/strategy/fills.py

@@ -0,0 +1,131 @@
+"""What a run keeps about its intents: which one a frame names, and what settled.
+
+Two things a run holds beside the ledger, because neither is the ledger's.
+
+**An ordinal is how a case names an intent.** ``conformance.md`` section 3 says a
+frame names its intent by ordinal and never by an engine's own id: 1 is the first
+intent the run placed, 2 the second, and a case cannot know the id another engine
+minted, so it must not depend on its spelling. An ordinal greater than the number
+of intents the run placed is how a case hands an engine a frame naming an order
+its ledger does not hold, and that is step 1 of the fold rather than a mistake
+here, so the map answers with nothing and lets the ledger refuse it.
+
+**A fill is what the money is folded from**, and the two sizes of a position
+either side of the settlement are kept here rather than read back from the leg.
+The leg reports a net and a fill settles against one position reference, and the
+two are different numbers whenever a leg holds more than one position, which is
+every flip. They are folded in the order the frames were folded in, from the same
+deltas, so they are the same arithmetic the position book did rather than a second
+reading of its result.
+
+A refused frame settles nothing and is not a fill.
+"""
+
+from typing import Dict, List, Optional, Sequence, Tuple
+
+from ..accounting.shapes import RecordedFill
+from .intents import OrderIntent
+from .rows import FrameOutcome
+
+
+class Intents:
+    """Every intent a run has placed, in the order it placed them.
+
+    The ordinal is the position in that order, counting from one, and it counts
+    every intent rather than every ledger row: a bracket and a cancellation take
+    an ordinal and append no row, because an ordinal names what the engine handed
+    over and a row records what was ordered.
+    """
+
+    def __init__(self) -> None:
+        self._placed: List[OrderIntent] = []
+        self._by_id: Dict[int, OrderIntent] = {}
+
+    def record(self, intents: Sequence[OrderIntent]) -> None:
+        """The intents one bar handed over, in the order the bar applied them."""
+        for intent in intents:
+            self._placed.append(intent)
+            self._by_id[intent.intent_id] = intent
+
+    def count(self) -> int:
+        return len(self._placed)
+
+    def at_ordinal(self, ordinal: int) -> Optional[OrderIntent]:
+        """The intent a case's ordinal names, or nothing where it names none."""
+        if ordinal < 1 or ordinal > len(self._placed):
+            return None
+        return self._placed[ordinal - 1]
+
+    def by_id(self, intent_id: int) -> Optional[OrderIntent]:
+        return self._by_id.get(intent_id)
+
+    def ordinal_of(self, intent_id: int) -> int:
+        """Which intent of the run this is, or ``0`` for one this run never placed.
+
+        What a record writes beside a ledger row, so that a case names an order by
+        a number every engine agrees about.
+        """
+        for at, intent in enumerate(self._placed):
+            if intent.intent_id == intent_id:
+                return at + 1
+        return 0
+
+
+class Fills:
+    """The fills a run has settled, in fold order, with what each moved."""
+
+    def __init__(self) -> None:
+        self._fills: List[RecordedFill] = []
+        self._sizes: Dict[int, float] = {}
+        self._seq = 0
+
+    def settled(self) -> Tuple[RecordedFill, ...]:
+        return tuple(self._fills)
+
+    def record(
+        self,
+        outcomes: Sequence[FrameOutcome],
+        intents: Intents,
+        bar_index: int,
+        bar_time: Optional[float],
+        refs: Optional[Dict[int, str]] = None,
+    ) -> Tuple[RecordedFill, ...]:
+        """The fills one bar's fold settled, appended in the order they folded.
+
+        The bar is the bar the fold happened at, which is the bar the position
+        exists from. Where the fill itself traded is the bar before it or this
+        bar's own open, and neither is a bar the strategy could have acted on it
+        in.
+        """
+        made: List[RecordedFill] = []
+        for outcome in outcomes:
+            if outcome.refused is not None:
+                continue
+            if outcome.delta <= 0 or outcome.price is None:
+                continue
+            intent = intents.by_id(outcome.intent_id)
+            if intent is None or intent.side is None:
+                continue
+
+            before = self._sizes.get(intent.position_ref, 0.0)
+            after = before + (-outcome.delta if intent.side == "sell" else outcome.delta)
+            self._sizes[intent.position_ref] = after
+            self._seq += 1
+
+            fill = RecordedFill(
+                seq=self._seq,
+                intent_id=outcome.intent_id,
+                order_ref="" if refs is None else refs.get(outcome.intent_id, ""),
+                tag=intent.tag,
+                position_ref=intent.position_ref,
+                side=intent.side,
+                units=outcome.delta,
+                price=outcome.price,
+                bar_index=bar_index,
+                bar_time=bar_time,
+                ref_size_before=before,
+                ref_size_after=after,
+            )
+            self._fills.append(fill)
+            made.append(fill)
+        return tuple(made)