openscript 0.4.0__py3-none-any.whl

openscript/library/arithmetic.py

@@ -0,0 +1,128 @@
+"""The bare arithmetic of `stdlib.md` section 8.1.
+
+None of these has a warmup: each reads this bar's values only, so it produces a
+value on bar 0 whenever its arguments do. Every one is absent when any argument
+is absent, and every numeric result goes through ``result``, so a value with no
+finite real answer is absence rather than an infinity.
+
+`stdlib.md` section 20.10 names most of this file as arithmetic with no
+accumulation order to fix: ``abs`` and ``sign`` are one operation each, and
+``min``, ``max`` and ``clamp`` select a value and compute nothing. ``mod`` is the
+exception and its order is written out in section 8.1 and confirmed in 20.7: the
+division, then the floor, then the multiplication, then the subtraction.
+"""
+
+from .values import ABSENT, Value, floor_of, number, result
+
+
+def abs_of(x: Value) -> Value:
+    """``abs(x)``: magnitude without sign."""
+    value = number(x)
+    return ABSENT if value is None else result(abs(value))
+
+
+def sign(x: Value) -> Value:
+    """``sign(x)``: -1, 0 or 1.
+
+    Three comparisons rather than a division: the sign of a zero is not
+    observable in this language (`compiled-program.md` section 3.1), so a zero
+    of either sign answers 0 here.
+    """
+    value = number(x)
+    if value is None:
+        return ABSENT
+    if value > 0:
+        return 1.0
+    if value < 0:
+        return -1.0
+    return 0.0
+
+
+def minimum(a: Value, b: Value) -> Value:
+    """``min(a, b)``: the smaller of two."""
+    left = number(a)
+    right = number(b)
+    if left is None or right is None:
+        return ABSENT
+    return result(left if left < right else right)
+
+
+def maximum(a: Value, b: Value) -> Value:
+    """``max(a, b)``: the larger of two."""
+    left = number(a)
+    right = number(b)
+    if left is None or right is None:
+        return ABSENT
+    return result(left if left > right else right)
+
+
+def clamp(x: Value, low: Value, high: Value) -> Value:
+    """``clamp(x, lo, hi)``: ``x`` held inside a range.
+
+    Written as two comparisons in this order rather than as ``min(max(...))``,
+    because the two disagree when the bounds are crossed and this one answers
+    with the lower bound there, which is what a reader of the name expects.
+    """
+    value = number(x)
+    lower = number(low)
+    upper = number(high)
+    if value is None or lower is None or upper is None:
+        return ABSENT
+    if value < lower:
+        return result(lower)
+    if value > upper:
+        return result(upper)
+    return result(value)
+
+
+def mod(a: Value, b: Value) -> Value:
+    """``mod(a, b)``: ``a - b * floor(a / b)``, the floored remainder.
+
+    Its sign follows ``b``. The formula is written out rather than handed to the
+    interpreter's own remainder because "the modulo" names two different
+    functions in common use: this is the floored one and ``%`` is the truncated
+    one, so ``mod(-7, 3)`` is 2 where ``-7 % 3`` is -1 in this language. The two
+    agree for every positive ``b``, which is every use that wraps an index, a bar
+    count or a session offset.
+
+    **The host language's own floored remainder is not this function either.**
+    It agrees at every argument a script is likely to write and parts from it
+    where the division overflows, because it is exact rather than a division
+    followed by a floor: at ``mod(0.1, 1e-310)`` the quotient is an infinity and
+    this function is absent there, where the host's remainder answers
+    3.135287412051e-311.
+
+    ``mod(a, 0)`` is absent, on the rule of `stdlib.md` section 2.4 that a result
+    with no finite real value is absent.
+    """
+    left = number(a)
+    right = number(b)
+    if left is None or right is None or right == 0:
+        return ABSENT
+    return result(left - right * floor_of(left / right))
+
+
+def is_none(x: Value) -> bool:
+    """``isNone(x)``: true when the value is absent."""
+    return x is None
+
+
+def or_else(x: Value, fallback: Value) -> Value:
+    """``orElse(x, fallback)``: ``x`` when present, ``fallback`` when absent.
+
+    The fallback is returned as it stands, absence included, so
+    ``orElse(x, none)`` is ``x``.
+    """
+    return fallback if x is None else x
+
+
+def to_bool(x: Value) -> bool:
+    """``toBool(x)``: absence to false, a bool to itself.
+
+    A number is a type error the checker refuses, so an engine that reaches one
+    is looking at a program its verifier should not have accepted, and false is
+    the safe reading. Identity against ``True`` rather than truthiness, because
+    every non-zero number is truthy in this interpreter and one reaching here
+    would come back as a bool the language never made.
+    """
+    return x is True

