非目标

虽然提议的 typing 模块将包含一些用于运行时类型检查的构建块——特别是 get_type_hints() 函数——但将需要开发第三方包来实现特定的运行时类型检查功能，例如使用装饰器或元类。使用类型提示进行性能优化留给读者作为练习。

还应该强调的是，**Python 将仍然是一种动态类型语言，并且作者不希望将类型提示强制为强制性，即使是通过约定也是如此。**

可接受的类型提示

类型提示可以是内置类（包括在标准库或第三方扩展模块中定义的类）、抽象基类、在 types 模块中可用的类型以及用户定义的类（包括在标准库或第三方模块中定义的类）。

虽然注解通常是类型提示的最佳格式，但在某些情况下，使用特殊注释或在单独分发的存根文件中表示它们更合适。（请参阅以下示例。）

注解必须是有效的表达式，在定义函数时进行求值不会引发异常（但请参阅以下前向引用）。

注解应保持简单，否则静态分析工具可能无法解释这些值。例如，动态计算的类型不太可能被理解。（这是一个有意模糊的要求，具体包含和排除可能会根据讨论添加到本 PEP 的未来版本中。）

除了以上内容外，还可以使用以下定义的特殊结构：None、Any、Union、Tuple、Callable，所有 ABC 和来自 typing 的具体类的替身（例如 Sequence 和 Dict），类型变量和类型别名。

所有新引入的用于支持以下章节中描述的功能的名称（例如 Any 和 Union）都可以在 typing 模块中找到。

使用 None

在类型提示中使用时，表达式 None 被认为等价于 type(None)。

类型别名

类型别名通过简单的变量赋值来定义。

Url = str

def retry(url: Url, retry_count: int) -> None: ...

请注意，我们建议将别名名称大写，因为它们代表用户定义的类型，而用户定义的类型（如用户定义的类）通常以这种方式拼写。

类型别名可以像注释中的类型提示一样复杂——任何可以作为类型提示接受的内容都可以在类型别名中接受。

from typing import TypeVar, Iterable, Tuple

T = TypeVar('T', int, float, complex)
Vector = Iterable[Tuple[T, T]]

def inproduct(v: Vector[T]) -> T:
    return sum(x*y for x, y in v)
def dilate(v: Vector[T], scale: T) -> Vector[T]:
    return ((x * scale, y * scale) for x, y in v)
vec = []  # type: Vector[float]

这等价于

from typing import TypeVar, Iterable, Tuple

T = TypeVar('T', int, float, complex)

def inproduct(v: Iterable[Tuple[T, T]]) -> T:
    return sum(x*y for x, y in v)
def dilate(v: Iterable[Tuple[T, T]], scale: T) -> Iterable[Tuple[T, T]]:
    return ((x * scale, y * scale) for x, y in v)
vec = []  # type: Iterable[Tuple[float, float]]

可调用对象

期望特定签名的回调函数的框架可以使用 Callable[[Arg1Type, Arg2Type], ReturnType] 进行类型提示。示例

from typing import Callable

def feeder(get_next_item: Callable[[], str]) -> None:
    # Body

def async_query(on_success: Callable[[int], None],
                on_error: Callable[[int, Exception], None]) -> None:
    # Body

可以通过用文字省略号（三个点）替换参数列表来声明可调用对象的返回类型，而无需指定调用签名。

def partial(func: Callable[..., str], *args) -> Callable[..., str]:
    # Body

请注意，省略号周围没有方括号。在这种情况下，回调的参数完全不受约束（并且关键字参数是可以接受的）。

由于使用带关键字参数的回调不被认为是常见用例，因此目前不支持使用 Callable 指定关键字参数。类似地，也不支持使用特定类型的可变数量的参数指定回调签名。

因为 typing.Callable 同时充当 collections.abc.Callable 的替代品，所以 isinstance(x, typing.Callable) 的实现是委托给 isinstance(x, collections.abc.Callable)。但是，不支持 isinstance(x, typing.Callable[...])。

泛型

由于无法以通用方式静态推断容器中保存的对象的类型信息，因此扩展了抽象基类以支持订阅以表示容器元素的预期类型。示例

from typing import Mapping, Set

def notify_by_email(employees: Set[Employee], overrides: Mapping[str, str]) -> None: ...

可以使用 typing 中名为 TypeVar 的新工厂来参数化泛型。示例

from typing import Sequence, TypeVar

T = TypeVar('T')      # Declare type variable

def first(l: Sequence[T]) -> T:   # Generic function
    return l[0]

在这种情况下，约定是返回值与集合中保存的元素一致。

TypeVar() 表达式必须始终直接赋值给变量（它不应该用作较大表达式的部分）。TypeVar() 的参数必须是与其赋值的变量名称相同的字符串。类型变量不能重新定义。

TypeVar 支持将参数类型约束到一组固定的可能类型（注意：这些类型不能由类型变量参数化）。例如，我们可以定义一个仅在 str 和 bytes 之间变化的类型变量。默认情况下，类型变量在所有可能的类型上变化。约束类型变量的示例

from typing import TypeVar, Text

AnyStr = TypeVar('AnyStr', Text, bytes)

def concat(x: AnyStr, y: AnyStr) -> AnyStr:
    return x + y

函数 concat 可以使用两个 str 参数或两个 bytes 参数调用，但不能混合使用 str 和 bytes 参数。

如果有任何约束，则至少应有两个约束；不允许指定单个约束。

类型变量约束的类型的子类型应在类型变量的上下文中被视为其各自明确列出的基类型。考虑此示例

class MyStr(str): ...

x = concat(MyStr('apple'), MyStr('pie'))

该调用有效，但类型变量 AnyStr 将被设置为 str 而不是 MyStr。实际上，分配给 x 的返回值的推断类型也将是 str。

此外，Any 是每个类型变量的有效值。考虑以下情况

def count_truthy(elements: List[Any]) -> int:
    return sum(1 for elem in elements if elem)

这等价于省略泛型表示法，只说 elements: List。

用户定义的泛型类型

您可以包含一个 Generic 基类来将用户定义的类定义为泛型。示例

from typing import TypeVar, Generic
from logging import Logger

T = TypeVar('T')

