result.md

module result

Global Variables

• OkErr

---

function as_result

as_result(
    *exceptions: 'Type[TBE]'
) → Callable[[Callable[P, R]], Callable[P, Result[R, TBE]]]

Make a decorator to turn a function into one that returns a Result.

Regular return values are turned into Ok(return_value). Raised exceptions of the specified exception type(s) are turned into Err(exc).

---

function as_async_result

as_async_result(
    *exceptions: 'Type[TBE]'
) → Callable[[Callable[P, Awaitable[R]]], Callable[P, Awaitable[Result[R, TBE]]]]

Make a decorator to turn an async function into one that returns a Result. Regular return values are turned into Ok(return_value). Raised exceptions of the specified exception type(s) are turned into Err(exc).

---

function is_ok

is_ok(result: 'Result[T, E]') → TypeIs[Ok[T]]

A type guard to check if a result is an Ok

Usage:

r: Result[int, str] = get_a_result()
if is_ok(r):
     r   # r is of type Ok[int]
elif is_err(r):
     r   # r is of type Err[str]

---

function is_err

is_err(result: 'Result[T, E]') → TypeIs[Err[E]]

A type guard to check if a result is an Err

Usage:

r: Result[int, str] = get_a_result()
if is_ok(r):
     r   # r is of type Ok[int]
elif is_err(r):
     r   # r is of type Err[str]

---

function do

do(gen: 'Generator[Result[T, E], None, None]') → Result[T, E]

Do notation for Result (syntactic sugar for sequence of and_then() calls).

Usage:

// This is similar to
use do_notation::m;
let final_result = m! {
     x <- Ok("hello");
     y <- Ok(True);
     Ok(len(x) + int(y) + 0.5)
};

final_result: Result[float, int] = do(
         Ok(len(x) + int(y) + 0.5)
         for x in Ok("hello")
         for y in Ok(True)
     )

NOTE: If you exclude the type annotation e.g. Result[float, int] your type checker might be unable to infer the return type. To avoid an error, you might need to help it with the type hint.

---

function do_async

do_async(
    gen: 'Union[Generator[Result[T, E], None, None], AsyncGenerator[Result[T, E], None]]'
) → Result[T, E]

Async version of do. Example:

final_result: Result[float, int] = await do_async(
     Ok(len(x) + int(y) + z)
         for x in await get_async_result_1()
         for y in await get_async_result_2()
         for z in get_sync_result_3()
     )

NOTE: Python makes generators async in a counter-intuitive way.

# This is a regular generator:
     async def foo(): ...
     do(Ok(1) for x in await foo())

# But this is an async generator:
     async def foo(): ...
     async def bar(): ...
     do(
         Ok(1)
         for x in await foo()
         for y in await bar()
     )

We let users try to use regular do(), which works in some cases of awaiting async values. If we hit a case like above, we raise an exception telling the user to use do_async() instead. See do().

However, for better usability, it's better for do_async() to also accept regular generators, as you get in the first case:

async def foo(): ...
     do(Ok(1) for x in await foo())

Furthermore, neither mypy nor pyright can infer that the second case is actually an async generator, so we cannot annotate do_async() as accepting only an async generator. This is additional motivation to accept either.

---

class Ok

A value that indicates success and which stores arbitrary data for the return value.

method __init__

__init__(value: 'T') → None

---

property ok_value

Return the inner value.

---

property value

Return the inner value.

@deprecated Use ok_value or err_value instead. This method will be removed in a future version.

---

method and_then

and_then(op: 'Callable[[T], Result[U, E]]') → Result[U, E]

The contained result is Ok, so return the result of op with the original value passed in

---

method and_then_async

and_then_async(op: 'Callable[[T], Awaitable[Result[U, E]]]') → Result[U, E]

The contained result is Ok, so return the result of op with the original value passed in

---

method err

err() → None

Return None.

---

method expect

expect(_message: 'str') → T

Return the value.

---

method expect_err

expect_err(message: 'str') → NoReturn

Raise an UnwrapError since this type is Ok

---

method inspect

inspect(op: 'Callable[[T], Any]') → Result[T, E]

Calls a function with the contained value if Ok. Returns the original result.

---

method inspect_err

inspect_err(op: 'Callable[[E], Any]') → Result[T, E]

Calls a function with the contained value if Err. Returns the original result.

---

method is_err

is_err() → Literal[False]

---

method is_ok

is_ok() → Literal[True]

---

