PEP 492 -- Coroutines with async and await syntax 翻譯

摘要： 因為工作中慢慢開始用python的協程，所以想更好的理解一下實現方式，故翻譯此文 原文中把詞彙表放到最後，但是我個人覺得放在最開始比較好，這樣可以增加當你看原文時的理解程度 詞彙表 原生協程函式 Native coroutine function： 由async def定義的協...

因為工作中慢慢開始用python的協程，所以想更好的理解一下實現方式，故翻譯此文

原文中把詞彙表放到最後，但是我個人覺得放在最開始比較好，這樣可以增加當你看原文時的理解程度

詞彙表

原生協程函式 Native coroutine function：

由async def定義的協程函式，可以使用await和return value語句

原生協程 Native coroutine：

原生協程函式返回的物件。見“await表示式”一節。

基於生成器的協程函式 Generator-based coroutine function：

基於生成器語法的協程，最常見的是用 @asyncio.coroutine裝飾過的函式。

基於生成器的協程 Generator-based coroutine：

基於生成器的協程函式返回的物件。

協程 Coroutine：

“原生協程”和“基於生成器的協程”都是協程。

協程物件 Coroutine object：

“原生協程物件”和“基於生成器的協程物件”都是協程物件。

Future-like物件 Future-like object：

一個有__await__方法的物件，或一個有tp_as_async->am_await函式的C語言物件，它們返回一個迭代器。Future-like物件可以在協程裡被一條await語句消費（consume）。協程會被await語句掛起，直到await語句右邊的Future-like物件的__await__執行完畢、返回結果。見“await表示式”一節。

Awaitable

一個Future-like物件或一個協程物件。見“await表示式”一節。

非同步上下文管理器 Asynchronous context manager：

有__aenter__和__aexit__方法的物件，可以被async with語句使用。見“非同步上下文管理器和‘async with’”一節。

可非同步迭代物件 Asynchronous iterable：

有__aiter__方法的物件， 該方法返回一個非同步迭代器物件。可以被async for語句使用。見“非同步迭代器和‘async for’”一節。

非同步迭代器 Asynchronous iterator：

有__anext__方法的物件。見“非同步迭代器和‘async for’”一節。

摘要

隨著網際網路和連線程式的增長，引發了對響應性和可擴充套件程式碼的需求，該提議的目標是讓我們共容易的通過編寫顯示非同步，高併發的python程式碼並且更加Pythonic

它提出把寫成的概念獨立出來，並引入新的支援語法。最終的目標是幫助在python中建立一個通用的，易於接近的非同步程式設計構思模型，並使其儘可能接近於同步程式設計(說白了就是讓你通過類似寫同步程式設計的方式，寫出非同步程式碼 )

這個PEPE建設非同步任務是類似於標準模組asyncio.events.AbstractEventLoop的事件迴圈排程和協調。雖然這個PEP不依賴人去特定的時間迴圈實現，但它僅僅與使用yield作為排程程式訊號的協程型別相關，表示協程將等待知道事件(例如:IO)完成

我們相信，這裡提出的更改將有助於python在快速增長的非同步程式設計領域保持更好的競爭力，因為許多其他語言已經採或將要採用類似的功能

API設計和實施修訂

對Python 3.5的初始beta版本的反饋導致重新設計支援此PEP的物件模型，以更清楚地將原生協程與生成器分離 - 而不是一種新的生成器，現在原生協程有明確的獨立型別

這個改變主要是為了解決原生協程在tornado裡使用出現的一些問題

在CPython3.5.2 中更新了__aiter__ 協議。

在3.5.2之前，__aiter__ 是被期望返回一個等待解析為非同步迭代器，從3.5.2開始，__aiter__ 應該直接返回非同步迭代器

如果在3.5.2中使用舊協議中，Python將引發PendingDeprecationWarning異常

在CPython 3.6中，舊的__aiter__協議仍將受到引發DeprecationWarning的支援

在CPython 3.7中，將不再支援舊的__aiter__協議：如果__aiter__返回除非同步迭代器之外的任何內容，則將引發RuntimeError。

理論和目標

當前的Python支援通過生成器（PEP342）實現協程，並通過PEP380中引入的yield from 語法進一步增強，這種方法有很多缺點：

• 協程式與生成器具有相同的語法，很容易混淆，對於初級開發者來說尤其如此。
• 一個函式是否是一個協程，取決於它裡面是否出現了yield或yield from語句。這並不明顯，容易在重構函式的時候搞亂，導致出錯。
• 非同步呼叫被yield語法限制了，我們不能獲得、使用更多的語法特性，比如with和for。

這個PEP把協程從生成器獨立出來，成為Python的一個原生事物。這會消除協程和生成器之間的混淆，方便編寫不依賴特定庫的協程程式碼。也為linter和IDE進行程式碼靜態分析提供了機會。