class LoggedVar(Generic[T]):
    def __init__(self, value: T, name: str, logger: Logger) -> None:
        self.name = name
        self.logger = logger
        self.value = value

    def set(self, new: T) -> None:
        self.log('Set ' + repr(self.value))
        self.value = new

    def get(self) -> T:
        self.log('Get ' + repr(self.value))
        return self.value

    def log(self, message: str) -> None:
        self.logger.info('{}: {}'.format(self.name, message))

Generic[T] 作为基类定义类 LoggedVar 采用单个类型参数 T。这也使 T 在类体中作为类型有效。

Generic 基类使用一个元类来定义 __getitem__，以便 LoggedVar[t] 作为类型有效。

from typing import Iterable

def zero_all_vars(vars: Iterable[LoggedVar[int]]) -> None:
    for var in vars:
        var.set(0)

泛型类型可以具有任意数量的类型变量，并且类型变量可以被约束。这是有效的

from typing import TypeVar, Generic
...

T = TypeVar('T')
S = TypeVar('S')

class Pair(Generic[T, S]):
    ...

Generic 的每个类型变量参数都必须是不同的。因此，这是无效的

from typing import TypeVar, Generic
...

T = TypeVar('T')

class Pair(Generic[T, T]):   # INVALID
    ...

在您继承其他一些泛型类并为其参数指定类型变量的简单情况下，Generic[T] 基类是冗余的

from typing import TypeVar, Iterator

T = TypeVar('T')

class MyIter(Iterator[T]):
    ...

该类定义等价于

class MyIter(Iterator[T], Generic[T]):
    ...

您可以将 Generic 与多重继承一起使用。

from typing import TypeVar, Generic, Sized, Iterable, Container, Tuple

T = TypeVar('T')

class LinkedList(Sized, Generic[T]):
    ...

K = TypeVar('K')
V = TypeVar('V')

class MyMapping(Iterable[Tuple[K, V]],
                Container[Tuple[K, V]],
                Generic[K, V]):
    ...

在不指定类型参数的情况下继承泛型类将为每个位置假设 Any。在以下示例中，MyIterable 不是泛型，但隐式地继承自 Iterable[Any]。

from typing import Iterable

class MyIterable(Iterable):  # Same as Iterable[Any]
    ...

不支持泛型元类。

类型变量的作用域规则

类型变量遵循正常的名称解析规则。但是，在静态类型检查上下文中有一些特殊情况。

• 在泛型函数中使用的类型变量可以在同一代码块中被推断为表示不同的类型。示例

  from typing import TypeVar, Generic
  
  T = TypeVar('T')
  
  def fun_1(x: T) -> T: ...  # T here
  def fun_2(x: T) -> T: ...  # and here could be different
  
  fun_1(1)                   # This is OK, T is inferred to be int
  fun_2('a')                 # This is also OK, now T is str
  

• 在泛型类的某个方法中使用的类型变量，如果与参数化该类的变量之一重合，则始终绑定到该变量。示例

  from typing import TypeVar, Generic
  
  T = TypeVar('T')
  
  class MyClass(Generic[T]):
      def meth_1(self, x: T) -> T: ...  # T here
      def meth_2(self, x: T) -> T: ...  # and here are always the same
  
  a = MyClass()  # type: MyClass[int]
  a.meth_1(1)    # OK
  a.meth_2('a')  # This is an error!
  

• 在方法中使用的类型变量，如果与参数化该类的任何变量都不匹配，则使该方法成为该变量的泛型函数。

  T = TypeVar('T')
  S = TypeVar('S')
  class Foo(Generic[T]):
      def method(self, x: T, y: S) -> S:
          ...
  
  x = Foo()               # type: Foo[int]
  y = x.method(0, "abc")  # inferred type of y is str
  

• 未绑定的类型变量不应该出现在泛型函数的主体中，或者在类主体中除了方法定义之外。

  T = TypeVar('T')
  S = TypeVar('S')
  
  def a_fun(x: T) -> None:
      # this is OK
      y = []  # type: List[T]
      # but below is an error!
      y = []  # type: List[S]
  
  class Bar(Generic[T]):
      # this is also an error
      an_attr = []  # type: List[S]
  
      def do_something(x: S) -> S:  # this is OK though
          ...
  

• 出现在泛型函数内部的泛型类定义不应使用参数化泛型函数的类型变量。

  from typing import List
  
  def a_fun(x: T) -> None:
  
      # This is OK
      a_list = []  # type: List[T]
      ...
  
      # This is however illegal
      class MyGeneric(Generic[T]):
          ...
  

• 嵌套在另一个泛型类中的泛型类不能使用相同的类型变量。外部类的类型变量的作用域不涵盖内部类。

  T = TypeVar('T')
  S = TypeVar('S')
  
  class Outer(Generic[T]):
      class Bad(Iterable[T]):       # Error
          ...
      class AlsoBad:
          x = None  # type: List[T] # Also an error
  
      class Inner(Iterable[S]):     # OK
          ...
      attr = None  # type: Inner[T] # Also OK
  

实例化泛型类和类型擦除

用户定义的泛型类可以被实例化。假设我们编写了一个继承自 Generic[T] 的 Node 类

from typing import TypeVar, Generic

T = TypeVar('T')

class Node(Generic[T]):
    ...

要创建 Node 实例，您可以像普通类一样调用 Node()。在运行时，实例的类型（类）将是 Node。但是对于类型检查器来说，它是什么类型？答案取决于调用中提供了多少信息。如果构造函数（__init__ 或 __new__）在其签名中使用 T，并且传递了相应的参数值，则替换相应参数的类型。否则，将假定为 Any。示例

from typing import TypeVar, Generic

T = TypeVar('T')

class Node(Generic[T]):
    x = None  # type: T # Instance attribute (see below)
    def __init__(self, label: T = None) -> None:
        ...

x = Node('')  # Inferred type is Node[str]
y = Node(0)   # Inferred type is Node[int]
z = Node()    # Inferred type is Node[Any]

如果推断的类型使用 [Any]，但预期类型更具体，则可以使用类型注释（见下文）强制变量的类型，例如

# (continued from previous example)
a = Node()  # type: Node[int]
b = Node()  # type: Node[str]

或者，您可以实例化一个特定的具体类型，例如

# (continued from previous example)
p = Node[int]()
q = Node[str]()
r = Node[int]('')  # Error
s = Node[str](0)   # Error

