利用 Python 中的“->”操作为函数参数增加有价值的元信息

2023-09-27 14:11:54

当我们编写一个函数时，我们希望其他用户能够清楚地理解该函数的预期用途和使用方式。为此，我们可以使用函数参数注解，它可以为函数的参数提供额外的信息。Python 解释器不会对这些注解添加任何语义，它们不会被类型检查，并且在运行时与没有添加注解没有区别。

然而，函数参数注解可以作为一种文档形式，为其他开发者和我们自己提供有价值的信息。它们可以说明每个参数的预期类型、允许的值和任何其他相关信息。

为了添加函数参数注解，我们使用“->”操作，后跟参数的类型。例如，如果我们有一个接受两个整数作为参数并返回其和的函数，我们可以这样写：

def add_numbers(a: int, b: int) -> int:
    """
    计算两个整数的和。

    Args:
        a (int): 第一个整数。
        b (int): 第二个整数。

    Returns:
        int: 两个整数的和。
    """
    return a + b

在这个例子中，我们指定了 a 和 b 参数的类型为 int，并指定该函数返回一个 int 类型的值。我们还添加了一个文档字符串，它提供了函数的简要、每个参数的以及返回值的描述。

函数参数注解不仅可以提高代码的可读性，还可以作为一种轻量级的形式化文档。它们可以帮助其他开发者快速了解函数的预期行为，而无需深入研究函数的实现细节。

除了函数参数注解之外，我们还可以使用文档注释来提供有关函数的其他信息。文档注释是包含在三引号 (```) 中的字符串，通常放置在函数定义的顶部。它们可以包括有关函数目标、用法、限制和任何其他相关信息的信息。

例如，我们可以将以下文档注释添加到我们的 add_numbers 函数中：

def add_numbers(a: int, b: int) -> int:
    """
    计算两个整数的和。

    此函数接受两个整数作为参数并返回其和。参数必须是整数类型。

    Args:
        a (int): 第一个整数。
        b (int): 第二个整数。

    Returns:
        int: 两个整数的和。

    Raises:
        TypeError: 如果任何参数不是整数类型。

    Examples:
        >>> add_numbers(1, 2)
        3
        >>> add_numbers(3.5, 4.5)
        TypeError: 参数必须是整数类型。
    """
    if not isinstance(a, int) or not isinstance(b, int):
        raise TypeError("参数必须是整数类型。")

    return a + b