首页 › Python论坛 › PEP 484 类型提示 -- Python官方文档译文 [原创]

九月的虎 發表於 2020-1-22 13:17:00

PEP 484 类型提示 -- Python官方文档译文 [原创]

<blockquote>
<p>英文原文：https://www.python.org/dev/peps/pep-0484/<br>
采集日期：2019-12-27</p>
</blockquote>
<h1 id="pep-484----类型提示type-hints">PEP 484 -- 类型提示（Type Hints）</h1>
<p><strong>PEP</strong>: 484<br>
<strong>Title</strong>: Type Hints<br>
<strong>Author</strong>: Guido van Rossum <guido at="" python.org="">, Jukka Lehtosalo &lt;jukka.lehtosalo at iki.fi&gt;, ?ukasz Langa <lukasz at="" python.org=""><br>
<strong>BDFL-Delegate</strong>: Mark Shannon<br>
<strong>Discussions-To</strong>: Python-Dev <python-dev at="" python.org=""><br>
<strong>Status</strong>: Provisional<br>
<strong>Type</strong>: Standards Track<br>
<strong>Created</strong>: 29-Sep-2014<br>
<strong>Python-Version</strong>: 3.5<br>
<strong>Post-History</strong>: 16-Jan-2015、20-Mar-2015、17-Apr-2015、20-May-2015、22-May-2015<br>
<strong>Resolution</strong>:        https://mail.python.org/pipermail/python-dev/2015-May/140104.html</python-dev></lukasz></guido></p>
<ul>
<li>摘要（Abstract）</li>
<li>原由和目标（Rationale and goals）
<ul>
<li>非本文目标（Non-goals）</li>
</ul>
</li>
<li>注解的含义（The meaning of annotations）</li>
<li>类型定义的语法（Type definition syntax）
<ul>
<li>可接受的类型提示（Acceptable type hints）</li>
<li><code>None</code> 的用法（Using None）</li>
<li>类型别名（Type aliases）</li>
<li>Callable</li>
<li>泛型（Generics）</li>
<li>用户自定义的泛型类型（User-defined generic types）</li>
<li>类型变量的作用域规则（Scoping rules for type variables）</li>
<li>泛型类的实例化及类型清除（Instantiating generic classes and type erasure）</li>
<li>用任意泛型类型作为基类（Arbitrary generic types as base classes）)</li>
<li>抽象泛型类型（Abstract generic types）</li>
<li>带有类型上界的类型变量（Type variables with an upper bound）</li>
<li>协变和逆变（Covariance and contravariance）</li>
<li>数值类型的继承关系（The numeric tower）</li>
<li>向前引用（Forward references）</li>
<li>Union 类型（Union types）</li>
<li>用 Union 实现单实例类型的支持（Support for singleton types in unions）</li>
<li><code>Any</code> 类型（The <code>Any</code> type）</li>
<li><code>NoReturn</code> 类型（The NoReturn type）</li>
<li>类对象的类型（The type of class objects）</li>
<li>为实例和类方法加类型注解（Annotating instance and class methods）</li>
<li>版本和平台检查（Version and platform checking）</li>
<li>运行时检查还是类型检查？(Runtime or type checking?)</li>
<li>可变参数列表和默认参数值（Arbitrary argument lists and default argument values）</li>
<li>只采用位置参数（Positional-only arguments）</li>
<li>注解生成器函数和协程（Annotating generator functions and coroutines）</li>
</ul>
</li>
<li>与函数注解其他用法的兼容性（<br>
Compatibility with other uses of function annotations）</li>
<li>类型注释（Type comments）</li>
<li>指定类型（Cast）</li>
<li><code>NewType</code> 工具函数（NewType helper function）</li>
<li>存根文件（Stub Files）
<ul>
<li>函数/方法重载（Function/method overloading）</li>
<li>存根文件的存储和发布（Storing and distributing stub files）</li>
<li>typeshed 库（The Typeshed Repo）</li>
</ul>
</li>
<li>异常（Exceptions）</li>
<li>typing 模块（The typing Module）</li>
<li>Python 2.7 和跨版本代码的建议语法（Suggested syntax for Python 2.7 and straddling code）</li>
<li>未被接受的替代方案（Rejected Alternatives）
<ul>
<li>泛型参数该用什么括号？（Which brackets for generic type parameters?）</li>
<li>已存在的注解怎么办（What about existing uses of annotations?）</li>
<li>前向声明的问题（The problem of forward declarations）</li>
<li>双冒号（The double colon）</li>
<li>其他一些新语法格式（Other forms of new syntax）</li>
<li>其他的向下兼容约定（Other backwards compatible conventions）</li>
</ul>
</li>
<li>PEP 开发过程（PEP Development Process）</li>
<li>致谢（Acknowledgements）</li>
<li>参考文献（References）</li>
<li>版权（Copyright）</li>
</ul>
<h2 id="摘要abstract">摘要（Abstract）</h2>
<p>PEP 3107 已经引入了函数注解（annotation）的语法，但有意将语义（semantic）保留为未定义（undefined）。目前第三方的静态类型分析应用工具已经足够多了，社区人员采用标准用语和标准库中的基线（baseline）工具就将获益良多。</p>
<p>为了提供标准定义和工具，本 PEP 引入了一个临时（provisional）模块，并且列出了一些不适用注解情形的约定。</p>
<p>请注意，即便注解符合本规范，本 PEP 依然明确不会妨碍注解的其他用法，也不要求（或禁止）对注解进行任何特殊处理。正如 PEP 333 对 Web 框架的约定，这只是为了能更好地相互合作。</p>
<p>比如以下这个简单的函数，其参数和返回类型都在注解给出了声明：</p>
<pre><code>def greeting(name: str) -&gt; str:
    return 'Hello ' + name
</code></pre>
<p>虽然在运行时通过常规的 <code>__annotations__</code> 属性可以访问到上述注解，但运行时并不会进行类型检查。本提案假定存在一个独立的脱机类型检查程序，用户可以自愿对源代码运行此检查程序。这种类型检查程序实质上就是一种非常强大的查错工具（linter）。当然某些用户是可以在运行时采用类似的检查程序实现“契约式设计”或JIT优化，但这些工具尚未完全成熟。</p>
<p>本提案受到 mypy 的强烈启发。例如，“整数序列”类型可以写为 <code>Sequence</code>。方括号表示无需向语言添加新的语法。上述示例用到了自定义类型 <code>Sequence</code>，是从纯 Python 模块 <code>typing</code> 中导入的。通过实现元类（metaclass）中的 <code>__getitem__()</code> 方法，<code>Sequence</code> 表示法在运行时得以生效（但主要是对脱机类型检查程序有意义）。</p>
<p>类型系统支持类型组合（Union）、泛型类型（generic type）和特殊类型 <code>Any</code>，<code>Any</code> 类型可与所有类型相容（即可以赋值给所有类型，也可以从所有类型赋值）。<code>Any</code> 类型的特性取自渐进定型（gradual typing）的理念。渐进定型和全类型系统已在 PEP 483 中有所解释。</p>
<p>在 PEP 482 中，还介绍了其他一些已借鉴或可比较的方案。</p>
<div id="rationale-and-goals">
<h2 id="原由和目标rationale-and-goals">原由和目标（Rationale and Goals）</h2>
<p>PEP 3107已加入了为函数定义中的各个部分添加注解的支持。尽管没有为注解定义什么含义，但已经隐隐有了一个目标，即把注解用于类型提示 gvr-artima，在 PEP 3107 中这被列为第一个可能应用的场景。</p>
<p>本 PEP 旨在为类型注解提供一种标准语法，让 Python 代码更加开放、更易于静态分析和重构，提供一种潜在的运行时类型检查方案，以及（或许在某些上下文中）能利用类型信息生成代码。</p>
<p>在这些目标中，静态分析是最重要的。包括了对 mypy 这类脱机类型检查程序的支持，以及可供 IDE 使用的代码自动补全和重构的标准表示法。</p>
<div id="non-goals">
<h3 id="非本文目标non-goals">非本文目标（Non-goals）</h3>
<p>虽然本提案的 <code>typing</code> 模块将包含一些用于运行时类型检查的功能模块，特别是 <code>get_type_hints()</code> 函数，但必须开发第三方程序包才能实现特定的运行时类型检查功能，比如使用装饰器（decorator）或元类。至于如何利用类型提示进行性能优化，就留给读者当作练习吧。</p>
<p>还有一点应该强调一下，Python 仍将保持为一种动态类型语言，并且按惯例作者从没希望让类型提示成为强制特性。</p>
<div id="meaning-of-annotations">
<h2 id="注解的含义the-meaning-of-annotations">注解的含义（The meaning of annotations）</h2>
<p>不带注解的函数都应被视为其类​​型可能是最通用的，或者应被所有类型检查器忽略的。具有 <code>@no_type_check</code> 装饰器的函数应被视为不带注解的。</p>
<p>建议但不强求被检查函数的全部参数和返回类型都带有注解。被检查函数的参数和返回类型的缺省注解为 <code>Any</code>。不过有一种例外情况，就是实例和类方法的第一个参数。如果未带注解，则假定实例方法第一个参数的类型就是所在类（的类型），而类方法第一个参数的类型则为所在对象类（的类型）。例如，在类 A 中，实例方法第一个参数的类型隐含为 A。在类方法中，第一个参数的精确类型没法用类型注解表示。</p>
<p>请注意，<code>__init__</code> 的返回类型应该用 <code>-&gt; None</code> 进行注解。原因比较微妙。如果假定<code>__init__</code> 缺省用 <code>-&gt; None</code> 作为返回类型注解，那么是否意味着无参数、不带注解的<code>__init__</code> 方法还需要做类型检查？与其任其模棱两可或引入异常，还不如规定 <code>__init__</code> 应该带有返回类型注解，默认表现与其他方法相同。</p>
<p>类型检查程序应该对函数主体和所给注解的一致性进行检查。这些注解还可以用于检查其他被检函数对该函数的调用是否正确。</p>
<p>类型检查程序应该尽力推断出尽可能多的信息。最低要求是能够处理内置装饰器 <code>@ property</code>、<code>@ staticmethod</code> 和 <code>@classmethod</code>。</p>
<div id="type-definition-syntax">
<h2 id="类型定义的语法type-definition-syntax">类型定义的语法（Type definition syntax）</h2>
<p>这里的语法充分利用了 PEP 3107 风格的注解，并加入了以下章节介绍的一些扩展。类型提示的基本格式就是，把类名填入函数注解的位置：</p>
<pre><code>def greeting(name: str) -&gt; str:
    return 'Hello ' + name
</code></pre>
<p>以上表示参数 <code>name</code> 的预期类型为 <code>str</code>。类似地，预期的函数返回类型为 <code>str</code>。</p>
<p>其类型是特定参数类型的子类型的表达式也被该参数接受。</p>
<div id="acceptable-type-hints">
<h3 id="可接受的类型提示acceptable-type-hints">可接受的类型提示（Acceptable type hints）</h3>
<p>类型提示可以是内置类（含标准库或第三方扩展模块中定义的）、抽象基类、<code>types</code> 模块中提供的类型和用户自定义类（含标准库或第三方库中定义的）。</p>
<p>虽然注解通常是类型提示的最佳格式，但有时更适合用特殊注释（comment）或在单独发布的存根文件中表示。示例参见下文。</p>
<p>注解必须是有效的表达式，其求值过程不会让定义函数时引发异常，不过向前引用（forward reference）的用法还请参见下文。</p>
<p>注解应尽量保持简单，否则静态分析工具可能无法对其进行解析。例如，动态计算出来的类型就不大能被理解。本项要求是有意含糊其辞的，根据讨论结果可以在本 PEP 的未来版本中加入某些包含和排除项。</p>
<p>此外，以下结构也是可以用作类型注解的：<code>None</code>、<code>Any</code>、<code>Union</code>、<code>Tuple</code>、<code>Callable</code>、用于构建由 <code>typing</code> 导出的类（如 <code>Sequence</code> 和 <code>Dict</code>）的所有抽象基类（ABC）及其替代物（stand-in）、类型变量和类型别名。</p>
<p>以下章节介绍的特性当中，所有用于提供支持的新引入类型名（例如 <code>Any</code> 和 <code>Union</code>）都在 <code>typing</code> 模块中给出了。</p>
<div id="using-none">
<h3 id="none-的用法using-none"><code>None</code> 的用法（Using None）</h3>
<p>当 <code>None</code> 用于类型提示中时，表达式 <code>None</code> 视作与 <code>type(None)</code> 等价。</p>
<div id="type-aliases">
<h3 id="类型别名type-aliases">类型别名（Type aliases）</h3>
<p>定义类型别名很简单，只要用变量赋值语句即可：</p>
<pre><code>Url = str
def retry(url: Url, retry_count: int) -&gt; None: ...
</code></pre>
<p>请注意，类型别名建议首字母用大写，因为代表的是用户自定义类型，用户自定义的名称（如用户自定义的类）通常都用这种方式拼写。</p>
<p>类型别名的复杂程度可以和注解中的类型提示一样，类型注解可接受的内容在类型别名中均可接受：</p>
<pre><code>from typing import TypeVar, Iterable, Tuple

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