openscript/library/averages.py

@@ -0,0 +1,133 @@
+"""The six means of `stdlib.md` section 20.3 that are not built from another mean.
+
+Each is one of the two shapes of section 20.2 and nothing more: a fresh window
+sum, or a window mean that seeds a recurrence. What makes them six functions
+rather than one is the step and the weighting, and what makes each of them one
+function rather than a family is the arrangement, which is why every entry here
+names the arrangement it is not.
+
+A value arrives already read off this bar's arguments, and every one of these
+pushes it into a buffer of its own before it looks at the window, because a call
+that skipped a bar's contribution would have a window a bar out of step with the
+bars it is supposed to cover.
+"""
+
+from .series import Region, contributed, mean, seeded, total, window
+from .values import ABSENT, Value, number, result
+
+
+def simple(state: Region, value: Value, length: int | None) -> Value:
+    """``sma(src, len)``: the window sum of 20.2.1 divided by ``len``."""
+    values = contributed(state, "src", number(value), length)
+    held = window(values, length)
+    if held is None or length is None:
+        return ABSENT
+    return result(mean(held, length))
+
+
+def exponential(state: Region, value: Value, length: int | None) -> Value:
+    """``ema(src, len)``: the seeded recurrence with the weight of section 4.
+
+    **The step is the two products added**, and it is not
+    ``running + (value - running) * weight``. That third arrangement of the same
+    algebra is the one an engine reaches for, because it is one multiplication
+    rather than two, and over the fixture the release gate compares bit for bit
+    it differs on most of the values at every length.
+    """
+    values = contributed(state, "src", number(value), length)
+    if length is None:
+        return ABSENT
+    weight = 2 / (length + 1)
+    rest = 1 - weight
+
+    def step(running: float, value: float) -> float:
+        return value * weight + running * rest
+
+    return seeded(state, "run", values, length, step)
+
+
+def smoothed(state: Region, value: Value, length: int | None) -> Value:
+    """``rma(src, len)``: the recurrence the classic oscillators are built on.
+
+    **This is not the shape of ``ema`` with a weight of ``1 / len``.** The two
+    are one function in exact arithmetic and two numbers in binary64, and the
+    difference propagates into the strength reading, the average true range, the
+    trailing band and the directional index, which are the readings a chart is
+    most often asked to reproduce. Neither is
+    ``running + (value - running) / len``, which is a third arrangement again.
+    """
+    values = contributed(state, "src", number(value), length)
+    if length is None:
+        return ABSENT
+    span = float(length)
+
+    def step(running: float, value: float) -> float:
+        return (running * (span - 1) + value) / span
+
+    return seeded(state, "run", values, length, step)
+
+
+def linear(state: Region, value: Value, length: int | None) -> Value:
+    """``wma(src, len)``: weight 1 added first, weight ``len`` last, one division.
+
+    The weight on ``w[k]`` is ``len - k``, formed as a multiplication of the
+    value by the whole number weight and not by a precomputed fraction. Dividing
+    each term by the divisor as it is added is a different number.
+
+    Nothing is fixed about how the divisor itself is formed: its factors are a
+    whole number product scaled by a power of two, which is exact however it is
+    grouped.
+    """
+    values = contributed(state, "src", number(value), length)
+    held = window(values, length)
+    if held is None or length is None:
+        return ABSENT
+    span = float(length)
+    divisor = (span * (span + 1)) / 2
+    running = 0.0
+    for position in range(length):
+        running = running + held[length - 1 - position] * float(position + 1)
+    return result(running / divisor)
+
+
+def symmetric(state: Region, value: Value) -> Value:
+    """``swma(src)``: the fixed four bar mean, added left to right, divided once.
+
+    Over twenty thousand four bar windows of ordinary prices, regrouping the four
+    terms in the middle differs on 5281 of them, adding them right to left on
+    7230, and dividing each term by 6 as it is added on 9564. How the two middle
+    terms are doubled is not fixed, because an exact scaling by two is one value
+    however it is written.
+    """
+    values = contributed(state, "src", number(value), 4)
+    held = window(values, 4)
+    if held is None:
+        return ABSENT
+    running = held[3]
+    running = running + 2 * held[2]
+    running = running + 2 * held[1]
+    running = running + held[0]
+    return result(running / 6)
+
+
+def volume_weighted(state: Region, value: Value, size: Value, length: int | None) -> Value:
+    """``vwma(src, len)``: this bar's product formed first, then two window sums.
+
+    Dividing each sum by ``len`` first and then dividing one by the other is the
+    same quantity with two extra roundings in it, and it is not this
+    arrangement. The result is absent where the denominator is zero, which is a
+    window nothing traded in rather than an error.
+    """
+    price = number(value)
+    traded = number(size)
+    product = ABSENT if price is None or traded is None else price * traded
+    products = contributed(state, "flow", product, length)
+    volumes = contributed(state, "size", traded, length)
+    top = window(products, length)
+    bottom = window(volumes, length)
+    if top is None or bottom is None:
+        return ABSENT
+    divisor = total(bottom)
+    if divisor == 0:
+        return ABSENT
+    return result(total(top) / divisor)

