新的协程声明语法

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

async def read_data(db):
    pass

协程的关键属性

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

types.coroutine()

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

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

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

如果 fn 不是生成器函数，它将被包装。如果它返回一个生成器，它将被包装在一个可等待代理对象中（请参阅下面关于可等待对象的定义）。

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

Await 表达式

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

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

await 与 yield from 类似，会挂起 read_data 协程的执行，直到 db.fetch 可等待对象完成并返回结果数据。

它使用 yield from 实现，并额外增加了一个验证其参数的步骤。 await 仅接受一个 *可等待对象*，它可以是以下之一

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

  任何 yield from 调用链都以 yield 结尾。 这是 *Futures* 实现的根本机制。 由于协程在内部是特殊类型的生成器，因此每个 await 都通过 yield 在 await 调用链中的某个位置被挂起（有关详细解释，请参考 PEP 3156）。

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

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

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

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

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

将除 *可等待对象* 之外的任何对象传递给 await 表达式会引发 TypeError。

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

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

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

*异步上下文管理器* 是一种上下文管理器，它能够在其 *enter* 和 *exit* 方法中挂起执行。

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

一个异步上下文管理器的示例

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 槽），该方法返回一个 *可等待对象*。
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 装饰器行为没有影响。

有了这个提议，协程成为一个与生成器不同的原生概念。除了对从未等待的协程抛出 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 是一个可等待对象，则返回 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 ABC 用于类 Future 的类，这些类实现了 __await__ 方法。
• collections.abc.Coroutine ABC 用于协程对象，这些对象实现了 send(value)、throw(type, exc, tb)、close() 和 __await__() 方法。

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

  @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

PEP 3152 由 Gregory Ewing 提议，为协程提供了一种不同的机制（称为“cofunctions”）。一些关键点

1. 一个新的关键字 codef 来声明一个 cofunction。Cofunction 始终是一个生成器，即使其中没有 cocall 表达式。映射到本提案中的 async def。
2. 一个新的关键字 cocall 来调用一个 cofunction。只能在 cofunction 中使用。映射到本提案中的 await（有一些区别，请见下文）。
3. 没有 cocall 关键字，就无法调用 cofunction。
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__ 等效的项，该项被调用，其结果被传递给 yield from 在 cocall 表达式中。 await 关键字期望一个 可等待的 对象，验证类型，并在其上执行 yield from。尽管 __await__ 方法类似于 __cocall__，但它仅用于定义 类似 Future 的 对象。
2. await 的定义与语法中的 yield from 几乎相同（稍后强制执行 await 只能在 async def 内部使用）。可以简单地编写 await future，而 cocall 始终需要圆括号。
3. 要使 asyncio 与 PEP 3152 一起使用，需要修改 @asyncio.coroutine 装饰器，以将所有函数包装在具有 __cocall__ 方法的对象中，或者在生成器上实现 __cocall__。要从现有的基于生成器的协程调用 cofunctions，需要使用 costart(cofunc, *args, **kwargs) 内置函数。
4. 由于没有 cocall 关键字就无法调用 cofunction，因此它会自动防止忘记在基于生成器的协程上使用 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__”不返回一个可等待对象

PEP 492 在 CPython 3.5.0 中被接受，其中定义了 __aiter__ 作为一种方法，该方法预期返回一个可等待的对象，并解析为一个异步迭代器。

在 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”可以理解为“迭代器中每个异步项”。

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

为什么不使用 __future__ 导入

过渡计划 部分解释了如何修改词法分析器，以便在 async def 块中仅将 async 和 await 视为关键字。因此，async def 扮演了模块级编译器声明（例如 from __future__ import async_await）的功能。