openscript 0.4.0__py3-none-any.whl

openscript/library/ranges.py

@@ -0,0 +1,105 @@
+"""The readings of `stdlib.md` section 20.5 that are taken from the bar's own range.
+
+**There are two true ranges and they are different quantities.** The plain one is
+the call a script can make, and `stdlib.md` section 6 grants the oldest bar of
+the dataset the library's one exception to absence propagation there: the reading
+is ``high - low``, because the other two terms need a close that does not exist
+and the bar's own range is a true statement about that bar. The gap aware form is
+the same three terms with no exception, it is absent on that bar like any other
+change, and it is what the choppiness reading and the directional index take.
+Section 6 says which of the two a function takes by declaring its warmup one bar
+later than the plain reading would give.
+
+Neither form is written out again here. ``bars.py`` holds the three terms and the
+exception, and this file asks it for the reading it wants by saying whether the
+bar it is on is the oldest one.
+"""
+
+from typing import Optional
+
+from . import averages, elementary
+from .bars import true_range
+from .extremes import window_high, window_low
+from .series import Region, contributed, total, window
+from .values import ABSENT, Value, number, result
+
+
+def plain_range(ctx) -> Value:
+    """``trueRange()`` as a stateful caller reads it, oldest bar exception and all."""
+    return true_range(
+        ctx.bar("high"), ctx.bar("low"), ctx.bar("previousClose"), ctx.first_bar()
+    )
+
+
+def gap_range(ctx) -> Value:
+    """The gap aware form: the same three terms with no exception on the oldest bar.
+
+    It is not a call a script can make. An engine reaches it through this half of
+    the library, which is where the two functions that count changes rather than
+    levels ask for it.
+    """
+    return true_range(ctx.bar("high"), ctx.bar("low"), ctx.bar("previousClose"), False)
+
+
+def average_range(state: Region, ctx, length: Optional[int]) -> Value:
+    """``atr(len)``: ``rma`` over ``trueRange``, that first bar included."""
+    return averages.smoothed(state, plain_range(ctx), length)
+
+
+def normalised_range(state: Region, ctx, length: Optional[int]) -> Value:
+    """``natr(len)``: ``(100 * atr) / close``, the percentage form."""
+    width = average_range(state, ctx, length)
+    close = number(ctx.bar("close"))
+    if not isinstance(width, float) or close is None:
+        return ABSENT
+    if close == 0:
+        return ABSENT
+    return result((100 * width) / close)
+
+
+def channel(state: Region, ctx, length: Optional[int]) -> list:
+    """``donchian(len)``: the window's outright high, its midpoint and its low.
+
+    The midpoint is the mean of the two extremes as reported, which is the one
+    arrangement section 20.3 states for a midpoint of a channel.
+    """
+    highs = contributed(state, "high", number(ctx.bar("high")), length)
+    lows = contributed(state, "low", number(ctx.bar("low")), length)
+    upper = window_high(highs, length)
+    lower = window_low(lows, length)
+    if not isinstance(upper, float) or not isinstance(lower, float):
+        return [ABSENT, ABSENT, ABSENT]
+    return [upper, result((upper + lower) / 2), lower]
+
+
+def choppiness(state: Region, ctx, length: Optional[int]) -> Value:
+    """``chop(len)``: the distance travelled against the range covered.
+
+    The ratio is formed first, then its logarithm, then the multiplication by
+    100, then the division by the logarithm of the length. The result is absent
+    where the span or the distance is not above zero, and where the length is 1
+    and the scale is zero.
+
+    **This reading depends on ``log10``**, so it reaches gap 1 of section 20.11
+    and carries no cross-engine guarantee: there is no portable reference
+    algorithm for a logarithm anywhere in the specification.
+    """
+    ranges = contributed(state, "range", gap_range(ctx), length)
+    highs = contributed(state, "high", number(ctx.bar("high")), length)
+    lows = contributed(state, "low", number(ctx.bar("low")), length)
+    held = window(ranges, length)
+    upper = window_high(highs, length)
+    lower = window_low(lows, length)
+    if held is None or length is None:
+        return ABSENT
+    if not isinstance(upper, float) or not isinstance(lower, float):
+        return ABSENT
+    distance = total(held)
+    span = upper - lower
+    if span <= 0 or distance <= 0:
+        return ABSENT
+    travelled = elementary.log10(distance / span)
+    scale = elementary.log10(float(length))
+    if not isinstance(travelled, float) or not isinstance(scale, float) or scale == 0:
+        return ABSENT
+    return result((100 * travelled) / scale)