请注意，p 和 q 的运行时类型（类）仍然只是 Node——Node[int] 和 Node[str] 是可区分的类对象，但通过实例化它们创建的对象的运行时类不会记录这种区别。这种行为称为“类型擦除”；在具有泛型的语言（例如 Java、TypeScript）中，这是一种常见的做法。

使用泛型类（参数化或非参数化）访问属性将导致类型检查失败。在类定义体之外，不能分配类属性，并且只能通过访问没有同名实例属性的类实例来查找类属性。

# (continued from previous example)
Node[int].x = 1  # Error
Node[int].x      # Error
Node.x = 1       # Error
Node.x           # Error
type(p).x        # Error
p.x              # Ok (evaluates to None)
Node[int]().x    # Ok (evaluates to None)
p.x = 1          # Ok, but assigning to instance attribute

抽象集合（如 Mapping 或 Sequence）的泛型版本以及内置类的泛型版本——List、Dict、Set 和 FrozenSet——不能被实例化。但是，它们的具体用户定义子类和具体集合的泛型版本可以被实例化。

data = DefaultDict[int, bytes]()

请注意，不应混淆静态类型和运行时类。在这种情况下，类型仍然会被擦除，上述表达式只是以下表达式的简写形式：

data = collections.defaultdict()  # type: DefaultDict[int, bytes]

不建议在表达式中直接使用带下标的类（例如 Node[int]）——而是建议使用类型别名（例如 IntNode = Node[int]）。（首先，创建带下标的类（例如 Node[int]）会产生运行时成本。其次，使用类型别名更具可读性。）

任意泛型类型作为基类

Generic[T] 仅作为基类有效 - 它不是一个正确的类型。但是，用户定义的泛型类型（例如上述示例中的 LinkedList[T]）以及内置泛型类型和 ABC（例如 List[T] 和 Iterable[T]）既可以作为类型，也可以作为基类。例如，我们可以定义一个 Dict 的子类，它专门化类型参数

from typing import Dict, List, Optional

class Node:
    ...

class SymbolTable(Dict[str, List[Node]]):
    def push(self, name: str, node: Node) -> None:
        self.setdefault(name, []).append(node)

    def pop(self, name: str) -> Node:
        return self[name].pop()

    def lookup(self, name: str) -> Optional[Node]:
        nodes = self.get(name)
        if nodes:
            return nodes[-1]
        return None

SymbolTable 是 dict 的子类，也是 Dict[str, List[Node]] 的子类型。

如果泛型基类具有类型变量作为类型参数，则这使得定义的类成为泛型。例如，我们可以定义一个可迭代且是容器的泛型 LinkedList 类

from typing import TypeVar, Iterable, Container

T = TypeVar('T')

class LinkedList(Iterable[T], Container[T]):
    ...

现在 LinkedList[int] 是一个有效的类型。请注意，我们可以在基类列表中多次使用 T，只要我们在 Generic[...] 中不多次使用相同的类型变量 T 即可。

另请考虑以下示例

from typing import TypeVar, Mapping

T = TypeVar('T')

class MyDict(Mapping[str, T]):
    ...

在这种情况下，MyDict 只有一个参数 T。

抽象泛型类型

Generic 使用的元类是 abc.ABCMeta 的子类。泛型类可以通过包含抽象方法或属性来成为 ABC，并且泛型类也可以具有 ABC 作为基类，而不会发生元类冲突。

具有上限的类型变量

类型变量可以使用 bound=<type> 指定上限（注意：<type> 本身不能被类型变量参数化）。这意味着为类型变量替换的实际类型（显式或隐式）必须是边界类型的子类型。示例

from typing import TypeVar, Sized

ST = TypeVar('ST', bound=Sized)

def longer(x: ST, y: ST) -> ST:
    if len(x) > len(y):
        return x
    else:
        return y

longer([1], [1, 2])  # ok, return type List[int]
longer({1}, {1, 2})  # ok, return type Set[int]
longer([1], {1, 2})  # ok, return type Collection[int]

上限不能与类型约束结合使用（如使用 AnyStr，请参阅前面的示例）；类型约束导致推断的类型 _正好_ 是约束类型之一，而上限仅要求实际类型是边界类型的子类型。

协变和逆变

考虑一个具有子类 Manager 的类 Employee。现在假设我们有一个函数，其参数用 List[Employee] 进行注释。我们是否应该允许使用类型为 List[Manager] 的变量作为其参数来调用此函数？许多人会毫不犹豫地回答“是的，当然”，甚至不考虑后果。但除非我们了解有关该函数的更多信息，否则类型检查器应该拒绝此类调用：该函数可能会将一个 Employee 实例附加到列表中，这将违反调用方中变量的类型。

事实证明，此类参数的行为是逆变的，而直观的答案（在函数不修改其参数的情况下是正确的！）要求参数的行为是协变的。可以在 Wikipedia 和 PEP 483 中找到对这些概念的更详细介绍；在这里，我们只展示如何控制类型检查器的行为。

默认情况下，泛型类型在所有类型变量中都被认为是不变的，这意味着使用类似 List[Employee] 的类型注释的变量的值必须与类型注释完全匹配 - 不允许类型参数（在此示例中为 Employee）的子类或超类。

为了便于声明在协变或逆变类型检查可接受的容器类型，类型变量接受关键字参数 covariant=True 或 contravariant=True。最多只能传递其中一个。使用此类变量定义的泛型类型在相应的变量中被认为是协变或逆变的。按照惯例，建议使用以 _co 结尾的名称来表示使用 covariant=True 定义的类型变量，并使用以 _contra 结尾的名称来表示使用 contravariant=True 定义的类型变量。

一个典型的示例涉及定义一个不可变（或只读）容器类

from typing import TypeVar, Generic, Iterable, Iterator

T_co = TypeVar('T_co', covariant=True)

class ImmutableList(Generic[T_co]):
    def __init__(self, items: Iterable[T_co]) -> None: ...
    def __iter__(self) -> Iterator[T_co]: ...
    ...

class Employee: ...

class Manager(Employee): ...

def dump_employees(emps: ImmutableList[Employee]) -> None:
    for emp in emps:
        ...

mgrs = ImmutableList([Manager()])  # type: ImmutableList[Manager]
dump_employees(mgrs)  # OK

typing 中的只读集合类在其类型变量中都声明为协变（例如 Mapping 和 Sequence）。可变集合类（例如 MutableMapping 和 MutableSequence）声明为不变的。逆变类型的一个示例是 Generator 类型，它在 send() 参数类型中是逆变的（见下文）。