使用原生協程和相應的新語法，我們可以在非同步程式設計時使用上下文管理器（context manager）和迭代器。如下文所示，新的async with語句可以在進入、離開執行上下文（runtime context）時進行非同步呼叫，而async for語句可以在迭代時進行非同步呼叫。

規範

該提議引入了新的語法和語義來增強Python對協程支援。

請理解Python現有的協程（見PEP 342和PEP 380），這次改變的動機來自於asyncio框架（PEP 3156）和Confunctions提案（PEP 3152，此PEP已經被廢棄）。

由此，在本文中，我們使用“原生協程”指用新語法宣告的協程。“生成器實現的協程”指用傳統方法實現的協程。“協程”則用在兩個都可以使用的地方。

新的協程宣告語法

使用以下語法宣告原生協程：

async def read_data(db):
pass

協程語法的關鍵點：

• async def函式必定是協程，即使裡面不含有await語句。
• 如果在async函式裡面使用yield或yield from語句，會引發SyntaxError異常。

• 在CPython內部，引入兩個新的程式碼物件標識（code object flags）：
  CO_COROUTINE表示這是原生協程。（由新語法定義）
  CO_ITERABLE_COROUTINE表示這是用生成器實現的協程，但是和原生協程相容。（用裝飾器types.coroutine()裝飾過的生成器協程）
• 呼叫一個普通生成器，返回一個生成器物件（generator object）；相應的，呼叫一個協程返回一個協程物件（coroutine object
• 協程不再丟擲StopIteration異常，因為丟擲的StopIteration異常會被包裝（wrap）成一個RuntimeError異常。對於普通的生成器想要這樣需要進行future import
• 如果一個協程從未await等待就被垃圾收集器銷燬了，會引發一個RuntimeWarning異常

types.coroutine()

types模組添加了一個新函式coroutine(fn)，使用它，“生成器實現的協程”和“原生協程”之間可以進行互操作。

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

該函式將CO_ITERABLE_COROUTINE標誌應用於生成器函式的程式碼物件，使其返回一個協程物件。如果fn不是生成器函式，它將被包裝。如果它返回一個生成器，它將被包裝在一個等待的代理物件中（參見下面的等待物件的定義）。

types.coroutine()不會設定CO_COROUTINE標識，只有用新語法定義的原生協程才會有這個標識。

await表示式

新的await表示式用於獲得協程執行的結果：

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

await 和yield from 是非常類似的，會掛起read_data的執行，直到等待db.fetch完成並返回結果資料。

await使用yield from的實現，但是加入了一個額外步驟——驗證它的引數型別。await只接受awaitable物件，awaitable物件是以下的其中一個：

• 一個原生協程物件（由一個原生協程函式返回）
• 用裝飾器types.coroutine()裝飾的一個“生成器實現的協程”物件

• 一個有__await__方法的物件（__await__方法返回的一個迭代器）。呼叫鏈上的每一個yield from 最終都會以一個yield結束，這是Future實現的基本機制。在Python內部，協程是一種特殊的生成器，所以每個await最終會被await呼叫鏈條上的某個yield語句掛起。為了讓協程也有這樣的行為，添加了一個新的魔術方法__await__。

  例如，在asyncio模組，要想在await語句裡使用Future物件，唯一的修改是給asyncio.Future加一行：__await__ = __iter__

在本文中，有__await__方法的物件被稱為Future-like物件（協程會被await語句掛起，直到await語句右邊的Future-like物件的__await__執行完畢、返回結果。）

如果__await__返回的不是一個迭代器，則引發TypeError異常。

在CPython C API，有tp_as_async.am_await函式的物件，該函式返回一個迭代器（類似__await__方法）

如果在async def函式之外使用await語句，會引發SyntaxError異常。這和在def函式之外使用yield語句一樣。

如果await右邊不是一個awaitable物件，會引發TypeError異常。

新的運算子優先順序表

有效的語法示例

Expression	Will be parsed as
if await fut: pass	if (await fut): pass
if await fut + 1: pass	if (await fut) + 1: pass
pair = await fut, 'spam'	pair = (await fut), 'spam'
with await fut, open(): pass	with (await fut), open(): pass
await foo()['spam'].baz()()	await ( foo()['spam'].baz()() )
return await coro()	return ( await coro() )
res = await coro() ** 2	res = (await coro()) ** 2
func(a1=await coro(), a2=0)	func(a1=(await coro()), a2=0)
await foo() + await bar()	(await  foo()) + (await bar())
-await foo()	-(await foo())

無效的用法

Expression	Should be written as
await await coro()	await (await coro())
await -coro()	await (-coro())

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

非同步上下文管理器（asynchronous context manager），可以在它的enter和exit方法裡掛起、呼叫非同步程式碼。

為此，我們設計了一套方案，添加了兩個新的魔術方法：__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__(mgr)

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

與常規with語句一樣，可以在單個async with語句中指定多個上下文管理器。

在使用async with時，如果上下文管理器沒有__aenter__和__aexit__方法，則會引發錯誤。在async def函式之外使用async with則會引發SyntaxError異常。

