Publish docs

[francium]

Need to setup something to publish the library docs in an easy to view manner, rather than just pointing people to the source code as we currently do (in the readme).

Most likely a github.io site should be fine rendering from a docs/ folder containing generated html.

Could also try this to generate markdown docs: https://stackoverflow.com/questions/36237477/python-docstrings-to-github-readme-md

[GNUSheep]

Generated one with lazydocs: https://github.com/ml-tooling/lazydocs

I think the fastest (maybe not the best) way to generate doc is to use some kind of API like lazydocs

For sure, it can be improved a lot, some python docstrings should be reviewed to check if are correct, because sometimes markdown was not properly generated.

What do you think?

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]') → TypeGuard[Ok[T]]

A typeguard 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]') → TypeGuard[Err[E]]

A typeguard 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 Ok.__init__

__init__(value: 'T') → None

---

property Ok.ok_value

Return the inner value.

---

property Ok.value

Return the inner value.

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

---

method Ok.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 Ok.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 Ok.err

err() → None

Return None.

---

method Ok.expect

expect(_message: 'str') → T

Return the value.

---

method Ok.expect_err

expect_err(message: 'str') → NoReturn

Raise an UnwrapError since this type is Ok

---

method Ok.is_err

is_err() → Literal[False]

---

method Ok.is_ok

is_ok() → Literal[True]

---

method Ok.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 Ok.map_err

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

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

---

method Ok.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 Ok.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

ok() → T

Return the value.

---

method Ok.or_else

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

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

---

method Ok.unwrap

unwrap() → T

Return the value.

---

method Ok.unwrap_err

unwrap_err() → NoReturn

Raise an UnwrapError since this type is Ok

---

method Ok.unwrap_or

unwrap_or(_default: 'U') → T

Return the value.

---

method Ok.unwrap_or_else

unwrap_or_else(op: 'object') → T

Return the value.

---

method Ok.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 DoException.__init__

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

---

class Err

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

method Err.__init__

__init__(value: 'E') → None

---

property Err.err_value

Return the inner value.

---

property Err.value

Return the inner value.

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

---

method Err.and_then

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

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

---

method Err.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

err() → E

Return the error.

---

method Err.expect

expect(message: 'str') → NoReturn

Raises an UnwrapError.

---

method Err.expect_err

expect_err(_message: 'str') → E

Return the inner value

---

method Err.is_err

is_err() → Literal[True]

---

method Err.is_ok

is_ok() → Literal[False]

---

method Err.map

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

Return Err with the same value

---

method Err.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 Err.map_or

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

Return the default value

---

method Err.map_or_else

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

Return the result of the default operation

---

method Err.ok

ok() → None

Return None.

---

method Err.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 Err.unwrap

unwrap() → NoReturn

Raises an UnwrapError.

---

method Err.unwrap_err

unwrap_err() → E

Return the inner value

---

method Err.unwrap_or

unwrap_or(default: 'U') → U

Return default.

---

method Err.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 Err.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 UnwrapError.__init__

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

---

property UnwrapError.result

Returns the original result.

---

This file was automatically generated via lazydocs.

[francium]

Thanks for the suggestion @GNUSheep