PEP 492 — Coroutines with async and await syntax 翻譯

因為工作中慢慢開始用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__方法。