Python异步迭代器使用教程

Python的`async for`语句并非通用循环工具，而是严格依赖异步迭代协议（需同时实现`__aiter__`和`__anext__`方法）的专用语法，误用同步对象（如`range()`、列表或未`await`的第三方库返回值）将直接报错；最简洁可靠的实现方式是使用`async def`定义异步生成器，它自动满足协议且支持内部`await`；而调用第三方异步迭代器（如aiohttp、asyncpg）时务必先`await`获取真实迭代器对象，并高度重视异常中断下的资源清理——推荐优先选用支持`async with`的上下文管理型迭代器，或在手写`__anext__`时显式添加`try/finally`保障释放逻辑，避免连接泄漏与状态不一致。

async for 语句必须配合异步迭代器使用

Python 中 async for 不是万能的循环语法，它只接受实现了 __aiter__ 和 __anext__ 方法的对象。普通迭代器（只有 __iter__ 和 __next__）会直接报错：TypeError: 'X' object is not an async iterator。

常见错误场景包括：误把同步生成器、range()、列表或 requests 响应对象丢进 async for；或者自定义类只写了 __aiter__ 却漏了 __anext__（后者必须返回 awaitable）。

正确做法是确保对象满足异步迭代协议：

• __aiter__ 必须返回自身（或另一个实现了该协议的对象），且不能是 async 方法
• __anext__ 必须是 async 方法，返回一个可 await 的值，或抛出 StopAsyncIteration
• 若用 async def __aiter__(self)，需手动返回 self，不能直接 yield

异步生成器函数是最简捷的实现方式

比起手写 __aiter__/__anext__，用 async def 定义生成器更直观、不易出错。Python 会自动将其编译为异步迭代器对象。

示例：

async def a_range(n):
    for i in range(n):
        await asyncio.sleep(0.1)  # 模拟异步 IO
        yield i
<h1>使用</h1><p>async for x in a_range(3):
print(x)  # 输出 0, 1, 2，每项间隔 0.1 秒
</p>

注意点：

• 异步生成器内部可以 await，但不能在同步上下文中调用（比如普通 for 循环）
• 不能在异步生成器里用 return value（会触发 StopAsyncIteration，但 value 不会被捕获）
• 若想提前退出，用 break 或抛出 StopAsyncIteration，不要 return

第三方库返回的异步迭代器常需显式 await

像 aiohttp.ClientResponse.content、aiosqlite.Cursor、asyncpg.Connection.cursor() 等，返回的是异步迭代器，但它们的创建过程本身往往也是异步的。

典型错误写法：

# ❌ 错误：没 await cursor()，得到的是 coroutine 对象，不是迭代器
async for row in conn.cursor("SELECT * FROM t"):
    ...

正确写法：

# ✅ 正确：先 await 得到真正的异步迭代器
cursor = await conn.cursor("SELECT * FROM t")
async for row in cursor:
    ...

其他常见情况：

• aiohttp 的 response.content.iter_any() 是异步迭代器，但 response.content 本身不是
• httpx.AsyncClient.stream() 返回的是异步上下文管理器，需搭配 async with + async for
• 某些库（如 motor）的 find() 返回游标对象，需 await cursor.to_list(length) 或用 async for 遍历

异常传播和资源清理容易被忽略

异步迭代器在中途抛异常（如网络断开、数据库连接丢失）时，__aexit__ 不一定自动触发，尤其当没有用 async with 包裹时。

例如手动构造的异步迭代器，若 __anext__ 抛异常，Python 不会自动调用 aclose() —— 除非你显式实现并依赖 async for 的隐式调用逻辑（CPython 3.11+ 才保证调用 aclose()）。

稳妥做法：

• 优先使用支持 async with 的上下文管理型异步迭代器（如 aiofiles.open()）
• 若自己实现，建议在 __anext__ 中做 try/except，并在 finally 块中释放关键资源
• 避免在 async for 循环外保留对异步迭代器的引用，防止资源泄漏

最易被绕过的细节是：异步生成器函数里的 finally 块，在被 break 或异常中断时仍会执行；但手写的 __anext__ 若没包 try/finally，就可能跳过清理逻辑。

到这里，我们也就讲完了《Python异步迭代器使用教程》的内容了。个人认为，基础知识的学习和巩固，是为了更好的将其运用到项目中，欢迎关注golang学习网公众号，带你了解更多关于的知识点！