openscript/library/bars.py

@@ -0,0 +1,60 @@
+"""The readings taken from one bar and nothing before it.
+
+`stdlib.md` section 20.5 fixes the one that is not a single operation:
+
+```text
+result = max(high - low, abs(high - previousClose), abs(low - previousClose))
+```
+
+**The oldest bar of the dataset is the library's one deliberate exception to
+absence propagation**, and `stdlib.md` section 6 puts it there rather than
+leaving it to an engine: ``trueRange()`` is ``high - low`` on that bar. The other
+two terms need a close that does not exist there, and propagating absence would
+start every average of this reading one bar later than the declared warmup while
+adding nothing, because the bar's own range is a true statement about that bar.
+
+The exception is granted to ``trueRange`` and therefore to the averages of it. It
+is not granted to every function that happens to use a range: where a function's
+declared warmup shows it counts changes rather than levels, section 20.5's gap
+aware form is what it takes, and that one is absent on the oldest bar like any
+other change. Two functions use it and both declare a warmup one bar later than
+the plain reading would give, which is how the page says which of the two they
+take. That form is not a call a script can make, and an engine reaches it through
+the stateful half of this library rather than through here.
+
+**Where the previous close comes from is a host fact, not an arithmetic one.** An
+engine is handed it with the bar and that is the one it must use, because a call
+inside a branch does not see every bar and the close of the bar it last ran on is
+a different number. So it is an argument here, and this function holds nothing
+across bars.
+"""
+
+from .values import ABSENT, Value, number, result
+
+
+def true_range(high: Value, low: Value, previous_close: Value, first_bar: bool) -> Value:
+    """``trueRange()``: the bar's range, including any gap from the last close.
+
+    ``first_bar`` is the caller's answer to "is this the oldest bar of the
+    dataset", which is the question section 6's exception turns on and not one
+    the three numbers can answer. An absent previous close in the middle of a run
+    is a hole, and a hole propagates.
+    """
+    top = number(high)
+    bottom = number(low)
+    if first_bar:
+        if top is None or bottom is None:
+            return ABSENT
+        return result(top - bottom)
+    close_before = number(previous_close)
+    if top is None or bottom is None or close_before is None:
+        return ABSENT
+    within = top - bottom
+    up_gap = abs(top - close_before)
+    down_gap = abs(bottom - close_before)
+    widest = within
+    if up_gap > widest:
+        widest = up_gap
+    if down_gap > widest:
+        widest = down_gap
+    return result(widest)

openscript/library/bookkeeping.py