注意：协变或逆变不是类型变量的属性，而是使用此变量定义的泛型类的属性。方差仅适用于泛型类型；泛型函数不具有此属性。后者应仅使用没有 covariant 或 contravariant 关键字参数的类型变量来定义。例如，以下示例没问题

from typing import TypeVar

class Employee: ...

class Manager(Employee): ...

E = TypeVar('E', bound=Employee)

def dump_employee(e: E) -> None: ...

dump_employee(Manager())  # OK

而以下操作是被禁止的

B_co = TypeVar('B_co', covariant=True)

def bad_func(x: B_co) -> B_co:  # Flagged as error by a type checker
    ...

数字塔

PEP 3141 定义了 Python 的数字塔，stdlib 模块 numbers 实现了相应的 ABC（Number、Complex、Real、Rational 和 Integral）。这些 ABC 存在一些问题，但内置的具体数值类 complex、float 和 int 随处可见（尤其是后两者 :-）。

此 PEP 建议使用一种简单的快捷方式，而不是要求用户编写 import numbers 然后使用 numbers.Float 等，这种快捷方式几乎同样有效：当参数被注释为具有类型 float 时，类型为 int 的参数是可以接受的；类似地，对于注释为具有类型 complex 的参数，类型为 float 或 int 的参数是可以接受的。这不会处理实现相应 ABC 的类或 fractions.Fraction 类，但我们认为这些用例非常罕见。

前向引用

当类型提示包含尚未定义的名称时，该定义可以用字符串文字表示，以便稍后解析。

这种情况通常发生在容器类的定义中，其中正在定义的类出现在某些方法的签名中。例如，以下代码（简单二叉树实现的开头）不起作用

class Tree:
    def __init__(self, left: Tree, right: Tree):
        self.left = left
        self.right = right

为了解决这个问题，我们编写

class Tree:
    def __init__(self, left: 'Tree', right: 'Tree'):
        self.left = left
        self.right = right

字符串文字应该包含一个有效的 Python 表达式（即，compile(lit, '', 'eval') 应该是一个有效的代码对象），并且在模块完全加载后应该能够无错误地进行评估。对其进行评估的局部和全局命名空间应与在其中评估相同函数的默认参数的命名空间相同。

此外，表达式应可解析为有效的类型提示，即，它受上面“可接受的类型提示”一节中的规则约束。

允许将字符串文字用作类型提示的一部分，例如

class Tree:
    ...
    def leaves(self) -> List['Tree']:
        ...

前向引用的一种常见用法是，例如，在签名中需要 Django 模型。通常，每个模型都在一个单独的文件中，并且具有接受类型涉及其他模型的参数的方法。由于 Python 中循环导入的工作方式，通常无法直接导入所有需要的模型

# File models/a.py
from models.b import B
class A(Model):
    def foo(self, b: B): ...

# File models/b.py
from models.a import A
class B(Model):
    def bar(self, a: A): ...

# File main.py
from models.a import A
from models.b import B

假设首先导入 main，这将在 models/b.py 中的 from models.a import A 行引发 ImportError，该行在 models/a.py 导入 models/b.py 之前，而 a 尚未定义类 A。解决方案是切换到仅模块导入并通过其 _module_._class_ 名称引用模型

# File models/a.py
from models import b
class A(Model):
    def foo(self, b: 'b.B'): ...

# File models/b.py
from models import a
class B(Model):
    def bar(self, a: 'a.A'): ...

# File main.py
from models.a import A
from models.b import B

联合类型

由于为单个参数接受一小组预期类型很常见，因此有一个名为 Union 的新特殊工厂。示例

from typing import Union

def handle_employees(e: Union[Employee, Sequence[Employee]]) -> None:
    if isinstance(e, Employee):
        e = [e]
    ...

由 Union[T1, T2, ...] 构成的类型是所有类型 T1、T2 等的超类型，因此对于由 Union[T1, T2, ...] 注释的参数，属于这些类型之一的值是可以接受的。

联合类型的一种常见情况是可选类型。默认情况下，None 对于任何类型都是无效值，除非在函数定义中提供了 None 的默认值。示例

def handle_employee(e: Union[Employee, None]) -> None: ...

作为 Union[T1, None] 的简写，您可以编写 Optional[T1]；例如，以上等价于

from typing import Optional

def handle_employee(e: Optional[Employee]) -> None: ...

此 PEP 的过去版本允许类型检查器在默认值为 None 时假设可选类型，如下面的代码所示

def handle_employee(e: Employee = None): ...

这将被视为等价于

def handle_employee(e: Optional[Employee] = None) -> None: ...

这不再是推荐的行为。类型检查器应该转向要求显式说明可选类型。

在联合类型中支持单例类型

单例实例经常用于标记某些特殊条件，尤其是在None也是变量有效值的情况下。示例

_empty = object()

def func(x=_empty):
    if x is _empty:  # default argument value
        return 0
    elif x is None:  # argument was provided and it's None
        return 1
    else:
        return x * 2

为了在这种情况下允许精确类型检查，用户应该将Union类型与标准库提供的enum.Enum类结合使用，以便可以在静态时捕获类型错误。

from typing import Union
from enum import Enum

class Empty(Enum):
    token = 0
_empty = Empty.token

def func(x: Union[int, None, Empty] = _empty) -> int:

    boom = x * 42  # This fails type check

    if x is _empty:
        return 0
    elif x is None:
        return 1
    else:  # At this point typechecker knows that x can only have type int
        return x * 2

由于Enum的子类不能进一步被子类化，因此在上述示例的所有分支中都可以静态推断变量x的类型。如果需要多个单例对象，则可以使用具有多个值的枚举，方法相同。

class Reason(Enum):
    timeout = 1
    error = 2

def process(response: Union[str, Reason] = '') -> str:
    if response is Reason.timeout:
        return 'TIMEOUT'
    elif response is Reason.error:
        return 'ERROR'
    else:
        # response can be only str, all other possible values exhausted
        return 'PROCESSED: ' + response

Any 类型

一种特殊的类型是Any。每种类型都与Any一致。可以将其视为包含所有值和所有方法的类型。请注意，Any和内置类型object是完全不同的。

