openscript 0.4.0__py3-none-any.whl

openscript/adapter/sessions.py

@@ -0,0 +1,168 @@
+"""The session facts an engine derives, ``host-interface.md`` 4.3 and ``stdlib.md`` 12.4.
+
+**A session is the instrument's, never a window a script invents.** The record
+states a wall clock range, the days it runs on and the zone it is read in, and
+the engine derives the per-bar facts from those and the bar's own time: "an
+engine derives them and never asks a host for them: the facts a host states about
+an execution are the four of ``language.md`` section 7.2 and no others".
+
+**A record that states no session leaves every fact absent**, which is 4.1's own
+rule and is exactly what an instrument with no schedule looks like. A record that
+states one badly is refused instead (OS6012), because the difference between a
+fact nobody stated and a fact stated wrongly is the one thing reading the record
+can tell you.
+
+**The window arithmetic is not here.** A range of wall clock hours is two things
+in this engine, the record's session and the window a script writes for
+``session.isIn``, and ``hours.py`` is the one arithmetic both of them reach: a
+second copy would drift over midnight, or over which day a list of days is read
+against, on the dataset nobody tests. What is here is the record: its three
+refusals, and the two facts derived per bar.
+
+**Both derived facts are computed here and one of them is in the manifest.**
+``session.isFirstBar`` looks backwards, which an engine can answer on the bar it
+is executing. ``session.isLastBar`` is "true on the last bar of the schedule even
+if trading stopped early", so it is a bar slot measured against the scheduled
+close and it needs the interval, which ``intervals.py`` now reads;
+``last_bars`` below is that reading. It is not in ``SESSION_FACTS`` yet, because
+the seam that answers a session fact carries one bar fact to answer it with, and
+a name added to that tuple without a second fact beside it would answer
+``isLastBar`` with ``isFirstBar``'s value, which is worse than the refusal a
+program gets today (OS6004, naming the function).
+
+**The zone is read as the one this engine can read.** A calendar in any other
+zone is a reader the host supplies, so a case whose record names another zone is
+named ``unsupported`` by the caller rather than answered under the wrong
+calendar. ``zones.py`` states which zone that is and why it is one.
+"""
+
+from typing import Any, Mapping, Optional, Sequence, Tuple
+
+from ..hours import Hours, clock_minutes, days_numbered, standing_in
+from ..intervals import bar_minutes_of
+from ..values import ABSENT
+from ..zones import READABLE as READABLE_ZONE, fields_in
+from .spellings import Malformed
+
+#: ``stdlib.md`` 12.4: the entries of the namespace this engine serves.
+SESSION_FACTS: Tuple[str, ...] = ("session.isFirstBar",)
+
+#: The bar fact both readers of a session boundary take it from: the namespace
+#: entry above, and ``vwap``, which restarts where the session opened.
+SESSION_FIRST = "isSessionFirst"
+
+#: The record's session is a range of wall clock hours and nothing else, which is
+#: what lets it and a script's own window be one arithmetic.
+Session = Hours
+
+
+def _minutes(text: Any, field: str) -> int:
+    """``"HH:MM"``, in the one spelling 4.3 fixes, or the refusal it names.
+
+    ``"9:00"`` is the spelling a host writes first and it is not a time here, so
+    it is refused rather than read: a record stating a window in a spelling the
+    page does not have is a record whose author believes they stated a session.
+    """
+    held = clock_minutes(text)
+    if held is None:
+        raise Malformed(
+            f"instrument.json: the session's {field} is {text!r}, and host-interface.md 4.3 "
+            'spells a wall clock time "HH:MM", where the latest time it has is "24:00", '
+            "midnight at the end of the day"
+        )
+    return held
+
+
+def session_from(instrument: Mapping[str, Any]) -> Optional[Session]:
+    """The record's session, or nothing where it states none.
+
+    The three refusals are 4.3's own table, in its order: a window with no zone
+    to read it in, a bound that is not a wall clock time, and a day outside the
+    numbering ``date.dayOfWeek`` uses.
+    """
+    held = instrument.get("session")
+    if held is None:
+        return None
+    if not isinstance(held, dict):
+        raise Malformed("instrument.json: the session is not a window of a start, an end and days")
+    if not isinstance(instrument.get("timezone"), str):
+        raise Malformed(
+            "instrument.json states a session and no timezone, and host-interface.md 4.3 refuses "
+            "that record at load: a window is wall clock and a wall clock is read in a zone"
+        )
+    days = held.get("days")
+    if not isinstance(days, list) or not days_numbered(days):
+        raise Malformed(
+            f"instrument.json: the session states the days {days!r}, and 4.3 numbers Monday as 1 "
+            "through Sunday as 7, with an empty list not one of them"
+        )
+    return Session(_minutes(held.get("start"), "start"), _minutes(held.get("end"), "end"), tuple(days))
+
+
+def opening_day(time: int, session: Session) -> Optional[int]:
+    """Which session a bar belongs to, as the day it opened on, or nothing.
+
+    The day is an identity and not a date: two bars of one session share it, and
+    the bar that does not share it with the bar before it is the bar that opened
+    a session. A bar outside the window belongs to no session, which is a false
+    reading of every fact here rather than an absent one.
+    """
+    standing = _standing(time, session)
+    return None if standing is None or not standing.inside else standing.opening_day
+
+
+def first_bars(times: Sequence[int], session: Optional[Session]) -> Tuple[Any, ...]:
+    """Whether each bar opens its session, absent throughout where there is none.
+
+    Read forwards and never backwards: a bar opens a session when it is in one
+    and the last bar that was in one was in a different one. A bar outside the
+    window opens nothing and leaves the answer for the next bar alone, so a
+    session with a gap in the middle of it is one session and not two.
+    """
+    if session is None:
+        return tuple(ABSENT for _ in times)
+    found = []
+    previous: Optional[int] = None
+    for time in times:
+        opened = opening_day(time, session)
+        found.append(opened is not None and opened != previous)
+        if opened is not None:
+            previous = opened
+    return tuple(found)
+
+
+def last_bars(
+    times: Sequence[int], session: Optional[Session], interval: Any
+) -> Tuple[Any, ...]:
+    """Whether each bar is the last of its session's schedule, or absent.
+
+    The schedule and not the trading: a bar is the last one when the time left
+    until the scheduled close is no more than one bar, so it is true on the bar
+    that covers the close even if nothing traded in it and even if the feed
+    stopped an hour earlier. That is the whole reason 4.3 says a strategy which
+    must be flat by the close acts on this rather than on the appearance of a new
+    bar, which arrives too late.
+
+    Absent where there is no session, and absent where the host stated no
+    interval this engine can read: without a bar's length there is no slot to
+    measure against the close, and answering from the spacing of the bars would
+    be an engine promising something the specification does not, which is that
+    the bars are evenly spaced.
+    """
+    minutes = bar_minutes_of(interval)
+    if session is None or minutes is None:
+        return tuple(ABSENT for _ in times)
+    found = []
+    for time in times:
+        standing = _standing(time, session)
+        if standing is None:
+            found.append(ABSENT)
+        else:
+            found.append(standing.inside and standing.remaining <= minutes)
+    return tuple(found)
+
+
+def _standing(time: Any, session: Session) -> Optional[Any]:
+    """Where one bar's reading sits in the window, in the zone this engine reads."""
+    at = fields_in(time, READABLE_ZONE)
+    return None if at is None else standing_in(session, at)