@@ -0,0 +1,166 @@
+"""The comparisons and counters of `stdlib.md` section 9, named in 20.10.
+
+None of these accumulates. They compare this bar's value with an older one, or
+count bars, so there is one arrangement and no choice to record. What there is
+instead is a set of edge rules, and each of them is a decision somebody has to
+make the same way twice for two engines to agree:
+
+- **A crossing keeps the two series apart rather than subtracting them.** The
+  test turns on whether one was at or below the other, and a rounded zero would
+  change the answer on exactly the bars a crossing matters.
+- **A crossing is "at or below, then above"**, not "strictly below, then above",
+  so two series that touch and separate report one cross rather than none. The
+  alternative loses the case where the values are briefly equal, which is common
+  on instruments with a coarse tick.
+- **A run test needs its own changes to be present.** ``rising(src, len)`` reads
+  ``len`` changes and therefore ``len + 1`` values, which is where its warmup of
+  bar ``len`` comes from and why it is a bar later than a window of ``len``.
+- **The two that wait for a condition are absent, not zero, before it has ever
+  been true.** Zero would read as "it happened on this bar".
+"""
+
+from typing import Optional
+
+from .series import Region, back, contributed, raw_window, region
+from .values import ABSENT, Value, number, result
+
+
+def change(state: Region, value: Value, length: Optional[int]) -> Value:
+    """``change(src)`` and ``change(src, len)``: ``src - src[len]``, one subtraction."""
+    keep = None if length is None else length + 1
+    values = contributed(state, "src", number(value), keep)
+    older = back(values, length)
+    newer = values[len(values) - 1]
+    if not isinstance(newer, float) or not isinstance(older, float):
+        return ABSENT
+    return result(newer - older)
+
+
+def rising(state: Region, value: Value, length: Optional[int]) -> Value:
+    """``rising(src, len)``: true when each of the last ``len`` changes was positive."""
+    return _run(state, value, length, True)
+
+
+def falling(state: Region, value: Value, length: Optional[int]) -> Value:
+    """``falling(src, len)``: true when each of the last ``len`` changes was negative."""
+    return _run(state, value, length, False)
+
+
+def _run(state: Region, value: Value, length: Optional[int], up: bool) -> Value:
+    """The run test over the ``len + 1`` values the ``len`` changes are taken from.
+
+    **The changes are read oldest first and the answer is the first one that
+    settles it.** A change that is not in the direction asked for makes the run
+    false there and then, and a change that cannot be taken because one of its
+    two bars is absent makes the answer absent there and then. So a window with a
+    hole in it is false rather than absent whenever an older change had already
+    failed, which is not the blanket propagation of section 2.4 and is the order
+    this reading is taken in.
+    """
+    keep = None if length is None else length + 1
+    held = raw_window(contributed(state, "src", number(value), keep), keep)
+    if held is None or length is None:
+        return ABSENT
+    for age in range(length - 1, -1, -1):
+        newer = held[age]
+        older = held[age + 1]
+        if not isinstance(newer, float) or not isinstance(older, float):
+            return ABSENT
+        if up and not newer > older:
+            return False
+        if not up and not newer < older:
+            return False
+    return True
+
+
+def crossed_up(state: Region, first: Value, second: Value) -> Value:
+    """``crossUp(a, b)``: ``a`` was at or below ``b`` and is now above."""
+    pair = _pair(state, first, second)
+    if pair is None:
+        return ABSENT
+    (now_first, before_first), (now_second, before_second) = pair
+    return before_first <= before_second and now_first > now_second
+
+
+def crossed_down(state: Region, first: Value, second: Value) -> Value:
+    """``crossDown(a, b)``: ``a`` was at or above ``b`` and is now below."""
+    pair = _pair(state, first, second)
+    if pair is None:
+        return ABSENT
+    (now_first, before_first), (now_second, before_second) = pair
+    return before_first >= before_second and now_first < now_second
+
+
+def crossed(state: Region, first: Value, second: Value) -> Value:
+    """``cross(a, b)``: either direction, read from the one pair of readings."""
+    pair = _pair(state, first, second)
+    if pair is None:
+        return ABSENT
+    (now_first, before_first), (now_second, before_second) = pair
+    if before_first <= before_second and now_first > now_second:
+        return True
+    return before_first >= before_second and now_first < now_second
+
+
+def _pair(state: Region, first: Value, second: Value):
+    """This bar's and the previous bar's readings of both series, or absence.
+
+    Both are contributed on every bar whatever the other one did, so a hole in
+    one does not shift the other's idea of which bar was previous.
+    """
+    left = contributed(state, "a", number(first), 2)
+    right = contributed(state, "b", number(second), 2)
+    now_left, before_left = left[len(left) - 1], back(left, 1)
+    now_right, before_right = right[len(right) - 1], back(right, 1)
+    for reading in (now_left, before_left, now_right, before_right):
+        if not isinstance(reading, float):
+            return None
+    return (now_left, before_left), (now_right, before_right)
+
+
+def bars_since(state: Region, condition: Value) -> Value:
+    """``barsSince(cond)``: bars since the condition last held, 0 on the bar itself.
+
+    Absent until the condition has been true once. A bar the condition is absent
+    on is a bar it did not hold: the count goes on rather than stopping, because
+    the question is how long ago the last true bar was and an unknown bar in
+    between does not change the answer.
+    """
+    held = region(state, "since")
+    if condition is True:
+        held["bars"] = 0.0
+        return 0.0
+    since = held.get("bars")
+    if since is None:
+        return ABSENT
+    since = since + 1
+    held["bars"] = since
+    return since
+
+
+def value_when(
+    state: Region, condition: Value, value: Value, occurrence: Optional[int]
+) -> Value:
+    """``valueWhen(cond, src, occurrence)``: ``src`` as it stood on a true bar.
+
+    Occurrence 0 is the most recent true bar, 1 the one before it, and the answer
+    is absent until that many true bars have happened. The value recorded is
+    whatever ``src`` was on that bar, absence included: the condition decides
+    which bar is read and the source decides what was there.
+    """
+    wanted = 0 if occurrence is None else occurrence
+    held = region(state, "seen")
+    values = held.get("values")
+    if values is None:
+        values = []
+        held["values"] = values
+    if condition is True:
+        values.append(value)
+    depth = max(wanted + 1, held.get("depth", 1))
+    held["depth"] = depth
+    extra = len(values) - depth
+    if extra > 0:
+        del values[:extra]
+    if wanted < 0 or len(values) <= wanted:
+        return ABSENT
+    return values[len(values) - 1 - wanted]

