新协程声明语法

以下新语法用于声明一个 *原生协程*

async def read_data(db):
    pass

协程的关键属性

• async def 函数总是协程，即使它们不包含 await 表达式。
• 在 async 函数中存在 yield 或 yield from 表达式是 SyntaxError。
• 内部，引入了两个新的代码对象标志
  • CO_COROUTINE 用于标记 *原生协程*（用新语法定义）。
  • CO_ITERABLE_COROUTINE 用于使 *基于生成器的协程* 与 *原生协程* 兼容（由 types.coroutine() 函数设置）。
• 普通的生成器在被调用时返回一个 *生成器对象*；类似地，协程返回一个 *协程* 对象。
• StopIteration 异常不会从协程中传播出来，而是被 RuntimeError 替换。对于普通生成器，这种行为需要 future 导入（参见 PEP 479）。
• 当一个 *原生协程* 被垃圾回收时，如果它从未被 await 过，将引发 RuntimeWarning（另请参阅 调试功能）。
• 另请参阅 协程对象 部分。

types.coroutine()

一个新的函数 coroutine(fn) 被添加到 types 模块。它允许 asyncio 中现有的 *基于生成器的协程* 与本 PEP 引入的 *原生协程* 之间互操作

@types.coroutine
def process_data(db):
    data = yield from read_data(db)
    ...

该函数将 CO_ITERABLE_COROUTINE 标志应用于生成器函数的代码对象，使其返回一个 *协程* 对象。

如果 fn 不是 *生成器函数*，它将被包装。如果它返回一个 *生成器*，它将被包装在一个 *awaitable* 代理对象中（参见下面 awaitable 对象的定义）。

请注意，CO_COROUTINE 标志不被 types.coroutine() 应用，以便将使用新语法定义的 *原生协程* 与 *基于生成器的协程* 分开。

Await 表达式

新的 await 表达式用于获取协程执行结果

async def read_data(db):
    data = await db.fetch('SELECT ...')
    ...

await，与 yield from 类似，会暂停 read_data 协程的执行，直到 db.fetch *awaitable* 完成并返回结果数据。

它使用 yield from 的实现，并额外增加了对其参数的验证。await 只接受一个 *awaitable*，它可以是以下之一：

• 从 *原生协程函数* 返回的 *原生协程* 对象。
• 从用 types.coroutine() 装饰的函数返回的 *基于生成器的协程* 对象。
• 具有返回迭代器的 __await__ 方法的对象。

  任何 yield from 调用链都以一个 yield 结束。这是 *Futures* 实现的基本机制。由于协程在内部是特殊类型的生成器，每个 await 都会被 await 调用链中某个地方的 yield 暂停（请参阅 PEP 3156 以获取详细解释）。

  为了使协程能够实现这种行为，新增了一个名为 __await__ 的魔术方法。例如，在 asyncio 中，要在 await 语句中启用 *Future* 对象，唯一的更改是在 asyncio.Future 类中添加 __await__ = __iter__ 行。

  具有 __await__ 方法的对象在本 PEP 的其余部分中称为 *Future-like* 对象。

  如果 __await__ 返回的不是迭代器，则会引发 TypeError。

• 使用 CPython C API 定义的对象，其 tp_as_async.am_await 函数返回一个 *迭代器*（类似于 __await__ 方法）。

在 async def 函数之外使用 await 是 SyntaxError（就像在 def 函数之外使用 yield 是 SyntaxError 一样）。

将非 *awaitable* 对象传递给 await 表达式会引发 TypeError。

power ::=  await ["**" u_expr]
await ::=  ["await"] primary

primary ::=  atom | attributeref | subscription | slicing | call

异步上下文管理器和“async with”

一个 *异步上下文管理器* 是一个上下文管理器，它能够在其 *进入* 和 *退出* 方法中暂停执行。

为了实现这一点，提出了一个用于异步上下文管理器的新协议。添加了两个新的魔术方法：__aenter__ 和 __aexit__。两者都必须返回一个 *awaitable*。