openscript/adapter/spellings.py

@@ -0,0 +1,184 @@
+"""How a value is written in a case file and in a report, and how one is read back.
+
+``conformance.md`` sections 3 and 4 fix both directions and this module is the
+whole of them, so that a reader of a case file and a writer of a report cannot
+part company over a spelling.
+
+**A number is read strictly.** The page says a price is "written in the shortest
+form that reads back to the exact binary64 value intended", which is a decimal
+and nothing else. The interpreter's own reader is wider than that: it takes an
+infinity by name, a not-a-number, a hexadecimal fraction, surrounding space and
+an underscore between digits, and each of those would enter the run as a value
+``language.md`` section 5.1 says never appears. So the text is held to the
+grammar first and converted after, and a case carrying one of those spellings is
+malformed rather than quietly run.
+
+**A number is written by the language's own rule.** ``language.md`` section 5.5
+decides when the positional form is used and how an exponent is spelled, and
+``canonical.py`` next door already implements it for the compiled program's
+encoding. A second rule here would be the one that drifted, and the difference
+would show up as two engines reporting one value two ways in a document a person
+reads to decide which of them is wrong.
+
+**A colour is written after the alpha has become a byte**, which is
+``compiled-program.md`` section 3.1's one way conversion and the reason section 6
+can compare four integers rather than a float. The two spellings of a colour this
+package holds are both accepted here; the note in ``running.py`` says why there
+are two.
+"""
+
+import re
+from typing import Any, Optional
+
+from ..canonical import canonical_number
+from ..library.colour import Colour as LibraryColour, hex_byte
+from ..library.rounding import round_half_away
+from ..values import Colour as MachineColour
+from .page import ABSENT_TEXT
+
+#: A decimal, and nothing else: an optional sign, digits, an optional fraction
+#: and an optional exponent. Nothing else the interpreter's reader would accept.
+_DECIMAL = re.compile(r"^[+-]?(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)(?:[eE][+-]?[0-9]+)?$")
+
+#: A whole number of milliseconds, which is what every time in a case file is.
+_WHOLE = re.compile(r"^[+-]?[0-9]+$")
+
+#: The eight hexadecimal digits a colour is compared as, with the leading hash.
+_COLOUR = re.compile(r"^#[0-9a-f]{8}$")
+
+
+class Malformed(Exception):
+    """A case file that cannot be read, which section 9 files under ``error``.
+
+    Carries one sentence naming the file, the row and what was wrong with it. A
+    case is input to every engine that meets it, so the cost of a directory this
+    one cannot read lands on whoever wrote the directory, and the sentence is
+    what tells them which of the two it is.
+    """
+
+
+def read_number(text: str, where: str) -> float:
+    """A decimal as the binary64 value it names, or a refusal naming where."""
+    if not _DECIMAL.match(text):
+        raise Malformed(
+            f"{where}: {text!r} is not a decimal number. A case file writes a number in the "
+            "shortest form that reads back to the value intended, and every other spelling a "
+            "reader might accept, an infinity, a not-a-number or a digit separator, is a value "
+            "this language holds none of"
+        )
+    value = float(text)
+    if value != value or value in (float("inf"), float("-inf")):
+        raise Malformed(f"{where}: {text!r} is outside the finite range of a binary64 number")
+    return value
+
+
+def read_whole(text: str, where: str) -> int:
+    """A whole number, which is what a time and a quantity in a case file are."""
+    if not _WHOLE.match(text):
+        raise Malformed(f"{where}: {text!r} is not a whole number")
+    return int(text)
+
+
+def read_bool(text: str, where: str) -> bool:
+    if text == "true":
+        return True
+    if text == "false":
+        return False
+    raise Malformed(f"{where}: {text!r} is neither true nor false")
+
+
+def read_colour(text: str, where: str) -> str:
+    """A colour, kept as the eight digit spelling it is compared as.
+
+    It is not turned back into channels and an alpha. Section 3.1 says the
+    conversion to a byte is one way and not a round trip, so a colour read back
+    into the machine's own form and written out again would not always be the
+    text the file holds, and the text is what section 6 compares.
+    """
+    if not _COLOUR.match(text):
+        raise Malformed(
+            f"{where}: {text!r} is not a colour. A colour is written #rrggbbaa, always eight "
+            "hexadecimal digits and always lower case"
+        )
+    return text
+
+
+def colour_text(value: Any) -> str:
+    """A colour the machine holds, in the one spelling a case file writes.
+
+    The alpha becomes a byte here and nowhere else: ``round(alpha * 255)`` with
+    the language's own rounding, halves away from zero, which is section 3.1's
+    rule and the rounding ``stdlib.md`` section 11.2 gives every colour call.
+    """
+    if isinstance(value, MachineColour):
+        red, green, blue, alpha = value.red, value.green, value.blue, value.alpha
+    elif isinstance(value, LibraryColour):
+        red, green, blue, alpha = value.r, value.g, value.b, value.a
+    else:
+        raise Malformed(f"{value!r} is not a colour")
+    channels = "".join(hex_byte(one) for one in (red, green, blue))
+    return f"#{channels}{hex_byte(round_half_away(alpha * 255.0))}"
+
+
+def written(value: Any) -> str:
+    """A value as a report writes it, which is as an expected file writes it.
+
+    Section 9: "Numbers in a report are written as the shortest round-tripping
+    decimal, exactly as in an expected file, so a difference in the last bit is
+    visible in the report rather than rounded away by the reporting."
+    """
+    if value is None:
+        return ABSENT_TEXT
+    if isinstance(value, bool):
+        return "true" if value else "false"
+    if isinstance(value, (int, float)):
+        return canonical_number(float(value))
+    if isinstance(value, str):
+        return value
+    if isinstance(value, (MachineColour, LibraryColour)):
+        return colour_text(value)
+    return repr(value)
+
+
+def as_reported(value: Any) -> Any:
+    """One value of an answered channel, in the JSON shapes section 4 gives.
+
+    Absence is null, a number is a number, a bool is a bool, a string is itself,
+    and a colour is its eight digit spelling, because that is what section 6
+    compares a colour as and a JSON document has no colour of its own.
+    """
+    if value is None or isinstance(value, (bool, str)):
+        return value
+    if isinstance(value, (int, float)):
+        return float(value)
+    if isinstance(value, (MachineColour, LibraryColour)):
+        return colour_text(value)
+    return None
+
+
+def read_cell(text: str, kind: str, where: str) -> Optional[Any]:
+    """One field of ``expected.csv``, read as the channel's own type.
+
+    The type comes from the compiled program's channel table
+    (``compiled-program.md`` section 2.7) rather than from the shape of the
+    text, so a string channel holding ``none`` is a channel that produced
+    nothing and not the four letters.
+
+    An empty field and ``none`` are both absence here, and that is a narrowing
+    of section 4 rather than a reading of it: the page distinguishes "this
+    channel produced nothing on this bar" from an absent number, and a channel
+    on this machine has one state for both (section 2.7: a channel's value is
+    absent unless something wrote it). An engine that answered two different
+    values would be inventing a distinction it cannot observe.
+    """
+    if text == "" or text == ABSENT_TEXT:
+        return None
+    if kind == "number":
+        return read_number(text, where)
+    if kind == "bool":
+        return read_bool(text, where)
+    if kind == "color":
+        return read_colour(text, where)
+    if kind == "string":
+        return text
+    raise Malformed(f"{where}: {kind!r} is not a channel type this adapter reads")

