结果

用于Python 3 的简单结果类型受Rust启发，完全类型注释。

安装

最新版本:

$ pip install result

最新GitHub main分支版本:

$ pip install git+https://github.com/rustedpy/result

摘要

这个想法是，结果值可以是Ok(value)或Err(error)，有一种方法来区分这两者。Ok和Err都是封装任意值的类。Result[T, E]是一个泛型类型别名，表示typing.Union[Ok[T], Err[E]]。它将改变以下代码:

def get_user_by_email(email: str) -> Tuple[Optional[User], Optional[str]]:
    """
    返回用户实例或错误消息。
    """
    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('ueli@example.com')
if user is None:
    raise RuntimeError('Could not fetch user: %s' % reason)
else:
    do_something(user)

变为这样:

from result import Ok, Err, Result, is_ok, is_err

def get_user_by_email(email: str) -> Result[User, str]:
    """
    返回用户实例或错误消息。
    """
    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 is_ok(user_result):
    # type(user_result.ok_value) == User
    do_something(user_result.ok_value)
else:
    # type(user_result.err_value) == str
    raise RuntimeError('Could not fetch user: %s' % user_result.err_value)

请注意,.ok_value只存在于Ok的实例上,.err_value只存在于Err的实例上。

如果您使用的是Python版本3.10或更高版本,您还可以使用优雅的match语句:

from result import Result, Ok, Err

