openscript 0.4.0__py3-none-any.whl

openscript/library/flows.py

@@ -0,0 +1,220 @@
+"""The volume readings of `stdlib.md` section 20.6.
+
+**The running totals here are anchored accumulations rather than windows**, so
+each carries its total forward and adds one term per bar. That is what the
+quantity is, not a cheaper way to compute a window sum, and the refusal of a
+carried total in section 20.2.1 does not reach them: there is no window to sum.
+
+**Every total 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.
+
+Every function here is absent on every bar when the host supplies no volume for
+the instrument, which is one case of the same rule: an absent volume is not a
+zero volume, and a study that wants to branch on it tests the chart fact rather
+than inspecting the result.
+"""
+
+from typing import Optional
+
+from . import averages, prices, strength
+from .series import Region, back, contributed, region, running_total, total, window
+from .values import ABSENT, Value, number, result
+
+
+def session_average(state: Region, ctx, value: Value) -> Value:
+    """``vwap(src)``: the volume weighted average since the session opened."""
+    return _anchored(state, ctx, value, ctx.bar("isSessionFirst"))
+
+
+def anchored_average(state: Region, ctx, value: Value, anchor: Value) -> Value:
+    """``vwapAnchor(src, resetWhen)``: the same average, restarted on a condition.
+
+    One calculation and two entries. The session reading resets where the host
+    says a session began, this one where the script says so, and the reset
+    happens **before** the bar's own term is added, so an anchor bar is the first
+    bar of the new average rather than the last bar of the old one.
+    """
+    return _anchored(state, ctx, value, anchor)
+
+
+def _anchored(state: Region, ctx, value: Value, anchor: Value) -> Value:
+    """The two totals, the reset, and the one division both averages take."""
+    held = region(state, "vwap")
+    price = number(value)
+    traded = number(ctx.bar("volume"))
+    if anchor is not True and anchor is not False:
+        return ABSENT
+    if anchor:
+        held["flow"] = 0.0
+        held["traded"] = 0.0
+    if price is None or traded is None:
+        return ABSENT
+    flow = held.get("flow", 0.0) + price * traded
+    volume = held.get("traded", 0.0) + traded
+    held["flow"] = flow
+    held["traded"] = volume
+    if volume == 0:
+        return ABSENT
+    return result(flow / volume)
+
+
+def balance(state: Region, ctx) -> Value:
+    """``obv()``: the whole of the bar's volume, signed by the close's direction.
+
+    The first bar has no close before it to compare against, so it contributes
+    nothing and the reading there is the 0 the total started at. An unchanged
+    close contributes nothing either.
+    """
+    close = number(ctx.bar("close"))
+    traded = number(ctx.bar("volume"))
+    before = back(contributed(state, "close", close, 2), 1)
+    if close is None or traded is None:
+        return ABSENT
+    term = 0.0
+    if isinstance(before, float):
+        if close > before:
+            term = traded
+        elif close < before:
+            term = -traded
+    return running_total(state, "run", term)
+
+
+def accumulation(state: Region, ctx) -> Value:
+    """``ad()``: the running total of the term ``cmf`` sums over a window."""
+    return running_total(state, "run", position_flow(ctx))
+
+
+def position_flow(ctx) -> Value:
+    """The per-bar term ``ad`` and ``cmf`` share, formed as section 20.6 writes it.
+
+    The two bracketed differences are formed first and subtracted, then divided by
+    the span, then multiplied by the volume. **A bar whose span is not above zero
+    contributes an exact 0** rather than ending the total.
+    """
+    high = number(ctx.bar("high"))
+    low = number(ctx.bar("low"))
+    close = number(ctx.bar("close"))
+    traded = number(ctx.bar("volume"))
+    if high is None or low is None or close is None or traded is None:
+        return ABSENT
+    span = high - low
+    if span <= 0:
+        return 0.0
+    return result((((close - low) - (high - close)) / span) * traded)
+
+
+def flow_fraction(state: Region, ctx, length: Optional[int]) -> Value:
+    """``cmf(len)``: the window sum of that term over the window sum of the volume."""
+    terms = contributed(state, "term", position_flow(ctx), length)
+    volumes = contributed(state, "size", number(ctx.bar("volume")), length)
+    held = window(terms, length)
+    traded = window(volumes, length)
+    if held is None or traded is None:
+        return ABSENT
+    divisor = total(traded)
+    if divisor == 0:
+        return ABSENT
+    return result(total(held) / divisor)
+
+
+def accumulation_gap(
+    state: Region, ctx, fast_length: Optional[int], slow_length: Optional[int]
+) -> Value:
+    """``adOsc(fast, slow)``: the fast exponential mean of the running total less the slow.
+
+    The averages run over the running total, not over the per-bar term, which is
+    what dates the turns of the total rather than the turns of one bar's flow.
+    """
+    running = accumulation(region(state, "total"), ctx)
+    fast = averages.exponential(region(state, "fast"), running, fast_length)
+    slow = averages.exponential(region(state, "slow"), running, slow_length)
+    if not isinstance(fast, float) or not isinstance(slow, float):
+        return ABSENT
+    return result(fast - slow)
+
+
+def price_trend(state: Region, ctx) -> Value:
+    """``pvt()``: the running total of a proportion of the volume.
+
+    The proportion is formed and rounded before it meets the volume. The first
+    bar has no change behind it and is absent, and the second already carries its
+    own term on top of the zero the total started at.
+    """
+    close = number(ctx.bar("close"))
+    traded = number(ctx.bar("volume"))
+    before = back(contributed(state, "close", close, 2), 1)
+    if close is None or traded is None or not isinstance(before, float) or before == 0:
+        return ABSENT
+    return running_total(state, "run", ((close - before) / before) * traded)
+
+
+def money_flow(state: Region, ctx, length: Optional[int]) -> Value:
+    """``mfi(len)``: the strength reading computed on money flow, with window sums.
+
+    The arrangement of the last line is section 20.4's, and the result is 100
+    where the falling side is zero, for the reason given there. A bar whose
+    typical price is unchanged contributes an exact zero to both sides.
+    """
+    price = prices.typical(ctx)
+    traded = number(ctx.bar("volume"))
+    values = contributed(state, "typical", price, 2)
+    before = back(values, 1)
+    rise = ABSENT
+    fall = ABSENT
+    if isinstance(price, float) and traded is not None and isinstance(before, float):
+        flow = price * traded
+        rise = flow if price > before else 0.0
+        fall = flow if price < before else 0.0
+    rises = window(contributed(state, "rise", rise, length), length)
+    falls = window(contributed(state, "fall", fall, length), length)
+    if rises is None or falls is None:
+        return ABSENT
+    return strength.line_of(total(rises), total(falls))
+
+
+def movement(state: Region, ctx, length: Optional[int]) -> Value:
+    """``eom(len)``: how far price moved per unit of volume, then a simple mean.
+
+    The product is formed before the division. **There is no scaling constant**:
+    implementations of this reading usually multiply by a large divisor whose only
+    job is to bring the number into a readable range and they do not agree on it,
+    section 7 declares no such argument, and this is gap 3 of section 20.11. That
+    leaves the reading very small on a liquid instrument.
+    """
+    midpoint = prices.midpoint(ctx)
+    values = contributed(state, "midpoint", midpoint, 2)
+    before = back(values, 1)
+    high = number(ctx.bar("high"))
+    low = number(ctx.bar("low"))
+    traded = number(ctx.bar("volume"))
+    term = ABSENT
+    if isinstance(midpoint, float) and isinstance(before, float):
+        if high is not None and low is not None and traded is not None and traded != 0:
+            term = result(((midpoint - before) * (high - low)) / traded)
+    return averages.simple(region(state, "mean"), term, length)
+
+
+def force(state: Region, ctx, length: Optional[int]) -> Value:
+    """``forceIndex(len)``: the one bar close change times the volume, smoothed.
+
+    The product is formed per bar and fed to the average, so a bar with no volume
+    freezes the average rather than feeding it a change with nothing behind it.
+    """
+    close = number(ctx.bar("close"))
+    traded = number(ctx.bar("volume"))
+    before = back(contributed(state, "close", close, 2), 1)
+    term = ABSENT
+    if close is not None and traded is not None and isinstance(before, float):
+        term = result((close - before) * traded)
+    return averages.exponential(region(state, "mean"), term, length)
+
+
+def relative_volume(state: Region, ctx, length: Optional[int]) -> Value:
+    """``relativeVolume(len)``: the bar's volume over the simple mean of the volume."""
+    traded = number(ctx.bar("volume"))
+    average = averages.simple(region(state, "mean"), traded, length)
+    if traded is None or not isinstance(average, float) or average == 0:
+        return ABSENT
+    return result(traded / average)