openscript/bars.py

@@ -0,0 +1,157 @@
+"""Step 4 of the bar cycle: the host's bar written into every ``"bar"`` register.
+
+The derived price fields are written out as expressions rather than as formulas
+because **their order of operations is part of the contract** (section 2.10):
+``hlc3`` adds high to low, adds close to that, then divides. A different
+association gives a different last bit, and a study that matches a reference
+implementation on one engine and not on another is exactly the failure this
+project exists to prevent.
+
+**An absent volume rather than a zero is deliberate.** A script that sizes
+something by volume has to be able to tell "no trades" from "nobody told me",
+which is ``host-interface.md`` section 3.3 and three levels of the same
+distinction.
+
+Four of the eight bar facts are the host's and four are the engine's, and a fact
+the engine can derive is never also stated by the host, because two sources for
+one number can disagree and no rule would say which of them wins.
+"""
+
+from dataclasses import dataclass
+from typing import Any, Tuple
+
+from .contracts import Bar, BarState
+from .values import ABSENT, finite, is_number
+
+#: The bar fields section 2.10 names.
+#:
+#: ``oi`` is here and is the one field the section's own table does not list. It
+#: is a field of a bar everywhere else: ``host-interface.md`` section 3.1 states
+#: it, and section 2.16.2 folds it into a bucket bar by taking the last rather
+#: than the sum. A register kind the compiler can emit and this engine could not
+#: fill would be absent on every bar with nothing saying why, so it is filled and
+#: the omission is reported rather than resolved here.
+BAR_FIELDS: Tuple[str, ...] = (
+    "open",
+    "high",
+    "low",
+    "close",
+    "volume",
+    "time",
+    "hl2",
+    "hlc3",
+    "ohlc4",
+    "hlcc4",
+    "oi",
+    "bar.index",
+    "bar.count",
+    "bar.isFirst",
+    "bar.isLast",
+    "bar.isConfirmed",
+    "bar.isRealtime",
+    "bar.isNew",
+    "bar.updates",
+)
+
+
+def is_bar_field(name: str) -> bool:
+    return name in BAR_FIELDS
+
+
+@dataclass(frozen=True)
+class BarFacts:
+    """The eight facts of ``language.md`` section 7.2, for the bar being executed.
+
+    ``index`` is a position in the supplied data and not a universal address:
+    loading more history shifts every index, which is why a script that has to
+    remember a bar stores ``time`` instead.
+    """
+
+    index: int
+    count: int
+    is_first: bool
+    is_last: bool
+    is_confirmed: bool
+    is_realtime: bool
+    is_new: bool
+    updates: float
+
+
+def facts_for(index: int, supplied: int, state: BarState) -> BarFacts:
+    return BarFacts(
+        index=index,
+        count=index + 1,
+        is_first=index == 0,
+        # True when this is the greatest index the host has supplied. A live
+        # chart supplies bars one at a time, so its newest bar is always the
+        # last; a run over a whole dataset supplies them together, so only its
+        # final bar is.
+        is_last=index == supplied - 1,
+        is_confirmed=state.is_confirmed,
+        is_realtime=state.is_realtime,
+        is_new=state.is_new,
+        updates=float(state.updates),
+    )
+
+
+def _held(value: Any) -> Any:
+    return float(value) if is_number(value) else ABSENT
+
+
+def bar_field(field: str, bar: Bar, facts: BarFacts) -> Any:
+    """One bar field's value, by the definitions of section 2.10."""
+    if field == "open":
+        return _held(bar.open)
+    if field == "high":
+        return _held(bar.high)
+    if field == "low":
+        return _held(bar.low)
+    if field == "close":
+        return _held(bar.close)
+    if field == "volume":
+        return _held(bar.volume)
+    if field == "oi":
+        return _held(bar.oi)
+    if field == "time":
+        return _held(bar.time)
+
+    high, low, close, opened = (
+        _held(bar.high),
+        _held(bar.low),
+        _held(bar.close),
+        _held(bar.open),
+    )
+    if field == "hl2":
+        if high is ABSENT or low is ABSENT:
+            return ABSENT
+        return finite((high + low) / 2)
+    if field == "hlc3":
+        if high is ABSENT or low is ABSENT or close is ABSENT:
+            return ABSENT
+        return finite((high + low + close) / 3)
+    if field == "ohlc4":
+        if opened is ABSENT or high is ABSENT or low is ABSENT or close is ABSENT:
+            return ABSENT
+        return finite((opened + high + low + close) / 4)
+    if field == "hlcc4":
+        if high is ABSENT or low is ABSENT or close is ABSENT:
+            return ABSENT
+        return finite((high + low + close + close) / 4)
+
+    if field == "bar.index":
+        return float(facts.index)
+    if field == "bar.count":
+        return float(facts.count)
+    if field == "bar.isFirst":
+        return facts.is_first
+    if field == "bar.isLast":
+        return facts.is_last
+    if field == "bar.isConfirmed":
+        return facts.is_confirmed
+    if field == "bar.isRealtime":
+        return facts.is_realtime
+    if field == "bar.isNew":
+        return facts.is_new
+    if field == "bar.updates":
+        return float(facts.updates)
+    return ABSENT