def inproduct(v: Vector) -&gt; T:
    return sum(x*y for x, y in v)
def dilate(v: Vector, scale: T) -&gt; Vector:
    return ((x * scale, y * scale) for x, y in v)
vec = []# type: Vector
</code></pre>
<p>以上语句等同于：</p>
<pre><code>from typing import TypeVar, Iterable, Tuple

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

def inproduct(v: Iterable]) -&gt; T:
    return sum(x*y for x, y in v)
def dilate(v: Iterable], scale: T) -&gt; Iterable]:
    return ((x * scale, y * scale) for x, y in v)
vec = []# type: Iterable]
</code></pre>
<div id="callable">
<h3 id="callable">Callable</h3>
<p>如果软件框架需要返回特定签名的回调函数，则可以采用 <code>Callable [ ReturnType]</code> 的形式作为类型提示。例如：</p>
<pre><code>from typing import Callable

def feeder(get_next_item: Callable[[], str]) -&gt; None:
    # Body

def async_query(on_success: Callable[, None],
                on_error: Callable[, None]) -&gt; None:
    # Body
</code></pre>
<p>在声明返回 <code>Callable</code> 类型时也可以不指定调用签名，只要用省略号（3个句点）代替参数列表即可：</p>
<pre><code>def partial(func: Callable[..., str], *args) -&gt; Callable[..., str]:
    # Body
</code></pre>
<p>请注意，省略号两侧并不带方括号。在这种情况下，回调函数的参数完全没有限制，并且照样可以使用带关键字（keyword）的参数。</p>
<p>因为带关键字参数的回调函数并不常用，所以当前不支持指定 <code>Callable</code> 类型的带关键字参数。同理，也不支持参数数量可变的回调函数签名。</p>
<p>因为 <code>type.Callable</code> 带有双重职能，用于替代 <code>collections.abc.Callable</code>，所以 <code>isinstance(x, typing.Callable)</code> 的实现与 <code>isinstance(x, collections.abc.Callable)</code> 兼容。但是，<code>isinstance(x, typing.Callable[...])</code> 是不受支持的。</p>
<div id="generics">
<h2 id="泛型generics">泛型（Generics）</h2>
<p>因为容器中的对象类型信息无法以通用的方式做出静态推断，所以抽象基类已扩展为支持预约（subscription）特性，以标明容器内元素的预期类型。例如：</p>
<pre><code>from typing import Mapping, Set

def notify_by_email(employees: Set, overrides: Mapping) -&gt; None: ...
</code></pre>
<p>利用 <code>typing</code> 模块中新提供的工厂函数 <code>TypeVar</code>，可以对泛型实现参数化。例如：</p>
<pre><code>from typing import Sequence, TypeVar

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

def first(l: Sequence) -&gt; T:   # Generic function
    return l
</code></pre>
<p>以上就是约定了返回值的类型与集合内的元素保持一致。</p>
<p><code>TypeVar()</code> 表达式只能直接赋给某个变量（不允许用其组成其他表达式）。<code>TypeVar()</code> 的参数必须是一个字符串，该字符等于分配给它的变量名。类型变量不允许重定义（redefine）。</p>
<p><code>TypeVar</code> 支持把参数可能的类型限为一组固定值（注意：这里的类型不能用类型变量实现参数化）。例如，可以定义某个类型变量只能是 <code>str</code> 和 <code>bytes</code>。默认情况下，类型变量会覆盖所有可能的类型。以下是一个约束类型变量范围的示例：</p>
<pre><code>from typing import TypeVar, Text

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

def concat(x: AnyStr, y: AnyStr) -&gt; AnyStr:
    return x + y
</code></pre>
<p><code>concat</code> 函数对两个 <code>str</code> 或两个 <code>bytes</code> 参数都可以调用，但不能混合使用 <code>str</code> 和 <code>bytes</code> 参数。</p>
<p>只要存在约束条件，就至少应该有两个，不允许只指定单个约束条件。</p>
<p>在类型变量的上下文中，类型变量约束类型的子类型应被视作显式给出的对应基本类型。参见以下示例：</p>
<pre><code>class MyStr(str): ...

x = concat(MyStr('apple'), MyStr('pie'))
</code></pre>
<p>上述调用是合法的，只是类型变量 <code>AnyStr</code> 将被设为 <code>str</code> 而非 <code>MyStr</code>。实际上，赋给 <code>x</code> 的返回值，其推断类型也会是 <code>str</code>。</p>
<p>此外，<code>Any</code> 对于所有类型变量而言都是合法值。参见以下示例：</p>
<pre><code>def count_truthy(elements: List) -&gt; int:
    return sum(1 for elem in elements if elem)
</code></pre>
<p>上述语句相当于省略了泛型注解，只写了 <code>elements: List</code>。</p>
<div id="user-defined-generic-types">
<h3 id="用户自定义的泛型类型user-defined-generic-types">用户自定义的泛型类型（User-defined generic types）</h3>
<p>把 <code>Generic</code> 基类包含进来，即可将用户自定义类定义为泛型类。例如：</p>
<pre><code>from typing import TypeVar, Generic
from logging import Logger

T = TypeVar('T')

class LoggedVar(Generic):
    def __init__(self, value: T, name: str, logger: Logger) -&gt; None:
      self.name = name
      self.logger = logger
      self.value = value

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

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

    def log(self, message: str) -&gt; None:
      self.logger.info('{}: {}'.format(self.name, message))
</code></pre>
<p>作为基类的 <code>Generic</code> 定义了带有1个类型参数 <code>T</code> 的 <code>LoggedVar</code> 类。这也使得 <code>T</code> 能在类的体内作为类型来使用。</p>
<p><code>Generic</code> 基类会用到定义了 <code>__getitem__</code> 的元类，以便 <code>LoggedVar</code> 能作为类型来使用：</p>
<pre><code>from typing import Iterable

def zero_all_vars(vars: Iterable]) -&gt; None:
    for var in vars:
      var.set(0)
</code></pre>
<p>同一个泛型类型所赋的类型变量可以是任意多个，而且类型变量还可以用作约束条件。以下语句是合法的：</p>
<pre><code>from typing import TypeVar, Generic
...

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

class Pair(Generic):
    ...
</code></pre>
<p><code>Generic</code> 的每个类型变量参数都必须唯一。因此，以下语句是非法的：</p>
<pre><code>from typing import TypeVar, Generic
...

T = TypeVar('T')

class Pair(Generic):   # INVALID
    ...
</code></pre>
<p>在比较简单的场合，没有必要用到 <code>Generic</code>，这时可以继承其他的泛型类并指定类型变量参数：</p>
<pre><code>from typing import TypeVar, Iterator

T = TypeVar('T')

class MyIter(Iterator):
    ...
</code></pre>
<p>以上类的定义等价于：</p>
<pre><code>class MyIter(Iterator, Generic):

...
</code></pre>
<p>可以对 <code>Generic</code> 使用多重继承：</p>
<pre><code>from typing import TypeVar, Generic, Sized, Iterable, Container, Tuple

T = TypeVar('T')

class LinkedList(Sized, Generic):
    ...

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

class MyMapping(Iterable],
                Container],
                Generic):
    ...
</code></pre>
<p>如未指定类型参数，则泛型类的子类会假定参数的类型均为 <code>Any</code>。在以下示例中，<code>MyIterable</code> 就不是泛型类，而是隐式继承自 <code>Iterable</code>：</p>
<pre><code>from typing import Iterable

class MyIterable(Iterable):# Same as Iterable
    ...
</code></pre>
<p>泛型元类不受支持。</p>
<div id="scoping-rule">
<h3 id="类型变量的作用域规则scoping-rules-for-type-variables">类型变量的作用域规则（Scoping rules for type variables）</h3>
<p>类型变量遵循常规的名称解析规则。但在静态类型检查的上下文中，存在一些特殊情况：</p>
<ul>
<li>泛型函数中用到的类型变量可以被推断出来，以便在同一代码块中表示不同的类型。例如：</li>
</ul>
<pre><code>from typing import TypeVar, Generic

T = TypeVar('T')

def fun_1(x: T) -&gt; T: ...# T here
def fun_2(x: T) -&gt; 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
</code></pre>
<ul>
<li>当泛型类的方法中用到类型变量时，若该变量正好用作参数化类，那么此类型变量一定是绑定不变的。例如：</li>
</ul>
<pre><code>from typing import TypeVar, Generic

T = TypeVar('T')

class MyClass(Generic):
    def meth_1(self, x: T) -&gt; T: ...# T here
    def meth_2(self, x: T) -&gt; T: ...# and here are always the same

a = MyClass()# type: MyClass
a.meth_1(1)    # OK
a.meth_2('a')# This is an error!
</code></pre>
<ul>
<li>如果某个方法中用到的类型变量与所有用于参数化类的变量都不相符，则会使得该方法成为返回类型为该类型变量的泛型函数：</li>
</ul>
<pre><code>T = TypeVar('T')
S = TypeVar('S')
class Foo(Generic):
    def method(self, x: T, y: S) -&gt; S:
      ...

x = Foo()               # type: Foo
y = x.method(0, "abc")# inferred type of y is str
</code></pre>
<ul>
<li>在泛型函数体内不应出现未绑定的类型变量，在类中除方法定义以外的地方也不应出现：</li>
</ul>
<pre><code>T = TypeVar('T')
S = TypeVar('S')

def a_fun(x: T) -&gt; None:
    # this is OK
    y = []# type: List
    # but below is an error!
    y = []# type: List

class Bar(Generic):
    # this is also an error
    an_attr = []# type: List

    def do_something(x: S) -&gt; S:# this is OK though
      ...
</code></pre>
<ul>
<li>如果泛型类的定义位于某泛型函数内部，则其不允许使用参数化该泛型函数的类型变量：</li>
</ul>
<pre><code>from typing import List

def a_fun(x: T) -&gt; None:

    # This is OK
    a_list = []# type: List
    ...

    # This is however illegal
    class MyGeneric(Generic):
      ...
</code></pre>
<p>嵌套的泛型类不能使用相同的类型变量。外部类的类型变量，作用域不会覆盖内部类：</p>
<pre><code>T = TypeVar('T')
S = TypeVar('S')

class Outer(Generic):
    class Bad(Iterable):       # Error
      ...
    class AlsoBad:
      x = None# type: List # Also an error

    class Inner(Iterable):   # OK
      ...
    attr = None# type: Inner # Also OK
</code></pre>
<div id="instantiating-generic-classes">
<h3 id="实例化通用类和类型清除instantiating-generic-classes-and-type-erasure">实例化通用类和类型清除（Instantiating generic classes and type erasure）</h3>
<p>当然可以对用户自定义的泛型类进行实例化。假定编写了以下继承自 <code>Generic</code> 的 <code>Node</code> 类：</p>
<pre><code>from typing import TypeVar, Generic

T = TypeVar('T')

class Node(Generic):
    ...
