openscript 0.4.0__py3-none-any.whl

openscript/strategy/ledger.py

@@ -0,0 +1,270 @@
+"""The strategy's own order and fill ledger, ``stdlib.md`` 17.7.
+
+**Each strategy owns one.** It is the strategy's record of what it has actually
+done, it is what every position figure in the language is folded from, and it is
+per strategy rather than per account because an account position is shared with
+every other strategy and every manual trade in the same contract.
+
+**Nothing is read from a host's position row.** The engine is neither handed one
+nor asks for one. What it reads back is what it sent and what the destination
+said became of it, which is the only record whose owner is this strategy.
+
+**Frames fold at a bar boundary**, never during an execution, so every position
+fact is constant for the length of one execution and a re-execution of a moving
+bar sees exactly what the first execution saw (``host-interface.md`` 7.4). The
+intake takes one frame, returns nothing and is the only way in.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+from ..diagnostics import Diagnostic
+from .calls import call_of
+from .intents import Identity, IntentBar, OrderFrame, OrderIntent
+from .placing import intent_for, orders_for
+from .positions import Positions
+from .refusals import SentOnBar, refusal_in_call, refusal_in_order
+from .rows import UNKNOWN_INTENT, FrameOutcome, LedgerRow, Reduction, fold_frame
+from .statuses import PLACED
+
+
+@dataclass(frozen=True)
+class LedgerOptions:
+    """What the declaration and the chart fix before bar 0."""
+
+    instrument: Identity = Identity()
+    product: str = "intraday"
+    qty_type: str = "units"
+    declared_qty: float = 1.0
+    #: The instrument's tick size, absent where the host states none, so a price
+    #: is refused against nothing rather than against a default.
+    tick_size: Optional[float] = None
+    #: Entries allowed in one direction before one is refused.
+    pyramiding: float = 1.0
+
+
+@dataclass(frozen=True)
+class PlacedCall:
+    """What one order call sent, or why it sent nothing.
+
+    The two are exclusive, and that is the shape rather than an accident: a
+    refused call mints no id, appends no row and returns no intent.
+    """
+
+    intents: Tuple[OrderIntent, ...] = ()
+    refusal: Optional[Diagnostic] = None
+
+
+class _Context:
+    """What the mapping and the refusals are handed for one bar.
+
+    A view rather than the ledger itself, so that the two files reading it state
+    what they read: the declaration, the leg, and the rows of this ledger.
+    """
+
+    def __init__(self, ledger: "Ledger", bar: IntentBar) -> None:
+        options = ledger.options
+        self.instrument = options.instrument
+        self.product = options.product
+        self.qty_type = options.qty_type
+        self.declared_qty = options.declared_qty
+        self.tick_size = options.tick_size
+        self.pyramiding = options.pyramiding
+        self.bar = bar
+        self._ledger = ledger
+
+    def size(self) -> float:
+        return self._ledger.size()
+
+    def size_of(self, ref: int) -> float:
+        return self._ledger.size_of(ref)
+
+    def avg_price(self) -> Optional[float]:
+        return self._ledger.avg_price()
+
+    def mint(self) -> int:
+        return self._ledger.mint()
+
+    def rows(self) -> Sequence[LedgerRow]:
+        return self._ledger.rows()
+
+
+class Ledger:
+    """One strategy's rows, its position book, and the frames it has been handed."""
+
+    def __init__(self, options: LedgerOptions = LedgerOptions()) -> None:
+        self.options = options
+        self._by_intent: Dict[int, LedgerRow] = {}
+        self._placed: List[LedgerRow] = []
+        self._positions = Positions()
+        self._waiting: List[OrderFrame] = []
+        self._next = 1
+        #: The bar ``_sent`` describes, so the list empties when a new one begins.
+        self._at = -1
+        self._sent: List[SentOnBar] = []
+
+    # -- what a bar sends ---------------------------------------------------
+
+    def place(self, name: str, args: Sequence[Any], bar: IntentBar, position: Any) -> PlacedCall:
+        """Step 9 sent an order call. It becomes intents, and each becomes a row.
+
+        A row is appended when the order is sent, at ``placed``, which is the
+        engine's own status: an intent has left and nothing has come back.
+
+        **The whole call is read, mapped and refused before any of it is sent.**
+        Every order the call produces is held against the refusals first, and only
+        then does any of them take an id, so a call that sends two sends both or
+        neither.
+        """
+        if bar.index != self._at:
+            self._at = bar.index
+            self._sent = []
+
+        ctx = _Context(self, bar)
+        call = call_of(name, args, position)
+        refused = refusal_in_call(call, ctx)
+        if refused is not None:
+            return PlacedCall(refusal=refused)
+
+        orders = orders_for(call, ctx)
+        for order in orders:
+            bad = refusal_in_order(call, order, ctx, self._sent)
+            if bad is not None:
+                return PlacedCall(refusal=bad)
+
+        intents: List[OrderIntent] = []
+        for order in orders:
+            intent_id = self._next
+            self._next += 1
+            intent = intent_for(order.placement, intent_id, ctx)
+            intents.append(intent)
+            # Only an order that places one appends a row: a cancellation and a
+            # bracket carry an id a host can quote and nothing has been ordered
+            # by either. What a cancellation does to an order, and what a
+            # bracket's level does when it is reached, both arrive as frames.
+            placement = order.placement
+            if placement.kind == "place" and placement.side is not None:
+                self._append(intent, bar, order.reduces)
+                # One entry per appended row, in the same order, which is what
+                # lets a refused bar take back exactly the orders it appended.
+                self._sent.append(SentOnBar(call.name, position.line, placement.side))
+        return PlacedCall(intents=tuple(intents))
+
+    def discard(self, from_row: int) -> None:
+        """The bar sent nothing after all: every row it appended is taken back.
+
+        A refusal anywhere on a bar hands none of the bar's orders over, because
+        every call is mapped before any of them is routed, so the rows of the
+        calls that had already been mapped have to go too. Otherwise the ledger
+        reports an order at ``placed`` with an empty reference that no destination
+        was ever handed, and a host reconciling after a stopped run sees an order
+        it never received.
+
+        Taken back rather than never written, because a row has to be there while
+        the rest of the bar is mapped: a cancellation asks whether a tag names a
+        working order, pyramiding counts what a position already holds, and a
+        close measures what one tag entered.
+
+        The intent ids the bar minted are not reissued. An id is unique within a
+        run, a frame that quoted one must never match a later order, and a gap in
+        the numbering is invisible to a host.
+        """
+        dropped = len(self._placed) - from_row
+        if dropped <= 0:
+            return
+        for row in self._placed[from_row:]:
+            self._by_intent.pop(row.intent_id, None)
+        del self._placed[from_row:]
+        del self._sent[max(0, len(self._sent) - dropped):]
+
+    # -- what the destination answers ---------------------------------------
+
+    def deliver(self, frame: OrderFrame) -> None:
+        """A frame from the destination, held until the next bar boundary."""
+        self._waiting.append(frame)
+
+    def settle(self) -> Tuple[FrameOutcome, ...]:
+        """Folds every frame that has arrived, in the order it arrived in.
+
+        A host does not have to put its frames in order before it sends them. A
+        repeat, a pair that crossed in flight and one that arrives after the order
+        ended are ordinary traffic, and the fold is what says what each does.
+        """
+        if not self._waiting:
+            return ()
+        frames = self._waiting
+        self._waiting = []
+        outcomes: List[FrameOutcome] = []
+        for frame in frames:
+            row = self._by_intent.get(frame.intent_id)
+            if row is None:
+                # Step 1. It is not an order this strategy placed. Refused and
+                # recorded, and nothing is folded.
+                outcomes.append(FrameOutcome(intent_id=frame.intent_id, refused=UNKNOWN_INTENT))
+                continue
+            outcome = fold_frame(row, frame)
+            # Step 6, and the reason the row carries a position reference: the
+            # fill settles the position that order belongs to and not whichever
+            # position the leg holds now.
+            if outcome.delta > 0 and outcome.price is not None:
+                units = outcome.delta if row.side == "buy" else -outcome.delta
+                self._positions.settle(row.position_ref, units, outcome.price)
+            outcomes.append(outcome)
+        return tuple(outcomes)
+
+    # -- what a script reads ------------------------------------------------
+
+    def size(self) -> float:
+        """The leg's net position in units, ``0`` while flat."""
+        return self._positions.size()
+
+    def size_of(self, ref: int) -> float:
+        """The settled size of one position reference."""
+        return self._positions.size_of(ref)
+
+    def avg_price(self) -> Optional[float]:
+        """The average price of the open position, absent while flat."""
+        return self._positions.avg_price()
+
+    def mint(self) -> int:
+        """A fresh position reference."""
+        return self._positions.mint()
+
+    def rows(self) -> Sequence[LedgerRow]:
+        """Every row, oldest first, for a host that reports what the run did."""
+        return self._placed
+
+    def row_for(self, intent_id: int) -> Optional[LedgerRow]:
+        """The row one intent appended, or none where the intent appended none."""
+        return self._by_intent.get(intent_id)
+
+    # -- the append ---------------------------------------------------------
+
+    def _append(self, intent: OrderIntent, bar: IntentBar, reduces: Optional[Reduction]) -> None:
+        placement = intent.placement
+        row = LedgerRow(
+            intent_id=intent.intent_id,
+            tag=placement.tag,
+            # The only leg has no name of its own: a name comes from a leg
+            # declaration, and those are planned (``stdlib.md`` 17.6).
+            leg="",
+            position_ref=placement.position_ref,
+            instrument=intent.instrument,
+            product=intent.product,
+            side=placement.side,
+            qty=placement.qty,
+            order_type=placement.order_type,
+            price=placement.limit,
+            trigger=placement.trigger,
+            placed_at=bar.time,
+            updated_at=bar.time,
+            reduces=reduces,
+            # What this order puts into its position, in units, where the engine
+            # can read it. The unit is per order rather than per run, so a
+            # quantity the engine worked out is readable in a declaration whose
+            # own unit is not.
+            units=placement.qty if placement.qty_type == "units" else None,
+            status=PLACED,
+        )
+        self._placed.append(row)
+        self._by_intent[row.intent_id] = row