异步上下文管理器的示例

class AsyncContextManager:
    async def __aenter__(self):
        await log('entering context')

    async def __aexit__(self, exc_type, exc, tb):
        await log('exiting context')

async with EXPR as VAR:
    BLOCK

mgr = (EXPR)
aexit = type(mgr).__aexit__
aenter = type(mgr).__aenter__

VAR = await aenter(mgr)
try:
    BLOCK
except:
    if not await aexit(mgr, *sys.exc_info()):
        raise
else:
    await aexit(mgr, None, None, None)

async def commit(session, data):
    ...

    async with session.transaction():
        ...
        await session.update(data)
        ...

async with lock:
    ...

with (yield from lock):
    ...

异步迭代器和“async for”

一个 *异步可迭代对象* 能够在其 *iter* 实现中调用异步代码，而 *异步迭代器* 能够在其 *next* 方法中调用异步代码。为了支持异步迭代

1. 一个对象必须实现 __aiter__ 方法（或者，如果用 CPython C API 定义，则为 tp_as_async.am_aiter 槽），返回一个 *异步迭代器对象*。
2. 一个 *异步迭代器对象* 必须实现 __anext__ 方法（或者，如果用 CPython C API 定义，则为 tp_as_async.am_anext 槽），返回一个 *awaitable*。
3. 要停止迭代，__anext__ 必须引发 StopAsyncIteration 异常。

异步可迭代对象的示例

class AsyncIterable:
    def __aiter__(self):
        return self

    async def __anext__(self):
        data = await self.fetch_data()
        if data:
            return data
        else:
            raise StopAsyncIteration

    async def fetch_data(self):
        ...

async for TARGET in ITER:
    BLOCK
else:
    BLOCK2

iter = (ITER)
iter = type(iter).__aiter__(iter)
running = True
while running:
    try:
        TARGET = await type(iter).__anext__(iter)
    except StopAsyncIteration:
        running = False
    else:
        BLOCK
else:
    BLOCK2

async for data in cursor:
    ...

class Cursor:
    def __init__(self):
        self.buffer = collections.deque()

    async def _prefetch(self):
        ...

    def __aiter__(self):
        return self

    async def __anext__(self):
        if not self.buffer:
            self.buffer = await self._prefetch()
            if not self.buffer:
                raise StopAsyncIteration
        return self.buffer.popleft()

async for row in Cursor():
    print(row)

i = Cursor().__aiter__()
while True:
    try:
        row = await i.__anext__()
    except StopAsyncIteration:
        break
    else:
        print(row)

class AsyncIteratorWrapper:
    def __init__(self, obj):
        self._it = iter(obj)

    def __aiter__(self):
        return self

    async def __anext__(self):
        try:
            value = next(self._it)
        except StopIteration:
            raise StopAsyncIteration
        return value

async for letter in AsyncIteratorWrapper("abc"):
    print(letter)

def g1():
    yield from fut
    return 'spam'

def g2():
    yield from fut
    raise StopIteration('spam')

async def a1():
    await fut
    raise StopIteration('spam')

协程对象

调试功能

一个常见的初学者错误是忘记对协程使用 yield from

@asyncio.coroutine
def useful():
    asyncio.sleep(1) # this will do nothing without 'yield from'

为了调试这类错误，asyncio 中有一个特殊的调试模式，其中 @coroutine 装饰器用一个特殊的带有析构函数的对象包装所有函数，该析构函数会记录警告。每当被包装的生成器被垃圾回收时，都会生成一条详细的日志消息，其中包含装饰器函数定义的位置、收集时的堆栈跟踪等信息。包装器对象还提供了一个方便的 __repr__ 函数，其中包含有关生成器的详细信息。

唯一的问题是如何启用这些调试功能。由于调试功能在生产模式下应为无操作，@coroutine 装饰器根据操作系统环境变量 PYTHONASYNCIODEBUG 来决定是否包装。这样就可以运行带有 asyncio 自身函数检测的 asyncio 程序。EventLoop.set_debug，另一个调试功能，对 @coroutine 装饰器的行为没有影响。