</code></pre>
<p>若要创建 <code>Node</code> 的实例，像普通类一样调用 <code>Node()</code> 即可。在运行时，实例的类型（类）将会是 <code>Node</code>。但是对于类型检查程序而言，会要求具备什么类型呢？答案取决于调用时给出多少信hu息。如果构造函数（<code>__init__</code> 或 <code>__new__</code>）在其签名中用了 <code>T</code>，且传了相应的参数值，则会替换对应参数的类型。否则就假定为 <code>Any</code>。例如：</p>
<pre><code>from typing import TypeVar, Generic

T = TypeVar('T')

class Node(Generic):
    x = None# type: T # Instance attribute (see below)
    def __init__(self, label: T = None) -&gt; None:
      ...

x = Node('')# Inferred type is Node
y = Node(0)   # Inferred type is Node
z = Node()    # Inferred type is Node
</code></pre>
<p>如果推断的类型用了 <code></code>，但预期的类型更为具体，则可以用类型注释（参见下文）强行指定变量的类型，例如：</p>
<pre><code># (continued from previous example)
a = Node()# type: Node
b = Node()# type: Node
</code></pre>
<p>或者，也可以实例化具体的类型，例如：</p>
<pre><code># (continued from previous example)
p = Node()
q = Node()
r = Node('')# Error
s = Node(0)   # Error
</code></pre>
<p>请注意，<code>p</code> 和 <code>q</code> 的运行时类型（类）仍会保持为 <code>Node</code>，<code>Node</code> 和 <code>Node</code> 是可相互区别的类对象，但通过实例化创建对象的运行时类不会记录该区别。这种行为被称作“类型清除（type erasure）”。在 Java、TypeScript 之类的支持泛型的语言中，这是一种常见做法。</p>
<p>通过泛型类（不论是否参数化）访问属性将会导致类型检查失败。在类定义体之外，无法对类的属性进行赋值，它只能通过类的实例访问，且该实例还不能带有同名的实例属性：</p>
<pre><code># (continued from previous example)
Node.x = 1# Error
Node.x      # Error
Node.x = 1       # Error
Node.x         # Error
type(p).x      # Error
p.x            # Ok (evaluates to None)
Node().x    # Ok (evaluates to None)
p.x = 1          # Ok, but assigning to instance attribute
</code></pre>
<p>类似 <code>Mapping</code>、<code>Sequence</code> 这种抽象集合类的泛型版本，以及 <code>List</code>、<code>Dict</code>、<code>Set</code>、<code>FrozenSet</code> 这种内置类的泛型版本，都是不能被实例化的。但是，其具体的用户自定义子类和具体具体集合类的泛型版本，就能被实例化了：</p>
<pre><code>data = DefaultDict()
</code></pre>
<p>注意，请勿将静态类型和运行时类混为一谈。上述场合中，类型仍会被清除，并且以上表达式只是以下语句的简写形式：</p>
<pre><code>data = collections.defaultdict()# type: DefaultDict
</code></pre>
<p>不建议在表达式中直接使用带下标的类（例如 <code>Node</code>），最好是采用类型别名（如 <code>IntNode = Node </code>）。首先，创建 <code>Node</code> 这种带下标的类会有一定的运行开销。其次，使用类型别名的可读性会更好。</p>
<div id="as-base-classes">
<h3 id="用任意泛型类型作为基类arbitrary-generic-types-as-base-classes">用任意泛型类型作为基类（Arbitrary generic types as base classes）</h3>
<p><code>Generic</code> 只能用作基类，它可不合适当作类型来使用。不过上述示例中的用户自定义泛型类型（如 <code>LinkedList</code>），以及内置的泛型类型和抽象基类（如 <code>List</code> 和 <code>Iterable </code>），则既可以当作类型使用，也可以当作基类使用。例如，可以定义带有特定类型参数的 <code>Dict</code> 子类：</p>
<pre><code>from typing import Dict, List, Optional

class Node:
    ...

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

    def pop(self, name: str) -&gt; Node:
      return self.pop()

    def lookup(self, name: str) -&gt; Optional:
      nodes = self.get(name)
      if nodes:
            return nodes[-1]
      return None
</code></pre>
<p><code>SymbolTable</code> 既是 <code>dict</code> 的子类，也是 <code>Dict]</code> 的子类型。</p>
<p>如果某个泛型基类带有类型变量作为类型实参，则会使其定义成为泛型类。比如可以定义一个既可迭代又是容器的 <code>LinkedList</code> 泛型类：</p>
<pre><code>from typing import TypeVar, Iterable, Container

T = TypeVar('T')

class LinkedList(Iterable, Container):
    ...
</code></pre>
<p>这样 <code>LinkedList</code> 就是一种合法的类型。注意在基类列表中可以多次使用 <code>T</code>，只要不在 <code>Generic[...]</code> 中多次使用同类型的变量 <code>T</code> 即可。</p>
<p>再来看看以下示例：</p>
<pre><code>from typing import TypeVar, Mapping

T = TypeVar('T')

class MyDict(Mapping):
    ...
</code></pre>
<p>以上情况下，<code>MyDict</code> 带有单个参数 <code>T</code>。</p>
<div id="abstract-generic-types">
<h3 id="抽象泛型类型abstract-generic-types">抽象泛型类型（Abstract generic types）</h3>
<p><code>Generic</code> 使用的元类是 <code>abc.ABCMeta</code> 的一个子类。通过包含抽象方法或属性，泛型类可以成为抽象基类，并且泛型类也可以将抽象基类作为基类而不会出现元类冲突。</p>
<div id="upper-bound">
<h3 id="带类型上界的类型变量type-variables-with-an-upper-bound">带类型上界的类型变量（Type variables with an upper bound）</h3>
<p>类型变量可以用 <code>bound=&lt;type&gt;</code> 指定类型上界（注意 <code>&lt;type&gt;</code> 本身不能由类型变量参数化）。这意味着，替换（显式或隐式）类型变量的实际类型必须是上界类型的子类型。常见例子就是定义一个 <code>Comparable</code> 类型，这样就足以捕获最常见的错误了：</p>
<pre><code>from typing import TypeVar

class Comparable(metaclass=ABCMeta):
    @abstractmethod
    def __lt__(self, other: Any) -&gt; bool: ...
    ...# __gt__ etc. as well

CT = TypeVar('CT', bound=Comparable)

def min(x: CT, y: CT) -&gt; CT:
    if x &lt; y:
      return x
    else:
      return y

min(1, 2)      # ok, return type int
min('x', 'y')# ok, return type str
</code></pre>
<p>请注意，以上代码还不够理想，比如 <code>min('x', 1)</code> 在运行时是非法的，但类型检查程序只会推断出返回类型是 <code>Comparable</code>。不幸的是，解决这个问题需要引入一个强大且复杂得多的概念，F有界多态性（F-bounded polymorphism）。后续可能还会再来讨论这个问题。</p>
<p>类型上界不能与类型约束一起使用（如 <code>AnyStr</code> 中的用法，参见之前的示例），类型约束会使得推断出的类型一定是约束类型之一，而类型上界则只要求实际类型是上界类型的子类型。</p>
<div id="covariance">
<h3 id="协变和逆变covariance-and-contravariance">协变和逆变（Covariance and contravariance）</h3>
<p>不妨假定有一个 <code>Employee</code> 类及其子类 <code>Manager</code>。假如有一个函数，参数用 <code>List</code> 做了注解。那么调用函数时是否该允许使用类型为 <code>List</code> 的变量作参数呢？很多人都会不计后果地回答“是的，当然”。但是除非对该函数了解更多信息，否则类型检查程序应该拒绝此类调用：该函数可能会在 <code>List</code> 中加入 <code>Employee</code> 类型的实例，而这将与调用方的变量类型不符。</p>
<p>事实证明，以上这种参数是有逆变性的，直观的回答（如果函数不对参数作出修改则没问题！）是要求这种参数具备协变性。有关这些概念的详细介绍，请参见 Wikipedia 和 PEP 483。这里仅演示一下如何对类型检查程序的行为进行控制。</p>
<p>默认情况下，所有泛型类型的变量均被视作不可变的，这意味着带有 <code>List</code> 这种类型注解的变量值必须与类型注解完全相符，不能是类型参数的子类或超类（上述示例中即为Employee）。</p>
<p>为了便于声明可接受协变或逆变类型检查的容器类型，类型变量可带有关键字参数 <code>covariant=True</code> 或 <code>convariant=True</code>。两者只能有一个。如果泛型类型带有此类变量定义，则其变量会被相应视为具备协变或逆变性。按照约定，建议对带有 <code>covariant=True</code> 定义的类型变量命名时采用 <code>_co</code> 结尾，而对于带有 <code>convariant=True</code> 定义的类型变量则以 <code>_contra</code> 结尾来命名。</p>
<p>以下典型示例将会定义一个不可修改（immutable）或只读的容器类：</p>
<pre><code>from typing import TypeVar, Generic, Iterable, Iterator

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

class ImmutableList(Generic):
    def __init__(self, items: Iterable) -&gt; None: ...
    def __iter__(self) -&gt; Iterator: ...
    ...

class Employee: ...

class Manager(Employee): ...

def dump_employees(emps: ImmutableList) -&gt; None:
    for emp in emps:
      ...

mgrs = ImmutableList()# type: ImmutableList
dump_employees(mgrs)# OK
</code></pre>
<p><code>typing</code> 中的只读集合类都将类型变量声明为可协变的，比如 <code>Mapping</code> 和 <code>Sequence</code>。可修改的集合类（如 <code>MutableMapping</code> 和 <code>MutableSequence</code>）则声明为不可变的（invariant）。协变类型的一个例子是 <code>Generator</code> 类型，其 <code>send()</code> 的参数类型是可协变的（参见下文）。</p>
<p>注意：协变和逆变并不是类型变量的特性，而是用该变量定义的泛型类的特性。可变性仅适用于泛型类型，泛型函数则没有此特性。泛型函数只允许采用不带 <code>covariant</code> 和 <code>convariant</code> 关键字参数的类型变量进行定义。例如以下示例就很不错：</p>
<pre><code>from typing import TypeVar

class Employee: ...

class Manager(Employee): ...

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

def dump_employee(e: E) -&gt; None: ...

dump_employee(Manager())# OK
</code></pre>
<p>而以下写法是不可以的：</p>
<pre><code>B_co = TypeVar('B_co', covariant=True)

def bad_func(x: B_co) -&gt; B_co:# Flagged as error by a type checker
    ...
</code></pre>
<div id="numeric-tower">
<h3 id="数值类型的继承关系the-numeric-tower">数值类型的继承关系（The numeric tower）</h3>
<p>PEP 3141 定义了 Python 的数值类型层级关系（numeric tower），并且 stdlib 的模块 <code>numbers</code> 实现了对应的抽象基类（<code>Number</code>、<code>Complex</code>、<code>Real</code>、<code>Rational</code> 和 <code>Integral</code>）。关于这些抽象基类是存在一些争议，但内置的具体实现的数值类 <code>complex</code>、<code>float</code> 和 <code>int</code> 已得以广泛应用（尤其是后两个类:-）。</p>
<p>本 PEP 提出了一种简单、快捷、几乎也是高效的方案，用户不必先写 <code>import numbers</code> 语句再使用 <code>umbers.Float</code>：只要注解为 <code>float</code> 类型，即可接受 <code>int</code> 类型的参数。类似地，注解为 <code>complex</code> 类型的参数，则可接受 <code>float</code> 或 <code>int</code> 类型。这种方案无法应对实现抽象基类或 <code>Fractions.Fraction</code> 类的类，但可以相信那些用户场景极为罕见。</p>
<div id="forward-references">
<h3 id="向前引用forward-references">向前引用（Forward references）</h3>
<p>当类型提示包含尚未定义的名称时，未定义名称可以先表示为字符串字面量（literal），稍后再作解析。</p>
<p>在定义容器类时，通常就会发生这种情况，这时在某些方法的签名中会出现将要定义的类。例如，以下代码（简单的二叉树实现的开始部分）将无法生效：</p>
<pre><code>class Tree:
    def __init__(self, left: Tree, right: Tree):
      self.left = left
      self.right = right
</code></pre>
<p>为了解决问题，可以写为：</p>
<pre><code>class Tree:
    def __init__(self, left: 'Tree', right: 'Tree'):
      self.left = left
      self.right = right
