PEP 3107 -- 函数注解[译]

本文是PIP 3137的翻译。

背景

Python 2.x系列缺乏一个标准的方式来说明一个函数的参数和返回值,各种工具和库的出现填补了这一空白。一些工具使用了“PEP 318”中的装饰器,而其他的工具则去解析函数的文档注释,寻找注解。 在这一点上,众多已存在的机制和语法造成了很大的混乱。本PEP的目的是提供一个单一的,标准的方式指定这些信息,减少这些混乱。

函数注解的基础知识

在仔细讨论Python 3.0的函数注解的细节之前,首先让我们大致讨论下注解是什么、不是什么:

  1. 函数注解,无论是对参数的还是对返回值的函数注解,完全是可选的。

  2. 函数注解无非是一种方法,用来在编译时将任意Python表达式和函数的不同部分关联起来。就这点而言,Python并没有给注解赋予特殊的意义和重要性。Python仅仅让这些表达式可以被访问而已,以一种像本文的“访问函数注解”中描述的方法。注解对含义产生作用的唯一方式是当它们被第三方库解释的时候。这些注解的使用者可以用这些函数注解做他们想做的任何事情。例如,一个库可以利用字符串类型的注解来提供改进过的帮助信息:

    1
    2
    3
    4
    def compile(source: "something compilable",
    filename: "where the compilable thing comes from",
    mode: "is this a single statement or a suite?"):
    ...

    另一个库可以用来提供Python函数和方法的类型检查。这个库可以使用注解来说明函数的预期输入和返回值的类型:

    1
    2
    def haul(item: Haulable, \*vargs: PackAnimal) -> Distance:
    ...

    然而,不论是第一个例子中的字符串还是第二个例子中的类型信息,它们自己没有任何含义;含义来自第三方库。

  3. 根据第二点,该PEP不会试图引入一种标准的语义,即使是为那些内置类型。这个工作留给第三方库。

语法

参数

对参数的注解跟随着参数名,采用了一种可选表达式的形式:

1
2
def foo(a: expression, b: expression = 5):
...
阅读更多