本提案提出，协程是与生成器不同的原生概念。*除了* 在从未被 await 的协程上引发 RuntimeWarning 之外，还建议在 sys 模块中添加两个新函数：set_coroutine_wrapper 和 get_coroutine_wrapper。这是为了在 asyncio 和其他框架中启用高级调试功能（例如显示协程的创建位置，以及更详细的垃圾回收堆栈跟踪）。

新标准库函数

• types.coroutine(gen)。详情请参阅 types.coroutine() 部分。
• inspect.iscoroutine(obj) 如果 obj 是 *原生协程* 对象，则返回 True。
• inspect.iscoroutinefunction(obj) 如果 obj 是 *原生协程函数*，则返回 True。
• inspect.isawaitable(obj) 如果 obj 是 *awaitable*，则返回 True。
• inspect.getcoroutinestate(coro) 返回 *原生协程对象* 的当前状态（与 inspect.getfgeneratorstate(gen) 镜像）。
• inspect.getcoroutinelocals(coro) 返回 *原生协程对象* 的局部变量到其值的映射（与 inspect.getgeneratorlocals(gen) 镜像）。
• sys.set_coroutine_wrapper(wrapper) 允许拦截 *原生协程* 对象的创建。wrapper 必须是一个接受一个参数（一个 *协程* 对象）的可调用对象，或者是 None。None 会重置包装器。如果调用两次，新包装器会替换前一个。该函数是线程特有的。更多详情请参阅 调试功能。
• sys.get_coroutine_wrapper() 返回当前包装器对象。如果没有设置包装器，则返回 None。该函数是线程特有的。更多详情请参阅 调试功能。

新抽象基类

为了更好地与现有框架（如 Tornado，参见 [13]）和编译器（如 Cython，参见 [16]）集成，新增了两个抽象基类 (ABC)

• collections.abc.Awaitable 抽象基类，用于实现 __await__ 方法的 *Future-like* 类。
• collections.abc.Coroutine 抽象基类，用于实现 send(value)、throw(type, exc, tb)、close() 和 __await__() 方法的 *协程* 对象。

  请注意，带有 CO_ITERABLE_COROUTINE 标志的基于生成器的协程不实现 __await__ 方法，因此它们不是 collections.abc.Coroutine 和 collections.abc.Awaitable 抽象基类的实例

  @types.coroutine
  def gencoro():
      yield
  
  assert not isinstance(gencoro(), collections.abc.Coroutine)
  
  # however:
  assert inspect.isawaitable(gencoro())
  

为了方便测试对象是否支持异步迭代，又添加了两个 ABC

• collections.abc.AsyncIterable – 测试 __aiter__ 方法。
• collections.abc.AsyncIterator – 测试 __aiter__ 和 __anext__ 方法。

向后兼容性

本提案保留 100% 的向后兼容性。

语法更新

语法变化相当小

decorated: decorators (classdef | funcdef | async_funcdef)
async_funcdef: ASYNC funcdef

compound_stmt: (if_stmt | while_stmt | for_stmt | try_stmt | with_stmt
                | funcdef | classdef | decorated | async_stmt)

async_stmt: ASYNC (funcdef | with_stmt | for_stmt)

power: atom_expr ['**' factor]
atom_expr: [AWAIT] atom trailer*

废弃计划

async 和 await 名称将在 CPython 3.5 和 3.6 中被软废弃。在 3.7 中，我们将它们转换为正式关键字。在 3.7 之前将 async 和 await 转换为正式关键字可能会使人们更难将代码移植到 Python 3。

PEP 3152

Gregory Ewing 的 PEP 3152 提出了另一种协程机制（称为“协函数”）。一些关键点