openscript/strategy/placing.py

@@ -0,0 +1,206 @@
+"""One order call becomes one or more intents, ``stdlib.md`` 17.2 and 17.3.
+
+**This file says what a call means; ``sizing`` says how much it sends and against
+which position.**
+
+**Every order states its own side and its own quantity outright.** Nothing here
+computes a delta against an account position, for the reason 17.1 gives: an
+account position is held per contract, so a second strategy, a manual trade or
+this same script started twice all land in that one row, and an order sized
+against it is sized against somebody else's trade. What a flattening order does
+compute against is the strategy's own position, folded from its own settled
+fills, which is a different number with a different owner.
+
+**A bracket is an instruction, not an order.** ``exit`` and ``order.bracket`` set
+the leg's own protective level, which is what 17.2 means when it says a leg
+carries at most one stop and at most one target at a time. They send an intent so
+that a host has something to act on, and they append no ledger row and move no
+position, because nothing has been ordered until the level is reached. The tag
+they take defaults to the empty string and rides along as a label, so a bracket
+naming a tag nothing was ever placed with is an ordinary call.
+
+**A tag on a call that flattens is the other kind.** ``close``'s tag defaults to
+absence and names the part of the position that tag entered, which is a reference
+to rows this ledger holds.
+
+**Nothing here refuses anything.** ``refusals`` says what the language will not
+do, and the ledger asks it first. The two were one file once in the engine this
+one is written beside, and what that produced was a call whose quantity did not
+make sense returning an empty list: no order, no refusal, and a script that had
+been told nothing.
+"""
+
+from typing import Any, List, Optional, Tuple
+
+from .calls import OrderCall
+from .closable import closable_units, closing_for, closing_side
+from .holdings import protecting
+from .intents import NO_POSITION_REF, OrderIntent, Placement
+from .sizing import Entry, MappedOrder, adding, entering, flattening
+from .statuses import is_terminal
+
+
+def type_of(limit: Optional[float], trigger: Optional[float]) -> str:
+    """The type the prices imply, ``stdlib.md`` 17.2.
+
+    Stated on the intent rather than left to the host, so a destination never has
+    to infer it.
+    """
+    if limit is not None and trigger is not None:
+        return "stopLimit"
+    if limit is not None:
+        return "limit"
+    if trigger is not None:
+        return "stop"
+    return "market"
+
+
+def _cancelling(tag: str) -> Placement:
+    """A cancellation names the tag it cancels and nothing else.
+
+    No side, no quantity and no price: it is not an order, and what becomes of
+    the order it names arrives as a frame about that order.
+    """
+    return Placement(kind="cancel", tag=tag, position_ref=NO_POSITION_REF)
+
+
+def _bracketing(
+    ctx: Any,
+    tag: str,
+    qty: Optional[float],
+    target: Optional[float],
+    stop: Optional[float],
+    profit: Optional[float],
+    loss: Optional[float],
+) -> Tuple[MappedOrder, ...]:
+    """A protective level attached to a tag, ``stdlib.md`` 17.2 and 17.3."""
+    # A call that names no level at all removes one, which is a standing level of
+    # 17.9 and is planned. There is nothing to send.
+    if target is None and stop is None and profit is None and loss is None:
+        return ()
+    held = protecting(ctx)
+    return (
+        adding(
+            Placement(
+                kind="bracket",
+                qty=qty,
+                # A quantity the script stated is in the declaration's own unit;
+                # a bracket that names no part of the position states none.
+                qty_type="units" if qty is None else ctx.qty_type,
+                target=target,
+                stop=stop,
+                profit=profit,
+                loss=loss,
+                tag=tag,
+                # The position the level protects, and zero where the leg holds
+                # none, which is the value a cancellation already carries for the
+                # same reason: neither is an order and neither has a position of
+                # its own. Minting one here would hand a host a reference no
+                # order ever carries.
+                position_ref=NO_POSITION_REF if held is None else held,
+            )
+        ),
+    )
+
+
+def orders_for(call: OrderCall, ctx: Any) -> Tuple[MappedOrder, ...]:
+    """The orders one call sends, in the order it sends them.
+
+    A call that has nothing to send sends nothing: flattening a leg that holds
+    nothing and reversing a position that does not exist are both instructions
+    about a position the strategy does not hold, and inventing a side for either
+    would be the engine deciding a direction the script never stated.
+    """
+    name = call.name
+
+    if name in ("buy", "sell", "order.place"):
+        side = call.side
+        # A side that is not one of the two is not a direction, and a buy is not
+        # the safe guess: a computed value outside the set sends nothing rather
+        # than the opposite of what the script meant. A side the script stated as
+        # absent never reaches here at all: that is OS7002.
+        if side is None:
+            return ()
+        return entering(
+            ctx,
+            Entry(
+                side=side,
+                limit=call.limit,
+                trigger=call.trigger,
+                # A type outside the set falls back to the one the prices imply,
+                # which is the correspondence 17.2 fixes between the two.
+                order_type=call.order_type or type_of(call.limit, call.trigger),
+                tag=call.tag or "",
+            ),
+            call.qty,
+        )
+
+    if name == "close":
+        # The side comes from the part the call names, which is the leg only
+        # where it names no tag.
+        closing = closing_for(ctx, call.tag)
+        if closing is None:
+            return ()
+        return flattening(
+            ctx, closable_units(ctx, call.tag), closing, call.qty, call.tag or "", call.tag
+        )
+
+    if name == "order.reverse":
+        size = ctx.size()
+        closing = closing_side(size)
+        if closing is None:
+            return ()
+        tag = call.tag or ""
+        # What is left to close rather than the whole leg, so that a reverse
+        # after a close on the same bar does not send the position twice.
+        out: List[MappedOrder] = list(
+            flattening(ctx, closable_units(ctx, None), closing, None, tag, None)
+        )
+        # The replacement is a position of its own, minted here, so that a fill
+        # on the outgoing order settles the position it belonged to.
+        ref = ctx.mint()
+        out.append(
+            adding(
+                Placement(
+                    kind="place",
+                    side=closing,
+                    qty=abs(size) if call.qty is None else call.qty,
+                    qty_type="units" if call.qty is None else ctx.qty_type,
+                    order_type="market",
+                    tag=tag,
+                    position_ref=ref,
+                )
+            )
+        )
+        return tuple(out)
+
+    if name == "exit":
+        return _bracketing(
+            ctx, call.tag or "", call.qty, call.target, call.stop, call.profit, call.loss
+        )
+
+    if name == "order.bracket":
+        return _bracketing(ctx, call.tag or "", None, None, None, call.profit, call.loss)
+
+    if name == "cancel":
+        return (adding(_cancelling(call.tag or "")),)
+
+    if name == "cancelAll":
+        tags: List[str] = []
+        for row in ctx.rows():
+            if not is_terminal(row.status) and row.tag not in tags:
+                tags.append(row.tag)
+        return tuple(adding(_cancelling(tag)) for tag in tags)
+
+    return ()
+
+
+def intent_for(placement: Placement, intent_id: int, ctx: Any) -> OrderIntent:
+    """The intent one placement becomes, ``host-interface.md`` 7.1."""
+    return OrderIntent(
+        intent_id=intent_id,
+        placement=placement,
+        instrument=ctx.instrument,
+        product=ctx.product,
+        bar=ctx.bar,
+    )