当值的类型为object时，类型检查器将拒绝对其进行几乎所有操作，并将它赋值给更专业类型的变量（或用作返回值）将是类型错误。另一方面，当值类型为Any时，类型检查器将允许对其进行所有操作，并且Any类型的值可以赋值给更受约束类型的变量（或用作返回值）。

没有注释的函数参数被假定为使用Any进行注释。如果使用泛型类型但未指定类型参数，则假定它们为Any。

from typing import Mapping

def use_map(m: Mapping) -> None:  # Same as Mapping[Any, Any]
    ...

此规则也适用于Tuple，在注释上下文中它等效于Tuple[Any, ...]，进而等效于tuple。同样，注释中的裸Callable等效于Callable[..., Any]，进而等效于collections.abc.Callable。

from typing import Tuple, List, Callable

def check_args(args: Tuple) -> bool:
    ...

check_args(())           # OK
check_args((42, 'abc'))  # Also OK
check_args(3.14)         # Flagged as error by a type checker

# A list of arbitrary callables is accepted by this function
def apply_callbacks(cbs: List[Callable]) -> None:
    ...

NoReturn 类型

typing模块提供了一种特殊的类型NoReturn来注释永远不会正常返回的函数。例如，无条件引发异常的函数。

from typing import NoReturn

def stop() -> NoReturn:
    raise RuntimeError('no way')

NoReturn注释用于诸如sys.exit之类的函数。静态类型检查器将确保注释为返回NoReturn的函数确实永远不会返回，无论是隐式还是显式。

import sys
from typing import NoReturn

  def f(x: int) -> NoReturn:  # Error, f(0) implicitly returns None
      if x != 0:
          sys.exit(1)

检查器还将识别此类函数调用之后的代码是无法访问的，并将相应地进行处理。

# continue from first example
def g(x: int) -> int:
    if x > 0:
        return x
    stop()
    return 'whatever works'  # Error might be not reported by some checkers
                             # that ignore errors in unreachable blocks

NoReturn类型仅在函数的返回注释中有效，如果出现在其他位置则被视为错误。

from typing import List, NoReturn

# All of the following are errors
def bad1(x: NoReturn) -> int:
    ...
bad2 = None  # type: NoReturn
def bad3() -> List[NoReturn]:
    ...

类对象的类型

有时您想讨论类对象，特别是从给定类继承的类对象。这可以写成Type[C]，其中C是一个类。澄清一下：当C（用作注释时）指的是类C的实例时，Type[C]指的是C的子类。（这与object和type之间的区别类似。）

例如，假设我们有以下类：

class User: ...  # Abstract base for User classes
class BasicUser(User): ...
class ProUser(User): ...
class TeamUser(User): ...

并假设我们有一个函数，如果传递给它一个类对象，它将创建一个这些类之一的实例：

def new_user(user_class):
    user = user_class()
    # (Here we could write the user object to a database)
    return user

如果没有Type[]，我们对new_user()进行注释的最佳方法是：

def new_user(user_class: type) -> User:
    ...

但是，使用Type[]和具有上限的类型变量，我们可以做得更好：

U = TypeVar('U', bound=User)
def new_user(user_class: Type[U]) -> U:
    ...

现在，当我们使用User的特定子类调用new_user()时，类型检查器将推断结果的正确类型。

joe = new_user(BasicUser)  # Inferred type is BasicUser

对应于Type[C]的值必须是C的子类型的实际类对象，而不是特殊形式。换句话说，在上面的示例中，调用例如new_user(Union[BasicUser, ProUser])会被类型检查器拒绝（除了在运行时失败，因为您不能实例化联合）。

请注意，将类的联合用作Type[]的参数是合法的，例如：

def new_non_team_user(user_class: Type[Union[BasicUser, ProUser]]):
    user = new_user(user_class)
    ...

但是，在运行时传递的实际参数仍然必须是具体的类对象，例如在上面的示例中：

new_non_team_user(ProUser)  # OK
new_non_team_user(TeamUser)  # Disallowed by type checker

Type[Any]也受支持（有关其含义，请参见下文）。

Type[T]（其中T是类型变量）在注释类方法的第一个参数时是允许的（请参阅相关部分）。

任何其他特殊构造，如Tuple或Callable，都不允许作为Type的参数。

此功能存在一些问题：例如，当new_user()调用user_class()时，这意味着User的所有子类都必须在其构造函数签名中支持此功能。但是，这并非Type[]独有：类方法也有类似的问题。类型检查器应该标记此类假设的违规情况，但默认情况下，与指示的基类（上例中的User）中的构造函数签名匹配的构造函数调用应该被允许。包含复杂或可扩展类层次结构的程序也可以通过使用工厂类方法来处理此问题。此 PEP 的未来修订版可能会引入更好的方法来解决这些问题。

当Type被参数化时，它需要恰好一个参数。没有括号的普通Type等效于Type[Any]，而这又等效于type（Python 元类层次结构的根）。这种等价性也促使了名称Type，而不是诸如Class或SubType之类的替代方案，这些方案是在此功能正在讨论时提出的；这类似于例如List和list之间的关系。

关于Type[Any]（或Type或type）的行为，访问具有此类型的变量的属性只会提供由type定义的属性和方法（例如，__repr__()和__mro__）。此类变量可以用任意参数调用，并且返回值为Any。

Type在其参数中是协变的，因为Type[Derived]是Type[Base]的子类型。

def new_pro_user(pro_user_class: Type[ProUser]):
    user = new_user(pro_user_class)  # OK
    ...

注解实例方法和类方法

在大多数情况下，类和实例方法的第一个参数不需要进行注释，并且假定它对实例方法具有包含类的类型，对类方法具有对应于包含类对象的类型对象类型。此外，实例方法中的第一个参数可以用类型变量进行注释。在这种情况下，返回类型可以使用相同的类型变量，从而使该方法成为泛型函数。例如：

T = TypeVar('T', bound='Copyable')
class Copyable:
    def copy(self: T) -> T:
        # return a copy of self

class C(Copyable): ...
c = C()
c2 = c.copy()  # type here should be C

这同样适用于在第一个参数的注释中使用Type[]的类方法。

T = TypeVar('T', bound='C')
class C:
    @classmethod
    def factory(cls: Type[T]) -> T:
        # make a new instance of cls

class D(C): ...
d = D.factory()  # type here should be D

请注意，一些类型检查器可能会对此使用施加限制，例如要求使用适当的上限类型变量（请参见示例）。

