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#
| Type | Definition | Description |
|---|---|---|
AsyncResult | type 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]]| Parameter | Type | Description |
|---|---|---|
u | object |
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| Parameter | Type | Description |
|---|---|---|
result | AsyncResult[object, object] |
Returns bool
def is_waiting(result: AsyncResult[object, object]) -> bool:
return result.waitingis_initial#
is_initial[A, E](result) -> TypeIs[Initial[A, E]]| Parameter | Type | Description |
|---|---|---|
result | AsyncResult[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]]| Parameter | Type | Description |
|---|---|---|
result | AsyncResult[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]]| Parameter | Type | Description |
|---|---|---|
result | AsyncResult[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]]| Parameter | Type | Description |
|---|---|---|
result | AsyncResult[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| Parameter | Type | Description |
|---|---|---|
result | AsyncResult[object, object] |
Returns bool
def is_interrupted(result: AsyncResult[object, object]) -> bool:
return isinstance(result, Failure) and result.cause.has_interrupts_onlyinitial#
initial[A = Never, E = Never](waiting=False) -> Initial[A, E]| Parameter | Type | Description |
|---|---|---|
waiting | bool = 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).
| Parameter | Type | Description |
|---|---|---|
value | A | |
waiting | bool = False | |
timestamp | int | 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]| Parameter | Type | Description |
|---|---|---|
cause | Cause[E] | |
previous_success | Option[Success[A, E]] = None | |
waiting | bool = 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.
| Parameter | Type | Description |
|---|---|---|
cause | Cause[E] | |
previous | Option[AsyncResult[A, E]] | |
waiting | bool = 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]| Parameter | Type | Description |
|---|---|---|
error | E | |
previous_success | Option[Success[A, E]] = None | |
waiting | bool = 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]| Parameter | Type | Description |
|---|---|---|
error | E | |
previous | Option[AsyncResult[A, E]] | |
waiting | bool = 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]| Parameter | Type | Description |
|---|---|---|
exit | Exit[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]| Parameter | Type | Description |
|---|---|---|
exit | Exit[A, E] | |
previous | Option[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.
| Parameter | Type | Description |
|---|---|---|
previous | Option[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.
| Parameter | Type | Description |
|---|---|---|
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 resulttouch#
touch[R: AsyncResult[Any, Any]](result) -> RA success with a new timestamp; anything else as it is.
| Parameter | Type | Description |
|---|---|---|
result | R |
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 resultreplace_previous#
replace_previous[A, E](self, previous) -> AsyncResult[A, E]A failure's previous success taken from previous; anything else
as it is.
| Parameter | Type | Description |
|---|---|---|
self | AsyncResult[Any, E] | |
previous | Option[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 selfvalue#
value[A, E](self) -> Option[A]A success's value, or a failure's previous one.
| Parameter | Type | Description |
|---|---|---|
self | AsyncResult[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 Noneget_or_else#
get_or_else[A, E, B](self, or_else) -> A | B| Parameter | Type | Description |
|---|---|---|
self | AsyncResult[A, E] | |
or_else | Callable[[], 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.valueget_or_raise#
get_or_raise[A, E](self) -> AThe value (Effect's getOrThrow), or raise
NoSuchElementException.
| Parameter | Type | Description |
|---|---|---|
self | AsyncResult[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.valuecause#
cause[A, E](self) -> Option[Cause[E]]| Parameter | Type | Description |
|---|---|---|
self | AsyncResult[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 Noneerror#
error[A, E](self) -> Option[E]A failure's first typed error.
| Parameter | Type | Description |
|---|---|---|
self | AsyncResult[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 Noneto_exit#
to_exit[A, E](self) -> Exit[A, E | NoSuchElementException]| Parameter | Type | Description |
|---|---|---|
self | AsyncResult[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.
| Parameter | Type | Description |
|---|---|---|
self | AsyncResult[A, E] | |
f | Callable[[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]| Parameter | Type | Description |
|---|---|---|
self | AsyncResult[A, EE] | |
f | Callable[[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| Parameter | Type | Description |
|---|---|---|
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] |
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| Parameter | Type | Description |
|---|---|---|
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] |
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| Parameter | Type | Description |
|---|---|---|
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] |
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.
| Parameter | Type | Description |
|---|---|---|
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.
| Parameter | Type | Description |
|---|---|---|
self | AsyncResult[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.
| Parameter | Type | Description |
|---|---|---|
success | Codec[A, AI, RD, RE] | None = None | |
error | Codec[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_)On This Page
TypesClassesFunctionsis_async_resultis_waitingis_initialis_not_initialis_successis_failureis_interruptedinitialsuccessfailurefailure_with_previousfailfail_with_previousfrom_exitfrom_exit_with_previouswaiting_fromwaitingtouchreplace_previousvalueget_or_elseget_or_raisecauseerrorto_exitmapflat_mapmatchmatch_with_errormatch_with_waitingallbuilderSchema