def divide(a: int, b: int) -> Result[int, str]:
    if b == 0:
        return Err("Cannot divide by zero")
    return Ok(a // b)

values = [(10, 0), (10, 5)]
for a, b in values:
    match divide(a, b):
        case Ok(value):
            print(f"{a} // {b} == {value}")
        case Err(e):
            print(e)

并非所有方法(https://doc.rust-lang.org/std/result/enum.Result.html)都已实现,只实现了在Python上下文中有意义的方法。所有这些都在一个包中,使得更容易处理可能为"确定"或"不确定"的值,而无需求助于自定义异常。

API

自动生成的API文档也可在./docs/README.md中找到。

创建实例:

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

检查结果是否为Ok或Err:

if is_err(result):
    raise RuntimeError(result.err_value)
do_something(result.ok_value)

或者

if is_ok(result):
    do_something(result.ok_value)
else:
    raise RuntimeError(result.err_value)

另外,也可以使用isinstance(与类型守卫函数is_ok和is_err可互换使用)。但是,依赖于isinstance可能会导致代码稍微不太可读和不太简洁:

if isinstance(result, Err):
    raise RuntimeError(result.err_value)
do_something(result.ok_value)

您还可以使用OkErr类型检查对象是否为Ok或Err。请注意,此类型仅为方便而设计,不应用于其他任何目的。使用(Ok, Err)也可以work fine:

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

将Result转换为值或None:

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

将Result转换为错误或None:

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

直接访问值,无需任何其他检查:

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

请注意,这是一个属性,您无法对其进行赋值。结果是不可变的。

当值内部无关紧要时,我们建议使用None或bool,但您可以自由使用任何您认为最合适的值。Result(Ok或Err)实例中必须始终包含某些内容。如果您正在寻找可能包含值的类型,您可能对maybe感兴趣。

unwrap方法在Ok时返回值,unwrap_err方法在Err时返回错误值,否则会引发UnwrapError:

>>> res1 = Ok('yay')
>>> res2 = Err('nay')
>>> res1.unwrap()
'yay'
>>> res2.unwrap()
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
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'

你可以使用expect和expect_err来显示自定义错误消息:

>>> res1 = Ok('yay')
>>> res2 = Err('nay')
>>> res1.expect('not ok')
'yay'
>>> res2.expect('not ok')
Traceback (most recent call last):
File "<stdin>", line 1, in <module>
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'

可以使用unwrap_or或unwrap_or_else返回默认值:

>>> res1 = Ok('yay')
>>> res2 = Err('nay')
>>> res1.unwrap_or('default')
'yay'
>>> res2.unwrap_or('default')
'default'
>>> res1.unwrap_or_else(str.upper)
'yay'
>>> res2.unwrap_or_else(str.upper)
'NAY'

unwrap方法会引发UnwrapError。可以使用unwrap_or_raise方法引发自定义异常:

>>> res1 = Ok('yay')
>>> res2 = Err('nay')
>>> res1.unwrap_or_raise(ValueError)
'yay'
>>> res2.unwrap_or_raise(ValueError)
ValueError: nay

可以使用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).map_or(-1, lambda x: x + 1)
2
>>> Err(1).map_or(-1, lambda x: x + 1)
-1
>>> Ok(1).map_or_else(lambda: 3, lambda x: x + 1)
2
>>> Err('nay').map_or_else(lambda: 3, lambda x: x + 1)
3
>>> Ok(1).map_err(lambda x: x + 1)
Ok(1)
>>> Err(1).map_err(lambda x: x + 1)
Err(2)

为了节省内存,Ok和Err类都是'slotted',即它们定义了__slots__。这意味着为实例分配任意属性将引发AttributeError。

as_result装饰器

as_result()装饰器可用于通过指定一个或多个异常类型快速将"普通"函数转换为Result返回函数:

@as_result(ValueError, IndexError)
def f(value: int) -> int:
    if value == 0:
        raise ValueError  # becomes Err
    elif value == 1:
        raise IndexError  # becomes Err
    elif value == 2:
        raise KeyError  # raises Exception
    else:
        return value  # becomes Ok

res = f(0)  # Err[ValueError()]
res = f(1)  # Err[IndexError()]
res = f(2)  # raises KeyError
res = f(3)  # Ok[3]

可以指定Exception(甚至BaseException)以创建一个"catch all"Result返回类型。这实际上与try后跟except Exception相同,在大多数情况下不被视为良好实践,因此需要显式选择。

由于as_result是一个常规装饰器,它可以用于包装现有函数(包括来自其他库的函数),尽管语法略有不同寻常(没有通常的@):

import third_party

x = third_party.do_something(...)  # 可能会引发异常,谁知道呢?

safe_do_something = as_result(Exception)(third_party.do_something)

res = safe_do_something(...)  # Ok(...) or Err(...)
if is_ok(res):
    print(res.ok_value)

Do notation

语法糖是用于一系列and_then()调用的记号记法。 和Rust或Haskell中的等价物类似,但语法有所不同。 与其写x <- Ok(1),不如写for x in Ok(1)。因为语法基于生成器,最终结果必须是第一行,而不是最后一行。

final_result: Result[int, str] = do(
    Ok(x + y)
    for x in Ok(1)
    for y in Ok(2)
)

注意,如果你省略了类型注解, final_result: Result[float, int] = ...,你的类型检查器可能无法推断返回类型。为了避免类型检查器的错误或警告,在使用do函数时应添加类型提示。

这与Rust的m!宏类似:

use do_notation::m;
let r = m! {
    x <- Some(1);
    y <- Some(2);
    Some(x + y)
};

注意,如果你的do语句有多个for,你可以访问前一个for中绑定的标识符。例如:

my_result: Result[int, str] = do(
    f(x, y, z)
    for x in get_x()
    for y in calculate_y_from_x(x)
    for z in calculate_z_from_x_y(x, y)
)

你可以如下使用do()配合awaited值:

async def process_data(data) -> Result[int, str]:
    res1 = await get_result_1(data)
    res2 = await get_result_2(data)
    return do(
        Ok(x + y)
        for x in res1
        for y in res2
    )

但是,如果你想在表达式中await某些东西,请使用do_async():

async def process_data(data) -> Result[int, str]:
    return do_async(
        Ok(x + y)
        for x in await get_result_1(data)
        for y in await get_result_2(data)
    )

故障排除do()调用:

TypeError("Got async_generator but expected generator")

有时常规的do()可以处理async值,但这个错误意味着你遇到了一种它无法处理的情况。这种情况下你应该使用do_async()。