版本和平台检查

类型检查器预计会理解简单的版本和平台检查，例如：

import sys

if sys.version_info[0] >= 3:
    # Python 3 specific definitions
else:
    # Python 2 specific definitions

if sys.platform == 'win32':
    # Windows specific definitions
else:
    # Posix specific definitions

不要期望检查器理解诸如"".join(reversed(sys.platform)) == "xunil"之类的混淆。

运行时类型检查还是静态类型检查？

有时，某些代码必须由类型检查器（或其他静态分析工具）看到，但不能执行。对于这种情况，typing模块定义了一个常量TYPE_CHECKING，在类型检查（或其他静态分析）期间它被视为True，但在运行时被视为False。示例：

import typing

if typing.TYPE_CHECKING:
    import expensive_mod

def a_func(arg: 'expensive_mod.SomeClass') -> None:
    a_var = arg  # type: expensive_mod.SomeClass
    ...

（请注意，类型注释必须用引号括起来，使其成为“前向引用”，以从解释器运行时隐藏expensive_mod引用。在# type注释中，不需要引号。）

此方法也可能有助于处理导入循环。

任意参数列表和默认参数值

任意参数列表也可以进行类型注释，以便定义：

def foo(*args: str, **kwds: int): ...

是可以接受的，并且表示例如以下所有内容都表示具有有效参数类型的函数调用：

foo('a', 'b', 'c')
foo(x=1, y=2)
foo('', z=0)

在函数 foo 的主体中，变量 args 的类型被推断为 Tuple[str, ...]，而变量 kwds 的类型为 Dict[str, int]。

在存根文件中，将参数声明为具有默认值而不指定实际的默认值可能很有用。例如

def foo(x: AnyStr, y: AnyStr = ...) -> AnyStr: ...

默认值应该是什么样子？任何选项 ""、b"" 或 None 都无法满足类型约束。

在这种情况下，默认值可以指定为文字省略号，即上述示例就是您要编写的字面意思。

仅位置参数

某些函数被设计为仅以位置方式获取其参数，并期望其调用者永远不要使用参数的名称以关键字方式提供该参数。所有名称以 __ 开头的参数都被假定为仅限位置，除非它们的名称也以 __ 结尾。

def quux(__x: int, __y__: int = 0) -> None: ...

quux(3, __y__=1)  # This call is fine.

quux(__x=3)  # This call is an error.

注解生成器函数和协程

生成器函数的返回类型可以用 typing.py 模块提供的泛型类型 Generator[yield_type, send_type, return_type] 进行注释。

def echo_round() -> Generator[int, float, str]:
    res = yield
    while res:
        res = yield round(res)
    return 'OK'

在 PEP 492 中引入的协程使用与普通函数相同的语法进行注释。但是，返回类型注释对应于 await 表达式的类型，而不是协程类型。

async def spam(ignored: int) -> str:
    return 'spam'

async def foo() -> None:
    bar = await spam(42)  # type: str

该 typing.py 模块提供了 ABC collections.abc.Coroutine 的泛型版本，用于指定也支持 send() 和 throw() 方法的可等待对象。类型变量的方差和顺序与 Generator 的对应，即 Coroutine[T_co, T_contra, V_co]，例如

from typing import List, Coroutine
c = None  # type: Coroutine[List[str], str, int]
...
x = c.send('hi')  # type: List[str]
async def bar() -> None:
    x = await c  # type: int

该模块还提供了泛型 ABC Awaitable、AsyncIterable 和 AsyncIterator，用于无法指定更精确类型的场景。

def op() -> typing.Awaitable[str]:
    if cond:
        return spam(42)
    else:
        return asyncio.Future(...)

函数/方法重载

@overload 装饰器允许描述支持多种不同参数类型组合的函数和方法。这种模式在内置模块和类型中经常使用。例如，bytes 类型的 __getitem__() 方法可以描述如下

from typing import overload

class bytes:
    ...
    @overload
    def __getitem__(self, i: int) -> int: ...
    @overload
    def __getitem__(self, s: slice) -> bytes: ...

这种描述比使用联合类型（无法表达参数和返回类型之间的关系）所能达到的更精确。

from typing import Union

class bytes:
    ...
    def __getitem__(self, a: Union[int, slice]) -> Union[int, bytes]: ...

另一个 @overload 很有用的例子是内置 map() 函数的类型，它根据可调用对象的类型采用不同数量的参数

from typing import Callable, Iterable, Iterator, Tuple, TypeVar, overload

T1 = TypeVar('T1')
T2 = TypeVar('T2')
S = TypeVar('S')

@overload
def map(func: Callable[[T1], S], iter1: Iterable[T1]) -> Iterator[S]: ...
@overload
def map(func: Callable[[T1, T2], S],
        iter1: Iterable[T1], iter2: Iterable[T2]) -> Iterator[S]: ...
# ... and we could add more items to support more than two iterables

请注意，我们还可以轻松地添加项目以支持 map(None, ...)

@overload
def map(func: None, iter1: Iterable[T1]) -> Iterable[T1]: ...
@overload
def map(func: None,
        iter1: Iterable[T1],
        iter2: Iterable[T2]) -> Iterable[Tuple[T1, T2]]: ...

如上所示使用 @overload 装饰器适用于存根文件。在常规模块中，一系列 @overload 装饰的定义必须后跟一个完全不带 @overload 装饰的定义（对于相同的函数/方法）。@overload 装饰的定义仅供类型检查器使用，因为它们将被不带 @overload 装饰的定义覆盖，而后者在运行时使用，但类型检查器应该忽略它。在运行时，直接调用 @overload 装饰的函数将引发 NotImplementedError。以下是一个无法使用联合类型或类型变量轻松表达的非存根重载示例

@overload
def utf8(value: None) -> None:
    pass
@overload
def utf8(value: bytes) -> bytes:
    pass
@overload
def utf8(value: unicode) -> bytes:
    pass
def utf8(value):
    <actual implementation>

注意：虽然可以使用此语法提供多重分派实现，但其实现需要使用 sys._getframe()，这是不推荐的。此外，设计和实现有效的多分派机制是困难的，这就是为什么之前的尝试被放弃而支持 functools.singledispatch()。（参见 PEP 443，特别是其“替代方法”部分。）将来我们可能会提出令人满意的多分派设计，但我们不希望这种设计受存根文件中定义的类型提示重载语法约束。这两个功能也可能彼此独立地发展（因为类型检查器中的重载与运行时的多分派具有不同的用例和需求——例如，后者不太可能支持泛型类型）。

