PEP 3107 -- 函数注解[译]

本文是PIP 3137的翻译。

背景

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

函数注解的基础知识

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

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

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

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

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

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

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

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

语法

参数

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

def foo(a: expression, b: expression = 5):
    ...