GitHub

async_result

API reference for async_result.

AsyncResult: the state of a value computed asynchronously (Effect's effect/reactivity/AsyncResult).

An AsyncResult[A, E] is Initial (no value yet), Success (a value and when it arrived) or Failure (a Cause, and the last success if there was one). Each also says whether a newer computation is waiting. Atoms backed by effects and streams hold one.

Two results are equal when their tags, waiting and value (or cause) are: a success's timestamp and a failure's previous success do not count.

The functions are data-first (map(result, f)); take a result apart with match::

match result:
    case Success(value=value):
        ...
    case Failure(cause=cause):
        ...
    case Initial():
        ...

Types

TypeDefinitionDescription
AsyncResulttype AsyncResult[A, E = Never] = Initial[A, E] | Success[A, E] | Failure[A, E]

Classes

Functions

is_async_result

is_async_result(u) -> TypeIs[AsyncResult[object, object]]
ParameterTypeDescription
uobject

Returns TypeIs[AsyncResult[object, object]]

def is_async_result(u: object) -> TypeIs[AsyncResult[object, object]]:
    return isinstance(u, _Base)

is_waiting

is_waiting(result) -> bool
ParameterTypeDescription
resultAsyncResult[object, object]

Returns bool

def is_waiting(result: AsyncResult[object, object]) -> bool:
    return result.waiting

is_initial

is_initial[A, E](result) -> TypeIs[Initial[A, E]]
ParameterTypeDescription
resultAsyncResult[A, E]

Returns TypeIs[Initial[A, E]]

def is_initial[A, E](result: AsyncResult[A, E]) -> TypeIs[Initial[A, E]]:
    return isinstance(result, Initial)

is_not_initial

is_not_initial[A, E](result) -> TypeIs[Success[A, E] | Failure[A, E]]
ParameterTypeDescription
resultAsyncResult[A, E]

Returns TypeIs[Success[A, E] | Failure[A, E]]

def is_not_initial[A, E](result: AsyncResult[A, E]) -> TypeIs[Success[A, E] | Failure[A, E]]:
    return not isinstance(result, Initial)

is_success

is_success[A, E](result) -> TypeIs[Success[A, E]]
ParameterTypeDescription
resultAsyncResult[A, E]

Returns TypeIs[Success[A, E]]

def is_success[A, E](result: AsyncResult[A, E]) -> TypeIs[Success[A, E]]:
    return isinstance(result, Success)

is_failure

is_failure[A, E](result) -> TypeIs[Failure[A, E]]
ParameterTypeDescription
resultAsyncResult[A, E]

Returns TypeIs[Failure[A, E]]

def is_failure[A, E](result: AsyncResult[A, E]) -> TypeIs[Failure[A, E]]:
    return isinstance(result, Failure)

is_interrupted

is_interrupted(result) -> bool
ParameterTypeDescription
resultAsyncResult[object, object]

Returns bool

def is_interrupted(result: AsyncResult[object, object]) -> bool:
    return isinstance(result, Failure) and result.cause.has_interrupts_only

initial

initial[A = Never, E = Never](waiting=False) -> Initial[A, E]
ParameterTypeDescription
waitingbool = False

Returns Initial[A, E]

def initial[A = Never, E = Never](waiting: bool = False) -> Initial[A, E]:
    return Initial(waiting)

success

success[A, E = Never](value, *, waiting=False, timestamp=None) -> Success[A, E]

A success at timestamp (now by default).

ParameterTypeDescription
valueA
waitingbool = False
timestampint | None = None

Returns Success[A, E]

def success[A, E = Never](
    value: A, *, waiting: bool = False, timestamp: int | None = None
) -> Success[A, E]:
    """A success at ``timestamp`` (now by default)."""
    return Success(value, waiting, timestamp)

failure

failure[A = Never, E = Never](cause, *, previous_success=None, waiting=False) -> Failure[A, E]
ParameterTypeDescription
causeCause[E]
previous_successOption[Success[A, E]] = None
waitingbool = False

Returns Failure[A, E]

def failure[A = Never, E = Never](
    cause: Cause[E], *, previous_success: Option[Success[A, E]] = None, waiting: bool = False
) -> Failure[A, E]:
    return Failure(cause, previous_success, waiting)

failure_with_previous

failure_with_previous[A, E](cause, *, previous, waiting=False) -> Failure[A, E]

A failure keeping the last success of previous.

ParameterTypeDescription
causeCause[E]
previousOption[AsyncResult[A, E]]
waitingbool = False

Returns Failure[A, E]

def failure_with_previous[A, E](
    cause: Cause[E], *, previous: Option[AsyncResult[A, E]], waiting: bool = False
) -> Failure[A, E]:
    """A failure keeping the last success of ``previous``."""
    return Failure(cause, _previous_success(previous), waiting)

fail

fail[E, A = Never](error, *, previous_success=None, waiting=False) -> Failure[A, E]
ParameterTypeDescription
errorE
previous_successOption[Success[A, E]] = None
waitingbool = False

Returns Failure[A, E]

def fail[E, A = Never](
    error: E, *, previous_success: Option[Success[A, E]] = None, waiting: bool = False
) -> Failure[A, E]:
    return Failure(cause_.fail(error), previous_success, waiting)

fail_with_previous

fail_with_previous[A, E](error, *, previous, waiting=False) -> Failure[A, E]
ParameterTypeDescription
errorE
previousOption[AsyncResult[A, E]]
waitingbool = False

Returns Failure[A, E]

def fail_with_previous[A, E](
    error: E, *, previous: Option[AsyncResult[A, E]], waiting: bool = False
) -> Failure[A, E]:
    return failure_with_previous(cause_.fail(error), previous=previous, waiting=waiting)

from_exit

from_exit[A, E](exit) -> Success[A, E] | Failure[A, E]
ParameterTypeDescription
exitExit[A, E]

Returns Success[A, E] | Failure[A, E]

def from_exit[A, E](exit: Exit[A, E]) -> Success[A, E] | Failure[A, E]:
    if isinstance(exit, ExitSuccess):
        return Success(exit.value)
    return Failure(exit.cause)

from_exit_with_previous

from_exit_with_previous[A, E](exit, previous) -> Success[A, E] | Failure[A, E]
ParameterTypeDescription
exitExit[A, E]
previousOption[AsyncResult[A, E]]

Returns Success[A, E] | Failure[A, E]

def from_exit_with_previous[A, E](
    exit: Exit[A, E], previous: Option[AsyncResult[A, E]]
) -> Success[A, E] | Failure[A, E]:
    if isinstance(exit, ExitSuccess):
        return Success(exit.value)
    return failure_with_previous(exit.cause, previous=previous)

waiting_from

waiting_from[A, E](previous) -> AsyncResult[A, E]

previous marked waiting, or a waiting Initial.

ParameterTypeDescription
previousOption[AsyncResult[A, E]]

Returns AsyncResult[A, E]

def waiting_from[A, E](previous: Option[AsyncResult[A, E]]) -> AsyncResult[A, E]:
    """``previous`` marked waiting, or a waiting ``Initial``."""
    if previous is None:
        return Initial(True)
    return waiting(previous.value)

waiting

waiting[R: AsyncResult[Any, Any]](self: R, /, *, touch: bool = False) -> R
waiting[R: AsyncResult[Any, Any]](*, touch: bool = False) -> Callable[[R], R]

self marked waiting; with touch, a success also gets a new timestamp. Without self, the function that does it.

ParameterTypeDescription
self= None
touch= False
@overload
def waiting[R: AsyncResult[Any, Any]](self: R, /, *, touch: bool = False) -> R: ...
@overload
def waiting[R: AsyncResult[Any, Any]](*, touch: bool = False) -> Callable[[R], R]: ...
def waiting(self: Any = None, /, *, touch: bool = False) -> Any:
    """``self`` marked waiting; with ``touch``, a success also gets a new
    timestamp. Without ``self``, the function that does it."""
    if self is None:

        def mark(result: AsyncResult[Any, Any]) -> AsyncResult[Any, Any]:
            return waiting(result, touch=touch)

        return mark
    current = cast("AsyncResult[Any, Any]", self)
    if current.waiting:
        return _touch(current) if touch else current
    result = _copy(current, True)
    if touch and isinstance(result, Success):
        result.timestamp = now_millis()
    return result

touch

touch[R: AsyncResult[Any, Any]](result) -> R

A success with a new timestamp; anything else as it is.

ParameterTypeDescription
resultR

Returns R

def touch[R: AsyncResult[Any, Any]](result: R) -> R:
    """A success with a new timestamp; anything else as it is."""
    if isinstance(result, Success):
        touched: AsyncResult[Any, Any] = Success(result.value, result.waiting)
        return touched  # pyright: ignore[reportReturnType]
    return result

replace_previous

replace_previous[A, E](self, previous) -> AsyncResult[A, E]

A failure's previous success taken from previous; anything else as it is.

ParameterTypeDescription
selfAsyncResult[Any, E]
previousOption[AsyncResult[A, Any]]

Returns AsyncResult[A, E]

def replace_previous[A, E](
    self: AsyncResult[Any, E], previous: Option[AsyncResult[A, Any]]
) -> AsyncResult[A, E]:
    """A failure's previous success taken from ``previous``; anything else
    as it is."""
    if isinstance(self, Failure):
        return Failure(self.cause, _previous_success(previous), self.waiting)
    return self

value

value[A, E](self) -> Option[A]

A success's value, or a failure's previous one.

ParameterTypeDescription
selfAsyncResult[A, E]

Returns Option[A]

def value[A, E](self: AsyncResult[A, E]) -> Option[A]:
    """A success's value, or a failure's previous one."""
    match self:
        case Success():
            return Some(self.value)
        case Failure(previous_success=Some(previous)):
            return Some(previous.value)
        case _:
            return None

get_or_else

get_or_else[A, E, B](self, or_else) -> A | B
ParameterTypeDescription
selfAsyncResult[A, E]
or_elseCallable[[], B]

Returns A | B

def get_or_else[A, E, B](self: AsyncResult[A, E], or_else: Callable[[], B]) -> A | B:
    found = value(self)
    return or_else() if found is None else found.value

get_or_raise

get_or_raise[A, E](self) -> A

The value (Effect's getOrThrow), or raise NoSuchElementException.

ParameterTypeDescription
selfAsyncResult[A, E]

Returns A

def get_or_raise[A, E](self: AsyncResult[A, E]) -> A:
    """The value (Effect's ``getOrThrow``), or raise
    ``NoSuchElementException``."""
    found = value(self)
    if found is None:
        raise NoSuchElementException("AsyncResult.getOrThrow: no value found")
    return found.value

cause

cause[A, E](self) -> Option[Cause[E]]
ParameterTypeDescription
selfAsyncResult[A, E]

Returns Option[Cause[E]]

def cause[A, E](self: AsyncResult[A, E]) -> Option[Cause[E]]:
    return Some(self.cause) if isinstance(self, Failure) else None

error

error[A, E](self) -> Option[E]

A failure's first typed error.

ParameterTypeDescription
selfAsyncResult[A, E]

Returns Option[E]

def error[A, E](self: AsyncResult[A, E]) -> Option[E]:
    """A failure's first typed error."""
    if isinstance(self, Failure):
        found = self.cause.find_error()
        return Some(found.value) if isinstance(found, Ok) else None
    return None

to_exit

to_exit[A, E](self) -> Exit[A, E | NoSuchElementException]
ParameterTypeDescription
selfAsyncResult[A, E]

Returns Exit[A, E | NoSuchElementException]

def to_exit[A, E](self: AsyncResult[A, E]) -> Exit[A, E | NoSuchElementException]:
    match self:
        case Success():
            return exit_succeed(self.value)
        case Failure():
            return ExitFailure(self.cause)
        case Initial():
            return exit_fail(NoSuchElementException())

map

map[A, E, B](self, f) -> AsyncResult[B, E]

f of the value, and of a failure's previous success.

ParameterTypeDescription
selfAsyncResult[A, E]
fCallable[[A], B]

Returns AsyncResult[B, E]

def map[A, E, B](self: AsyncResult[A, E], f: Callable[[A], B]) -> AsyncResult[B, E]:
    """``f`` of the value, and of a failure's previous success."""
    match self:
        case Initial():
            return Initial(self.waiting)
        case Failure():
            previous = self.previous_success
            return Failure(
                self.cause,
                None
                if previous is None
                else Some(
                    Success(
                        f(previous.value.value), previous.value.waiting, previous.value.timestamp
                    )
                ),
                self.waiting,
            )
        case Success():
            return Success(f(self.value), self.waiting, self.timestamp)

flat_map

flat_map[A, B, EE](self, f) -> AsyncResult[B, EE]
ParameterTypeDescription
selfAsyncResult[A, EE]
fCallable[[A, Success[A, EE]], AsyncResult[B, EE]]

Returns AsyncResult[B, EE]

def flat_map[A, B, EE](
    self: AsyncResult[A, EE], f: Callable[[A, Success[A, EE]], AsyncResult[B, EE]]
) -> AsyncResult[B, EE]:
    match self:
        case Initial():
            return Initial(self.waiting)
        case Failure():
            previous = self.previous_success
            kept: Option[Success[B, EE]] = None
            if previous is not None:
                nxt = f(previous.value.value, previous.value)
                kept = Some(nxt) if isinstance(nxt, Success) else None
            return Failure(self.cause, kept, self.waiting)
        case Success():
            return f(self.value, self)

match

match[A, E, X, Y, Z](self, *, on_initial, on_failure, on_success) -> X | Y | Z
ParameterTypeDescription
selfAsyncResult[A, E]
on_initialCallable[[Initial[A, E]], X]
on_failureCallable[[Failure[A, E]], Y]
on_successCallable[[Success[A, E]], Z]

Returns X | Y | Z

def match[A, E, X, Y, Z](
    self: AsyncResult[A, E],
    *,
    on_initial: Callable[[Initial[A, E]], X],
    on_failure: Callable[[Failure[A, E]], Y],
    on_success: Callable[[Success[A, E]], Z],
) -> X | Y | Z:
    match self:
        case Initial():
            return on_initial(self)
        case Failure():
            return on_failure(self)
        case Success():
            return on_success(self)

match_with_error

match_with_error[A, E, W, X, Y, Z](self, *, on_initial, on_error, on_defect, on_success) -> W | X | Y | Z
ParameterTypeDescription
selfAsyncResult[A, E]
on_initialCallable[[Initial[A, E]], W]
on_errorCallable[[E, Failure[A, E]], X]
on_defectCallable[[object, Failure[A, E]], Y]
on_successCallable[[Success[A, E]], Z]

Returns W | X | Y | Z

def match_with_error[A, E, W, X, Y, Z](
    self: AsyncResult[A, E],
    *,
    on_initial: Callable[[Initial[A, E]], W],
    on_error: Callable[[E, Failure[A, E]], X],
    on_defect: Callable[[object, Failure[A, E]], Y],
    on_success: Callable[[Success[A, E]], Z],
) -> W | X | Y | Z:
    match self:
        case Initial():
            return on_initial(self)
        case Failure():
            return _error_or_defect(self, on_error, on_defect)
        case Success():
            return on_success(self)

match_with_waiting

match_with_waiting[A, E, W, X, Y, Z](self, *, on_waiting, on_error, on_defect, on_success) -> W | X | Y | Z
ParameterTypeDescription
selfAsyncResult[A, E]
on_waitingCallable[[AsyncResult[A, E]], W]
on_errorCallable[[E, Failure[A, E]], X]
on_defectCallable[[object, Failure[A, E]], Y]
on_successCallable[[Success[A, E]], Z]

Returns W | X | Y | Z

def match_with_waiting[A, E, W, X, Y, Z](
    self: AsyncResult[A, E],
    *,
    on_waiting: Callable[[AsyncResult[A, E]], W],
    on_error: Callable[[E, Failure[A, E]], X],
    on_defect: Callable[[object, Failure[A, E]], Y],
    on_success: Callable[[Success[A, E]], Z],
) -> W | X | Y | Z:
    if self.waiting:
        return on_waiting(self)
    match self:
        case Initial():
            return on_waiting(self)
        case Failure():
            return _error_or_defect(self, on_error, on_defect)
        case Success():
            return on_success(self)

all

all[A, E](results: Mapping[str, AsyncResult[A, E]], /) -> AsyncResult[dict[str, A], E]
all[A, E](results: Iterable[AsyncResult[A, E]], /) -> AsyncResult[list[A], E]
all(results: Mapping[str, object], /) -> AsyncResult[dict[str, Any], Any]
all(results: Iterable[object], /) -> AsyncResult[list[Any], Any]

One result of many (a list, or a mapping by key); values that are not results are kept as they are. The first failure or initial result wins; a failure keeps the combined previous successes when every input has a value.

ParameterTypeDescription
results
@overload
def all[A, E](  # pyright: ignore[reportOverlappingOverload]
    results: Mapping[str, AsyncResult[A, E]], /
) -> AsyncResult[dict[str, A], E]: ...
@overload
def all[A, E](results: Iterable[AsyncResult[A, E]], /) -> AsyncResult[list[A], E]: ...
@overload
def all(results: Mapping[str, object], /) -> AsyncResult[dict[str, Any], Any]: ...
@overload
def all(results: Iterable[object], /) -> AsyncResult[list[Any], Any]: ...
def all(results: Iterable[object] | Mapping[str, object], /) -> AsyncResult[Any, Any]:
    """One result of many (a list, or a mapping by key); values that are
    not results are kept as they are. The first failure or initial result
    wins; a failure keeps the combined previous successes when every input
    has a value."""
    as_dict = isinstance(results, Mapping)
    entries: builtins.list[tuple[object, object]] = (
        builtins.list(cast("Mapping[str, object]", results).items())
        if as_dict
        else builtins.list(enumerate(results))
    )
    successes: dict[object, object] = {}
    any_waiting = False
    for key, result in entries:
        if not is_async_result(result):
            successes[key] = result
            continue
        if isinstance(result, Failure):
            return Failure(result.cause, _combined_previous(entries, as_dict), result.waiting)
        if isinstance(result, Initial):
            return result
        successes[key] = result.value
        any_waiting = any_waiting or result.waiting
    return Success(_shape(successes, as_dict), any_waiting)

builder

builder[A, E](self) -> Builder[Never, A, E]

A Builder rendering self.

ParameterTypeDescription
selfAsyncResult[A, E]

Returns Builder[Never, A, E]

def builder[A, E](self: AsyncResult[A, E]) -> Builder[Never, A, E]:
    """A ``Builder`` rendering ``self``."""
    return Builder(self)

Schema

Schema[A = Never, E = Never, AI = Never, EI = Never, RD = Never, RE = Never](*, success=None, error=None) -> AsyncResultSchema[A, E, AI, EI, RD, RE]

An AsyncResult whose success success takes and whose failure's errors error takes (Effect's AsyncResult.Schema; either left out is S.Never). Issues are at ["value"], ["previous_success", "value"] and ["cause"]; anything else is Expected AsyncResult.

ParameterTypeDescription
successCodec[A, AI, RD, RE] | None = None
errorCodec[E, EI, RD, RE] | None = None

Returns AsyncResultSchema[A, E, AI, EI, RD, RE]

def Schema[A = Never, E = Never, AI = Never, EI = Never, RD = Never, RE = Never](
    *,
    success: Codec[A, AI, RD, RE] | None = None,
    error: Codec[E, EI, RD, RE] | None = None,
) -> AsyncResultSchema[A, E, AI, EI, RD, RE]:
    """An ``AsyncResult`` whose success ``success`` takes and whose
    failure's errors ``error`` takes (Effect's ``AsyncResult.Schema``;
    either left out is ``S.Never``). Issues are at ``["value"]``,
    ``["previous_success", "value"]`` and ``["cause"]``; anything else is
    ``Expected AsyncResult``."""
    success_ = cast("Codec[A, AI, RD, RE]", NeverSchema if success is None else success)
    error_ = cast("Codec[E, EI, RD, RE]", NeverSchema if error is None else error)
    cause = CauseSchema(error_, cast("Any", Defect()))
    node = ast.Declaration(
        (success_.__codec__().ast, cause.ast),
        _run,
        annotations={
            "expected": "AsyncResult",
            "to_codec": _to_codec,
            "to_equivalence": _equivalence,
            "to_formatter": _formatter,
        },
    )
    return AsyncResultSchema(node, success_, error_)