</code></pre>
<p>此字符串字面量应包含一个合法的 Python 表达式，即 <code>compile(lit, '', 'eval')</code> 应该是有效的代码对象，并且在模块全部加载完成后对其求值应该不会出错。对该表达式求值时所处的局部和全局命名空间应与对同一函数的默认参数求值时的命名空间相同。</p>
<p>此外，该表达式应可被解析为合法的类型提示，即受限于“可接受的类型提示”一节中的规则约束。</p>
<p>允许将字符串字面量用作类型提示的一部分，例如：</p>
<pre><code>class Tree:
    ...
    def leaves(self) -&gt; List['Tree']:
      ...
</code></pre>
<p>向前引用的常见应用场景是签名需要用到 Django 模型。通常，每个模型都存放在单独的文件中，并且模型有一些方法的参数类型会涉及到其他的模型。因为 Python 存在循环导入（circular import）处理机制，往往不可能直接导入所有要用到的模型：</p>
<pre><code># 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
</code></pre>
<p>假定先导入了 main，则 models/b.py 的 <code>from models.a import A</code> 一行将会运行失败，报错 <code>ImportError</code>，因为在 <code>a</code> 定义类 <code>A</code> 之前就打算从 <code>model/a.py</code> 导入它。解决办法是换成只导入模块，并通过_module_._class_名引用 models：</p>
<pre><code># 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
</code></pre>
<div id="union-types">
<h3 id="union-类型union-types">Union 类型（Union types）</h3>
<p>因为一个参数可接受数量有限的几种预期类型是常见需求，所以系统新提供了一个特殊的工厂类，名为 <code>Union</code>。例如：</p>
<pre><code>from typing import Union

def handle_employees(e: Union]) -&gt; None:
    if isinstance(e, Employee):
      e =
    ...
</code></pre>
<p><code>Union</code> 生成（factor）的类型是所有 <code>T</code>、<code>T2</code> 等类型的超级类型（supertype），因此只要是这些类型之一的值就可被 <code>Union</code> 注解的参数所接受。</p>
<p>Union 类型的一种常见情况是 Optional 类型。除非函数定义中提供了默认值 None，否则 None 默认是不能当任意类型的值使用。例如：</p>
<pre><code>def handle_employee(e: Union) -&gt; None: ...
</code></pre>
<p><code>Union</code> 可以简写为 <code>Optional</code>，比如以上语句等同于：</p>
<pre><code>from typing import Optional

def handle_employee(e: Optional) -&gt; None: ...
</code></pre>
<p>本 PEP 以前允许类型检查程序在默认值为 <code>None</code> 时假定采用 <code>Optional</code> 类型，如下所示：</p>
<pre><code>def handle_employee(e: Employee = None): ...
</code></pre>
<p>将被视为等效于：</p>
<pre><code>def handle_employee(e: Optional = None) -&gt; None: ...
</code></pre>
<p>现在不再推荐这种做法了。类型检查程序应该与时俱进，将需要 <code>Optional</code> 类型的地方明确指出来。</p>
<div id="singleton-types">
<h3 id="用-union-实现单实例类型的支持support-for-singleton-types-in-unions">用 Union 实现单实例类型的支持（Support for singleton types in unions）</h3>
<p>单实例通常用于标记某些特殊条件，特别是 <code>None</code> 也是合法变量值的情况下。例如：</p>
<pre><code>_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
</code></pre>
<p>为了在这种情况下允许精确设定类型，用户应结合使用 Union 类型和标准库提供的 <code>enum.Enum</code> 类，这样就能静态捕获类型错误了：</p>
<pre><code>from typing import Union
from enum import Enum

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

def func(x: Union = _empty) -&gt; 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
</code></pre>
<p>因为 <code>Enum</code> 的子类无法被继承，所以在上述示例的所有分支中都能静态推断出变量 <code>x</code> 的类型。需要多种单例对象的情形也同样适用，可以使用包含多个值的枚举：</p>
<pre><code>class Reason(Enum):
    timeout = 1
    error = 2

def process(response: Union = '') -&gt; 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
</code></pre>
<div id="any-type">
<h3 id="any-类型the-any-type"><code>Any</code> 类型（The <code>Any</code> type）</h3>
<p><code>Any</code> 是一种特殊的类型。每种类型都与 <code>Any</code> 相符。可以将其视为包含所有值和所有方法的类型。请注意，<code>Any</code> 和内置的类型对象完全不同。</p>
<p>当某个值的类型为 <code>object</code> 时，类型检查程序将拒绝几乎所有对其进行的操作，将其赋给类型更具体的变量（或将其用作返回值）将是一种类型错误。反之，当值的类型为<code>Any</code>时，类型检查程序将允许对其执行的所有操作，并且<br>
<code>Any</code> 类型的值可以赋给类型更具体（constrained）的变量（或用作返回值）。</p>
<p>不带类型注解的函数参数假定就是用 <code>Any</code> 作为注解的。如果用了泛型类型但又未指定类型参数，则也假定参数类型为 <code>Any</code>：</p>
<pre><code>from typing import Mapping

def use_map(m: Mapping) -&gt; None:# Same as Mapping
    ...
</code></pre>
<p>上述规则也适用于 <code>Tuple</code>，在类型注解的上下文中，<code>Tuple</code> 等效于 <code>Tuple</code>，即等效于 <code>tuple</code>。同样，类型注解中的 <code>Callable</code> 等效于 <code>Callable[[...], Any]</code>，即等效于 <code>collections.abc.Callable</code>：</p>
<pre><code>from typing import Tuple, List, Callable

def check_args(args: Tuple) -&gt; 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) -&gt; None:
    ...
</code></pre>
<div id="noreturn">
<h3 id="noreturn-类型the-noreturn-type"><code>NoReturn</code> 类型（The NoReturn type）</h3>
<p><code>typing</code> 模块提供了一种特殊的类型 <code>NoReturn</code>，用于注解一定不会正常返回的函数。例如一个将无条件引发异常的函数：</p>
<pre><code>from typing import NoReturn

def stop() -&gt; NoReturn:
    raise RuntimeError('no way')
</code></pre>
<p>类型注解 <code>NoReturn</code> 用于 <code>sys.exit</code> 之类的函数。静态类型检查程序将会确保返回类型注解为 <code>NoReturn</code> 的函数确实不会隐式或显式地返回：</p>
<pre><code>import sys
from typing import NoReturn

def f(x: int) -&gt; NoReturn:# Error, f(0) implicitly returns None
      if x != 0:
          sys.exit(1)
</code></pre>
<p>类型检查程序还会识别出调用此类函数后面的代码是否可达，并采取相应动作：</p>
<pre><code># continue from first example
def g(x: int) -&gt; int:
    if x &gt; 0:
      return x
    stop()
    return 'whatever works'# Error might be not reported by some checkers
                           # that ignore errors in unreachable blocks
</code></pre>
<p><code>NoReturn</code> 类型仅可用于函数的返回类型注解，出现在其他位置则被认为是错误：</p>
<pre><code>from typing import List, NoReturn

# All of the following are errors
def bad1(x: NoReturn) -&gt; int:
    ...
bad2 = None# type: NoReturn
def bad3() -&gt; List:
    ...
</code></pre>
<div id="type-of-class">
<h3 id="类对象的类型the-type-of-class-objects">类对象的类型（The type of class objects）</h3>
<p>有时会涉及到类对象，特别是从某个类继承而来的类对象。类对象可被写为 <code>Type</code>，这里的 <code>C</code> 是一个类。为了清楚起见，<code>C</code> 在用作类型注解时指的是类 <code>C</code> 的实例，<code>Type</code> 指的是 <code>C</code> 的子类。这类似于对象和类型之间的区别。</p>
<p>例如，假设有以下类：</p>
<pre><code>class User: ...# Abstract base for User classes
class BasicUser(User): ...
class ProUser(User): ...
class TeamUser(User): ...
</code></pre>
<p>假设有一个函数，如果传一个类对象进去，就会创建出该类的一个实例：</p>
<pre><code>def new_user(user_class):
    user = user_class()
    # (Here we could write the user object to a database)
    return user
</code></pre>
<p>若不用 <code>Type[]</code>，能给 <code>new_user()</code> 加上的最好的类型注解将会是：</p>
<pre><code>def new_user(user_class: type) -&gt; User:
    ...
</code></pre>
<p>但采用 <code>Type[]</code> 和带上界的类型变量，就可以注解得更好：</p>
<pre><code>U = TypeVar('U', bound=User)
def new_user(user_class: Type) -&gt; U:
    ...
</code></pre>
<p>现在，若用 <code>User</code> 的某个子类做参数调用 <code>new_user()</code>，类型检查程序将能推断出结果的正确类型：</p>
<pre><code>joe = new_user(BasicUser)# Inferred type is BasicUser
</code></pre>
<p><code>Type</code> 对应的值必须是类型为 <code>C</code> 的子类型的类对象实体，而不是某个具体的类型。换句话说，在上述示例中，<code>new_user(Union)</code> 之类的调用将被类型检查程序拒绝（并且会运行失败，因为 union 无法实例化）。</p>
<p>请注意，用类的 union 作 <code>Type[]</code> 的参数是合法的，如下所示：</p>
<pre><code>def new_non_team_user(user_class: Type]):
    user = new_user(user_class)
    ...
</code></pre>
<p>但是，在运行时上例中传入的实际参数仍必须是具体的类对象：</p>
<pre><code>new_non_team_user(ProUser)# OK
new_non_team_user(TeamUser)# Disallowed by type checker
</code></pre>
<p><code>Type</code> 也是支持的，含义参见下文。</p>
<p>为类方法的第一个参数标注类型注解时，允许采用 <code>Type</code>，这里的 <code>T</code> 是一个类型变量，具体请参阅相关章节。</p>
<p>任何其他的结构（如 <code>Tuple</code> 或 <code>Callable</code>）均不能用作 <code>Type</code> 的参数。</p>
<p>此特性存在一些问题：比如若 <code>new_user()</code> 要调用 <code>user_class()</code>，就意味着 <code>User</code> 的所有子类都必须在其构造函数的签名中支持该调用。不过并不是只有 <code>Type[]</code> 才会如此，类方法也有类似的问题。类型检查程序应该将违反这种假定的行为标记出来，但与所标明基类（如上例中的 <code>User</code>）的构造函数签名相符的构造函数，应该默认是允许调用的。如果程序中包含了比较复杂的或可扩展的类体系，也可以采用工厂类方法来作处理。本 PEP 的未来修订版本可能会引入更好的方法来解决这些问题。</p>
<p>当 <code>Type</code> 带有参数时，仅要求有一个参数。不带中括号的普通类型等效于 <code>Type</code>，也即等效于 <code>type</code>（Python 元类体系中的根类）。这种等效性也促成了其名称 <code>Type</code>，而没有采用 <code>Class</code> 或 <code>SubType</code> 这种名称，在讨论此特性时这些名称都被提出过，这有点类似 <code>List</code> 和 <code>list</code> 的关系。</p>
<p>关于 <code>Type</code>（或 <code>Type</code>、<code>Type</code>）的行为，如果要访问该类型变量的属性，则只提供了 <code>type</code> 定义的属性和方法（如 <code>__repr__()</code> 和 <code>__mro__</code>）。此类变量可以用任意参数进行调用，返回类型则为 <code>Any</code>。</p>
<p><code>Type</code> 的参数是协变的，因为 <code>Type</code> 是 <code>Type</code> 的子类型：</p>
<pre><code>def new_pro_user(pro_user_class: Type):
    user = new_user(pro_user_class)# OK
    ...
</code></pre>
<div id="instance-method">
<h3 id="为实例和类方法加类型注解annotating-instance-and-class-methods">为实例和类方法加类型注解（Annotating instance and class methods）</h3>
<p>大多数情况下，类和实例方法的第一个参数不需要加类型注解，对实例方法而言假定它的类型就是所在类（的类型），对类方法而言它则是所在类对象对应的类型对​​象（的类型）。另外，实例方法的第一个参数加类型注解时可以带有一个类型变量。这时返回类型可以采用相同的类型变量，从而使该方法成为泛型函数。例如：</p>
<pre><code>T = TypeVar('T', bound='Copyable')
class Copyable:
    def copy(self: T) -&gt; T:
      # return a copy of self

