Function Anonotations (Python 3)

简介

Function annotations是Python 3的一项特性，可以让用户为函数添加任意的元数据，功能类似于Python 2中的docstrings。总之function annotations可以为用户带来一定的便利，但不是必须的，没有它也可以工作。

示例

下面是一个foo()函数，其作用就是简单的加和三个参数，并且不返回任何值。

• 第一个参数a没有任何注释
• 第二个参数b的注释是一个字符串
• 第三个参数c的注释是int型
• 返回值注释为fload型

def foo(a, b: 'annotating b', c: int) -> float:
    print(a + b + c)

传入不同类型参数的调用结果如下：

foo('Hello', ', ', 'World!')
Hello, World!

foo(1, 2, 3)
6

对比定义和调用结果可以得到一下几点：

• 参数的注释用:声明
• 返回值的注释用->声明
• 注释可以是字符串也可以是数据类型
• 注释在代码调用时似乎并没有强制传入的参数型，看起来似乎没有其作用

默认参数值

在使用function annotations时，默认参数放在注释后面：

def foo(x: 'an argument that defaults to 5' = 5):
    print(x)

foo(7)
7

foo()
5

获取Function Annotations

函数对象有一个__annotations__属性，其将参数名何其对应的注释一映射的方式存储：

def foo(a, b: 'annotating b', c: int) -> float:
    print(a + b + c)

print(foo.__annotations__)
{'c': <class 'int'>, 'b': 'annotating b', 'return': <class 'float'>}

其中返回值在映射中的关键词为'return'。

多中注释并存

Function annotations也支持同时标注多种类型的注释，例如type和help string，如下：

def div(a: dict(type=float, help='the dividend'),
        b: dict(type=float, help='the divisor (must be different than 0)')
    ) -> dict(type=float, help='the result of dividing a by b'):
    """Divide a by b"""
    return a / b

print(div.__annotations__)
{'a': {'help': 'the dividend', 'type': float},
 'b': {'help': 'the divisor (must be different than 0)', 'type': float},
 'return': {'help': 'the result of dividing a by b', 'type': float}}

可以用Function Annotations做什么

如前所说function annotations不是必须的，但确实可以带来一些便利，比如可以为函数提供格式更规范的文档信息，如下，

Docstrings方式：

def div(a, b):
    """Divide a by b  
    args:
        a - the dividend
        b - the divisor (must be different than 0)
    return:
        the result of dividing a by b
    """
    return a / b

Function Annotations方式：

def div(a: 'the dividend',
        b: 'the divisor (must be different than 0)') -> 'the result of dividing a by b':
    """Divide a by b"""
    return a / b

另一方面可以将function annotations与decorators一齐使用等等。

TODO

Function Annotations与Decorators