API Reference

outcome.capture(sync_fn: Callable[ArgsT, ResultT], *args: ArgsT.args, **kwargs: ArgsT.kwargs) → Value[ResultT] | Error

Run sync_fn(*args, **kwargs) and capture the result.

Returns:

Either a Value or Error as appropriate.

await outcome.acapture(async_fn: Callable[ArgsT, Awaitable[ResultT]], *args: ArgsT.args, **kwargs: ArgsT.kwargs) → Value[ResultT] | Error

Run await async_fn(*args, **kwargs) and capture the result.

Returns:

Either a Value or Error as appropriate.

class outcome.Outcome

An abstract class representing the result of a Python computation.

This class has two concrete subclasses: Value representing a value, and Error representing an exception.

In addition to the methods described below, comparison operators on Value and Error objects (==, <, etc.) check that the other object is also a Value or Error object respectively, and then compare the contained objects.

Outcome objects are hashable if the contained objects are hashable.

abstractmethod await asend(agen: AsyncGenerator[ResultT, ValueT]) → ResultT

Send or throw the contained value or exception into the given async generator object.

Parameters:

agen – An async generator object supporting .asend() and .athrow() methods.

abstractmethod send(gen: Generator[ResultT, ValueT, object]) → ResultT

Send or throw the contained value or exception into the given generator object.

Parameters:

gen – A generator object supporting .send() and .throw() methods.

abstractmethod unwrap() → ValueT

Return or raise the contained value or exception.

These two lines of code are equivalent:

x = fn(*args)
x = outcome.capture(fn, *args).unwrap()

outcome.Maybe = Value[ResultT] | Error

A convenience alias to a union of both results. This allows type checkers to perform exhaustiveness checking when isinstance() is used with either class:

outcome: Maybe[int] = capture(some_function, 1, 2, 3)
if isinstance(outcome, Value):
    # Type checkers know it's a Value[int] here.
else:
    # It must be an Error.

class outcome.Value(value: ValueT)

Concrete Outcome subclass representing a regular value.

await asend(agen: AsyncGenerator[ResultT, ValueT]) → ResultT

Send or throw the contained value or exception into the given async generator object.

Parameters:

agen – An async generator object supporting .asend() and .athrow() methods.

send(gen: Generator[ResultT, ValueT, object]) → ResultT

Send or throw the contained value or exception into the given generator object.

Parameters:

gen – A generator object supporting .send() and .throw() methods.

unwrap() → ValueT

Return or raise the contained value or exception.

These two lines of code are equivalent:

x = fn(*args)
x = outcome.capture(fn, *args).unwrap()

class outcome.Error(error: BaseException)

Concrete Outcome subclass representing a raised exception.

await asend(agen: AsyncGenerator[ResultT, NoReturn]) → ResultT

Send or throw the contained value or exception into the given async generator object.

Parameters:

agen – An async generator object supporting .asend() and .athrow() methods.

send(gen: Generator[ResultT, NoReturn, object]) → ResultT

Send or throw the contained value or exception into the given generator object.

Parameters:

gen – A generator object supporting .send() and .throw() methods.

unwrap() → NoReturn

Return or raise the contained value or exception.

These two lines of code are equivalent:

x = fn(*args)
x = outcome.capture(fn, *args).unwrap()

class outcome.AlreadyUsedError

An Outcome can only be unwrapped once.