class C(Copyable): ...
c = C()
c2 = c.copy()# type here should be C
</code></pre>
<p>同样，可以对类方法第一个参数的类型注解中使用 <code>Type[]</code>：</p>
<pre><code>T = TypeVar('T', bound='C')
class C:
    @classmethod
    def factory(cls: Type) -&gt; T:
      # make a new instance of cls

class D(C): ...
d = D.factory()# type here should be D
</code></pre>
<p>请注意，某些类型检查程序可能对以上用法施加限制，比如要求所用类型变量具备合适的类型上界（参见示例）。</p>
<div id="version-check">
<h3 id="版本和平台检查version-and-platform-checking">版本和平台检查（Version and platform checking）</h3>
<p>类型检查程序应该能理解简单的版本和平台检查语句，例如：</p>
<pre><code>import sys

if sys.version_info &gt;= 3:
    # Python 3 specific definitions
else:
    # Python 2 specific definitions

if sys.platform == 'win32':
    # Windows specific definitions
else:
    # Posix specific definitions
</code></pre>
<p>请别指望类型检查程序能理解诸如 <code>"".join(reversed(sys.platform)) == "xunil"</code> 这种晦涩语句。</p>
<div id="runtime">
<h3 id="运行时检查还是类型检查runtime-or-type-checking">运行时检查还是类型检查？(Runtime or type checking?)</h3>
<p>有时候，有些代码必须由类型检查程序（或其他静态分析工具）进行检查，而不应拿去运行。<code>typing</code> 模块为这种情况定义了一个常量 <code>TYPE_CHECKING</code>，在类型检查（或其他静态分析）期间视其为 <code>True</code>，在运行时视其为 <code>False</code>。例如：</p>
<pre><code>import typing

if typing.TYPE_CHECKING:
    import expensive_mod

def a_func(arg: 'expensive_mod.SomeClass') -&gt; None:
    a_var = arg# type: expensive_mod.SomeClass
    ...
</code></pre>
<p>注意，这里的类型注解必须用引号引起来，使其成为“向前引用”，以便向解释器隐藏 <code>expensive_mod</code> 引用。在 <code># type</code> 注释中无需加引号。</p>
<p>这种做法对于处理循环导入也会比较有用。</p>
<div id="argument">
<h3 id="可变参数列表和默认参数值arbitrary-argument-lists-and-default-argument-values">可变参数列表和默认参数值（Arbitrary argument lists and default argument values）</h3>
<p>可变参数列表也可以加注类型注解，以下定义是可行的：</p>
<pre><code>def foo(*args: str, **kwds: int): ...
</code></pre>
<p>这表示以下函数调用的参数类型都是合法的：</p>
<pre><code>foo('a', 'b', 'c')
foo(x=1, y=2)
foo('', z=0)
</code></pre>
<p>在 <code>foo</code> 函数体中，变量 <code>args</code> 的类型被推导为 <code>Tuple</code>，变量 <code>kwds</code> 的类型被推导为 <code>Dict </code>。</p>
<p>在存根（stub）文件中，将参数声明为带有默认值，但不指定实际的默认值，这会很有用。例如：</p>
<pre><code>def foo(x: AnyStr, y: AnyStr = ...) -&gt; AnyStr: ...
</code></pre>
<p>默认值应该是如何的？<code>""</code>、<code>b""</code> 或 <code>None</code> 都不符合类型约束。</p>
<p>这时可将默认值指定为省略号，其实就是以上示例。</p>
<div id="positional-only">
<h3 id="只采用位置参数positional-only-arguments">只采用位置参数（Positional-only arguments）</h3>
<p>有一些函数被设计成只能按位置接收参数，并希望调用者不要使用参数名称，不通过关键字给出参数。名称以__开头的参数均被假定为只按位置访问，除非同时以__结尾：</p>
<pre><code>def quux(__x: int, __y__: int = 0) -&gt; None: ...

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

quux(__x=3)# This call is an error.
</code></pre>
<div id="coroutine">
<h3 id="为生成器函数和协程加类型注解annotating-generator-functions-and-coroutines">为生成器函数和协程加类型注解（Annotating generator functions and coroutines）</h3>
<p>生成器函数的返回类型可以用 <code>type.py</code> 模块提供的泛型 <code>Generator</code> 进行类型注解：</p>
<pre><code>def echo_round() -&gt; Generator:
    res = yield
    while res:
      res = yield round(res)
    return 'OK'
</code></pre>
<p>PEP 492 中引入的协程（coroutine）可用与普通函数相同的语法进行类型注解。但是，返回类型的类型注解对应的是 <code>await</code> 表达式的类型，而不是协程的类型：</p>
<pre><code>async def spam(ignored: int) -&gt; str:
    return 'spam'

async def foo() -&gt; None:
    bar = await spam(42)# type: str
</code></pre>
<p><code>type.py</code> 模块提供了一个抽象基类 <code>collections.abc.Coroutine</code> 的泛型版本，以支持可异步调用（awaitable）特性，同时支持 <code>send()</code> 和 <code>throw()</code> 方法。类型变量定义及其顺序与 <code>Generator</code> 的相对应，即 <code>Coroutine</code>，例如：</p>
<pre><code>from typing import List, Coroutine
c = None# type: Coroutine, str, int]
...
x = c.send('hi')# type: List
async def bar() -&gt; None:
    x = await c# type: int
</code></pre>
<p>该模块还为无法指定更精确类型的情况提供了泛型抽象基类 <code>Awaitable</code>、<code>AsyncIterable</code> 和 <code>AsyncIterator</code>：</p>
<pre><code>def op() -&gt; typing.Awaitable:
    if cond:
      return spam(42)
    else:
      return asyncio.Future(...)
</code></pre>
<div id="compatibility">
<h2 id="与函数注解其他用法的兼容性compatibility-with-other-uses-of-function-annotations">与函数注解其他用法的兼容性（Compatibility with other uses of function annotations）</h2>
<p>有一些函数注解的使用场景，与类型提示是不兼容的。这些用法可能会引起静态类型检查程序的混乱。但因为类型提示的注解在运行时不起作用（计算注解表达式、将注解存储在函数对象的 <code>__annotations__</code> 属性中除外），所以不会让程序报错，只是可能会让类型检查程序发出虚报警告或错误。</p>
<p>如果要让某部分程序不受类型提示的影响，可以用以下一种或几种方法进行标记：</p>
<ul>
<li>用 <code># type: ignore</code> 加注释（comment）；</li>
<li>为类或函数加上 <code>@no_type_check</code> 装饰符（decorator）；</li>
<li>为自定义类或函数装饰符加上 <code>@no_type_check_decorator</code> 标记。</li>
</ul>
<p>更多详情，请参见后续章节。</p>
<p>为了最大程度与脱机类型检查过程保持兼容，将依赖于类型注解的接口改成其他机制（例如装饰器）可能比较合适些。不过这在 Python 3.5 中没什么关系。更多讨论请参见后续的“未被采纳的其他方案”。</p>
<div id="type-comment">
<h2 id="类型注释type-comments">类型注释（Type comments）</h2>
<p>本 PEP 并未将变量明确标为某类型提供一等语法支持。为了有助于在复杂情况下进行类型推断，可以采用以下格式的注释：</p>
<pre><code>x = []                # type: List
x, y, z = [], [], []# type: List, List, List
x, y, z = [], [], []# type: (List, List, List)
a, b, *c = range(5)   # type: float, float, List
x =             # type: List
</code></pre>
<p>类型注释应放在变量定义语句的最后一行，还可以紧挨着冒号放在 <code>with</code> 和 <code>for</code> 语句后面。</p>
<p>以下是<code>with</code> 和 <code>for</code> 语句的类型注解示例：</p>
<pre><code>with frobnicate() as foo:# type: int
    # Here foo is an int
    ...

for x, y in points:# type: float, float
    # Here x and y are floats
    ...
</code></pre>
<p>在存根（stub）文件中，只声明变量的存在但不给出初值可能会比较有用。这用 PEP 526 的变量注解语法即可实现：</p>
<pre><code>from typing import IO

stream: IO
</code></pre>
<p>上述语法在所有版本的 Python 的存根文件中均可接受。但在 Python 3.5 以前版本的非存根文件代码中，存在一种特殊情况：</p>
<pre><code>from typing import IO

stream = None# type: IO
</code></pre>
<p>尽管 <code>None</code> 与给定类型不符，类型检查程序不应对上述语句报错，也不应将类型推断结果更改为 <code>Optional[...]</code>（虽然规则要求对注解默认值为 <code>None</code> 的参数如此操作）。这里假定将由其他代码保证赋予变量类型合适的值，并且所有调用都可假定该变量具有给定类型。</p>
<p>注释 <code># type: ignore</code> 应该放在错误信息所在行上：</p>
<pre><code>import http.client
errors = {
    'not_found': http.client.NOT_FOUND# type: ignore
}
</code></pre>
<p>如果注释 <code># type: ignore</code> 位于文件的开头、单独占一行、在所有文档字符串（docstring）、<code>import</code> 语句或其他可执行代码之前，则会让文件中所有错误都不报错。空行和其他注释（如 shebang 代码行和编码 cookie）可以出现在 <code># type: ignore</code> 之前。</p>
<p>某些时候，类型注释可能需要与查错（lint）工具或其他注释同处一行。此时类型注释应位于其他注释和 lint 标记之前：</p>
<pre><code># type: ignore # &lt;comment or other marker&gt;
</code></pre>
<p>如果大多时候类型提示能被证明有用，那么将来版本的 Python 可能会为 typing 变量提供语法。</p>
<p><em>更新</em>：该语法已通过 PEP 526 在 Python 3.6 加入。</p>
<div id="cast">
<h2 id="指定类型cast">指定类型（Cast）</h2>
<p>偶尔，类型检查程序可能需要另一种类型提示：程序员可能知道，某个表达式的类型比类型检查程序能够推断出来的更为准确。例如：</p>
<pre><code>from typing import List, cast

def find_first_str(a: List) -&gt; str:
    index = next(i for i, x in enumerate(a) if isinstance(x, str))
    # We only get here if there's at least one string in a
    return cast(str, a)
</code></pre>
<p>某些类型检查程序可能无法推断出 <code>a</code> 的类型为 <code>str</code>，而只能推断出是个对象或 <code>Any</code>，但大家都知道（如果代码能够运行到该点）它必须是个字符串。<code>ast(t, x)</code> 调用会通知类型检查程序，确信 <code>x</code> 的类型就是 <code>t</code>。在运行时，<code>cast</code> 始终会原封不动地返回表达式，不作类型检查，也不对值作任何转换或强制转换。</p>
<p><code>cast</code> 与类型注释（参见上一节）不同。用了类型注释，类型检查程序仍应验证推断出的类型是否与声明的类型一致。若用了 <code>cast</code> ，类型检查程序就会完全信任程序员。<code>cast</code> 还可以在表达式中使用，而类型注释则只能在赋值时使用。</p>
<div id="newtype">
<h2 id="newtype-工具函数newtype-helper-function"><code>NewType</code> 工具函数（NewType helper function）</h2>
<p>还有些时候，为了避免逻辑错误，程序员可能会创建简单的类。例如：</p>
<pre><code>class UserId(int):
    pass

get_by_user_id(user_id: UserId):
    ...
</code></pre>
<p>但创建类会引入运行时的开销。为了避免这种情况，<code>typeing.py</code> 提供了一个工具函数 <code>NewType</code>，该函数能够创建运行开销几乎为零的唯一简单类型。对于静态类型检查程序而言，<code>Derived = NewType('Derived', Base)</code> 大致等同于以下定义：</p>
<pre><code>class Derived(Base):
    def __init__(self, _x: Base) -&gt; None:
      ...
</code></pre>
<p>在运行时，<code>NewType('Derived', Base)</code> 将返回一个伪（dummy）函数，该伪函数只是简单地将参数返回。类型检查程序在用到 <code>UserId</code> 时要求由 <code>int</code> 显式转换（cast）而来，而用到 <code>int</code> 时要求由 <code>UserId</code> 显式转换而来。例如：</p>
<pre><code>UserId = NewType('UserId', int)

