morphir-python 0.0.1__py3-none-any.whl

morphir/sdk/maybe.py

@@ -0,0 +1,135 @@
+"""Morphir.SDK.Maybe: a value that may or may not exist.
+
+`Maybe[A]` is the union of two frozen dataclasses, `Just[A]` and `Nothing`. Use
+structural pattern matching to take a `Maybe` apart:
+
+    >>> from morphir.sdk.maybe import Just, Maybe, Nothing
+    >>> def describe(m: Maybe[int]) -> str:
+    ...     match m:
+    ...         case Just(value):
+    ...             return f"just {value}"
+    ...         case Nothing():
+    ...             return "nothing"
+    >>> describe(Just(1))
+    'just 1'
+
+All functions take their arguments in Elm order, with the `Maybe` last.
+"""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+__all__ = [
+    "Just",
+    "Maybe",
+    "Nothing",
+    "and_then",
+    "has_value",
+    "map",
+    "map2",
+    "map3",
+    "map4",
+    "map5",
+    "with_default",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class Just[A]:
+    """A `Maybe` that holds a value."""
+
+    value: A
+
+
+@dataclass(frozen=True, slots=True)
+class Nothing:
+    """A `Maybe` that holds no value. All instances are equal."""
+
+
+type Maybe[A] = Just[A] | Nothing
+"""Either `Just[A]` or `Nothing`."""
+
+
+def with_default[A](default: A, maybe: Maybe[A]) -> A:
+    """Return the value of a `Just`, or the default for `Nothing`."""
+    match maybe:
+        case Just(value):
+            return value
+        case Nothing():
+            return default
+
+
+def has_value[A](maybe: Maybe[A]) -> bool:
+    """Check that a `Maybe` is a `Just`. This is a Morphir addition to elm/core."""
+    return isinstance(maybe, Just)
+
+
+def map[A, B](f: Callable[[A], B], maybe: Maybe[A]) -> Maybe[B]:
+    """Apply a function to the value of a `Just`."""
+    if isinstance(maybe, Just):
+        return Just(f(maybe.value))
+    return Nothing()
+
+
+def map2[A, B, R](f: Callable[[A, B], R], ma: Maybe[A], mb: Maybe[B]) -> Maybe[R]:
+    """Apply a function when both arguments are `Just`."""
+    if isinstance(ma, Just) and isinstance(mb, Just):
+        return Just(f(ma.value, mb.value))
+    return Nothing()
+
+
+def map3[A, B, C, R](
+    f: Callable[[A, B, C], R], ma: Maybe[A], mb: Maybe[B], mc: Maybe[C]
+) -> Maybe[R]:
+    """Apply a function when all three arguments are `Just`."""
+    if isinstance(ma, Just) and isinstance(mb, Just) and isinstance(mc, Just):
+        return Just(f(ma.value, mb.value, mc.value))
+    return Nothing()
+
+
+def map4[A, B, C, D, R](
+    f: Callable[[A, B, C, D], R],
+    ma: Maybe[A],
+    mb: Maybe[B],
+    mc: Maybe[C],
+    md: Maybe[D],
+) -> Maybe[R]:
+    """Apply a function when all four arguments are `Just`."""
+    if (
+        isinstance(ma, Just)
+        and isinstance(mb, Just)
+        and isinstance(mc, Just)
+        and isinstance(md, Just)
+    ):
+        return Just(f(ma.value, mb.value, mc.value, md.value))
+    return Nothing()
+
+
+def map5[A, B, C, D, E, R](
+    f: Callable[[A, B, C, D, E], R],
+    ma: Maybe[A],
+    mb: Maybe[B],
+    mc: Maybe[C],
+    md: Maybe[D],
+    me: Maybe[E],
+) -> Maybe[R]:
+    """Apply a function when all five arguments are `Just`."""
+    if (
+        isinstance(ma, Just)
+        and isinstance(mb, Just)
+        and isinstance(mc, Just)
+        and isinstance(md, Just)
+        and isinstance(me, Just)
+    ):
+        return Just(f(ma.value, mb.value, mc.value, md.value, me.value))
+    return Nothing()
+
+
+def and_then[A, B](f: Callable[[A], Maybe[B]], maybe: Maybe[A]) -> Maybe[B]:
+    """Chain a computation that can fail onto a `Maybe`."""
+    if isinstance(maybe, Just):
+        return f(maybe.value)
+    return Nothing()

morphir/sdk/number.py

@@ -0,0 +1,237 @@
+"""Morphir.SDK.Number: exact rational numbers.
+
+A `Number` is a frozen dataclass with an integer `numerator` and `denominator`.
+Python integers have no size limit, so all arithmetic is exact.
+
+As in the Elm runtime, arithmetic does not reduce its result:
+`add(1/2, 1/2)` is `4/4`. Use `simplify` to reduce a number. Because of this,
+`==` on two `Number` values is structural (`Number(1, 2) != Number(2, 4)`); use
+`equal` to compare by value.
+
+The name `abs` in this module shadows a Python built-in. Import the module with
+an alias, not the names:
+
+    >>> from morphir.sdk import number as Number
+    >>> Number.to_fractional_string(Number.add(Number.from_int(1), Number.one))
+    '2/1'
+
+Departures from the Elm runtime:
+
+* Comparisons move a negative sign out of the denominator before they
+  cross-multiply. The Elm runtime does not, so it orders `3/-4` and `1/2`
+  wrongly.
+* `simplify` yields a positive denominator: `3/-6` becomes `-1/2`. The Elm
+  runtime yields `1/-2`.
+"""
+
+import builtins
+import math
+from dataclasses import dataclass
+
+from morphir.sdk import decimal as _sdk_decimal
+from morphir.sdk import maybe
+from morphir.sdk.maybe import Just, Maybe, Nothing
+from morphir.sdk.result import Err, Ok, Result
+
+__all__ = [
+    "DivisionByZero",
+    "Number",
+    "abs",
+    "add",
+    "coerce_to_decimal",
+    "divide",
+    "equal",
+    "from_int",
+    "greater_than",
+    "greater_than_or_equal",
+    "is_simplified",
+    "less_than",
+    "less_than_or_equal",
+    "multiply",
+    "negate",
+    "not_equal",
+    "one",
+    "reciprocal",
+    "simplify",
+    "subtract",
+    "to_decimal",
+    "to_fractional_string",
+    "zero",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class Number:
+    """A rational number. The fraction is not reduced."""
+
+    numerator: int
+    denominator: int
+
+
+@dataclass(frozen=True, slots=True)
+class DivisionByZero:
+    """The error that `divide` yields for a zero divisor."""
+
+
+zero: Number = Number(0, 1)
+"""The number 0, as 0/1."""
+
+one: Number = Number(1, 1)
+"""The number 1, as 1/1."""
+
+
+def from_int(n: int) -> Number:
+    """Convert an integer to a `Number` with a denominator of 1."""
+    return Number(n, 1)
+
+
+# Convert to
+
+
+def to_decimal(n: Number) -> Maybe[_sdk_decimal.Decimal]:
+    """Convert to a `Decimal`, or `Nothing` when the denominator is zero.
+
+    A quotient that is not exact has 50 significant digits.
+    """
+    return _sdk_decimal.div(
+        _sdk_decimal.from_int(n.numerator), _sdk_decimal.from_int(n.denominator)
+    )
+
+
+def coerce_to_decimal(default: _sdk_decimal.Decimal, n: Number) -> _sdk_decimal.Decimal:
+    """Convert to a `Decimal`, or yield the default when the denominator is zero."""
+    return maybe.with_default(default, to_decimal(n))
+
+
+def to_fractional_string(n: Number) -> str:
+    """Convert to a string of the form "numerator/denominator"."""
+    return f"{n.numerator}/{n.denominator}"
+
+
+# Comparison
+
+
+def _cross_products(a: Number, b: Number) -> tuple[int, int]:
+    """Return the two integers whose order is the order of `a` and `b`.
+
+    A negative denominator changes the direction of the comparison, so the sign
+    moves to the numerator first.
+    """
+    sign = (-1 if a.denominator < 0 else 1) * (-1 if b.denominator < 0 else 1)
+    return (
+        sign * a.numerator * b.denominator,
+        sign * b.numerator * a.denominator,
+    )
+
+
+def equal(a: Number, b: Number) -> bool:
+    """Check `a == b` by value, so 1/2 equals 2/4."""
+    x, y = _cross_products(a, b)
+    return x == y
+
+
+def not_equal(a: Number, b: Number) -> bool:
+    """Check `a /= b` by value."""
+    return not equal(a, b)
+
+
+def less_than(a: Number, b: Number) -> bool:
+    """Check `a < b`."""
+    x, y = _cross_products(a, b)
+    return x < y
+
+
+def less_than_or_equal(a: Number, b: Number) -> bool:
+    """Check `a <= b`."""
+    x, y = _cross_products(a, b)
+    return x <= y
+
+
+def greater_than(a: Number, b: Number) -> bool:
+    """Check `a > b`."""
+    x, y = _cross_products(a, b)
+    return x > y
+
+
+def greater_than_or_equal(a: Number, b: Number) -> bool:
+    """Check `a >= b`."""
+    x, y = _cross_products(a, b)
+    return x >= y
+
+
+# Arithmetic
+
+
+def _is_zero(n: Number) -> bool:
+    return n.numerator == 0
+
+
+def negate(n: Number) -> Number:
+    """Change the sign of a number."""
+    return Number(-n.numerator, n.denominator)
+
+
+def abs(n: Number) -> Number:
+    """Return the absolute value of a number."""
+    return Number(builtins.abs(n.numerator), builtins.abs(n.denominator))
+
+
+def reciprocal(n: Number) -> Number:
+    """Swap the numerator and the denominator. Zero stays as it is, as in Elm."""
+    return n if _is_zero(n) else Number(n.denominator, n.numerator)
+
+
+def add(a: Number, b: Number) -> Number:
+    """Add two numbers. The result is not reduced."""
+    return Number(
+        a.numerator * b.denominator + a.denominator * b.numerator,
+        a.denominator * b.denominator,
+    )
+
+
+def subtract(a: Number, b: Number) -> Number:
+    """Subtract the second number from the first. The result is not reduced."""
+    return Number(
+        a.numerator * b.denominator - a.denominator * b.numerator,
+        a.denominator * b.denominator,
+    )
+
+
+def multiply(a: Number, b: Number) -> Number:
+    """Multiply two numbers. The result is not reduced."""
+    return Number(a.numerator * b.numerator, a.denominator * b.denominator)
+
+
+def divide(a: Number, b: Number) -> Result[DivisionByZero, Number]:
+    """Divide two numbers, or yield `Err(DivisionByZero())` for a zero divisor.
+
+    The result is not reduced.
+    """
+    if _is_zero(b):
+        return Err(DivisionByZero())
+    return Ok(Number(a.numerator * b.denominator, a.denominator * b.numerator))
+
+
+# Simplify
+
+
+def simplify(n: Number) -> Maybe[Number]:
+    """Reduce a number to lowest terms, with a positive denominator.
+
+    Yields `Nothing` when the denominator is zero.
+    """
+    if n.denominator == 0:
+        return Nothing()
+    factor = math.gcd(n.numerator, n.denominator)
+    if n.denominator < 0:
+        factor = -factor
+    return Just(Number(n.numerator // factor, n.denominator // factor))
+
+
+def is_simplified(n: Number) -> bool:
+    """Check that `simplify` does not change a number.
+
+    A number with a zero denominator counts as simplified, as in the Elm
+    runtime.
+    """
+    return maybe.with_default(n, simplify(n)) == n

morphir/sdk/regex.py

@@ -0,0 +1,287 @@
+r"""Morphir.SDK.Regex: regular expressions.
+
+The reference is the API of elm/regex 1.0.0. A `Regex` holds a compiled pattern
+of the standard library `re` module. Lists are tuples, as in `morphir.sdk.list`.
+
+    >>> from morphir.sdk import regex as Regex
+    >>> from morphir.sdk import maybe as Maybe
+    >>> comma = Maybe.with_default(Regex.never, Regex.from_string(" *, *"))
+    >>> Regex.split(comma, "tom , 99, 90")
+    ('tom', '99', '90')
+    >>> Regex.replace(comma, lambda match: ";", "tom , 99, 90")
+    'tom;99;90'
+
+Departures from elm/regex:
+
+* **Pattern syntax.** elm/regex compiles a pattern with the JavaScript `RegExp`
+  (with no `u` flag). This module compiles it with Python `re`. Most patterns
+  mean the same in the two, but not all. The known differences are:
+
+  * A named group is `(?P<name>...)` and a reference to it is `(?P=name)`. The
+    JavaScript forms `(?<name>...)` and `\k<name>` are not valid.
+  * `\d`, `\w`, `\s` and `\b` use the Unicode character properties. In
+    JavaScript `\d` and `\w` match ASCII characters only. Write `[0-9]` for the
+    ASCII digits.
+  * `case_insensitive` uses the Unicode case rules.
+  * `$` with no `multiline` option also matches before a line feed at the end
+    of the text. Use `\Z` for the end of the text only.
+  * Python rejects an escape of an ASCII letter that it does not know, such as
+    the JavaScript control escape `\cJ`. The JavaScript classes `[^]` and `[]`
+    are not valid.
+  * A lookbehind must have a fixed width.
+  * A pattern that JavaScript accepts can therefore give `Nothing` here, and the
+    reverse is also possible.
+
+* **Index.** `Match.index` counts Unicode code points, as all string functions
+  in this SDK do. In Elm it counts UTF-16 code units.
+* **Empty matches in `split`.** In Elm, `split` does not stop when the pattern
+  matches the empty string. Here the search continues after an empty match one
+  character later, as `re.finditer` does: `split` with the pattern `""` gives
+  the characters with an empty string at the two ends.
+* **A negative count.** `split_at_most` with a negative count does no split. In
+  Elm a negative count means no limit.
+
+Behaviour of elm/regex that this module keeps:
+
+* A group that matched the empty string is `Nothing` in `Match.submatches`, the
+  same as a group that did not take part in the match.
+* `find` and `find_at_most` stop at an empty match that ends where the search
+  for it started: `find` with `a*` on `"baaa"` gives one empty match.
+* `replace` replaces empty matches in the same way as JavaScript and Python.
+"""
+
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from morphir.sdk.maybe import Just, Maybe, Nothing
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+__all__ = [
+    "Match",
+    "Options",
+    "Regex",
+    "contains",
+    "find",
+    "find_at_most",
+    "from_string",
+    "from_string_with",
+    "never",
+    "replace",
+    "replace_at_most",
+    "split",
+    "split_at_most",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class Regex:
+    """A compiled regular expression.
+
+    Make one with `from_string` or `from_string_with`. Two values are equal when
+    they have the same pattern text and the same options.
+    """
+
+    pattern: re.Pattern[str]
+
+
+@dataclass(frozen=True, slots=True)
+class Options:
+    """The options of `from_string_with`."""
+
+    case_insensitive: bool
+    """Ignore the case of letters."""
+
+    multiline: bool
+    """Let `^` and `$` match at the start and the end of each line."""
+
+
+@dataclass(frozen=True, slots=True)
+class Match:
+    """The data of one match."""
+
+    match: str
+    """The text that matched."""
+
+    index: int
+    """The position of the match in the text, in code points from 0."""
+
+    number: int
+    """The number of the match: 1 for the first match, 2 for the second."""
+
+    submatches: tuple[Maybe[str], ...]
+    """The text of each group in the pattern.
+
+    A group that took no part in the match, or that matched the empty string, is
+    `Nothing`.
+    """
+
+
+def from_string_with(options: Options, string: str) -> Maybe[Regex]:
+    """Compile a pattern with options.
+
+    Args:
+        options: The options.
+        string: The pattern, in the syntax of the Python `re` module.
+
+    Returns:
+        `Just` the regular expression, or `Nothing` when the pattern is not
+        valid.
+    """
+    flags = re.NOFLAG
+    if options.case_insensitive:
+        flags |= re.IGNORECASE
+    if options.multiline:
+        flags |= re.MULTILINE
+    try:
+        return Just(Regex(re.compile(string, flags)))
+    except (re.PatternError, OverflowError, RecursionError):
+        return Nothing()
+
+
+def from_string(string: str) -> Maybe[Regex]:
+    """Compile a pattern that is case sensitive and not multiline.
+
+    Args:
+        string: The pattern, in the syntax of the Python `re` module.
+
+    Returns:
+        `Just` the regular expression, or `Nothing` when the pattern is not
+        valid.
+    """
+    return from_string_with(Options(case_insensitive=False, multiline=False), string)
+
+
+never: Regex = Regex(re.compile(r".^"))
+"""A regular expression that never matches."""
+
+
+def contains(regex: Regex, string: str) -> bool:
+    """Check that a regular expression matches somewhere in a string."""
+    return regex.pattern.search(string) is not None
+
+
+def _to_match(found: re.Match[str], number: int) -> Match:
+    return Match(
+        match=found.group(0),
+        index=found.start(),
+        number=number,
+        submatches=tuple(
+            Just(group) if group else Nothing() for group in found.groups()
+        ),
+    )
+
+
+def split_at_most(number: int, regex: Regex, string: str) -> tuple[str, ...]:
+    """Split a string at the first matches of a regular expression.
+
+    Args:
+        number: The maximum number of splits. Zero or less gives no split.
+        regex: The regular expression that matches the separators.
+        string: The string to split.
+
+    Returns:
+        The parts between the separators. The text of the groups in the pattern
+        is not in the result.
+    """
+    parts: list[str] = []
+    start = 0
+    for count, found in enumerate(regex.pattern.finditer(string)):
+        if count >= number:
+            break
+        parts.append(string[start : found.start()])
+        start = found.end()
+    parts.append(string[start:])
+    return tuple(parts)
+
+
+def split(regex: Regex, string: str) -> tuple[str, ...]:
+    """Split a string at all matches of a regular expression.
+
+    Args:
+        regex: The regular expression that matches the separators.
+        string: The string to split.
+
+    Returns:
+        The parts between the separators.
+    """
+    return split_at_most(len(string) + 1, regex, string)
+
+
+def find_at_most(number: int, regex: Regex, string: str) -> tuple[Match, ...]:
+    """Find the first matches of a regular expression in a string.
+
+    Args:
+        number: The maximum number of matches.
+        regex: The regular expression.
+        string: The string to search.
+
+    Returns:
+        The matches, in the sequence in which they occur.
+    """
+    matches: list[Match] = []
+    position = 0
+    previous_end = -1
+    while len(matches) < number:
+        found = regex.pattern.search(string, position)
+        if found is None or found.end() == previous_end:
+            break
+        matches.append(_to_match(found, len(matches) + 1))
+        previous_end = position = found.end()
+    return tuple(matches)
+
+
+def find(regex: Regex, string: str) -> tuple[Match, ...]:
+    """Find all matches of a regular expression in a string.
+
+    Args:
+        regex: The regular expression.
+        string: The string to search.
+
+    Returns:
+        The matches, in the sequence in which they occur.
+    """
+    return find_at_most(len(string) + 1, regex, string)
+
+
+def replace_at_most(
+    number: int, regex: Regex, with_: Callable[[Match], str], string: str
+) -> str:
+    r"""Replace the first matches of a regular expression in a string.
+
+    Args:
+        number: The maximum number of replacements.
+        regex: The regular expression.
+        with_: A function that gives the replacement text for a match. The text
+            is used as it is: `\1` and `$1` have no special meaning.
+        string: The string to change.
+
+    Returns:
+        The string with the replacements.
+    """
+    if number <= 0:
+        return string
+    count = 0
+
+    def replacement(found: re.Match[str]) -> str:
+        nonlocal count
+        count += 1
+        return with_(_to_match(found, count))
+
+    return regex.pattern.sub(replacement, string, count=number)
+
+
+def replace(regex: Regex, with_: Callable[[Match], str], string: str) -> str:
+    """Replace all matches of a regular expression in a string.
+
+    Args:
+        regex: The regular expression.
+        with_: A function that gives the replacement text for a match.
+        string: The string to change.
+
+    Returns:
+        The string with the replacements.
+    """
+    return replace_at_most(len(string) + 1, regex, with_, string)