openscript/library/rounding.py

@@ -0,0 +1,123 @@
+"""Rounding, and the one rule that decides every case.
+
+**Halves go away from zero, never to even.** `stdlib.md` section 8.1 fixes it
+and gives the reason: a price rounded for display should agree with what a
+trader would write down, and round half to even surprises people at exactly the
+values that matter. Fixing it also means two engines cannot differ by one tick.
+
+**Adding a half and taking the floor is not this function.** It is the usual
+shortcut and it is wrong for the value just below a half, where adding 0.5 rounds
+up to the next representable number before the floor ever runs and the answer
+comes out one too high. `stdlib.md` section 20.7 writes the comparison of the
+fractional part out instead, which has no such case, and that is what is below.
+
+**The scale of a fixed decimal rounding is not a floating point power.** 20.7
+again: it is the binary64 nearest to ten to that count, the value the literal
+``1e23`` reads as. On one host the two differ by an ulp at a count of 23 out of
+the 309 a binary64 can hold, and over a price walk that one count moved 814
+results. The table here is built once from exact whole number arithmetic, which
+is the "exact integer power converted once" 20.7 names, and it is the one table:
+the display conversion of ``text(x, decimals)`` scales by it as well.
+"""
+
+import math
+
+from .values import ABSENT, Value, floor_of, number, result, whole
+
+
+def round_half_away(x: float) -> float:
+    """The nearest whole number, halves away from zero.
+
+    A value with no whole number near it, an infinity produced by a scaling that
+    overflowed, is returned unchanged for ``result`` to turn into absence.
+    """
+    if not math.isfinite(x):
+        return x
+    below = floor_of(x)
+    fraction = x - below
+    if fraction > 0.5:
+        return below + 1.0
+    if fraction < 0.5:
+        return below
+    # Exactly a half. Away from zero: upward above zero, and `below` already is
+    # the downward answer for a negative, since the floor of -2.5 is -3.
+    return below + 1.0 if x > 0 else below
+
+
+# Ten to each whole power a binary64 can hold, as the binary64 nearest to it.
+# Built from exact whole number arithmetic rather than from a floating point
+# power, for the reason at the top of this file.
+_POWERS_OF_TEN: tuple[float, ...] = tuple(float(10**count) for count in range(309))
+
+
+def scale_of(decimals: int) -> float:
+    """The scale for a digit count: the nearest binary64 to ten to that power.
+
+    Past the last finite power it is the infinity the power would have been, so
+    that a count a script computed scales to absence rather than to a wrong
+    number.
+    """
+    if 0 <= decimals < len(_POWERS_OF_TEN):
+        return _POWERS_OF_TEN[decimals]
+    return math.inf
+
+
+def floor(x: Value) -> Value:
+    """``floor(x)``: toward negative infinity."""
+    value = number(x)
+    return ABSENT if value is None else result(floor_of(value))
+
+
+def ceil(x: Value) -> Value:
+    """``ceil(x)``: toward positive infinity."""
+    value = number(x)
+    if value is None:
+        return ABSENT
+    return result(value if not math.isfinite(value) else float(math.ceil(value)))
+
+
+def trunc(x: Value) -> Value:
+    """``trunc(x)``: toward zero."""
+    value = number(x)
+    if value is None:
+        return ABSENT
+    return result(value if not math.isfinite(value) else float(math.trunc(value)))
+
+
+def round_to_whole(x: Value) -> Value:
+    """``round(x)``: to the nearest whole number, halves away from zero."""
+    value = number(x)
+    return ABSENT if value is None else result(round_half_away(value))
+
+
+def round_to(x: Value, decimals: Value) -> Value:
+    """``round(x, decimals)``: scale, round once, scale back."""
+    value = number(x)
+    count = whole(decimals)
+    if value is None or count is None:
+        return ABSENT
+    scale = scale_of(count)
+    return result(round_half_away(value * scale) / scale)
+
+
+def round_to_step(x: Value, step: Value) -> Value:
+    """``roundToStep(x, step)``: to the nearest multiple of ``step``."""
+    value = number(x)
+    size = number(step)
+    if value is None or size is None or size <= 0:
+        return ABSENT
+    return result(round_half_away(value / size) * size)
+
+
+def round_to_tick(price: Value, tick_size: Value) -> Value:
+    """``roundToTick(price)``: to the instrument's tick.
+
+    Absent when the host has stated no tick size, rather than the price
+    unrounded. Returning the input would produce an order price that looks
+    rounded and is not, and a venue refuses an order off the tick, so a script
+    that cannot round has to be able to see that it cannot.
+    """
+    tick = number(tick_size)
+    if tick is None or tick <= 0:
+        return ABSENT
+    return round_to_step(price, tick)