受约束的 TypeVar 类型通常可以代替使用 @overload 装饰器。例如，此存根文件中 concat1 和 concat2 的定义是等效的

from typing import TypeVar, Text

AnyStr = TypeVar('AnyStr', Text, bytes)

def concat1(x: AnyStr, y: AnyStr) -> AnyStr: ...

@overload
def concat2(x: str, y: str) -> str: ...
@overload
def concat2(x: bytes, y: bytes) -> bytes: ...

某些函数，例如上面的 map 或 bytes.__getitem__，无法使用类型变量精确表示。但是，与 @overload 不同，类型变量也可以在存根文件之外使用。我们建议仅在类型变量不足的情况下使用 @overload，因为它具有特殊的仅存根状态。

像 AnyStr 这样的类型变量与使用 @overload 之间的另一个重要区别是，前者还可以用于定义泛型类类型参数的约束。例如，泛型类 typing.IO 的类型参数受到约束（只有 IO[str]、IO[bytes] 和 IO[Any] 是有效的）

class IO(Generic[AnyStr]): ...

存储和分发存根文件

存根文件存储和分发的最简单形式是将它们与同一目录中的 Python 模块放在一起。这使得程序员和工具都易于找到它们。但是，由于包维护人员可以自由地不向其包添加类型提示，因此也支持从 PyPI 通过 pip 安装的第三方存根。在这种情况下，我们必须考虑三个问题：命名、版本控制、安装路径。

本 PEP 没有提供关于第三方存根文件包应该使用的命名方案的建议。可发现性希望基于包的流行度，例如 Django 包。

第三方存根必须使用与之兼容的源包的最低版本进行版本控制。例如：FooPackage 有版本 1.0、1.1、1.2、1.3、2.0、2.1、2.2。版本 1.1、2.0 和 2.2 中存在 API 更改。存根文件包维护人员可以自由地发布所有版本的存根，但至少需要 1.0、1.1、2.0 和 2.2 才能使最终用户检查所有版本的类型。这是因为用户知道最接近的 *低于或等于* 版本的存根是兼容的。在提供的示例中，对于 FooPackage 1.3，用户将选择存根版本 1.1。

请注意，如果用户决定使用“最新”可用的源包，则如果“最新”存根文件经常更新，则通常也应该可以使用它们。

第三方存根包可以使用任何位置进行存根存储。类型检查器应使用 PYTHONPATH 搜索它们。始终检查的一个默认回退目录是 shared/typehints/pythonX.Y/（对于由类型检查器确定的某个 PythonX.Y，而不仅仅是已安装的版本）。由于每个环境中每个给定的 Python 版本只能安装一个包，因此在该目录下不执行其他版本控制（就像 pip 在 site-packages 中执行的裸目录安装一样）。存根文件包作者可能会在 setup.py 中使用以下代码段

...
data_files=[
    (
        'shared/typehints/python{}.{}'.format(*sys.version_info[:2]),
        pathlib.Path(SRC_PATH).glob('**/*.pyi'),
    ),
],
...

（*更新：*截至 2018 年 6 月，分发第三方包类型提示的推荐方法已更改——除了 typeshed（请参阅下一节）之外，现在有一种分发类型提示的标准，PEP 561。它支持单独安装包含存根的包，与包的可执行代码在同一发行版中包含的存根文件，以及内联类型提示，后两种选项通过在包中包含名为 py.typed 的文件来启用。）

Typeshed 代码库

有一个 共享存储库，其中正在收集有用的存根。此处收集的存根的相关策略将单独决定并在存储库的文档中报告。请注意，如果包所有者明确要求省略，则此处不会包含给定包的存根。

泛型类型参数使用什么括号？

大多数人熟悉在 C++、Java、C# 和 Swift 等语言中使用尖括号（例如 List<int>）来表示泛型类型的参数化。这些问题在于它们真的很难解析，特别是对于像 Python 这样简单的解析器。在大多数语言中，歧义通常通过仅在特定语法位置允许尖括号来解决，在这些位置不允许使用通用表达式。（并且还通过使用能够回溯任意代码段的非常强大的解析技术。）

但在 Python 中，我们希望类型表达式（在语法上）与其他表达式相同，以便我们可以使用例如变量赋值来创建类型别名。考虑这个简单的类型表达式

List<int>

从 Python 解析器的角度来看，该表达式以与链式比较相同的四个标记（NAME、LESS、NAME、GREATER）开头

a < b > c  # I.e., (a < b) and (b > c)

我们甚至可以举出一个可以两种方式解析的例子

a < b > [ c ]

假设我们在语言中使用了尖括号，这可以解释为以下两种情况之一

(a<b>)[c]      # I.e., (a<b>).__getitem__(c)
a < b > ([c])  # I.e., (a < b) and (b > [c])

当然有可能想出一个规则来消除此类情况的歧义，但对于大多数用户来说，这些规则会让人感觉武断且复杂。它还需要我们彻底改变 CPython 解析器（以及 Python 的每个其他解析器）。需要注意的是，Python 的当前解析器故意设计为“愚蠢”——简单的语法更容易让用户理解。

由于所有这些原因，方括号（例如 List[int]）是（并且长期以来一直是）泛型类型参数的首选语法。它们可以通过在元类上定义 __getitem__() 方法来实现，并且根本不需要任何新的语法。此选项适用于所有最新版本的 Python（从 Python 2.2 开始）。Python 在这种语法选择上并不孤单——Scala 中的泛型类也使用方括号。

现有注解的用途如何处理？

有一条论点指出，PEP 3107 明确支持在函数注释中使用任意表达式。然后，新的提案被认为与 PEP 3107 的规范不兼容。

我们对此的回应是，首先，当前提案没有引入任何直接的不兼容性，因此在 Python 3.4 中使用注释的程序在 Python 3.5 中仍然可以正确地工作，并且没有任何偏见。

我们确实希望类型提示最终成为注释的唯一用途，但这需要额外的讨论，并在使用 Python 3.5 发布 typing 模块后进行一段弃用期。当前的 PEP 将具有临时状态（请参阅 PEP 411），直到 Python 3.6 发布。最快可行的方案是在 3.6 中引入对非类型提示注释的静默弃用，在 3.7 中完全弃用，并在 Python 3.8 中声明类型提示是注释的唯一允许用途。这应该为使用注释的包的作者提供足够的时间来设计另一种方法，即使类型提示一夜之间获得成功。

