Result

.. image:: https://img.shields.io/github/workflow/status/dbrgn/result/CI/master :alt: GitHub Workflow Status (branch) :target: https://github.com/dbrgn/result/actions?query=workflow%3ACI+branch%3Amaster

.. image:: https://codecov.io/gh/dbrgn/result/branch/master/graph/badge.svg :alt: Coverage :target: https://codecov.io/gh/dbrgn/result

A simple Result type for Python 3

inspired by Rust

The idea is that a result value can be either

Ok(value)

Err(error)

Ok

Err

Result[T, E]

typing.Union[Ok[T], Err[E]]

.. sourcecode:: python

def get_user_by_email(email: str) -> Tuple[Optional[User], Optional[str]]:
    """
    Return the user instance or an error message.
    """
    if not user_exists(email):
        return None, 'User does not exist'
    if not user_active(email):
        return None, 'User is inactive'
    user = get_user(email)
    return user, None

user, reason = get_user_by_email('[email protected]')
if user is None:
    raise RuntimeError('Could not fetch user: %s' % reason)
else:
    do_something(user)

To something like this:

.. sourcecode:: python

from result import Ok, Err, Result

def get_user_by_email(email: str) -> Result[User, str]:
    """
    Return the user instance or an error message.
    """
    if not user_exists(email):
        return Err('User does not exist')
    if not user_active(email):
        return Err('User is inactive')
    user = get_user(email)
    return Ok(user)
user_result = get_user_by_email(email)
if isinstance(user_result, Ok):
    # type(user_result.value) == User
    do_something(user_result.value)
else:
    # type(user_result.value) == str
    raise RuntimeError('Could not fetch user: %s' % user_result.value)

As this is Python and not Rust, you will lose some of the advantages that it brings, like elegant combinations with the

match

Not all methods (https://doc.rust-lang.org/std/result/enum.Result.html) have been implemented, only the ones that make sense in the Python context. By using

isinstance

Ok

Err

MyPy 

API

Creating an instance::

>>> from result import Ok, Err
>>> res1 = Ok('yay')
>>> res2 = Err('nay')

Checking whether a result is

Ok

Err

isinstance

is_ok()

is_err()

>>> res = Ok('yay')
>>> isinstance(res, Ok)
True
>>> isinstance(res, Err)
False
>>> res.is_ok()
True
>>> res.is_err()
False

You can also check if an object is

Ok

Err

OkErr

(Ok, Err)

>>> res1 = Ok('yay')
>>> res2 = Err('nay')
>>> isinstance(res1, OkErr)
True
>>> isinstance(res2, OkErr)
True
>>> isinstance(1, OkErr)
False
>>> isinstance(res1, (Ok, Err))
True

Convert a

Result

None

>>> res1 = Ok('yay')
>>> res2 = Err('nay')
>>> res1.ok()
'yay'
>>> res2.ok()
None

Convert a

Result

None

>>> res1 = Ok('yay')
>>> res2 = Err('nay')
>>> res1.err()
None
>>> res2.err()
'nay'

Access the value directly, without any other checks::

>>> res1 = Ok('yay')
>>> res2 = Err('nay')
>>> res1.value
'yay'
>>> res2.value
'nay'

Note that this is a property, you cannot assign to it. Results are immutable.

For your convenience, simply creating an

Ok

True

>>> res1 = Ok()
>>> res1.value
True

The

unwrap

Ok

unwrap_err

Err

UnwrapError

>>> res1 = Ok('yay')
>>> res2 = Err('nay')
>>> res1.unwrap()
'yay'
>>> res2.unwrap()
Traceback (most recent call last):
File "", line 1, in 
File "C:\project\result\result.py", line 107, in unwrap
    return self.expect("Called `Result.unwrap()` on an `Err` value")
File "C:\project\result\result.py", line 101, in expect
    raise UnwrapError(message)
result.result.UnwrapError: Called `Result.unwrap()` on an `Err` value
>>> res1.unwrap_err()
Traceback (most recent call last):
...
>>>res2.unwrap_err()
'nay'

A custom error message can be displayed instead by using

expect

expect_err

>>> res1 = Ok('yay')
>>> res2 = Err('nay')
>>> res1.expect('not ok')
'yay'
>>> res2.expect('not ok')
Traceback (most recent call last):
File "", line 1, in 
File "C:\project\result\result.py", line 101, in expect
    raise UnwrapError(message)
result.result.UnwrapError: not ok
>>> res1.expect_err('not err')
Traceback (most recent call last):
...
>>> res2.expect_err('not err')
'nay'

A default value can be returned instead by using

unwrap_or

>>> res1 = Ok('yay')
>>> res2 = Err('nay')
>>> res1.unwrap_or('default')
'yay'
>>> res2.unwrap_or('default')
'default'

Values and errors can be mapped using

map

map_or

map_or_else

map_err

Ok(1).map(lambda x: x + 1) Ok(2) Err('nay').map(lambda x: x + 1) Err('nay') Ok(1).mapor(-1, lambda x: x + 1) 2 Err(1).mapor(-1, lambda x: x + 1) -1 Ok(1).maporelse(lambda: 3, lambda x: x + 1) 2 Err('nay').maporelse(lambda: 3, lambda x: x + 1) 3 Ok(1).maperr(lambda x: x + 1) Ok(1) Err(1).maperr(lambda x: x + 1) Err(2)

FAQ

• Why do I get the "Cannot infer type argument" error with MyPy?

There is

a bug in MyPy

if isinstance(res, Ok)

if res.is_ok()

one of these workarounds

License

MIT License