def name_by_id(user_id: UserId) -&gt; str:
    ...

UserId('user')          # Fails type check

name_by_id(42)          # Fails type check
name_by_id(UserId(42))# OK

num = UserId(5) + 1   # type: int
</code></pre>
<p><code>NewType</code> 只能接受两个参数：新的唯一类型名称、基类。后者应为合法的类（即不是 <code>Union</code> 这种类型结构），或者是通过调用 <code>NewType</code> 创建的其他唯一类型。<code>NewType</code> 返回的函数仅接受一个参数，这等同于仅支持一个构造函数，构造函数只能接受一个基类实例作参数（参见上文）。例如：</p>
<pre><code>class PacketId:
    def __init__(self, major: int, minor: int) -&gt; None:
      self._major = major
      self._minor = minor

TcpPacketId = NewType('TcpPacketId', PacketId)

packet = PacketId(100, 100)
tcp_packet = TcpPacketId(packet)# OK

tcp_packet = TcpPacketId(127, 0)# Fails in type checker and at runtime
</code></pre>
<p>对 <code>NewType('Derived', Base)</code> 进行 <code>isinstance</code>、<code>issubclass</code> 和派生子类的操作都会失败，因为函数对象不支持这些操作。</p>
<div id="stub-file">
<h2 id="存根文件stub-files">存根文件（Stub Files）</h2>
<p>存根文件是包含类型提示信息的文件，这些提示信息仅供类型检查程序使用，而在运行时则不会用到。存根文件有以下几种使用场景：</p>
<ul>
<li>扩展模块</li>
<li>作者尚未添加类型提示的第三方模块</li>
<li>尚未编写类型提示的标准库模块</li>
<li>必须与 Python 2和3兼容的模块</li>
<li>因为其他目的使用类型注解的模块</li>
</ul>
<p>存根文件的语法与常规 Python 模块相同。<code>typing</code> 模块中有一项特性在存根文件中会有所不同：<code>@overload</code> 装饰器，后续将会介绍。</p>
<p>类型检查程序只应检查存根文件中的函数签名，建议存根文件中的函数体只写一个省略号（...）。</p>
<p>类型检查程序应可配置存根文件的搜索路径。如果能找到存根文件，类型检查程序就不应再去读取对应的“实际”代码模块了。</p>
<p>尽管存根文件在语法上是合法的 Python 模块，但他们采用 <code>.pyi</code> 作为扩展名，这样就能将存根文件与对应的实际模块在同一目录中加以管理了。这也强调了以下观念：存根文件不该具备任何运行时的行为。</p>
<p>存根文件的一些其他注意事项：</p>
<ul>
<li>除非采用 <code>import ... as ...</code> 或等效的 <code>from ... import ... as ...</code> 形式，否则导入到存根文件中的模块和变量均不视作能从存根文件导出（export）的。</li>
<li>但上一条有一个例外，所有用 <code>from ... import *</code> 导入存根文件的对象均被视为导出属性。这样从某个模块中导出所有对象就更加容易了，此模块的内容可能因不同的 Python 版本而各不相同。</li>
<li>正如普通的 Python 文件导入 一样，子模块在导入之后会自动成为其父模块的导出属性。比如假设 <code>spam</code> 包带有以下目录结构：</li>
</ul>
<pre><code>spam/
    __init__.pyi
    ham.pyi
</code></pre>
<p>这里 <code>__init__.pyi</code> 中包含一条 <code>from . import ham</code> 或 <code>from .ham import Ham</code> 语句，则 <code>ham</code> 就成为 <code>spam</code> 的一条导出属性。</p>
<ul>
<li>存根文件可以不完整。为了让类型检查程序意识到这一点，存根文件可以包含以下代码：</li>
</ul>
<pre><code>def __getattr__(name) -&gt; Any: ...
</code></pre>
<p>因此，所有未在存根文件中定义的标识符都假定为 <code>Any</code> 类型。</p>
<div id="overload">
<h3 id="函数方法重载functionmethod-overloading">函数/方法重载（Function/method overloading）</h3>
<p><code>@overload</code> 装饰器可用于描述那些支持多种类型组合参数的函数和方法。内置模块和类型中经常使用这种模式。例如，<code>bytes</code> 类型的 <code>__getitem__()</code> 方法可以描述如下：</p>
<pre><code>from typing import overload

class bytes:
    ...
    @overload
    def __getitem__(self, i: int) -&gt; int: ...
    @overload
    def __getitem__(self, s: slice) -&gt; bytes: ...
</code></pre>
<p>这种描述方式能比 union（无法表达参数和返回类型之间的关系）更为精确：</p>
<pre><code>from typing import Union

class bytes:
    ...
    def __getitem__(self, a: Union) -&gt; Union: ...
</code></pre>
<p><code>@overload</code> 的另一个用武之地是内置 <code>map()</code> 函数的类型，该函数的参数数量不定，具体取决于 callable 对象的类型：</p>
<pre><code>from typing import Callable, Iterable, Iterator, Tuple, TypeVar, overload

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

@overload
def map(func: Callable[, S], iter1: Iterable) -&gt; Iterator: ...
@overload
def map(func: Callable[, S],
      iter1: Iterable, iter2: Iterable) -&gt; Iterator: ...
# ... and we could add more items to support more than two iterables
</code></pre>
<p>请注意，还可以轻松加入参数项以支持 <code>map(None, ...)</code>：</p>
<pre><code>@overload
def map(func: None, iter1: Iterable) -&gt; Iterable: ...
@overload
def map(func: None,
      iter1: Iterable,
      iter2: Iterable) -&gt; Iterable]: ...
</code></pre>
<p><code>@overload</code> 装饰器的上述用法同样适用于存根文件。在常规模块中，一串<code>@overload</code> 装饰的定义之后必须紧跟一个非 <code>@overload</code> 定义（对于同一函数/方法而言）。 <code>@overload</code> 装饰的定义仅对类型检查程序有用，因为他们将被非 <code>@overload</code> 装饰的定义覆盖掉，非 <code>@overload</code> 装饰的定义在运行时有用而应被类型检查程序忽略。在运行时，直接调用 <code>@overload</code> 装饰过的函数将会引发 <code>NotImplementedError</code>。下面是一个非存根方式重载的示例，它无法简单地用 union 或类型变量进行表达：</p>
<pre><code>@overload
def utf8(value: None) -&gt; None:
    pass
@overload
def utf8(value: bytes) -&gt; bytes:
    pass
@overload
def utf8(value: unicode) -&gt; bytes:
    pass
def utf8(value):
    &lt;actual implementation&gt;
</code></pre>
<p><strong>注意</strong>：虽然用上述语法有可能实现多重分派（multiple dispatch），但这种实现需要用到 <code>sys._getframe()</code>，这是令人生厌的。同样，设计并实现高效的多重分派机制是很难的，这就是为什么以前的尝试因 <code>functools.singledispatch()</code> 而被放弃的原因。（请参阅 PEP 443，尤其是其“替代方案”部分。）将来，可能会有令人满意的多重分派设计，但是设计方案不应受到上述重载语法的限制，此重载语法是为存根文件中的类型提示定义的。也有可能这两种特性会彼此独立地研发（因为类型检查程序中的重载与运行时的多重派发具有不同的应用场景和要求，比如后者不太可能支持泛型）。</p>
<p>通常可以用受限的 <code>TypeVar</code> 类型来代替 <code>@overload</code> 装饰器。例如，以下存根文件中的 <code>concat1</code> 和 <code>concat2</code> 定义是等价的：</p>
<pre><code>from typing import TypeVar, Text

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

def concat1(x: AnyStr, y: AnyStr) -&gt; AnyStr: ...

