asyncio timeout 语义怎么配置或排查

Python 异步代码里“超时了”并不只对应一个 API。asyncio.timeout() 限制当前任务的一段作用域，asyncio.wait_for() 限制一个 awaitable，而 asyncio.wait() 只是到点返回任务集合。排查时先看超时边界，再看取消对象，最后看异常是在上下文内还是外层抛出。

官方资料：https://docs.python.org/3/library/asyncio-task.html

先分清 asyncio.timeout 与 wait_for

如果一个请求包含鉴权、查询和组装三个 await，通常应该把它们放进同一个超时作用域。这样期限属于当前任务，超时由上下文管理器转换为 TimeoutError，捕获位置要放在 async with 外面：

import asyncio

async def load_page():
    # 作用域内的多个 await 共享 2 秒截止时间
    try:
        async with asyncio.timeout(2):
            await asyncio.sleep(0.2)  # 模拟鉴权
            await asyncio.sleep(3)    # 模拟慢查询
    except TimeoutError:
        # 超时异常在上下文外捕获，便于统一返回降级结果
        return "timeout"
    return "ok"

asyncio.run(load_page())

若只想限制一个操作，则使用 wait_for(operation(), timeout=2)。它的语义更窄：超时后会向这个 awaitable 发出取消请求。不要把两者当成“同一个函数的两种写法”，前者适合业务期限，后者适合单次等待。

TimeoutError 捕获不到时，先查版本和位置

asyncio.timeout() 与 asyncio.timeout_at() 自 Python 3.11 加入。它们在上下文内通过取消当前任务结束等待，再在上下文退出时转换为内置 TimeoutError。因此下面的写法容易失效：

async with asyncio.timeout(1):
    try:
        await slow_call()
    except TimeoutError:
        # 这里通常接不到 timeout 上下文转换出的异常
        return "fallback"

应把 try 包在 async with 外面。跨 Python 3.10 及更早版本维护 wait_for() 时，还要注意旧版本抛出的是 asyncio.TimeoutError；Python 3.11 起它已是内置 TimeoutError 的别名。兼容代码可以统一捕获内置异常，并在旧版本测试矩阵中单独验证。

超时后为什么还没返回：看取消链

wait_for() 不是硬切断。它取消被等待对象后，还会等待取消过程完成；被等待协程若在 finally 里关闭连接、刷新日志或等待清理，外层返回就可能晚于 timeout。清理代码应保留取消信号，不要无条件吞掉 CancelledError：

async def fetch():
    try:
        await asyncio.sleep(10)
    except asyncio.CancelledError:
        # 做必要清理后继续抛出，不能把取消伪装成成功
        raise
    finally:
        # 关闭连接、释放锁等清理动作放在这里
        pass

async def main():
    task = asyncio.create_task(fetch())
    try:
        await asyncio.wait_for(task, timeout=0.5)
    except TimeoutError:
        # 这里说明等待期限已到，不代表清理耗时为零
        print("timed out")

asyncio.run(main())

如果底层任务必须继续运行，可显式使用 asyncio.shield(task)，但这只保护任务不被这次等待取消，调用方仍要保存任务引用并在后续回收它。不要为了让日志“看起来成功”而吞掉取消异常。

asyncio.wait 不抛超时异常，检查 done 和 pending

批量任务需要“到点收割已经完成的结果”时，用 asyncio.wait(tasks, timeout=2)。它到时间后直接返回两个集合，未完成任务会出现在 pending，不会自动抛 TimeoutError，也不会替你取消它们：

done, pending = await asyncio.wait(tasks, timeout=2)

# 先读取已完成任务，再明确决定如何处理未完成任务
for task in done:
    if task.cancelled():
        continue
    print(task.result())

for task in pending:
    # 这里可以取消、转入后台或记录重试，而不是误报异常
    task.cancel()

最后按这张清单复查：作用域期限还是单个 awaitable？捕获位置是否在 timeout 外？Python 版本对应哪个异常名？被等待协程是否在清理阶段拖长返回？使用 wait() 时是否处理了 pending？这几项能覆盖大多数“timeout 配了却不生效”的误判。

相关问题

timeout 和 timeout_at 有什么区别？ 前者接收相对秒数，后者接收事件循环时钟上的绝对截止时间；多个嵌套操作共享一个 deadline 时，后者更直观。

timeout(None) 有什么用？ 可以先建立无期限上下文，拿到外部期限后通过 reschedule() 设置截止时间，并用 expired() 复查是否已经过期。

为什么设置 1 秒却超过 1 秒？ 常见原因是取消后的清理仍在等待；先检查 finally、底层驱动和是否错误地吞掉了 CancelledError。