openscript/library/momentum.py

@@ -0,0 +1,203 @@
+"""The momentum readings of `stdlib.md` section 20.4, and the two gaps between means.
+
+**These scale by 100 before dividing**, which is the association their own
+readings have always carried and the opposite of the directional index of section
+20.3. Writing one of them the other way round moves every value it reports.
+
+Two of them are named in section 20.4 only so that the absence of a recipe is not
+read as an oversight: the momentum reading is a single subtraction, and the
+awesome oscillator is the fast simple mean of the bar midpoint less the slow one,
+in that order.
+"""
+
+from typing import Optional
+
+from . import averages, bookkeeping, composites, prices
+from .series import Region, back, contributed, region, total, window
+from .values import ABSENT, Value, number, result
+
+
+def gap(
+    state: Region,
+    value: Value,
+    fast_length: Optional[int],
+    slow_length: Optional[int],
+    signal_length: Optional[int],
+    percent: bool,
+) -> list:
+    """``macd(...)`` and ``ppo(...)``, which differ only in the first line.
+
+    The signal average is fed the line absences and all, so it seeds on the first
+    ``signal`` values the line produced, which is where its warmup comes from. The
+    histogram is the difference of the two values as reported, not recomputed
+    from the averages.
+    """
+    fast = averages.exponential(region(state, "fast"), value, fast_length)
+    slow = averages.exponential(region(state, "slow"), value, slow_length)
+    line = ABSENT
+    if isinstance(fast, float) and isinstance(slow, float):
+        if not percent:
+            line = result(fast - slow)
+        elif slow != 0:
+            line = result((100 * (fast - slow)) / slow)
+    trigger = averages.exponential(region(state, "signal"), line, signal_length)
+    histogram = ABSENT
+    if isinstance(line, float) and isinstance(trigger, float):
+        histogram = result(line - trigger)
+    return [line, trigger, histogram]
+
+
+def distance(state: Region, value: Value, length: Optional[int]) -> Value:
+    """``mom(src, len)``: ``src - src[len]``, which is the change of section 9."""
+    return bookkeeping.change(state, value, length)
+
+
+def rate(state: Region, value: Value, length: Optional[int]) -> Value:
+    """``roc(src, len)``: the same change as a percentage of the older value."""
+    keep = None if length is None else length + 1
+    values = contributed(state, "src", number(value), keep)
+    now = values[len(values) - 1]
+    before = back(values, length)
+    if not isinstance(now, float) or not isinstance(before, float) or before == 0:
+        return ABSENT
+    return result((100 * (now - before)) / before)
+
+
+def midpoint_gap(
+    state: Region, ctx, fast_length: Optional[int], slow_length: Optional[int]
+) -> Value:
+    """``awesomeOsc(fast, slow)``: the fast simple mean of the midpoint less the slow one."""
+    value = prices.midpoint(ctx)
+    fast = averages.simple(region(state, "fast"), value, fast_length)
+    slow = averages.simple(region(state, "slow"), value, slow_length)
+    if not isinstance(fast, float) or not isinstance(slow, float):
+        return ABSENT
+    return result(fast - slow)
+
+
+def smoothed_rate(state: Region, value: Value, length: Optional[int]) -> Value:
+    """``trix(src, len)``: the one bar percentage change of a triple exponential mean.
+
+    The other reading in circulation takes the change of the logarithm of the
+    average instead. It is a different number and it is not what section 5
+    describes.
+    """
+    smoothed = composites.smoothed_three(region(state, "chain"), value, length)
+    values = contributed(state, "smoothed", smoothed, 2)
+    now = values[len(values) - 1]
+    before = back(values, 1)
+    if not isinstance(now, float) or not isinstance(before, float) or before == 0:
+        return ABSENT
+    return result((100 * (now - before)) / before)
+
+
+def double_smoothed(
+    state: Region, value: Value, long_length: Optional[int], short_length: Optional[int]
+) -> Value:
+    """``tsi(src, longLen, shortLen)``: the one bar change smoothed twice, over its own size.
+
+    The long length comes first and the short one second, and the absolute size
+    of the change is smoothed the same way in its own pair of state regions.
+    """
+    values = contributed(state, "src", number(value), 2)
+    now = values[len(values) - 1]
+    before = back(values, 1)
+    delta = ABSENT
+    size = ABSENT
+    if isinstance(now, float) and isinstance(before, float):
+        delta = now - before
+        size = abs(delta)
+    smoothed_change = _twice(region(state, "change"), delta, long_length, short_length)
+    smoothed_size = _twice(region(state, "size"), size, long_length, short_length)
+    if not isinstance(smoothed_change, float) or not isinstance(smoothed_size, float):
+        return ABSENT
+    if smoothed_size == 0:
+        return ABSENT
+    return result((100 * smoothed_change) / smoothed_size)
+
+
+def _twice(
+    state: Region, value: Value, long_length: Optional[int], short_length: Optional[int]
+) -> Value:
+    """One quantity smoothed with the long length and then with the short one."""
+    once = averages.exponential(region(state, "long"), value, long_length)
+    return averages.exponential(region(state, "short"), once, short_length)
+
+
+def detrended(state: Region, value: Value, length: Optional[int]) -> Value:
+    """``dpo(src, len)``: the simple mean removed as it stood, displaced back.
+
+    The displacement is ``floor(len / 2) + 1`` bars, which is what the declared
+    warmup of bar ``len + floor(len / 2)`` requires.
+    """
+    price = number(value)
+    average = averages.simple(region(state, "mean"), price, length)
+    shift = None if length is None else length // 2 + 1
+    keep = None if shift is None else shift + 1
+    held = contributed(state, "mean-values", average, keep)
+    older = back(held, shift)
+    if price is None or not isinstance(older, float):
+        return ABSENT
+    return result(price - older)
+
+
+def blended(
+    state: Region,
+    ctx,
+    first_length: Optional[int],
+    second_length: Optional[int],
+    third_length: Optional[int],
+) -> Value:
+    """``ultimateOsc(len1, len2, len3)``: pressure over range, blended over three windows.
+
+    Both per-bar terms are formed against the previous close, which is the close
+    of the bar before this one as this call site saw it and not a fact the host
+    states: this reading counts changes, so the oldest bar has no term at all and
+    the exception section 6 grants the plain true range has nothing to do with
+    it. The three weighted terms are added left to right, shortest window first,
+    and the division by 7 is applied once at the end.
+    """
+    high = number(ctx.bar("high"))
+    low = number(ctx.bar("low"))
+    close = number(ctx.bar("close"))
+    before = back(contributed(state, "close", number(ctx.bar("close")), 2), 1)
+    pressure = ABSENT
+    span = ABSENT
+    if high is not None and low is not None and close is not None:
+        if isinstance(before, float):
+            floor_of = low if low < before else before
+            ceiling_of = high if high > before else before
+            pressure = close - floor_of
+            span = ceiling_of - floor_of
+    deepest = _deepest(first_length, second_length, third_length)
+    pressures = contributed(state, "pressure", pressure, deepest)
+    spans = contributed(state, "range", span, deepest)
+    fast = _ratio(pressures, spans, first_length)
+    middle = _ratio(pressures, spans, second_length)
+    slow = _ratio(pressures, spans, third_length)
+    if not isinstance(fast, float) or not isinstance(middle, float):
+        return ABSENT
+    if not isinstance(slow, float):
+        return ABSENT
+    blend = 4 * fast
+    blend = blend + 2 * middle
+    blend = blend + slow
+    return result((100 * blend) / 7)
+
+
+def _deepest(*lengths) -> Optional[int]:
+    """The widest of the three windows, which is what both buffers keep."""
+    known = [one for one in lengths if one is not None]
+    return max(known) if known else None
+
+
+def _ratio(pressures, spans, length: Optional[int]) -> Value:
+    """One window's pressure over its range, each the fresh sum of section 20.2.1."""
+    top = window(pressures, length)
+    bottom = window(spans, length)
+    if top is None or bottom is None:
+        return ABSENT
+    divisor = total(bottom)
+    if divisor == 0:
+        return ABSENT
+    return total(top) / divisor

