TaskGroup 是 Python 3.12 引入的结构化并发原语,用于安全批量管理子任务;它在任一子任务异常时自动取消其余任务并等待退出,而 asyncio.gather 不主动取消,仅聚合异常。

TaskGroup 是什么,为什么不能用 asyncio.gather 替代
TaskGroup 是 Python 3.12 引入的正式标准库并发原语(位于 asyncio 模块),用于安全地批量创建和管理子任务。它不是 asyncio.gather 的语法糖——关键区别在于错误传播和生命周期控制:TaskGroup 遇到任一子任务抛出未捕获异常时,会自动取消其余正在运行的任务,并等待它们退出;而 gather(return_exceptions=False) 仅聚合异常,不主动 cancel 其他协程。
常见错误现象:asyncio.gather 中某个任务卡死或无限重试,会导致整个调用永远不返回,且其他已完成任务的结果也被阻塞释放。
- 使用场景:需要“全成功才提交”或“任一失败就中止并清理”的批处理,比如并发上传多个文件、批量调用外部 API 并确保资源及时释放
- 性能影响:
TaskGroup自带结构化并发语义,开销略高于裸create_task,但远低于手动维护asyncio.wait+ 取消逻辑 - 兼容性:仅 Python 3.12+,旧版本需用第三方库如
anyio.TaskGroup或自行封装
基本用法:with async with TaskGroup() as tg:
必须用 async with 语法进入上下文,否则会报 RuntimeError: TaskGroup is not running。不能只写 TaskGroup() 然后调 tg.create_task(...) —— 这是常见误用。
正确示例:
import asyncio
<p>async def fetch(url):
await asyncio.sleep(0.1)
return f"done {url}"</p><p>async def main():
async with asyncio.TaskGroup() as tg:
task1 = tg.create_task(fetch("<a href="https://www.php.cn/link/4a2dd4fd7b6db6c7600ecb27cc83a7c4">https://www.php.cn/link/4a2dd4fd7b6db6c7600ecb27cc83a7c4</a>"))
task2 = tg.create_task(fetch("<a href="https://www.php.cn/link/b7be11f1c3a8aba967e0a54a2fb2bd21">https://www.php.cn/link/b7be11f1c3a8aba967e0a54a2fb2bd21</a>"))</p><h1>此处所有任务已结束,task1.result() 和 task2.result() 可安全调用</h1><pre class="brush:php;toolbar:false;">print(task1.result(), task2.result())
asyncio.run(main())
-
tg.create_task()返回的是asyncio.Task实例,不是协程对象,不可再await它本身(应await原协程或调.result()) - 所有子任务共享父协程的事件循环和上下文变量(
contextvars),这点和gather一致 - 若在
with块内未保存对 task 的引用,其结果会丢失——TaskGroup不自动收集返回值
错误处理:异常会立即传播,但需注意捕获时机
TaskGroup 内任一子任务 raise 未处理异常,会立刻终止上下文并把该异常抛出到 async with 外层。但要注意:异常不是由“出错的那个 task”直接抛出,而是由 TaskGroup 统一包装为 ExceptionGroup(Python 3.11+ 新类型)。
当现有的脚本或服务需要将作用域化的仓库工作委托给 Claude Code 并以编程方式消费结构化响应时,请使用 Claude Agent SDK for Python。
例如一个任务抛 ValueError,另一个抛 TimeoutError,外层收到的是 ExceptionGroup,里面包含两个异常实例。
- 捕获方式:用
except* ValueError:(注意是except*,不是except)匹配子异常;或用except ExceptionGroup as eg:接住整体再遍历eg.exceptions - 容易踩的坑:写成
except ValueError:会漏掉,因为抛出的不是原始ValueError,而是包裹它的ExceptionGroup - 如果所有子任务都成功,
TaskGroup不抛异常,也不返回任何值——结果得靠你显式保存 task 对象再取.result()
嵌套 TaskGroup 与 cancel_scope 的边界
可以嵌套使用 TaskGroup,内层的 cancel 信号不会自动透传给外层,但外层被 cancel 时,内层会随之被取消(因为子任务也是外层 TaskGroup 管理的 task)。这符合结构化并发预期。
但要注意:不能在 TaskGroup 上下文里手动调 task.cancel() 来试图精细控制单个任务——虽然技术上可行,但违背设计初衷,且可能干扰 TaskGroup 自身的错误同步逻辑。
- 真正需要差异化取消策略时,应考虑拆分逻辑:用外层
TaskGroup管理几组独立任务,每组内部再用一个TaskGroup -
asyncio.timeout()仍可与TaskGroup共用,但超时异常会作为TimeoutError进入ExceptionGroup,需用except* TimeoutError:捕获 - 调试时留意:
asyncio.current_task().get_coro()在TaskGroup子任务里返回的是原始协程,不是包装器,这点和gather生成的 task 行为一致
最易被忽略的一点:TaskGroup 不提供类似 concurrent.futures.as_completed 的“按完成顺序消费”能力——所有任务必须等全部结束才能统一取结果。如果业务需要流式响应,得退回到 asyncio.create_task + asyncio.wait(..., return_when=FIRST_COMPLETED) 组合。
Python免费学习笔记(深入):立即使用
在学习笔记中,你将探索 Python 的核心概念和高级技巧!










