当前位置：首页 > 文章列表 > 文章 > python教程 > Python异步迭代器使用教程

Python异步迭代器使用教程

2026-02-13 20:48:46 0浏览收藏

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

Python 异步迭代器的使用方式

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 遍历