@overload
def concat2(x: str, y: str) -&gt; str: ...
@overload
def concat2(x: bytes, y: bytes) -&gt; bytes: ...
</code></pre>
<p>某些函数（如上述 <code>map</code> 或 <code>bytes.__ getitem__</code>）无法用类型变量来做精确表达。但与 <code>@overload</code> 不同，类型变量在存根文件之外也可以使用。建议仅在类型变量不足时才使用 <code>@overload</code>，因为它只能特定用于存根文件。</p>
<p>类型变量（如 <code>AnyStr</code>）和采用 <code>@overload</code> 还有另一个重要区别，就是类型变量还可用于定义泛型类的类型参数的限制条件。例如，泛型类 <code>typing.IO</code> 的 <code>type</code> 参数就受到限制（合法类型只有 <code>IO</code>、<code>IO</code> 和 <code>IO</code>）：</p>
<pre><code>class IO(Generic): ...
</code></pre>
<div id="distribute-stub">
<h3 id="存根文件的存储和发布storing-and-distributing-stub-files">存根文件的存储和发布（Storing and distributing stub files）</h3>
<p>存根文件最简单的存储和发布形式，就是将其放入 Python 模块的同一目录中。这样程序员和软件工具就都能轻松找到他们了。但由于软件包（package）的维护人员完全可以不在包中加入类型提示，因此通过 Pip 从 PyPI 安装第三方存根文件也是被支持的。这时必须考虑3个问题：命名、版本管理、安装路径。</p>
<p>本 PEP 不提供第三方存根文件包的命名方案建议。但愿软件包的可发现性（discoverability）将会因其普及程度而定，例如 Django 软件包。</p>
<p>第三方存根文件必须用源代码包兼容的最低版本进行版本管理。例如：<code>FooPackage</code> 的版本有 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版的存根文件。</p>
<p>请注意，如果用户决定采用可用的“最新”源代码包，则只要经常更新存根文件，采用最新的存根文件通常也就应该可以了。</p>
<p>第三方存根软件包可以把存根文件保存在任何位置。类型检查程序应该用 <code>PYTHONPATH</code> 进行搜索。一定会作检查的默认后备目录为 <code>shared/typehints/pythonX.Y/</code>（某些 PythonX.Y 由类型检查程序确定，而不仅是已安装的版本）。因为每种环境只能为给定的 Python 版本安装一个包，所以在该目录下不会再区分版本了（就像 pip 在 site-packages 下的纯目录安装一样）。存根文件包的作者可以在 setup.py 中采用以下代码段：</p>
<pre><code>...
data_files=[
    (
      'shared/typehints/python{}.{}'.format(*sys.version_info[:2]),
      pathlib.Path(SRC_PATH).glob('**/*.pyi'),
    ),
],
...
</code></pre>
<p><em>更新</em>：自2018年6月起，为第三方软件包发布类型提示存根文件的推荐方式已作更改，除了 typeshed（参阅下一节）之外，现在有了一个用于发布类型提示的标准 PEP 561。它支持可单独安装的包，包中可包含存根文件、作为可执行代码包同步发布的存根文件、行内（inline）类型提示，后两种方式可通过在包中包含一个名为<code>py.typed</code> 的文件进行启用。</p>
<div id="typeshed">
<h3 id="typeshed-库the-typeshed-repo">typeshed 库（The Typeshed Repo）</h3>
<p>有一个共享库将有用的存根文件都搜集在了一起，那就是 typeshed。存根文件的收集策略是独立的，并在库文档中做了报告。注意，如果某个包的所有者明确要求忽略，则此包的存根文件将不会包含进来。</p>
<div id="exception">
<h2 id="异常exceptions">异常（Exceptions）</h2>
<p>针对本特性可引发的异常，没有语法上的建议。目前本特性唯一已知的应用场景就是作为文档记录，这时建议将信息放入文档字符串（docstring）中。</p>
<div id="typing">
<h2 id="typing-模块the-typing-module">typing 模块（The typing Module）</h2>
<p>为了将静态类型检查特性开放给 Python 3.5 以下的版本使用，需要有一个统一的命名空间。为此，标准库中引入了一个名为 <code>typing</code> 的新模块。</p>
<p><code>typing</code> 模块定义了用于构建类型的基础构件（如 <code>Any</code>）、表示内置集合类的泛型变体类型（如 <code>List</code>）、表示集合类的泛型抽象基类类型（如 <code>Sequence</code>）和一批便捷类定义。</p>
<p>请注意，只有在类型注解的上下文中才支持用 <code>TypeVar</code> 定义的特殊类型结构，比如 <code>Any</code>、<code>Union</code>和类型变量，而 <code>Generic</code> 则只能用作基类。如果出现在 <code>isinstance</code> 或 <code>issubclass</code> 中，所有这些（未参数化的泛型除外）都将引发 <code>TypeError</code> 异常。</p>
<p>基础构件：</p>
<ul>
<li>Any，用法为 <code>def get(key: str) -&gt; Any: ...</code>。</li>
<li>Union，用法为 <code>Union</code>。</li>
<li>Callable，用法为 <code>Callable[, ReturnType]</code>。</li>
<li>Tuple，用于列出元素类型，比如 <code>Tuple</code>。空元组类型可以表示为 <code>Tuple[()]</code>。可变长同构元组可以表示为一个类型和省略号，比如 <code>Tuple</code>，此处的 <code>...</code> 是语法的组成部分。</li>
<li>TypeVar，用法为 <code>X = TypeVar('X', Type1, Type2, Type3)</code> 或简化为 <code>Y = TypeVar('Y')</code>（详见上文）。</li>
<li>Generic，用于创建用户自定义泛型类。</li>
<li>Type，用于对类对象做类型注解。</li>
</ul>
<p>内置集合类的泛型变体：</p>
<ul>
<li>Dict，用法为 <code>Dict</code>。</li>
<li>DefaultDict，用法为 <code>DefaultDict</code>，是 <code>collections.defaultdict</code> 的泛型变体。</li>
<li>List，用法为 <code>List</code>。</li>
<li>Set，用法为 <code>Set</code>。参阅下文有关 <code>AbstractSet</code> 的备注信息。</li>
<li>FrozenSet，用法为 <code>FrozenSet</code>。</li>
</ul>
<p><strong>注意</strong>：<code>Dict</code>、<code>DefaultDict</code>、<code>List</code>、<code>Set</code> 和 <code>FrozenSet</code> 主要用于对返回值做类型注解。而函数参数的注解，建议采用下述抽象集合类型，比如 <code>Mapping</code>、<code>Sequence</code> 或 <code>AbstractSet</code>。</p>
<p>容器类抽象基类的泛型变体（及一些非容器类）：</p>
<ul>
<li>Awaitable</li>
<li>AsyncIterable</li>
<li>AsyncIterator</li>
<li>ByteString</li>
<li>Callable（详见上文）</li>
<li>Collection</li>
<li>Container</li>
<li>ContextManager</li>
<li>Coroutine</li>
<li>Generator，用法为 <code>Generator</code>，表示生成器函数的返回值。此为 <code>Iterable</code> 的子类型。并且为 <code>send()</code> 方法可接受的类型加入了类型变量（可逆变）。可逆变的意思是，在要求可发送 <code>Manager</code> 实例的上下文中，生成器允许发送 <code>Employee</code> 实例，并返回生成器的类型。</li>
<li>Hashable（非泛型）</li>
<li>ItemsView</li>
<li>Iterable</li>
<li>Iterator</li>
<li>KeysView</li>
<li>Mapping</li>
<li>MappingView</li>
<li>MutableMapping</li>
<li>MutableSequence</li>
<li>MutableSet</li>
<li>Sequence</li>
<li>Set，重命名为 <code>AbstractSet</code>。因为 <code>typing</code> 模块中的 <code>Set</code> 表示泛型 <code>set()</code>，所以需要改名。</li>
<li>Sized（非泛型）</li>
<li>ValuesView</li>
</ul>
<p>一些用于测试某个方法的一次性类型，类似于 <code>Hashable</code> 或 <code>Sized</code>：</p>
<ul>
<li>Reversible，用于测试 <code>__reversed__</code></li>
<li>SupportsAbs，用于测试 <code>__abs__</code></li>
<li>SupportsComplex，用于测试 <code>__complex__</code></li>
<li>SupportsFloat，用于测试 <code>__float__</code></li>
<li>SupportsInt，用于测试 <code>__int__</code></li>
<li>SupportsRound，用于测试 <code>__round__</code></li>
<li>SupportsBytes，用于测试 <code>__bytes__</code></li>
</ul>
<p>便捷类定义：</p>
<ul>
<li>Optional，定义为 <code>Optional == Union</code>。</li>
<li>Text，只是 Python 3 中 <code>str</code>、Python 2 中 <code>unicode</code> 的别名。</li>
<li>AnyStr，定义为 <code>TypeVar('AnyStr', Text, bytes)</code>。</li>
<li>NamedTuple，用法为 <code>NamedTuple(type_name, [(field_name, field_type), ...])</code> 等价于 <code>collections.namedtuple(type_name, )</code>。在为命名元组类型的字段进行类型声明时，这会很有用。</li>
<li>NewType，用于创建运行开销很小的唯一类型，如 <code>UserId = NewType('UserId', int)</code>。</li>
<li>cast()，如前所述。</li>
<li>@no_type_check，用于禁止对某个类或函数做类型检查的装饰器（参见下文）。</li>
<li>@no_type_check_decorator，用于创建自定义装饰器的装饰器，含义与 <code>@no_type_check</code> 相同（参见下文）。</li>
<li>@type_check_only，仅在对存根文件做类型检查时可用的装饰器，标记某个类或函数在运行时不可用。</li>
<li>@overload，如上所述。</li>
<li>get_type_hints()，用于获取函数或方法的类型提示信息的工具函数。给定一个函数或方法对象，它将以 <code>__annotations__</code> 的格式返回一个<code>dict</code>，向前引用将在原函数或方法定义的上下文中进行表达式求值。</li>
<li>TYPE_CHECKING，运行时为 <code>False</code>，而对类型检查器则为 <code>True</code>。</li>
</ul>
<p>I/O相关的类型：</p>
<ul>
<li>IO（基于 <code>AnyStr</code> 的泛型）</li>
<li>BinaryIO（只是 <code>IO</code> 子类型)</li>
<li>TextIO（只是 <code>IO</code> 子类型)</li>
</ul>
<p>与正则表达式和 <code>re</code> 模块相关的类型：</p>
<ul>
<li><code>Match</code> 和 <code>Pattern</code>，<code>re.match()</code> 和 <code>re.compile()</code> 的结果类型（基于 <code>AnyStr</code> 的泛型）。</li>
</ul>
<div id="straddling">
<h2 id="python-27-和跨版本代码的建议语法suggested-syntax-for-python-27-and-straddling-code">Python 2.7 和跨版本代码的建议语法（Suggested syntax for Python 2.7 and straddling code）</h2>
<p>某些工具软件可能想在必须与 Python 2.7 兼容的代码中支持类型注解。为此，本 PEP 在此给出建议性（而并非强制）扩展，其中函数的类型注解放入 <code># type</code> 注释（comment）中。这种注释必须紧挨着函数头之后，但在文档字符串之前。举个例子，下述 Python 3 代码：</p>
<pre><code>def embezzle(self, account: str, funds: int = 1000000, *fake_receipts: str) -&gt; None:
    """Embezzle funds from account using fake receipts."""
    &lt;code goes here&gt;
</code></pre>
<p>等价于以下代码：</p>
<pre><code>def embezzle(self, account, funds=1000000, *fake_receipts):
    # type: (str, int, *str) -&gt; None
    """Embezzle funds from account using fake receipts."""
    &lt;code goes here&gt;
</code></pre>
<p>请注意，方法的 <code>self</code> 不需要注明类型。</p>
<p>无参数方法则应如下所示：</p>
<pre><code>def load_cache(self):
    # type: () -&gt; bool
    &lt;code&gt;
</code></pre>
<p>有时需要仅为函数或方法指定返回类型，而暂不指定参数类型。为了明确这种需求，可以用省略号替换参数列表。例如：</p>
<pre><code>def send_email(address, sender, cc, bcc, subject, body):
    # type: (...) -&gt; bool
    """Send an email message.Return True if successful."""
    &lt;code&gt;
</code></pre>
<p>参数列表有时会比较长，难以用一条 <code># type:</code> 注释来指定类型。为此可以每行给出一个参数，并在每个参数的逗号之后加上必要的 <code># type:</code> 注释。返回类型可以用省略号语法指定。指定返回类型不是强制性要求，也不是每个参数都需要指定类型。带有 <code># type:</code> 注释的行应该只包含一个参数。最后一个参数的类型注释应该在右括号之前。例如：</p>
<pre><code>def send_email(address,   # type: Union]
               sender,      # type: str
               cc,          # type: Optional]
               bcc,         # type: Optional]
               subject='',
               body=None    # type: List
               ):
    # type: (...) -&gt; bool
    """Send an email message.Return True if successful."""
    &lt;code&gt;
</code></pre>
<p>注意事项：</p>
<ul>
<li>只要工具软件支持这种类型注释语法，就应该与 Python 版本无关。为了支持横跨 Python 2 和 Python 3 的代码，必须如此。</li>
<li>参数或返回值不得同时带有类型注解（annotation）和类型注释（comment）。</li>
<li>如果要采用简写格式（如 <code># type: (str, int) -&gt; None</code>），则每一个参数都必须如此，实例和类方法的第一个参数除外。这第一个参数通常会省略注释，但也允许带上。</li>
<li>简写格式必须带有返回类型。如果是 Python 3 则会省略某些参数或返回类型，而 Python 2 则应使用 <code>Any</code>。</li>
<li>采用简写格式时，<code>*args</code> 和 <code>**kwds</code> 的类型注解前面请对应放置1或2个星号。在用 Python 3 注解格式时，此处的注解表示的是每一个参数值​​的类型，而不是由特殊参数值 <code>args</code> 或 <code>kwds</code> 接收到的 <code>tuple</code>/<code>dict</code> 的类型。</li>
<li>与其他的类型注释相类似，类型注解中用到的任何名称都必须由包含注解的模块导入或定义。</li>
<li>采用简写格式时，整个注解必须在一行之内。</li>
<li>简写格式也可以与右括号处于同一行，例如：</li>
</ul>
<pre><code>def add(a, b):# type: (int, int) -&gt; int
    return a + b
</code></pre>
<ul>
<li>类型检查程序会将位置不对的类型注释标记为错误。如有必要，可以对此类注释作两次注释标记。例如：</li>
</ul>
<pre><code>def f():
    '''Docstring'''
    # type: () -&gt; None# Error!

def g():
    '''Docstring'''
    # # type: () -&gt; None# This is OK