openscript/library/number_text.py

@@ -0,0 +1,223 @@
+"""How a number becomes text, and how text becomes a number.
+
+`language.md` section 5.5 is one rule for every place a number is written: the
+``text`` call, a table cell, an alert's message, a constant in a compiled
+program, a case file and an expected column. Two engines compare numbers as bits
+and text as text, so a number that two rules could spell two ways is a
+disagreement with no number wrong anywhere.
+
+**The digits** are the shortest string of decimal digits that reads back as the
+same binary64 value. That is the conversion the host already performs natively
+and two hosts have been measured to agree on it, so it is taken rather than
+rebuilt. **The layout is where hosts part company**: where the point goes, when
+an exponent starts, and what is never written. The host's own writing turns to an
+exponent at a different magnitude, spells the exponent with a sign and a leading
+zero, and writes a point and a zero after a whole number, and all four of those
+are wrong here.
+
+**That layout is written out once, in ``canonical.py``, and this file calls it.**
+It was written out twice for one stage, here and there, with the two thresholds
+typed into each; both passed the vectors, so the copy cost nothing until the day
+one of them moved. What is this file's is what the layout is used for: the value
+a script asks for as text, the fixed decimal conversion built on the same digits,
+and the reading back of text as a number.
+
+`spec/vectors/number-text.json` holds the boundary cases as bit patterns and as
+text, in both directions, so an engine in any language can be held to the rule
+without reading either engine's source. ``tests/test_number_text.py`` is this
+engine held to it.
+
+**``text(x, decimals)`` is the one call whose layout is always positional**, at
+every magnitude, and its digits are this rule's digits for the rounded and scaled
+whole number, zero filled. A conversion that changed shape above a threshold
+would be a label that read correctly until the day a cumulative volume crossed
+it.
+"""
+
+import math
+
+from ..canonical import canonical_number, spread
+from .code_points import trimmed
+from .colour import Colour, hex_byte
+from .rounding import round_half_away, scale_of
+from .values import ABSENT, Value, is_number, number, result, whole
+
+
+def _carry(digits: str) -> str:
+    """One added to a string of digits, which grows it when every digit is nine."""
+    out = list(digits)
+    for at in range(len(out) - 1, -1, -1):
+        if out[at] != "9":
+            out[at] = chr(ord(out[at]) + 1)
+            return "".join(out)
+        out[at] = "0"
+    return "1" + "".join(out)
+
+
+def _written(digits: str, point: int) -> str:
+    """A spread written out, rounded half up where the point falls inside it.
+
+    Half up on a magnitude is half away from zero, because the sign is carried
+    separately by every caller.
+    """
+    if point >= len(digits):
+        return digits + "0" * (point - len(digits))
+    if point < 0:
+        return "0"
+    kept = digits[:point]
+    if digits[point] < "5":
+        return kept if kept != "" else "0"
+    return _carry(kept)
+
+
+def fixed(x: float, decimals: int) -> str:
+    """``text(x, decimals)``: a sign, at least one digit, and exactly ``decimals``.
+
+    The rounding is done on the number before it is written rather than left to a
+    formatting routine, because a routine's tie rule is the host's and the two
+    disagree at exactly the values a price lands on: this is halves away from
+    zero over the scaled value, and the host's is halves to even over the exact
+    binary expansion.
+
+    **The scale is ``round(x, decimals)``'s**, so the display conversion and the
+    rounding call multiply by one value (`stdlib.md` 20.7) and cannot part by an
+    ulp at the one count where a floating point power does.
+
+    Where the scaling leaves binary64 altogether there is nothing left to round:
+    a binary64 that large is a whole number already and a decimal place that far
+    from its leading digit is past every digit it carries, so the digits are the
+    unscaled value's and the point is moved instead.
+    """
+    scaled = round_half_away(x * scale_of(decimals))
+    usable = math.isfinite(scaled)
+    negative = scaled < 0 if usable else x < 0
+    sign = "-" if negative else ""
+    if usable:
+        digits, point = spread(canonical_number(abs(scaled)))
+    else:
+        digits, point = spread(canonical_number(abs(x)), decimals)
+    written = _written(digits, point).rjust(decimals + 1, "0")
+    if decimals == 0:
+        return sign + written
+    cut = len(written) - decimals
+    return sign + written[:cut] + "." + written[cut:]
+
+
+def fixed_length(x: float, decimals: int) -> int:
+    """How long ``text(x, decimals)`` will be, before a character is built.
+
+    A floor rather than the exact count: a carry off the front adds one digit and
+    a negative adds the sign, and both are caught by the ceiling the built string
+    is checked against. What this is for is the decimal count a script computed,
+    which can ask for a string no engine can hold, and building it to find that
+    out is how an engine runs out of memory instead of reporting that it would
+    have. The ceiling itself is the interpreter's: nothing in this package raises.
+    """
+    _, point = spread(canonical_number(abs(x)))
+    return max(1, point) + decimals + (1 if decimals > 0 else 0)
+
+
+def text_of(x: Value, decimals: Value) -> Value:
+    """``text(x, decimals)`` as the library entry calls it."""
+    value = number(x)
+    count = whole(decimals)
+    if value is None or count is None:
+        return ABSENT
+    return fixed(value, count)
+
+
+def text_length(x: Value, decimals: Value) -> int | None:
+    """``text(x, decimals)``'s length, as the interpreter asks for it.
+
+    Absence for arguments the call itself answers absence for, because a call
+    that builds no string cannot pass a ceiling on strings.
+    """
+    value = number(x)
+    count = whole(decimals)
+    if value is None or count is None:
+        return None
+    return fixed_length(value, count)
+
+
+_DIGITS = "0123456789"
+
+
+def to_number(text: Value) -> Value:
+    """``toNumber(s)``: a string to a number, absent for what does not parse.
+
+    The grammar is walked here rather than handed to the host's own reader, which
+    accepts an infinity, a not-a-number and digit group separators, and which of
+    those a host accepts differs between hosts and moves between their releases.
+    Absence rather than zero for text that is not a number, so a
+    script can tell text that is not a number apart from the number zero. Only
+    these ten digits count: the host's own digit test accepts the decimal digits
+    of every script Unicode has, which would read a number no writer of the
+    script could have typed and no second engine would agree with.
+
+    The whitespace ignored at either end is ``str.trim``'s set and no other.
+    """
+    if not isinstance(text, str):
+        return ABSENT
+    bare = trimmed(text)
+    at = 0
+    end = len(bare)
+    if at < end and bare[at] in "+-":
+        at += 1
+    before = 0
+    while at < end and bare[at] in _DIGITS:
+        at += 1
+        before += 1
+    after = 0
+    if at < end and bare[at] == ".":
+        at += 1
+        while at < end and bare[at] in _DIGITS:
+            at += 1
+            after += 1
+    if before == 0 and after == 0:
+        return ABSENT
+    if at < end and bare[at] in "eE":
+        at += 1
+        if at < end and bare[at] in "+-":
+            at += 1
+        power = 0
+        while at < end and bare[at] in _DIGITS:
+            at += 1
+            power += 1
+        if power == 0:
+            return ABSENT
+    if at != end:
+        return ABSENT
+    return result(float(bare))
+
+
+def spell(value: Value, of_reference=None) -> str:
+    """A value as ``text(x)`` spells it.
+
+    Absence is the word ``none``, a bool is its own word, a string is itself, and
+    a number is the rule at the top of this file. A colour is the ``#rrggbbaa``
+    spelling the conformance suite compares, where the alpha byte is
+    ``round(alpha * 255)`` with the language's own rounding: that conversion is
+    one way and is not a round trip, and nothing in the language observes the
+    difference, because a script reads an alpha with ``alpha()`` from the machine
+    value and never from the wire form.
+
+    A reference is the interpreter's: the heap and the object in it are not this
+    package's, so ``of_reference`` is asked for the kind of one and the word
+    ``none`` stands where no interpreter answered.
+    """
+    if value is None:
+        return "none"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if is_number(value):
+        return canonical_number(float(value))
+    if isinstance(value, str):
+        return value
+    if isinstance(value, Colour):
+        alpha = round_half_away(value.a * 255)
+        return "#" + hex_byte(value.r) + hex_byte(value.g) + hex_byte(value.b) + hex_byte(alpha)
+    if of_reference is None:
+        return "none"
+    return of_reference(value)