method map

map(op: 'Callable[[T], U]') → Ok[U]

The contained result is Ok, so return Ok with original value mapped to a new value using the passed in function.

---

method map_async

map_async(op: 'Callable[[T], Awaitable[U]]') → Ok[U]

The contained result is Ok, so return the result of op with the original value passed in

---

method map_err

map_err(op: 'object') → Ok[T]

The contained result is Ok, so return Ok with the original value

---

method map_or

map_or(default: 'object', op: 'Callable[[T], U]') → U

The contained result is Ok, so return the original value mapped to a new value using the passed in function.

---

method map_or_else

map_or_else(default_op: 'object', op: 'Callable[[T], U]') → U

The contained result is Ok, so return original value mapped to a new value using the passed in op function.

---

method ok

ok() → T

Return the value.

---

method or_else

or_else(op: 'object') → Ok[T]

The contained result is Ok, so return Ok with the original value

---

method unwrap

unwrap() → T

Return the value.

---

method unwrap_err

unwrap_err() → NoReturn

Raise an UnwrapError since this type is Ok

---

method unwrap_or

unwrap_or(_default: 'U') → T

Return the value.

---

method unwrap_or_else

unwrap_or_else(op: 'object') → T

Return the value.

---

method unwrap_or_raise

unwrap_or_raise(e: 'object') → T

Return the value.

---

class DoException

This is used to signal to do() that the result is an Err, which short-circuits the generator and returns that Err. Using this exception for control flow in do() allows us to simulate and_then() in the Err case: namely, we don't call op, we just return self (the Err).

method __init__

__init__(err: 'Err[E]') → None

---

class Err

A value that signifies failure and which stores arbitrary data for the error.

method __init__

__init__(value: 'E') → None

---

property err_value

Return the inner value.

---

property value

Return the inner value.

@deprecated Use ok_value or err_value instead. This method will be removed in a future version.

---

method and_then

and_then(op: 'object') → Err[E]

The contained result is Err, so return Err with the original value

---

method and_then_async

and_then_async(op: 'object') → Err[E]

The contained result is Err, so return Err with the original value

---

method err

err() → E

Return the error.

---

method expect

expect(message: 'str') → NoReturn

Raises an UnwrapError.

---

method expect_err

expect_err(_message: 'str') → E

Return the inner value

---

method inspect

inspect(op: 'Callable[[T], Any]') → Result[T, E]

Calls a function with the contained value if Ok. Returns the original result.

---

method inspect_err

inspect_err(op: 'Callable[[E], Any]') → Result[T, E]

Calls a function with the contained value if Err. Returns the original result.

---

method is_err

is_err() → Literal[True]

---

method is_ok

is_ok() → Literal[False]

---

method map

map(op: 'object') → Err[E]

Return Err with the same value

---

method map_async

map_async(op: 'object') → Err[E]

The contained result is Ok, so return the result of op with the original value passed in

---

method map_err

map_err(op: 'Callable[[E], F]') → Err[F]

The contained result is Err, so return Err with original error mapped to a new value using the passed in function.

---

method map_or

map_or(default: 'U', op: 'object') → U

Return the default value

---

method map_or_else

map_or_else(default_op: 'Callable[[], U]', op: 'object') → U

Return the result of the default operation

---

method ok

ok() → None

Return None.

---

method or_else

or_else(op: 'Callable[[E], Result[T, F]]') → Result[T, F]

The contained result is Err, so return the result of op with the original value passed in

---

method unwrap

unwrap() → NoReturn

Raises an UnwrapError.

---

method unwrap_err

unwrap_err() → E

Return the inner value

---

method unwrap_or

unwrap_or(default: 'U') → U

Return default.

---

method unwrap_or_else

unwrap_or_else(op: 'Callable[[E], T]') → T

The contained result is Err, so return the result of applying op to the error value.

---

method unwrap_or_raise

unwrap_or_raise(e: 'Type[TBE]') → NoReturn

The contained result is Err, so raise the exception with the value.

---

class UnwrapError

Exception raised from .unwrap_<...> and .expect_<...> calls.

The original Result can be accessed via the .result attribute, but this is not intended for regular use, as type information is lost: UnwrapError doesn't know about both T and E, since it's raised from Ok() or Err() which only knows about either T or E, not both.

method __init__

__init__(result: 'Result[object, object]', message: 'str') → None

---

property result

Returns the original result.

---

This file was automatically generated via lazydocs.