openscript/library/series.py

@@ -0,0 +1,213 @@
+"""The two shapes of `stdlib.md` section 20.2, and the region they are kept in.
+
+Almost every length taking function of the stateful half is one of these two or
+is built out of them, so they are written once here and read from everywhere
+else. Getting them right is most of the work, and getting them wrong is a whole
+library that is plausible and never bit identical.
+
+**A region is plain data and nothing else.** `compiled-program.md` section 2.11
+requires a state region to be snapshottable by a mechanical copy, by an engine
+that does not know which function owns it, so what a function keeps here is
+dictionaries, lists and numbers. An object with behaviour in it would copy in a
+way the engine cannot promise, and the rollback of section 6 would carry a
+reference where it meant to carry a value.
+
+**A buffer holds what the bars contributed, not what the bars were.** A call
+inside a branch does not run on every bar, and the window of section 20.1 is the
+values this call site contributed, oldest still reachable at the end. The depth
+kept is the largest length the call has asked for, because `stdlib.md` section
+2.5 measures a series length's warmup against the largest value it has taken and
+a buffer trimmed to today's length could not answer tomorrow's.
+
+**Absence is not arithmetic.** A window with a hole in it is absent, which is
+section 2.4's rule for every windowed function, and the three that pass over a
+hole say so in their names and ask for the raw window instead.
+"""
+
+from typing import Any, Callable, Dict, List, Optional, Sequence
+
+from .values import ABSENT, Value, result
+
+#: One call site's state region: what the engine created, copies and rolls back.
+Region = Dict[str, Any]
+
+#: The step of a seeded recurrence: what this bar's value does to the running one.
+Step = Callable[[float, float], float]
+
+
+def region(state: Region, key: str) -> Region:
+    """A named region inside a region, for a function built out of others.
+
+    ``dema`` is two exponential means and ``macd`` is three, and each of them
+    has to keep its own running value. Nesting rather than prefixing every key
+    means a function composes without its parts having to know they were
+    composed.
+    """
+    held = state.get(key)
+    if held is None:
+        held = {}
+        state[key] = held
+    return held
+
+
+def contributed(state: Region, key: str, value: Value, keep: Optional[int]) -> List[Value]:
+    """This bar's contribution pushed into a named buffer, and the buffer back.
+
+    ``keep`` is how many of the most recent contributions this bar's call needs.
+    The buffer keeps the largest depth it has ever been asked for, so a length
+    that grows mid-run still has the history behind it, and one bar is kept even
+    where the caller asked for nothing, because a call whose length is absent on
+    this bar still happened on this bar.
+    """
+    held = state.get(key)
+    if held is None:
+        held = {"values": [], "depth": 1}
+        state[key] = held
+    if keep is not None and keep > held["depth"]:
+        held["depth"] = keep
+    values: List[Value] = held["values"]
+    values.append(value)
+    extra = len(values) - held["depth"]
+    if extra > 0:
+        del values[:extra]
+    return values
+
+
+def raw_window(values: Sequence[Value], length: Optional[int]) -> Optional[List[Value]]:
+    """The last ``length`` contributions, newest first, holes and all.
+
+    Newest first is section 20.1's indexing: ``w[0]`` is what this bar
+    contributed and ``w[len - 1]`` is the oldest value still in the window. The
+    answer is absent only where the window is not full yet, which is the warmup
+    every entry in sections 4 to 9 declares.
+    """
+    if length is None or length < 1 or len(values) < length:
+        return None
+    held = list(values[len(values) - length :])
+    held.reverse()
+    return held
+
+
+def window(values: Sequence[Value], length: Optional[int]) -> Optional[List[float]]:
+    """The same window, absent where any bar in it is absent.
+
+    Section 2.4: every windowed function propagates absence. A window that
+    dropped its holes would be a mean of however many bars happened to have a
+    value, which is a different quantity and one whose divisor nobody could
+    state.
+    """
+    held = raw_window(values, length)
+    if held is None:
+        return None
+    for value in held:
+        if not isinstance(value, float):
+            return None
+    return held  # type: ignore[return-value]
+
+
+def back(values: Sequence[Value], offset: Optional[int]) -> Value:
+    """What the buffer held ``offset`` contributions ago, or absence.
+
+    Offset 0 is this bar. Absence here is "the run is not that old yet", which
+    is why it is the same answer as a hole: neither is a value the caller can
+    compute with.
+    """
+    if offset is None or offset < 0 or len(values) <= offset:
+        return ABSENT
+    return values[len(values) - 1 - offset]
+
+
+def total(held: Sequence[float]) -> float:
+    """Section 20.2.1: the window sum, taken fresh, oldest first.
+
+    The window arrives newest first, so the index runs from ``len - 1`` down to
+    0 and the oldest value is added to zero first. Carrying a total forward and
+    subtracting the value that leaves the window is the same quantity in exact
+    arithmetic, a different number in binary64, and refused outright by
+    `compiled-program.md` section 8.3.
+    """
+    running = 0.0
+    for at in range(len(held) - 1, -1, -1):
+        running = running + held[at]
+    return running
+
+
+def mean(held: Sequence[float], length: int) -> float:
+    """The window mean: one division applied to the finished sum.
+
+    Never a running mean, and never a sum divided term by term as it is built.
+    Section 20.2.1 states it in one sentence and it is the sentence most easily
+    lost, because a running mean is the cheaper thing to write.
+    """
+    return total(held) / length
+
+
+def seeded(
+    state: Region,
+    key: str,
+    values: Sequence[Value],
+    length: Optional[int],
+    step: Step,
+) -> Value:
+    """Section 20.2.2: the seeded recurrence every seeded average in the library has.
+
+    Absent before the seed bar, the window mean on it, and ``step`` after it. The
+    seed bar is the first bar whose window holds ``length`` present values, which
+    is what makes the warmups of `stdlib.md` compose rather than having to be
+    asserted one call at a time.
+
+    **A hole after the seed freezes the recurrence.** The bar is absent and the
+    running value is left where it was, so the next present bar continues from
+    the last present one. Consuming absence as zero drags the average toward
+    nothing and re-seeding lets one missing bar restart a two hundred bar
+    average.
+
+    Seeding from bar 0 with the first value is the common and cheaper
+    alternative. It is not this one: it draws a line where there should be a gap
+    and stays materially wrong until the seed decays away.
+    """
+    held = region(state, key)
+    running = held.get("running")
+    if running is None:
+        full = window(values, length)
+        if full is None or length is None:
+            return ABSENT
+        running = mean(full, length)
+        held["running"] = running
+        return _reported(running)
+    value = values[len(values) - 1] if values else ABSENT
+    if not isinstance(value, float):
+        return ABSENT
+    running = step(running, value)
+    held["running"] = running
+    return _reported(running)
+
+
+def running_total(state: Region, key: str, term: Value) -> Value:
+    """Section 20.6's anchored accumulation: one term per bar, from zero.
+
+    Every total here starts at zero before any bar has contributed to it, and an
+    absent bar produces an absent bar out and leaves the total where it was. It
+    is neither reset nor fed a zero in place of the missing term, so a gap costs
+    the reading the bars it covers and nothing after them.
+
+    This is not the carried total section 20.2.1 refuses. There is no window to
+    sum here, so it is a different quantity rather than a cheaper way to compute
+    the same one.
+    """
+    held = region(state, key)
+    if not isinstance(term, float):
+        return ABSENT
+    running = held.get("running", 0.0) + term
+    held["running"] = running
+    return _reported(running)
+
+
+def _reported(running: float) -> Value:
+    """A running value as it is reported, under `compiled-program.md` 3.1.
+
+    The state keeps what the arithmetic produced and the caller is handed what
+    the language can hold, so an overflow is absent on the chart without the
+    recurrence quietly re-seeding itself on the bar after it.
+    """
+    return result(running)