openscript/library/prices.py

@@ -0,0 +1,36 @@
+"""The two derived prices the stateful half forms for itself, from facts it read.
+
+A study that calls ``hlc3`` is handed the bar register `compiled-program.md`
+section 2.10 defines, and never reaches this file. What reaches this file is the
+library's own readings: ``cci`` and ``mfi`` are written against the typical
+price, and ``eom``, ``awesomeOsc`` and the trailing band against the midpoint,
+and none of those takes a source argument, so the value has to be formed from the
+three bar facts the call read.
+
+**The order of operations is section 2.10's and is part of the contract**, which
+is why these are two named functions rather than an expression written out at
+five call sites: a different association gives a different last bit, and a study
+that matched a reference implementation on one engine and not on another is
+exactly the failure this project exists to prevent.
+"""
+
+from .values import ABSENT, Value, number, result
+
+
+def midpoint(ctx) -> Value:
+    """``(high + low) / 2``, the bar's midpoint."""
+    high = number(ctx.bar("high"))
+    low = number(ctx.bar("low"))
+    if high is None or low is None:
+        return ABSENT
+    return result((high + low) / 2)
+
+
+def typical(ctx) -> Value:
+    """``(high + low + close) / 3``: high to low, close to that, then the division."""
+    high = number(ctx.bar("high"))
+    low = number(ctx.bar("low"))
+    close = number(ctx.bar("close"))
+    if high is None or low is None or close is None:
+        return ABSENT
+    return result((high + low + close) / 3)