（更新：截至 2017 年秋季，此 PEP 及 typing.py 模块的临时状态结束的时间线已更改，其他注释用途的弃用计划也已更改。有关更新的计划，请参阅 PEP 563。）

另一种可能的结果是，类型提示最终将成为注释的默认含义，但始终会保留一个禁用它们的选项。为此，当前提案定义了一个装饰器 @no_type_check，它在给定的类或函数中禁用将注释解释为类型提示的默认解释。它还定义了一个元装饰器 @no_type_check_decorator，可用于装饰装饰器（!），导致用后者装饰的任何函数或类中的注释被类型检查器忽略。

还有 # type: ignore 注释，静态检查器应该支持配置选项以在选定的包中禁用类型检查。

尽管有所有这些选项，但已经发布了一些提案，允许类型提示和其他形式的注释共存以供单个参数使用。一项提案建议，如果给定参数的注释是字典文字，则每个键表示不同的注释形式，并且键 'type' 将用于类型提示。这个想法及其变体的难题在于，表示法变得非常“嘈杂”且难以阅读。此外，在现有库使用注释的大多数情况下，很少需要将它们与类型提示结合起来。因此，选择性地禁用类型提示的更简单方法似乎就足够了。

前向声明的问题

当前的提案在类型提示必须包含前向引用时确实次优。Python 要求在使用名称之前定义所有名称。除了循环导入之外，这很少是一个问题：“使用”在这里指的是“在运行时查找”，并且对于大多数“前向”引用，在确保在调用使用它的函数之前定义名称方面没有问题。

类型提示的问题在于，注释（根据 PEP 3107，类似于默认值）在定义函数时进行评估，因此在注释中使用的任何名称都必须在定义函数时已经定义。一个常见的场景是类定义，其方法需要在其注释中引用类本身。（更一般地，它也可能发生在相互递归的类中。）例如，对于容器类型，这是很自然的

class Node:
    """Binary tree node."""

    def __init__(self, left: Node, right: Node):
        self.left = left
        self.right = right

按原样编写，这将无法工作，因为 Python 的一个特性是类名在执行完类的整个主体后才被定义。我们的解决方案虽然不是特别优雅，但可以完成工作，即允许在注释中使用字符串文字。不过，大多数情况下您不必使用它——预计类型提示的大多数用途都是引用内置类型或在其他模块中定义的类型。

一项反提案将更改类型提示的语义，以便它们根本不会在运行时进行评估（毕竟，类型检查是在脱机进行的，那么类型提示为什么需要在运行时进行评估呢）。这当然会违反向后兼容性，因为 Python 解释器实际上不知道特定注释是类型提示还是其他内容。

一种折衷方案是，__future__ 导入可以启用将给定模块中的所有注释转换为字符串文字，如下所示

from __future__ import annotations

class ImSet:
    def add(self, a: ImSet) -> List[ImSet]: ...

assert ImSet.add.__annotations__ == {'a': 'ImSet', 'return': 'List[ImSet]'}

此类 __future__ 导入语句可能会在单独的 PEP 中提出。

（更新：该 __future__ 导入语句及其后果在 PEP 563 中进行了讨论。）

双冒号

一些有创意的人试图为这个问题发明解决方案。例如，有人建议对类型提示使用双冒号(::)，一次解决两个问题：区分类型提示和其他注释，以及更改语义以排除运行时评估。然而，这个想法有几个问题。

• 它很难看。Python 中的单冒号有很多用途，并且它们看起来都很熟悉，因为它们类似于英语文本中冒号的使用。这是一个 Python 遵守的大多数标点符号形式的经验法则；异常通常来自其他编程语言。但是这种使用::在英语中是闻所未闻的，在其他语言（例如 C++）中，它用作作用域运算符，这是一个非常不同的东西。相反，用于类型提示的单冒号读起来很自然——这不足为奇，因为它就是为此目的而精心设计的（这个想法早于 PEP 3107）。它也以相同的方式在从 Pascal 到 Swift 的其他语言中使用。
• 您将如何处理返回类型注释？
• 类型提示在运行时进行评估实际上是一项功能。
  • 在运行时提供类型提示允许在类型提示之上构建运行时类型检查器。
  • 即使没有运行类型检查器，它也能捕获错误。由于它是一个单独的程序，用户可以选择不运行它（甚至不安装它），但仍然可能希望使用类型提示作为简洁的文档形式。即使用于文档，损坏的类型提示也毫无用处。
• 因为它是一种新的语法，所以使用双冒号进行类型提示会将它们限制在仅适用于 Python 3.5 的代码中。通过使用现有语法，当前提案可以轻松地适用于旧版本的 Python 3。（事实上，mypy 支持 Python 3.2 及更高版本。）
• 如果类型提示获得成功，我们很可能会决定将来添加新的语法来声明变量的类型，例如 var age: int = 42。如果我们要对参数类型提示使用双冒号，为了保持一致性，我们必须对未来的语法使用相同的约定，从而延续这种丑陋。

其他新的语法形式

已经提出了一些其他形式的替代语法，例如 引入 where 关键字和受 Cobra 启发的 requires 子句。但这些都与双冒号存在一个问题：它们不适用于早期版本的 Python 3。新的 __future__ 导入也会出现同样的情况。

其他向后兼容的约定

提出的想法包括

• 装饰器，例如 @typehints(name=str, returns=str)。这可以工作，但它非常冗长（多一行，并且必须重复参数名称），并且与 PEP 3107 表示法相比，优雅程度相差甚远。
• 存根文件。我们确实需要存根文件，但它们主要用于向不适合添加类型提示的现有代码添加类型提示，例如第三方包、需要支持 Python 2 和 Python 3 的代码，尤其是扩展模块。对于大多数情况，将注释与函数定义放在一起会使它们更有用。
• 文档字符串。有一个现有的文档字符串约定，基于 Sphinx 表示法(:type arg1: description)。这非常冗长（每个参数多一行），而且不太优雅。我们也可以想出一些新的东西，但注释语法很难超越（因为它就是为此目的而设计的）。

有人还建议再等待一个版本。但这会解决什么问题？这只会是拖延。