morphir-python 0.0.1__py3-none-any.whl

morphir/sdk/result.py

@@ -0,0 +1,162 @@
+"""Morphir.SDK.Result: a computation that may fail.
+
+`Result[E, A]` is the union of two frozen dataclasses, `Ok[A]` and `Err[E]`.
+The type parameter order is Elm's: the error type first, then the value type.
+All functions take their arguments in Elm order, with the `Result` last.
+"""
+
+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__ = [
+    "Err",
+    "Ok",
+    "Result",
+    "and_then",
+    "from_maybe",
+    "map",
+    "map2",
+    "map3",
+    "map4",
+    "map5",
+    "map_error",
+    "to_maybe",
+    "with_default",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class Ok[A]:
+    """A `Result` that holds a success value."""
+
+    value: A
+
+
+@dataclass(frozen=True, slots=True)
+class Err[E]:
+    """A `Result` that holds an error."""
+
+    error: E
+
+
+type Result[E, A] = Ok[A] | Err[E]
+"""Either `Ok[A]` or `Err[E]`."""
+
+
+def with_default[E, A](default: A, result: Result[E, A]) -> A:
+    """Return the value of an `Ok`, or the default for an `Err`."""
+    match result:
+        case Ok(value):
+            return value
+        case Err():
+            return default
+
+
+def map[E, A, B](f: Callable[[A], B], result: Result[E, A]) -> Result[E, B]:
+    """Apply a function to the value of an `Ok`."""
+    if isinstance(result, Ok):
+        return Ok(f(result.value))
+    return result
+
+
+def map2[E, A, B, R](
+    f: Callable[[A, B], R], ra: Result[E, A], rb: Result[E, B]
+) -> Result[E, R]:
+    """Apply a function when both arguments are `Ok`; else yield the first `Err`."""
+    if isinstance(ra, Err):
+        return ra
+    if isinstance(rb, Err):
+        return rb
+    return Ok(f(ra.value, rb.value))
+
+
+def map3[E, A, B, C, R](
+    f: Callable[[A, B, C], R],
+    ra: Result[E, A],
+    rb: Result[E, B],
+    rc: Result[E, C],
+) -> Result[E, R]:
+    """Apply a function when all arguments are `Ok`; else yield the first `Err`."""
+    if isinstance(ra, Err):
+        return ra
+    if isinstance(rb, Err):
+        return rb
+    if isinstance(rc, Err):
+        return rc
+    return Ok(f(ra.value, rb.value, rc.value))
+
+
+def map4[E, A, B, C, D, R](
+    f: Callable[[A, B, C, D], R],
+    ra: Result[E, A],
+    rb: Result[E, B],
+    rc: Result[E, C],
+    rd: Result[E, D],
+) -> Result[E, R]:
+    """Apply a function when all arguments are `Ok`; else yield the first `Err`."""
+    if isinstance(ra, Err):
+        return ra
+    if isinstance(rb, Err):
+        return rb
+    if isinstance(rc, Err):
+        return rc
+    if isinstance(rd, Err):
+        return rd
+    return Ok(f(ra.value, rb.value, rc.value, rd.value))
+
+
+def map5[E, A, B, C, D, F, R](
+    f: Callable[[A, B, C, D, F], R],
+    ra: Result[E, A],
+    rb: Result[E, B],
+    rc: Result[E, C],
+    rd: Result[E, D],
+    re: Result[E, F],
+) -> Result[E, R]:
+    """Apply a function when all arguments are `Ok`; else yield the first `Err`."""
+    if isinstance(ra, Err):
+        return ra
+    if isinstance(rb, Err):
+        return rb
+    if isinstance(rc, Err):
+        return rc
+    if isinstance(rd, Err):
+        return rd
+    if isinstance(re, Err):
+        return re
+    return Ok(f(ra.value, rb.value, rc.value, rd.value, re.value))
+
+
+def and_then[E, A, B](
+    f: Callable[[A], Result[E, B]], result: Result[E, A]
+) -> Result[E, B]:
+    """Chain a computation that can fail onto a `Result`."""
+    if isinstance(result, Ok):
+        return f(result.value)
+    return result
+
+
+def map_error[E, F, A](f: Callable[[E], F], result: Result[E, A]) -> Result[F, A]:
+    """Apply a function to the error of an `Err`."""
+    if isinstance(result, Err):
+        return Err(f(result.error))
+    return result
+
+
+def to_maybe[E, A](result: Result[E, A]) -> Maybe[A]:
+    """Convert to a `Maybe`, which drops the error."""
+    if isinstance(result, Ok):
+        return Just(result.value)
+    return Nothing()
+
+
+def from_maybe[E, A](error: E, maybe: Maybe[A]) -> Result[E, A]:
+    """Convert from a `Maybe`, with the given error for `Nothing`."""
+    if isinstance(maybe, Just):
+        return Ok(maybe.value)
+    return Err(error)

morphir/sdk/result_list.py

@@ -0,0 +1,169 @@
+"""Morphir.SDK.ResultList: operations on lists of results.
+
+A `ResultList[E, A]` is a tuple of `Result[E, A]` values: a list that holds a
+mix of failed and successful records. These operations model a processing
+pipeline where an error can occur at any step, but must not stop the pipeline.
+A record that failed at an earlier step stays in the list as it is, and each
+step works on the successful records only.
+
+All functions take their arguments in Elm order, with the result list last.
+They accept any `Sequence` and always yield a tuple.
+
+`filter` and `map` shadow Python built-ins. Import the module with an alias,
+not the names:
+
+    >>> from morphir.sdk import result_list as ResultList
+    >>> from morphir.sdk.result import Err, Ok
+    >>> ResultList.keep_all_errors((Ok(1), Err("foo"), Ok(3), Err("bar")))
+    Err(error=('foo', 'bar'))
+"""
+
+from typing import TYPE_CHECKING
+
+from morphir.sdk.result import Err, Ok, Result
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+
+__all__ = [
+    "ResultList",
+    "errors",
+    "filter",
+    "filter_or_fail",
+    "from_list",
+    "keep_all_errors",
+    "keep_first_error",
+    "map",
+    "map_or_fail",
+    "partition",
+    "successes",
+]
+
+type ResultList[E, A] = tuple[Result[E, A], ...]
+"""A list that holds a mix of failed (`Err`) and successful (`Ok`) records."""
+
+
+# Create
+
+
+def from_list[E, A](xs: Sequence[A]) -> ResultList[E, A]:  # pyright: ignore[reportInvalidTypeVarUse]
+    """Create a result list from a list. Every element becomes an `Ok`."""
+    return tuple(Ok(x) for x in xs)
+
+
+# Process
+
+
+def filter[E, A](
+    f: Callable[[A], bool], result_list: Sequence[Result[E, A]]
+) -> ResultList[E, A]:
+    """Keep the successful records that pass the test, and all failed records."""
+    return tuple(
+        result for result in result_list if isinstance(result, Err) or f(result.value)
+    )
+
+
+def filter_or_fail[E, A](
+    f: Callable[[A], Result[E, bool]], result_list: Sequence[Result[E, A]]
+) -> ResultList[E, A]:
+    """Filter with a test that can fail.
+
+    A successful record stays when the test yields `Ok(True)` and goes when the
+    test yields `Ok(False)`. When the test yields an `Err`, that error replaces
+    the record. All records that failed before stay.
+
+    Args:
+        f: The test.
+        result_list: The result list.
+
+    Returns:
+        The filtered result list.
+    """
+    kept: list[Result[E, A]] = []
+    for result in result_list:
+        if isinstance(result, Err):
+            kept.append(result)
+            continue
+        match f(result.value):
+            case Ok(passed):
+                if passed:
+                    kept.append(result)
+            case Err() as failure:
+                kept.append(failure)
+    return tuple(kept)
+
+
+def map[E, A, B](
+    f: Callable[[A], B], result_list: Sequence[Result[E, A]]
+) -> ResultList[E, B]:
+    """Apply a function to every successful record. Failed records stay."""
+    return tuple(
+        Ok(f(result.value)) if isinstance(result, Ok) else result
+        for result in result_list
+    )
+
+
+def map_or_fail[E, A, B](
+    f: Callable[[A], Result[E, B]], result_list: Sequence[Result[E, A]]
+) -> ResultList[E, B]:
+    """Apply a function that can fail to every successful record.
+
+    An `Err` from the function replaces the record. All records that failed
+    before stay.
+    """
+    return tuple(
+        f(result.value) if isinstance(result, Ok) else result for result in result_list
+    )
+
+
+# Decompose
+
+
+def errors[E, A](result_list: Sequence[Result[E, A]]) -> tuple[E, ...]:
+    """Extract the errors of all failed records."""
+    return tuple(result.error for result in result_list if isinstance(result, Err))
+
+
+def successes[E, A](result_list: Sequence[Result[E, A]]) -> tuple[A, ...]:
+    """Extract the values of all successful records."""
+    return tuple(result.value for result in result_list if isinstance(result, Ok))
+
+
+def partition[E, A](
+    result_list: Sequence[Result[E, A]],
+) -> tuple[tuple[E, ...], tuple[A, ...]]:
+    """Divide a result list into its errors and its successful values."""
+    return (errors(result_list), successes(result_list))
+
+
+# Map to a single result
+
+
+def keep_all_errors[E, A](
+    result_list: Sequence[Result[E, A]],
+) -> Result[tuple[E, ...], tuple[A, ...]]:
+    """Turn a result list into a single result that keeps all errors.
+
+    Returns:
+        `Ok` with all values when no record failed (also for an empty list),
+        else `Err` with all errors in list order.
+    """
+    errs = errors(result_list)
+    if errs:
+        return Err(errs)
+    return Ok(successes(result_list))
+
+
+def keep_first_error[E, A](
+    result_list: Sequence[Result[E, A]],
+) -> Result[E, tuple[A, ...]]:
+    """Turn a result list into a single result that keeps only the first error.
+
+    Returns:
+        `Ok` with all values when no record failed (also for an empty list),
+        else `Err` with the error of the first failed record.
+    """
+    errs = errors(result_list)
+    if errs:
+        return Err(errs[0])
+    return Ok(successes(result_list))

morphir/sdk/rule.py

@@ -0,0 +1,103 @@
+"""Morphir.SDK.Rule: business logic as a sequence of rules.
+
+A `Rule[A, B]` is a partial function: a function from `A` to `Maybe[B]` that
+yields `Just` a result when it applies to the input, and `Nothing` when it does
+not. `chain` composes rules into one rule that tries them in sequence. Morphir
+supports only sequential evaluation, so the result is always predictable.
+
+`any`, `is_`, `any_of` and `none_of` are the matchers for the cells of a
+decision table:
+
+    >>> from morphir.sdk import rule as Rule
+    >>> from morphir.sdk.maybe import Just, Maybe, Nothing
+    >>> def discount(order: tuple[str, int]) -> Maybe[float]:
+    ...     kind, quantity = order
+    ...     if Rule.is_("gold", kind) and Rule.any(quantity):
+    ...         return Just(0.2)
+    ...     if Rule.any_of(("silver", "bronze"), kind) and Rule.none_of((0,), quantity):
+    ...         return Just(0.1)
+    ...     return Nothing()
+    >>> Rule.chain((discount, lambda order: Just(0.0)))(("bronze", 3))
+    Just(value=0.1)
+
+`any` shadows the Python built-in, and `is` is a Python keyword, so it is `is_`.
+Import the module with an alias, not the names.
+"""
+
+from typing import TYPE_CHECKING
+
+from morphir.sdk import _compare
+from morphir.sdk.maybe import Just, Maybe, Nothing
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+
+__all__ = [
+    "Rule",
+    "any",
+    "any_of",
+    "chain",
+    "is_",
+    "none_of",
+]
+
+type Rule[A, B] = Callable[[A], Maybe[B]]
+"""A function that yields `Just` a result when it applies, else `Nothing`."""
+
+
+def chain[A, B](rules: Sequence[Rule[A, B]]) -> Rule[A, B]:
+    """Chain a list of rules into a single rule.
+
+    The rules are evaluated in the sequence in which they were supplied. The
+    first rule that yields a `Just` gives the result, and the rules after it do
+    not run.
+
+    Args:
+        rules: The rules, in the sequence of evaluation.
+
+    Returns:
+        A rule that yields the result of the first rule that matches, or
+        `Nothing` when no rule matches.
+    """
+    fixed = tuple(rules)
+
+    def chained(value: A) -> Maybe[B]:
+        for rule in fixed:
+            result = rule(value)
+            if isinstance(result, Just):
+                return result
+        return Nothing()
+
+    return chained
+
+
+def any(value: object) -> bool:
+    """Return `True` for any input. Use as a wildcard in a decision table."""
+    return True
+
+
+def is_[A](ref: A, value: A) -> bool:
+    """Check that the value is structurally equal to the reference (Elm `is`).
+
+    Raises:
+        TypeError: If a value is a function or holds a function.
+    """
+    return _compare.equal(ref, value)
+
+
+def any_of[A](ref: Sequence[A], value: A) -> bool:
+    """Check that the value is in the list of references, by structural equality.
+
+    Raises:
+        TypeError: If a value is a function or holds a function.
+    """
+    return next((True for item in ref if _compare.equal(value, item)), False)
+
+
+def none_of[A](ref: Sequence[A], value: A) -> bool:
+    """Check that the value is not in the list of references.
+
+    Raises:
+        TypeError: If a value is a function or holds a function.
+    """
+    return not any_of(ref, value)

morphir/sdk/set.py

@@ -0,0 +1,214 @@
+"""Morphir.SDK.Set: a collection of unique comparable values.
+
+This module follows elm/core 1.0.5. A `Set[A]` is a frozen dataclass that holds
+its members as a tuple, sorted in ascending order by `basics.compare`, with no
+member twice. Thus `to_list` yields the members in order, and two sets with the
+same members are equal (`==`) and have the same hash, no matter in which order
+the members were inserted.
+
+Members can be any comparable value: numbers, strings, and tuples or lists of
+comparables. A member that is not comparable raises `TypeError`.
+
+Build a `Set` with `empty`, `singleton`, `from_list` and `insert`. Do not pass
+members to the `Set` constructor, because it does not sort them.
+
+Some names in this module shadow Python built-ins (`filter`, `map`). Import the
+module with an alias, not the names:
+
+    >>> from morphir.sdk import set as Set
+    >>> Set.to_list(Set.from_list((3, 1, 3, 2)))
+    (1, 2, 3)
+"""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from morphir.sdk import _compare
+from morphir.sdk._compare import Comparable, Order
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Sequence
+
+__all__ = [
+    "Set",
+    "diff",
+    "empty",
+    "filter",
+    "foldl",
+    "foldr",
+    "from_list",
+    "insert",
+    "intersect",
+    "is_empty",
+    "map",
+    "member",
+    "partition",
+    "remove",
+    "singleton",
+    "size",
+    "to_list",
+    "union",
+]
+
+
+@dataclass(frozen=True, slots=True)
+class Set[A: Comparable]:
+    """An immutable set with its members sorted.
+
+    Use `from_list`, `singleton` or `insert` to build one. The constructor
+    accepts only members that are already sorted with no member twice, and
+    stores every list inside a member as a tuple.
+
+    Raises:
+        ValueError: If the members are not sorted, or a member repeats.
+        TypeError: If two members are not comparable with each other.
+    """
+
+    entries: tuple[A, ...] = ()
+
+    def __post_init__(self) -> None:
+        entries = tuple(_compare.freeze(member) for member in self.entries)
+        _compare.check_strictly_ascending(entries, "Set")
+        object.__setattr__(self, "entries", entries)
+
+
+def _identity[A](value: A) -> A:
+    return value
+
+
+def _search[A: Comparable](value: A, set_: Set[A]) -> tuple[bool, int]:
+    return _compare.search(value, set_.entries, _identity)
+
+
+# Build
+
+
+def empty[A: Comparable]() -> Set[A]:  # pyright: ignore[reportInvalidTypeVarUse]
+    """Create an empty set."""
+    return Set()
+
+
+def singleton[A: Comparable](value: A) -> Set[A]:
+    """Create a set with one member."""
+    return Set((value,))
+
+
+def insert[A: Comparable](value: A, set_: Set[A]) -> Set[A]:
+    """Insert a value into a set.
+
+    Raises:
+        TypeError: If the value is not comparable with the members of the set.
+    """
+    found, index = _search(value, set_)
+    if found:
+        return set_
+    return Set((*set_.entries[:index], value, *set_.entries[index:]))
+
+
+def remove[A: Comparable](value: A, set_: Set[A]) -> Set[A]:
+    """Remove a value from a set. A value that is not there changes nothing."""
+    found, index = _search(value, set_)
+    if not found:
+        return set_
+    return Set((*set_.entries[:index], *set_.entries[index + 1 :]))
+
+
+# Query
+
+
+def is_empty[A: Comparable](set_: Set[A]) -> bool:
+    """Check that a set is empty."""
+    return not set_.entries
+
+
+def member[A: Comparable](value: A, set_: Set[A]) -> bool:
+    """Check that a value is in a set."""
+    return _search(value, set_)[0]
+
+
+def size[A: Comparable](set_: Set[A]) -> int:
+    """Return the number of members in a set."""
+    return len(set_.entries)
+
+
+# Lists
+
+
+def to_list[A: Comparable](set_: Set[A]) -> tuple[A, ...]:
+    """Return the members, from lowest to highest."""
+    return set_.entries
+
+
+def from_list[A: Comparable](values: Sequence[A]) -> Set[A]:
+    """Create a set from a list of values.
+
+    Raises:
+        TypeError: If the values are not comparable with each other.
+    """
+    entries: list[A] = []
+    for value in sorted(values, key=_compare.sort_key(_compare.compare)):
+        if not entries or _compare.compare(entries[-1], value) is not Order.EQ:
+            entries.append(value)
+    return Set(tuple(entries))
+
+
+# Transform
+
+
+def map[A: Comparable, B: Comparable](f: Callable[[A], B], set_: Set[A]) -> Set[B]:
+    """Apply a function to every member.
+
+    The result is sorted again and has no duplicates, so it can be smaller than
+    the input.
+    """
+    return from_list(tuple(f(value) for value in set_.entries))
+
+
+def foldl[A: Comparable, R](f: Callable[[A, R], R], initial: R, set_: Set[A]) -> R:
+    """Reduce the members from lowest to highest."""
+    accumulator = initial
+    for value in set_.entries:
+        accumulator = f(value, accumulator)
+    return accumulator
+
+
+def foldr[A: Comparable, R](f: Callable[[A, R], R], initial: R, set_: Set[A]) -> R:
+    """Reduce the members from highest to lowest."""
+    accumulator = initial
+    for value in reversed(set_.entries):
+        accumulator = f(value, accumulator)
+    return accumulator
+
+
+def filter[A: Comparable](predicate: Callable[[A], bool], set_: Set[A]) -> Set[A]:
+    """Keep the members that pass the test."""
+    return Set(tuple(value for value in set_.entries if predicate(value)))
+
+
+def partition[A: Comparable](
+    predicate: Callable[[A], bool], set_: Set[A]
+) -> tuple[Set[A], Set[A]]:
+    """Split a set into the members that pass the test and those that fail."""
+    passed: list[A] = []
+    failed: list[A] = []
+    for value in set_.entries:
+        (passed if predicate(value) else failed).append(value)
+    return (Set(tuple(passed)), Set(tuple(failed)))
+
+
+# Combine
+
+
+def union[A: Comparable](left: Set[A], right: Set[A]) -> Set[A]:
+    """Return the values that are in one set or the other."""
+    return from_list((*left.entries, *right.entries))
+
+
+def intersect[A: Comparable](left: Set[A], right: Set[A]) -> Set[A]:
+    """Return the values that are in both sets."""
+    return Set(tuple(value for value in left.entries if member(value, right)))
+
+
+def diff[A: Comparable](left: Set[A], right: Set[A]) -> Set[A]:
+    """Return the values of the first set that are not in the second."""
+    return Set(tuple(value for value in left.entries if not member(value, right)))

morphir/sdk/stateful_app.py

@@ -0,0 +1,49 @@
+"""Morphir.SDK.StatefulApp: the model of a stateful application.
+
+A `StatefulApp` holds one function, the business logic. The function gets the
+current state (`Nothing` when there is no state yet) and a command. It yields
+the new state (`Nothing` to delete the state) and an event:
+
+    >>> from morphir.sdk.maybe import Just, Maybe, Nothing
+    >>> from morphir.sdk.stateful_app import StatefulApp
+    >>> def logic(state: Maybe[int], command: str) -> tuple[Maybe[int], str]:
+    ...     total = (state.value if isinstance(state, Just) else 0) + 1
+    ...     return (Just(total), f"{command}: {total}")
+    >>> app: StatefulApp[str, str, int, str] = StatefulApp(logic)
+    >>> app.logic(Nothing(), "open")
+    (Just(value=1), 'open: 1')
+
+The module has a type and no functions, as in Elm.
+"""
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from morphir.sdk.maybe import (
+    Maybe,  # noqa: TC001 - the dataclass field annotation needs it at run time
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+__all__ = ["StatefulApp"]
+
+
+@dataclass(frozen=True, slots=True)
+class StatefulApp[K, C, S, E]:
+    """A stateful application (Elm `StatefulApp (Maybe s -> c -> ( Maybe s, e ))`).
+
+    The type parameters fit the application to a use case:
+
+    * `K`: the key that partitions commands, events and state. No field uses
+      it, as in Elm; it is there for the type checker only.
+    * `C`: the commands that the application accepts.
+    * `S`: the state that the application manages.
+    * `E`: the events that the application publishes.
+
+    Attributes:
+        logic: The business logic. It gets the current state and a command, and
+            yields the new state and an event.
+    """
+
+    logic: Callable[[Maybe[S], C], tuple[Maybe[S], E]]