例子

使用非同步上下文管理器，可以輕鬆地為協同程式實現適當的資料庫事務管理器：

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

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

加鎖的處理也更加簡潔

async with lock:
...

而不再是：

with (yield from lock):
...

非同步迭代器和“async for”

非同步迭代器可以在它的iter實現裡掛起、呼叫非同步程式碼，也可以在它的__next__方法裡掛起、呼叫非同步程式碼。要支援非同步迭代，需要：

• 物件必須實現__aiter__方法（或者，如果使用CPython C API，需要定義tp_as_async.am_aiter）返回一個非同步迭代器物件
• 一個非同步迭代物件必須實現一個__anext__方法（或者，如果使用CPython C API，需要定義tp_as_async.am_anext）返回一個awaitable
• 要停止迭代，__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的迭代器不支援__aiter__方法，則引發TypeError異常。如果在async def函式外使用async for，則引發SyntaxError異常。

和普通的for語句一樣，async for有一個可選的else分句。

例子1

使用非同步迭代協議，可以在迭代期間非同步緩衝資料：

async for data in cursor:
...

其中cursor是一個非同步迭代器，它在每N次迭代後從資料庫中預取N行資料。

以下程式碼說明了新的非同步迭代協議：

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()

然後，可以這樣使用Cursor類

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

與下述程式碼相同：

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

例子2：

以下是將常規迭代轉換為非同步迭代的實用程式類。雖然這不是一件非常有用的事情，但程式碼說明了常規迭代器和非同步迭代器之間的關係。

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)

為什麼是StopAsyncIteration？

協程在內部仍然是基於生成器實現的，因此，在PEP479之前，下面兩者是沒有區別的

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

和

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

由於PEP 479已被正式採納，並作用於協程，以下程式碼的StopIteration會被包裝（wrapp）成一個RuntimeError。

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

所以，要想通知外部程式碼迭代已經結束，丟擲一個StopIteration異常的方法不行了。因此，添加了一個新的內建異常StopAsyncIteration，用於表示迭代結束。

此外，根據PEP 479，協程丟擲的所有StopIteration異常都會被包裝成RuntimeError異常。

協程物件

和生成器的不同之處

本節僅適用於具有CO_COROUTINE的原生協程，即使用新的async def 定義的函式

對於asyncio模組裡現有的“基於生成器的協程”，仍然保持不變。

為了把協程和生成器的概念區分開來：

1. 原生協程物件不實現__iter__和__next__方法，因此，不能對其進行迭代（如for...in迴圈），也不能傳遞給iter()，list()，tuple()及其它內建函式。如果嘗試對其使用__iter__或__next__方法，會引發TypeError異常。
2. 未裝飾的生成器不能yield from一個原生協程，這樣做會引發TypeError異常。
3. “基於生成器的協程”在經過 @asyncio.coroutine裝飾後，可以yield from原生協程物件。
4. 對於原生協程物件和原生協程函式，呼叫inspect.isgenerator()和inspect.isgeneratorfunction()會返回False。

協程物件的方法

協程是基於生成器實現的，因此它們有共同的程式碼。像生成器物件那樣，協程也有throw()，send()和close()方法。

對於協程，StopIteration和GeneratorExit起著同樣的作用（雖然PEP 479已經應用於協程）。詳見PEP 342、PEP 380，以及Python文件。

對於協程，send()，throw()方法用於往Future-like物件傳送內容、丟擲異常。

除錯特性

初級開發者在使用協程時可能忘記使用yield from語句，比如：

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

為了除錯這種錯誤，在asyncio中有一個特殊的除錯模式，其中@coroutine裝飾器用一個特殊物件包裝所有函式，並使用解構函式記錄警告。每當一個包裝的生成器被垃圾回收時，就會生成一條詳細的日誌訊息，其中包含有關定義裝飾器函式的確切位置，堆疊跟蹤收集位置等的資訊.Wrapper物件還提供了一個方便的__repr__函式，其中包含有關生成器的詳細資訊。

新標準庫函式

• 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必須是一個接受一個引數callable（一個協程物件），或者是None。None會重置（reset）這個wrapper。如果再次呼叫，新的wrapper會取代舊的。這個函式是執行緒專有的（thread-specific）。詳見“排程特性”一節。
• sys.get_coroutine_wrapper() 返回當前的包裝物件(wrapper object)。如果沒有則返回None。這個函式是執行緒專有的（thread-specific）。詳見“排程特性”一節。

新的抽象基類

為了更好地與現有框架（如Tornado，見[13]）和編譯器（如Cython，見[16]）整合，增加了兩個新的抽象基類（ABC）：

1. collections.abc.Awaitable，Future-like類的抽象基類，實現__await__方法。
2. 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：

1. collections.abc.AsyncIterable --用於測試__aiter__方法。
2. collections.abc.AsyncIterator --用於測試__aiter__和__anext__方法。