</code></pre>
<p>在对 Python 2.7 代码做类型检查时，类型检查程序应将 <code>int</code> 和 <code>long</code> 视为相同类型。对于注解为 <code>Text</code> 的参数，<code>str</code> 和 <code>unicode</code> 类型也应该是可接受的。</p>
<div id="rejected">
<h2 id="未被接受的替代方案rejected-alternatives">未被接受的替代方案（Rejected Alternatives）</h2>
<p>在讨论本 PEP 的早期草案时，出现过各种反对意见，并提出过一些替代方案。在此讨论其中一些意见，并解释一下未被接受的原因。</p>
<p>下面是几个主要的反对意见。</p>
<div id="bracket">
<h3 id="泛型参数该用什么括号which-brackets-for-generic-type-parameters">泛型参数该用什么括号？（Which brackets for generic type parameters?）</h3>
<p>大多数人都熟知，在C++、Java、C# 和 Swift 等语言当中，用尖括号（如 <code>List&lt;int&gt;</code>）来表示泛型的参数化。这种格式的问题是真的难以解析，尤其是对于像 Python 这种思维简单的解析器而言。在大多数语言中，通常只允许在特定的语法位置用尖括号来解决歧义，而这些位置不允许出现泛型表达式。并且还得采用非常强大的解析技术，可对任何一段代码进行重复解析（backtrack）。</p>
<p>但在 Python 中，更愿意让类型表达式（在语法上）与其他表达式一样，以便用变量赋值之类的操作就能创建类型别名。不妨看看下面这个简单的类型表达式：</p>
<pre><code>List&lt;int&gt;
</code></pre>
<p>从 Python 解析程序的角度来看，以4个短语（名称、小于、名称、大于）开头的表达式将视为连续（chained）比较：</p>
<pre><code>a &lt; b &gt; c# I.e., (a &lt; b) and (b &gt; c)
</code></pre>
<p>甚至可以创建一个两种解析方式共存的示例：</p>
<pre><code>a &lt; b &gt; [ c ]
</code></pre>
<p>假设语言中包含尖括号，则以下两种解释都是可以的：</p>
<pre><code>(a&lt;b&gt;)      # I.e., (a&lt;b&gt;).__getitem__(c)
a &lt; b &gt; ()# I.e., (a &lt; b) and (b &gt; )
</code></pre>
<p>当然能够再提出一种规则来消除上述情况的歧义，但对于大多数用户而言，会觉得这些规则稍显随意和复杂。并且这还要将 CPython 解析程序（和其他所有Python 解析程序）做出很大的改动。有一点应该注意，Python 当前的解析程序是有意如此“愚蠢”的，这样用户很容易就能想到简单的语法。</p>
<p>因为上述所有原因，所以方括号（如 <code>List</code>）是（长期以来都是）泛型参数的首选语法。这通过在元类上定义 <code>__getitem__()</code> 方法就可以实现，根本不需要引入新的语法。这种方案在所有较新版本的 Python（从 Python 2.2 开始）中均有效。并非只有 Python 才选择这种语法，Scala 中的泛型类也采用了方括号。</p>
<div id="exist">
<h3 id="已在用的注解怎么办what-about-existing-uses-of-annotations">已在用的注解怎么办（What about existing uses of annotations?）</h3>
<p>有一条观点指出，PEP 3107 明确支持在函数注解中使用任意表达式。因此，本条新提案被认为与 PEP 3107 规范不兼容。</p>
<p>对此的回应是，首先本提案没有引入任何直接的不兼容性，因此使用注解的程序在 Python 3.4 中仍然可以正确运行，在 Python 3.5 中也毫无影响。</p>
<p>类型提示确实期望能最终成为注解的唯一用途，但这需要再多些讨论，而且 Python 3.5 才首次推出 <code>typing</code> 模块，也需要一段时间实现废弃（deprecation）。直至 Python 3.6 发布之前，当前的 PEP 都将为临时（provisional）状态（参阅 PEP 411）。可能的方案最快将自 3.6 开始无提示地废弃非类型提示的注解，自 3.7 开始完全废弃，并在 Python 3.8 中将类型提示声明为唯一允许使用的注解。即便类型提示在一夜之间取得了成功，也应该让带注解程序包的作者有足够的时间去更换方案。</p>
<p><em>更新</em>：2017年秋季，本 PEP 和 <code>type.py</code> 模块的临时状态终止计划已作更改，因此其他注解用法的弃用计划也已更改。更新过的时间计划请参阅 PEP 563。</p>
<p>另一种可能的结果是，类型提示最终将成为注解的默认含义，但将其禁用的选项也会一直保留。为此，本提案定义了一个装饰器 <code>@no_type_check</code>，该装饰器将禁止对给定类或函数中用作类型提示的注解作默认解释。这里还定义了一个元装饰器 <code>@no_type_check_decorator</code>，可用于对装饰器进行装饰，使得用其装饰的任何函数或类中的注解都会被类型检查程序忽略。</p>
<p>且还有 <code># type: ignore</code> 注解呢，静态检查程序应支持对选中包禁止类型检查的配置项。</p>
<p>尽管有这么多选择可用，但允许类型提示和其他形式的注解共存于参数中的提案已经发布过了一些。有一项提案建议，如果某个参数的注解是字典字面量，则每个字典键都表示一种不同格式的注解，字典键“<code>type</code>”将用于类型提示。这种想法及其变体的问题在于，注解会变得非常“杂乱”，可读性会很差。而且大多数现有采用注解的库，几乎不需要与类型提示混合使用。因此，只要有选择地禁用类型提示就足够了。</p>
<div id="forward-declaration">
<h3 id="前向声明的问题the-problem-of-forward-declarations">前向声明的问题（The problem of forward declarations）</h3>
<p>当类型提示必须包含向前引用时，当前提案无疑是次优选择。Python 要求所有变量在用到时再作定义。除了循环导入外，这不太会有问题：这里的“用到”表示“在运行时去作查找”，并且对于大多数“向前”引用而言，确保在用到名称的函数被调用之前定义名称就没有问题了。</p>
<p>类型提示的问题在于，在定义函数时会对注解进行求值（据 PEP 3107，类似于默认值），因此注解中使用的任何名称在定义函数时必须已经定义。常见的场景是类的定义，其方法需要在注解中引用类本身。更一般地说，在相互递归引用的类中也可能发生这种情况。对于容器类型而言这很自然，例如：</p>
<pre><code>class Node:
    """Binary tree node."""

    def __init__(self, left: Node, right: Node):
      self.left = left
      self.right = right
</code></pre>
<p>上述写法是行不通的，因为 Python 的特性就是，一旦类的全体代码执行完毕，类的名称就定义完成了。我们的解决方案不是特别优雅，但是可以完成任务，也就是允许在注解中使用字符串字面量。不过大多数时候都不必用到字符串，类型提示的大多数应用都应引用内置类型或其他模块中已定义的类型。</p>
<p>有一种答复将会修改类型提示的语义，以便根本不会在运行时对其进行求值。毕竟类型检查是脱机进行的，为什么要在运行时对类型提示进行求值呢。当然这与向下兼容有冲突，因为 Python 解释程序其实并不知道某个注解是要用作类型提示或是有其他用途。</p>
<p>有一种可行的折衷方案，就是用 <code>__future__</code> 导入可以将给定模块中的所有注解都转换为字符串字面量，如下所示：</p>
<pre><code>from __future__ import annotations

class ImSet:
    def add(self, a: ImSet) -&gt; List: ...

assert ImSet.add.__annotations__ == {'a': 'ImSet', 'return': 'List'}
</code></pre>
<p>这种 <code>__future__</code> 导入语句可能会在单独的 PEP 中给出。</p>
<p><em>更新</em>：PEP 563 中已讨论了 <code>__future__</code> 导入语句及其后果。</p>
<div id="double-colon">
<h3 id="双冒号the-double-colon">双冒号（The double colon）</h3>
<p>一些有创造力的人已经尝试发明了多种解决方案。比如有人提议让类型提示采用双冒号（:😃，可以一次解决两个问题：消除类型提示与其他注解之间的歧义、修改语义避免运行时求值。但这种想法有以下几个问题。</p>
<ul>
<li>难看（ugly）。在 Python 中单个冒号有很多用途，并且看起来都很熟悉，因为类似于英文中的冒号用法。这是一条普遍的经验法则，Python 会遵守标点符号的大多数使用格式，那些例外通常也是因其他编程语言而熟知的。但是 :: 的这种用法在英语中是闻所未闻的，而在其他语言（例如 C++）中是被用作作用域操作符的，这太与众不同了。相反，类型提示采用单个冒号读起来很自然，这不足为奇，因为这是为此目的而精心设计的（想法比 PEP 3107 gvr-artima 要早得多）。从 Pascal 到 Swift，其他很多语言也采用了相同的风格。</li>
<li>该如何处理返回类型的注解？</li>
<li>实际上这是在运行时对类型提示进行求值的特性。
<ul>
<li>让类型提示可用于运行时，使得能基于类型提示构建运行时的类型检查程序。</li>
<li>即便代码尚未运行，类型检查程序仍能捕获错误。因为类型检查程序是一个单独的程序，所以用户可以选择不运行（甚至不安装），但仍可能想把类型提示用作简明的文档。错误的类型提示即便当作文档也没啥用处。</li>
</ul>
</li>
<li>因为是新语法，所以把双冒号用于类型提示将会受到限制，只能适用于 Python 3.5 的代码。而利用现有的语法，本提案可以轻松应用于较低版本的Python 3。mypy 实际支持 Python 3.2 以上的版本。</li>
<li>如果类型提示获得成功，可能会决定在未来加入新的语法，用于声明变量的类型，比如 <code>var age: int = 42</code>。如果参数的类型提示采用双冒号，那么为了保持一致，未来的语法必须采用同样的约定，如此难看的语法将会一直流传下去。</li>
</ul>
<div id="other-form">
<h3 id="其他一些新语法格式other-forms-of-new-syntax">其他一些新语法格式（Other forms of new syntax）</h3>
<p>还有一些其他格式的语法也被提出来过，比如引入 <code>where</code> 关键字，以及 Cobra-inspired <code>requires</code> 子句。但这些语法都和双冒号一样存在同样的问题，他们不适用于低版本的 Python 3。新的__future__ 导入语法也同样如此。</p>
<div id="compatible">
<h3 id="其他的向下兼容约定other-backwards-compatible-conventions">其他的向下兼容约定（Other backwards compatible conventions）</h3>
<p>提出的想法有：</p>
<ul>
<li>装饰器，比如 <code>@typehints(name=str, returns=str)</code>。这可能会有用，但太啰嗦了（增加一行代码，并且参数名称必须重复一遍），且与 PEP 3107 的注解方式相去甚远。</li>
<li>存根文件。存根文件确实有需要，但主要是用来把类型提示加入已有代码中，这些代码本身不适合添加类型提示，例如：第三方软件包、需同时支持 Python 2和 Python 3 的代码、（特别是）扩展模块。在大多数情况下，与函数定义放在一起的行内注解会更加有用。</li>
<li>文档字符串。文档字符串对注解已有约定，即基于 Sphinx 注解方式 <code>(:type arg1: description)</code>。这真有点啰嗦（每个参数增加一行代码），而且不太优雅。当然再创造一些新语法也是可以的，但很难超越注解语法（因为它是专为此目的而设计的）。</li>
</ul>
<p>还有人提议，就坐等新的发行版本吧。但这能解决什么问题？只会是拖延下去罢了。</p>
<div id="development">
<h2 id="pep-开发过程pep-development-process">PEP 开发过程（PEP Development Process）</h2>
<p>本 PEP 的最新文稿位于 GitHub 上。另有一个议题跟踪包含了很多技术讨论内容。</p>
<p>GitHub 上的文稿会定期进行小幅更新。通常正式的 PEPS 库只在新文稿发布到 python-dev 时才会更新。</p>
<div id="acknowledgements">
<h2 id="致谢acknowledgements">致谢（Acknowledgements）</h2>
<p>没有 Jim Baker、Jeremy Siek、Michael Matson Vitousek、Andrey Vlasovskikh、Radomir Dopieralski、Peter Ludemann 和BDFL-Delegate、Mark Shannon 的宝贵投入、鼓励和建议，本文就无法完成。</p>
<p>本文受到 PEP 482 中提及的现有语言、库和框架的影响。非常感谢其创建者（按字母序排列）：Stefan Behnel、William Edwards、Greg Ewing、Larry Hastings、Anders Hejlsberg、Alok Menghrajani、Travis E. Oliphant、Joe Pamer、Raoul-Gabriel Urma、and Julien Verlaguet。</p>
<div id="references">
<h2 id="参考文献references">参考文献（References）</h2>
<div id="mypy">
<p> http://mypy-lang.org</p>
<div id="gvr-artima">
<p> http://www.artima.com/weblogs/viewpost.jsp?thread=85551</p>
<div id="wiki-variance">
<p> http://en.wikipedia.org/wiki/Covariance_and_contravariance_%28computer_science%29</p>
<div id="typeshed">
<p> https://github.com/python/typeshed/</p>
<div id="pyflakes">
<p> https://github.com/pyflakes/pyflakes/</p>
<div id="pylint">
<p> http://www.pylint.org</p>
<div id="roberge">
<p> http://aroberge.blogspot.com/2015/01/type-hinting-in-python-focus-on.html</p>
<div id="github">
<p> https://github.com/python/typing</p>
<div id="issues">
<p> https://github.com/python/typing/issues</p>
<div id="peps">
<p> https://hg.python.org/peps/file/tip/pep-0484.txt</p>
<div id="importdocs">
<p> https://docs.python.org/3/reference/import.html#submodules</p>
<div id="copyright">
<h2 id="版权copyright">版权（Copyright）</h2>
<p>本文已在公共领域公开。</p>
<p>来源：https://github.com/python/peps/blob/master/pep-0484.txt</p>
</div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div></div><br><br>
来源：https://www.cnblogs.com/popapa/p/PEP484.html

查看完整版本: PEP 484 类型提示 -- Python官方文档译文 [原创]