asyncio.timeout 怎样转换超时异常

使用 asyncio.timeout() 时，超时并不是在上下文内部直接抛出 TimeoutError。它先请求取消当前任务，产生 asyncio.CancelledError；退出超时上下文时，管理器再把这次取消转换成内置的 TimeoutError。所以，捕获代码应放在 async with 外面。

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

记住一条边界：TimeoutError 只能在 asyncio.timeout() 上下文之外捕获；在上下文内部捕获它，通常捕获不到这次超时。

为什么超时会经历两种异常

asyncio.timeout(delay) 是异步上下文管理器，适用于限制当前任务在一段代码上的等待时间。达到期限后，事件循环会向当前任务注入取消请求。上下文管理器在退出阶段识别这次由自己触发的取消，再把它转换为 TimeoutError。

这套设计把“取消机制”和“业务层超时结果”分开：底层仍然使用 asyncio 的取消协议，上层只需要按普通超时处理。也正因为转换发生在退出上下文时，异常捕获层级不能写反。

正确的捕获位置是 async with 外层

最小可用写法是先进入超时上下文，再在外层用 try/except TimeoutError 接住结果：

import asyncio

async def load_data():
    # 模拟一个可能超过时限的异步操作
    await asyncio.sleep(2)
    return {"status": "ok"}

async def main():
    try:
        # 超时发生后，TimeoutError 会在离开上下文时暴露
        async with asyncio.timeout(1):
            result = await load_data()
    except TimeoutError:
        # 这里处理业务层的超时结果，例如返回降级数据
        result = {"status": "timeout"}

    # 这里仍然可以继续执行上下文之外的逻辑
    print(result)

asyncio.run(main())

如果把 except TimeoutError 写到 async with 的内部，就错过了转换发生的时机。上下文内部若要做清理，应使用 finally；不要为了“把超时变成业务结果”而吞掉 CancelledError。

清理、重设和嵌套时看哪条边界

资源清理仍然放在被保护代码的 finally 中，连接、文件或临时状态应在取消到来时释放。若任务开始时还不知道期限，可以先传入 None，拿到配置后调用返回对象的 reschedule() 设置绝对截止时间：

import asyncio

async def run_job():
    loop = asyncio.get_running_loop()
    async with asyncio.timeout(None) as scope:
        # 运行时得到预算后，以事件循环时钟设置绝对截止时间
        scope.reschedule(loop.time() + 3)
        try:
            await load_data()
        finally:
            # 无论正常完成还是被取消，都在这里释放局部资源
            release_local_state()+
def release_local_state():
    # 示例只表达清理位置，真实项目中替换为连接或临时文件清理
    pass

asyncio.timeout() 可以嵌套。排查时先问“哪一层上下文的期限到了”，再看最外层捕获位置；不要把内部的取消异常当成普通业务异常重新抛出。文档还提供 expired() 查看上下文是否越过截止时间，但它不能替代外层的异常处理。

一张表排查为什么没有捕获到超时

如果只需要一个固定等待上限，直接使用 asyncio.timeout(秒数)；如果期限来自运行时配置，选择 None 加 reschedule()。核心不是记住某个异常名，而是记住“取消发生在内部，超时结果出现在外部”。

相关问题

asyncio.timeout 需要哪个 Python 版本？

官方文档标注它从 Python 3.11 起提供。低版本不能直接按这套接口写，应先确认项目运行时版本和依赖约束。

为什么不在内部捕获 CancelledError？

取消是 asyncio 的控制信号。除非你明确知道如何完成清理并继续传播，否则拦截它可能破坏超时上下文和任务取消语义。