openscript/strategy/positions.py

@@ -0,0 +1,124 @@
+"""The positions a leg holds, folded from settled fills and nothing else, 17.1 and 17.7.
+
+**A fill settles the position its own order names, never whichever position the
+leg holds now.** That is what the position reference is for: during a flip a leg
+holds two positions at once, the outgoing one and its replacement, and a fill
+that arrives late would otherwise be applied to the position that replaced the
+one it belonged to.
+
+**Reducing a position does not move its average price.** The units that leave
+leave at the price the position was opened at, so what remains is still the
+average of what was bought. An engine that took the closing fill's price into
+the average would report an entry at a price nothing was entered at, and every
+level a script measures from the entry would be measured from that.
+
+Nothing here is money. Realised profit, equity and the trade list are the
+planned entries of ``stdlib.md`` 17.4, and this holds the two facts the five
+position calls of this release read: how much is held, and at what average.
+"""
+
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+
+def sign(value: float) -> int:
+    """The sign of a quantity, as the three way answer the arithmetic below needs."""
+    if value > 0:
+        return 1
+    if value < 0:
+        return -1
+    return 0
+
+
+@dataclass
+class Held:
+    """One position: its signed size, and the signed cost of what is open."""
+
+    size: float = 0.0
+    cost: float = 0.0
+
+
+class Positions:
+    """The book a leg's fills settle into, one entry per position reference."""
+
+    def __init__(self) -> None:
+        self._held: Dict[int, Held] = {}
+        self._minted: List[int] = []
+        self._next = 1
+
+    def size_of(self, ref: int) -> float:
+        """The settled size of one reference, signed the way a position is.
+
+        Per reference rather than per leg, because which position an order is
+        sent against is a question about one position and the leg's net cannot
+        answer it: two positions that net to zero are not the same thing as no
+        position at all. Zero for a reference this book has never been given a
+        fill for, which is both a reference minted for an order that has not
+        settled and one that is not a reference at all.
+        """
+        one = self._held.get(ref)
+        return 0.0 if one is None else one.size
+
+    def mint(self) -> int:
+        """A fresh position, for the replacement half of a flip."""
+        ref = self._next
+        self._next += 1
+        self._held[ref] = Held()
+        self._minted.append(ref)
+        return ref
+
+    def settle(self, ref: int, units: float, price: float) -> None:
+        """Step 6 of the fold: ``units`` at ``price`` settle against one position."""
+        position = self._held.get(ref)
+        if position is None:
+            position = Held()
+            self._held[ref] = position
+            self._minted.append(ref)
+        before = position.size
+
+        if before == 0 or sign(units) == sign(before):
+            position.size = before + units
+            position.cost += units * price
+            return
+
+        average = position.cost / before
+        after = before + units
+        position.size = after
+        # A destination that filled more than the order asked takes the leg
+        # through zero. The remainder is a position in the other direction and
+        # it opened at this fill's price, which is the truthful reading of what
+        # the account now holds. Dropping it would leave the strategy blind to a
+        # position it is carrying.
+        at = average if sign(after) == sign(before) else price
+        position.cost = 0.0 if after == 0 else after * at
+
+    def size(self) -> float:
+        """The leg's net position in units, ``0`` while flat."""
+        total = 0.0
+        for position in self._held.values():
+            total += position.size
+        return total
+
+    def avg_price(self) -> Optional[float]:
+        """The average price of what the leg holds, absent while flat.
+
+        Absent rather than zero, because zero is a price and a script comparing
+        against it would take a branch that looks correct (``stdlib.md`` 17.4).
+
+        Averaged over the positions on the side of the leg's net, and not over
+        every position open at once. Summed across both sides the cost of a
+        position on the way out is subtracted from the cost of the one on the
+        way in, and the quotient is a price nothing was entered at.
+        """
+        net = self.size()
+        if net == 0:
+            return None
+        side = sign(net)
+        size = 0.0
+        cost = 0.0
+        for position in self._held.values():
+            if sign(position.size) != side:
+                continue
+            size += position.size
+            cost += position.cost
+        return None if size == 0 else cost / size