1. 一个新的关键字 codef 用于声明一个 *协函数*。*协函数* 总是生成器，即使它内部没有 cocall 表达式。在本提案中映射到 async def。
2. 一个新的关键字 cocall 用于调用 *协函数*。只能在 *协函数* 内部使用。在本提案中映射到 await（有一些差异，见下文）。
3. 没有 cocall 关键字，不可能调用 *协函数*。
4. cocall 语法上要求其后有括号

   atom: cocall | <existing alternatives for atom>
   cocall: 'cocall' atom cotrailer* '(' [arglist] ')'
   cotrailer: '[' subscriptlist ']' | '.' NAME
   

5. cocall f(*args, **kwds) 在语义上等同于 yield from f.__cocall__(*args, **kwds)。

与本提案的区别

1. 此 PEP 中没有 __cocall__ 的等价物，它被调用并且其结果在 cocall 表达式中传递给 yield from。await 关键字期望一个 *awaitable* 对象，验证类型，并在其上执行 yield from。尽管 __await__ 方法与 __cocall__ 相似，但它仅用于定义 *类 Future* 对象。
2. await 在语法上与 yield from 的定义几乎相同（后来强制规定 await 只能在 async def 内部）。可以直接写 await future，而 cocall 总是需要括号。
3. 为了使 asyncio 与 PEP 3152 一起工作，需要修改 @asyncio.coroutine 装饰器，将所有函数包装在一个带有 __cocall__ 方法的对象中，或者在生成器上实现 __cocall__。要从现有基于生成器的协程调用 *协函数*，需要使用内置函数 costart(cofunc, *args, **kwargs)。
4. 由于没有 cocall 关键字就无法调用 *协函数*，这自动防止了忘记对基于生成器的协程使用 yield from 的常见错误。本提案通过不同的方法解决了这个问题，请参阅 调试功能。
5. 强制要求 cocall 关键字来调用协程的一个缺点是，如果决定实现协程生成器——带有 yield 或 async yield 表达式的协程——我们将不需要 cocall 关键字来调用它们。因此，对于普通协程，我们将只有 __cocall__ 而没有 __call__；对于协程生成器，我们将只有 __call__ 而没有 __cocall__。
6. 在语法上要求括号也引入了许多新问题。

   以下代码

   await fut
   await function_returning_future()
   await asyncio.gather(coro1(arg1, arg2), coro2(arg1, arg2))
   

   会是这样

   cocall fut()  # or cocall costart(fut)
   cocall (function_returning_future())()
   cocall asyncio.gather(costart(coro1, arg1, arg2),
                         costart(coro2, arg1, arg2))
   

7. PEP 3152 中没有 async for 和 async with 的等价物。

协程生成器

有了 async for 关键字，我们期望有一个 *协程生成器* 的概念——一个带有 yield 和 yield from 表达式的协程。为了避免与普通生成器产生歧义，我们可能需要 yield 前面加上 async 关键字，而 async yield from 将引发 StopAsyncIteration 异常。

虽然实现协程生成器是可能的，但我们认为它们超出了本提案的范围。这是一个高级概念，应该仔细考虑和平衡，并且需要对当前生成器对象的实现进行非简单的更改。这是一个单独的 PEP 的问题。

为什么是“async”和“await”关键字

async/await 在编程语言中并非新概念

• C# 早已拥有此功能 [5]；
• ECMASCript 7 中添加 async/await 的提案 [2]；另请参见 Traceur 项目 [9]；
• Facebook 的 Hack/HHVM [6]；
• Google 的 Dart 语言 [7]；
• Scala [8]；
• 向 C++ 添加 async/await 的提案 [10]；
• 以及许多其他不那么流行的语言。

这是一个巨大的好处，因为一些用户已经有 async/await 的经验，而且它使得在一个项目中使用多种语言更容易（例如 Python 与 ECMAScript 7）。

为什么“__aiter__”不返回一个 awaitable

PEP 492 在 CPython 3.5.0 中被接受，其中 __aiter__ 被定义为一个方法，预期返回一个解析为异步迭代器的 awaitable。

在 3.5.2 中（因为 PEP 492 是临时接受的），__aiter__ 协议已更新为直接返回异步迭代器。

此更改的动机是为了能够在 Python 中实现异步生成器。更多详细信息请参阅 [19] 和 [20]。

