python：函数注解（Function Annotations）

函数注解（Function Annotations）

Python 的函数注解功能允许你为函数定义中的参数以及返回数据类型添加额外的解释性元数据。

在执行函数时，Python 解释器不会考虑这些注解。它们主要用于为程序员提供详细的文档说明，以便在 Python 集成开发环境（IDE）中使用。

虽然你可以使用 Python 的文档字符串（docstring）功能来记录函数的文档，但如果函数的原型发生了某些变化，文档字符串可能会过时。因此，作为 PEP 3107 的结果，Python 引入了注解功能。

https://peps.python.org/pep-3107/

函数注解是完全可选的元数据信息，用于描述用户自定义函数所使用的类型。

注解可以是添加到参数或返回数据类型上的任何有效的 Python 表达式。注解最简单的例子是指定参数的数据类型。

注解被存储在函数的 __annotations__ 属性中，作为一个字典，并且对函数的任何其他部分都没有影响。

函数参数的类型注解

函数参数的类型注解是通过在参数名后跟一个冒号来定义的，后面跟着一个表达式，该表达式求值为注解的值。
语法：

def 函数名称(形参名: 类型, 形参名: 类型, ...):
	pass

示例：函数参数注解

def my_function(a: int, b: int):
    return a + b

print(my_function(1, 2))
print(my_function('hello', 'world'))

运行输出：

3
helloworld

请记住，Python 是一种动态类型语言，在运行时不会强制执行任何类型检查。因此，用数据类型注解参数在调用函数时不会产生任何影响。即使提供非整数参数，Python 也不会检测到任何错误。

带有返回类型的函数注解

语法：

def 函数名称(形参名: 类型, 形参名: 类型, ...) -> 返回值类型:
	pass

示例

def my_function(a: int, b: int) -> int:
    return a + b


print(my_function(1, 2))
print(my_function.__annotations__)

运行输出：

3
{'a': <class 'int'>, 'b': <class 'int'>, 'return': <class 'int'>}

带有表达式的函数注解

由于在运行时会忽略用作注解的数据类型，因此你可以为参数添加任何作为元数据的表达式。因此，函数可以使用任意表达式作为注解。

示例1：为普通参数添加注解表达式

在下面的例子中，我们使用表达式作为函数注解。

def total(a: '语文分数', b: '数学分数') -> '总分数':
    return a + b


print(total(99, 100))
print(total.__annotations__)

运行输出：

199
{'a': '语文分数', 'b': '数学分数', 'return': '总分数'}

示例2：为任意数量位置参数和任意数量关键字参数添加注解

一个函数可以有任意数量的位置参数和/或关键字参数。也可以为它们添加注解。

def total(*args: '任意数量的位置参数', **kwargs: '任意数量的关键字参数') -> int:
    pass


print(total.__annotations__)

运行输出：

{'args': '任意数量的位置参数', 'kwargs': '任意数量的关键字参数', 'return': <class 'int'>}

示例3：为参数添加多个注解表达式

如果需要为一个函数参数提供多个注解表达式，请以字典对象的形式给出。

def my_divide(num: dict(type=float, msg='分子'), den: dict(type=float, msg='分母')) -> float:
    return num / den

print(my_divide.__annotations__)

运行输出：

{'num': {'type': <class 'float'>, 'msg': '分子'}, 'den': {'type': <class 'float'>, 'msg': '分母'}, 'return': <class 'float'>}

带有默认参数的函数注解

如果你想在注解的同时指定一个默认参数，你需要在注解表达式之后添加它。默认参数必须在参数列表中必选参数之后。

示例1

def total(a: int, b: int = 99) -> int:
    return a + b


print(total(80, 100))
print(total(80))
print(total.__annotations__)

运行输出：

180
179
{'a': <class 'int'>, 'b': <class 'int'>, 'return': <class 'int'>}