openscript/library/code_points.py

@@ -0,0 +1,85 @@
+"""The two string rules two engines have to share, written from the page.
+
+**A string is a sequence of code points** (`compiled-program.md` section 3.1),
+so length, indexing and comparison count code points and not the storage unit of
+whatever language an engine is written in. This host stores a string as code
+points already, which makes the rule free here and does not make it optional: an
+engine whose strings are sixteen bit units has to count and index past a
+surrogate pair as one element, or the two disagree about the length of a string
+holding a symbol outside the basic plane and about every substring taken after
+one.
+
+**Ordering.** Two strings are ordered by comparing code points from the front,
+the first difference deciding, and a string that runs out first ordering first
+(`language.md` section 9.3, `stdlib.md` section 10). It is the one order in the
+language: the four comparison operators and a sort over an array of strings
+agree. This host's own comparison is already by code point, so the function below
+is the rule written down rather than a correction of the host, and a test holds
+it to a pair the unit based order would get wrong.
+
+**Whitespace.** ``str.trim`` removes, and ``toNumber`` ignores at either end,
+exactly the code points `stdlib.md` section 10 lists, which are the ones with the
+Unicode White_Space property, and no other. The host's own strip removes a
+different set: it takes the four information separators U+001C to U+001F as well,
+and another host takes the byte order mark U+FEFF and leaves those, so neither
+host's default is the set and the set is written out here. ``tests/test_strings``
+walks every code point of the basic plane against the table read out of the page,
+which is what makes the page the input rather than this list.
+"""
+
+# The code points `stdlib.md` section 10 lists, in the order it lists them.
+_WHITESPACE: frozenset[int] = frozenset(
+    {
+        0x0009,  # character tabulation
+        0x000A,  # line feed
+        0x000B,  # line tabulation
+        0x000C,  # form feed
+        0x000D,  # carriage return
+        0x0020,  # space
+        0x0085,  # next line
+        0x00A0,  # no-break space
+        0x1680,  # ogham space mark
+        0x2000,  # en quad, through the hair space
+        0x2001,
+        0x2002,
+        0x2003,
+        0x2004,
+        0x2005,
+        0x2006,
+        0x2007,
+        0x2008,
+        0x2009,
+        0x200A,
+        0x2028,  # line separator
+        0x2029,  # paragraph separator
+        0x202F,  # narrow no-break space
+        0x205F,  # medium mathematical space
+        0x3000,  # ideographic space
+    }
+)
+
+
+def is_whitespace(point: int) -> bool:
+    """Whether one code point is in the trimmed set."""
+    return point in _WHITESPACE
+
+
+def trimmed(text: str) -> str:
+    """``text`` with the whitespace of the written set taken off both ends."""
+    start = 0
+    end = len(text)
+    while start < end and is_whitespace(ord(text[start])):
+        start += 1
+    while end > start and is_whitespace(ord(text[end - 1])):
+        end -= 1
+    return text[start:end]
+
+
+def compare(a: str, b: str) -> int:
+    """The order of two strings: negative when ``a`` comes first, by code point."""
+    for one, other in zip(a, b):
+        if one != other:
+            return -1 if ord(one) < ord(other) else 1
+    if len(a) == len(b):
+        return 0
+    return -1 if len(a) < len(b) else 1