“async”关键字的重要性

虽然可以只实现 await 表达式，并将所有至少带有一个 await 的函数视为协程，但这种方法会使 API 设计、代码重构及其长期支持变得更加困难。

假设 Python 只有 await 关键字

def useful():
    ...
    await log(...)
    ...

def important():
    await useful()

如果 useful() 函数经过重构，有人从中删除了所有 await 表达式，它将变成一个普通的 Python 函数，所有依赖于它的代码，包括 important()，都将损坏。为了缓解这个问题，必须引入一个类似于 @asyncio.coroutine 的装饰器。

为什么是“async def”

对一些人来说，裸露的 async name(): pass 语法可能比 async def name(): pass 更具吸引力。它无疑更容易键入。但另一方面，它打破了 async def、async with 和 async for 之间的对称性，在这些地方 async 是一个修饰符，表明该语句是异步的。它也更符合现有语法。

为什么不是“await for”和“await with”

async 是一个形容词，因此它更适合作为 *语句限定符* 关键字。await for/with 将意味着某些东西正在等待 for 或 with 语句的完成。

为什么是“async def”而不是“def async”

async 关键字是一个 *语句限定符*。一个很好的类比是其他语言中的“static”、“public”、“unsafe”关键字。“async for”是一个异步“for”语句，“async with”是一个异步“with”语句，“async def”是一个异步函数。

将“async”放在主要语句关键字之后可能会引入一些混淆，例如“for async item in iterator”可能被解读为“对于迭代器中的每个异步项”。

将 async 关键字放在 def、with 和 for 之前也使语言语法更简单。而且“async def”在视觉上更好地将协程与普通函数区分开来。

为什么不是 __future__ 导入

转换计划 部分解释了词法分析器如何修改，以便 *仅在* async def 块中将 async 和 await 视为关键字。因此，async def 扮演了一个模块级编译器声明（如 from __future__ import async_await）所扮演的角色。

为什么魔术方法以“a”开头

新的异步魔术方法 __aiter__、__anext__、__aenter__ 和 __aexit__ 都以相同的前缀“a”开头。另一种提案是使用“async”前缀，这样 __anext__ 就变成了 __async_next__。然而，为了使新的魔术方法与现有的方法（如 __radd__ 和 __iadd__）对齐，决定使用较短的版本。

为什么不重用现有的魔术名称

关于新的异步迭代器和上下文管理器的另一个想法是，通过向它们的声明添加 async 关键字来重用现有的魔术方法

class CM:
    async def __enter__(self): # instead of __aenter__
        ...

这种方法有以下缺点

• 不可能创建一个同时在 with 和 async with 语句中工作的对象；
• 这将破坏向后兼容性，因为在 Python <= 3.4 中，没有任何限制可以从 __enter__ 和/或 __exit__ 返回类 Future 对象；
• 本提案的主要观点之一是使原生协程尽可能简单和万无一失，因此协议之间有明确的分离。

为什么不重用现有的“for”和“with”语句

现有基于生成器的协程和本提案背后的愿景是让用户更容易看到代码可能暂停的位置。让现有的“for”和“with”语句识别异步迭代器和上下文管理器将不可避免地创建隐式暂停点，从而使代码推理变得更加困难。

推导式

可以提供异步推导式语法，但此构造超出本 PEP 的范围。

异步 lambda 函数

可以提供异步 lambda 函数的语法，但此构造超出本 PEP 的范围。

总体影响

本提案没有引入可观察的性能影响。以下是 Python 官方基准测试集 [4] 的输出

python perf.py -r -b default ../cpython/python.exe ../cpython-aw/python.exe

[skipped]

Report on Darwin ysmac 14.3.0 Darwin Kernel Version 14.3.0:
Mon Mar 23 11:59:05 PDT 2015; root:xnu-2782.20.48~5/RELEASE_X86_64
x86_64 i386

Total CPU cores: 8

### etree_iterparse ###
Min: 0.365359 -> 0.349168: 1.05x faster
Avg: 0.396924 -> 0.379735: 1.05x faster
Significant (t=9.71)
Stddev: 0.01225 -> 0.01277: 1.0423x larger

The following not significant results are hidden, use -v to show them:
django_v2, 2to3, etree_generate, etree_parse, etree_process, fastpickle,
fastunpickle, json_dump_v2, json_load, nbody, regex_v8, tornado_http.

词法分析器修改

解析修改后的词法分析器解析 Python 文件没有明显的减速：解析一个 12Mb 的文件（Lib/test/test_binop.py 重复 1000 次）花费相同的时间。

async/await

以下微基准测试用于确定“async”函数和生成器之间的性能差异

import sys
import time

def binary(n):
    if n <= 0:
        return 1
    l = yield from binary(n - 1)
    r = yield from binary(n - 1)
    return l + 1 + r

async def abinary(n):
    if n <= 0:
        return 1
    l = await abinary(n - 1)
    r = await abinary(n - 1)
    return l + 1 + r

def timeit(func, depth, repeat):
    t0 = time.time()
    for _ in range(repeat):
        o = func(depth)
        try:
            while True:
                o.send(None)
        except StopIteration:
            pass
    t1 = time.time()
    print('{}({}) * {}: total {:.3f}s'.format(
        func.__name__, depth, repeat, t1-t0))

结果是没有明显的性能差异

binary(19) * 30: total 53.321s
abinary(19) * 30: total 55.073s

binary(19) * 30: total 53.361s
abinary(19) * 30: total 51.360s

binary(19) * 30: total 49.438s
abinary(19) * 30: total 51.047s

请注意，深度为 19 意味着 1,048,575 次调用。

高级别更改和新协议列表

1. 定义协程的新语法：async def 和新的 await 关键字。
2. 类 Future 对象的新 __await__ 方法，以及 PyTypeObject 中的新 tp_as_async.am_await 槽。
3. 异步上下文管理器的新语法：async with。以及与 __aenter__ 和 __aexit__ 方法相关的协议。
4. 异步迭代的新语法：async for。以及与 __aiter__、__aexit__ 和新的内置异常 StopAsyncIteration 相关的协议。PyTypeObject 中的新 tp_as_async.am_aiter 和 tp_as_async.am_anext 槽。
5. 新的 AST 节点：AsyncFunctionDef, AsyncFor, AsyncWith, Await。
6. 新函数：sys.set_coroutine_wrapper(callback), sys.get_coroutine_wrapper(), types.coroutine(gen), inspect.iscoroutinefunction(func), inspect.iscoroutine(obj), inspect.isawaitable(obj), inspect.getcoroutinestate(coro), 和 inspect.getcoroutinelocals(coro)。
7. 代码对象的新 CO_COROUTINE 和 CO_ITERABLE_COROUTINE 位标志。
8. 新的抽象基类：collections.abc.Awaitable、collections.abc.Coroutine、collections.abc.AsyncIterable 和 collections.abc.AsyncIterator。
9. C API 更改：新的 PyCoro_Type（在 Python 中公开为 types.CoroutineType）和 PyCoroObject。PyCoro_CheckExact(*o) 用于测试 o 是否为 *原生协程*。

虽然更改和新事物的列表不短，但重要的是要理解，大多数用户不会直接使用这些功能。它们旨在用于框架和库中，为用户提供方便易用且明确的 API，并支持 async def、await、async for 和 async with 语法。

工作示例

本 PEP 中提出的所有概念均已实现 [3] 并可进行测试。

import asyncio

async def echo_server():
    print('Serving on localhost:8000')
    await asyncio.start_server(handle_connection,
                               'localhost', 8000)

async def handle_connection(reader, writer):
    print('New connection...')

    while True:
        data = await reader.read(8192)

        if not data:
            break

        print('Sending {:.10}... back'.format(repr(data)))
        writer.write(data)

loop = asyncio.get_event_loop()
loop.run_until_complete(echo_server())
try:
    loop.run_forever()
finally:
    loop.close()