asyncio.TaskGroup در پایتون؛ همزمانی ساختاریافته بهجای gather
چرا asyncio.gather کافی نیست؟ #
اگر با برنامهنویسی ناهمگام (async) در پایتون کار کرده باشید، احتمالاً اولین ابزاری که برای اجرای همزمان چند کار یاد گرفتید asyncio.gather() بوده است. چند درخواست HTTP، چند کوئری دیتابیس یا چند فایل را همزمان شروع میکنید و منتظر میمانید همه تمام شوند. ساده و کاربردی است؛ اما وقتی یکی از کارها خطا بدهد، ماجرا پیچیده میشود.
به این کد نگاه کنید:
import asyncio
async def fetch(name: str, delay: float, fail: bool = False):
await asyncio.sleep(delay)
if fail:
raise ValueError(f"{name} failed")
print(f"{name} done")
return name
async def main():
try:
await asyncio.gather(
fetch("A", 0.1, fail=True),
fetch("B", 1.0),
fetch("C", 2.0),
)
except ValueError as e:
print("caught:", e)
await asyncio.sleep(3)
asyncio.run(main())
خروجی این برنامه نشان میدهد که بعد از خطای A، کارهای B و C همچنان به اجرا ادامه میدهند و B done و C done چاپ میشوند. در حالت پیشفرض، gather اولین استثنا را بالا میدهد اما کارهای دیگر را لغو نمیکند. نتیجه؟ taskهای «یتیم» که در پسزمینه منابع مصرف میکنند، اتصالهای باز رها میشوند و خطاهای بعدی ممکن است هرگز دیده نشوند.
مستندات رسمی asyncio دقیقاً به همین نکته اشاره میکند: TaskGroup تضمینهای ایمنی قویتری نسبت به gather دارد، چون اگر یک task یا subtask خطا بدهد، taskهای باقیمانده را لغو میکند؛ کاری که gather انجام نمیدهد.
Structured Concurrency چیست؟ #
همزمانی ساختاریافته (Structured Concurrency) یک ایدهٔ ساده اما قدرتمند است: طول عمر هر کار همزمان باید به یک بلوک مشخص در کد محدود باشد. همانطور که یک متغیر محلی بعد از پایان تابع از بین میرود، taskهایی که داخل یک بلوک شروع میشوند هم باید قبل از خروج از آن بلوک تمام شوند؛ یا با موفقیت، یا با خطا، یا با لغو.

مزایای این مدل:
- هیچ task یتیمی باقی نمیماند: وقتی از بلوک خارج میشوید، مطمئن هستید همهٔ کارها تمام شدهاند.
- خطاها گم نمیشوند: همهٔ استثناها جمعآوری و گزارش میشوند.
- لغو قابل پیشبینی است: اگر والد لغو شود، همهٔ فرزندان هم لغو میشوند.
- کد خواناتر است: ساختار همزمانی از روی تورفتگی کد قابل فهم است.
پایتون از نسخهٔ ۳.۱۱ این ایده را با asyncio.TaskGroup به کتابخانهٔ استاندارد آورد.
آشنایی با asyncio.TaskGroup #
ساختار پایه بسیار ساده است:
import asyncio
async def fetch(name: str, delay: float) -> str:
await asyncio.sleep(delay)
return f"{name} result"
async def main():
async with asyncio.TaskGroup() as tg:
task1 = tg.create_task(fetch("users", 0.5))
task2 = tg.create_task(fetch("orders", 1.0))
# اینجا هر دو task قطعاً تمام شدهاند
print(task1.result(), task2.result())
asyncio.run(main())
دستور async with منتظر میماند تا همهٔ taskهای گروه تمام شوند. نکتهٔ جالب این است که تا وقتی گروه فعال است، میتوانید taskهای جدید هم اضافه کنید؛ مثلاً با پاس دادن tg به یکی از coroutineها و صدا زدن tg.create_task() در آنجا. بعد از خروج از بلوک، اضافه کردن task جدید ممکن نیست.
رفتار هنگام خطا #
اینجا قدرت واقعی TaskGroup مشخص میشود. طبق مستندات، اولین باری که یکی از taskها با استثنایی غیر از CancelledError شکست بخورد:
- بقیهٔ taskهای گروه لغو میشوند.
- هیچ task جدیدی نمیتواند به گروه اضافه شود.
- اگر بدنهٔ
async withهنوز در حال اجرا باشد، آن هم لغو میشود. - بعد از تمام شدن همهٔ taskها، استثناها در یک
ExceptionGroupجمع و بالا داده میشوند.
import asyncio
async def fetch(name: str, delay: float, fail: bool = False):
try:
await asyncio.sleep(delay)
if fail:
raise ValueError(f"{name} failed")
print(f"{name} done")
return name
except asyncio.CancelledError:
print(f"{name} cancelled")
raise
async def main():
try:
async with asyncio.TaskGroup() as tg:
tg.create_task(fetch("A", 0.1, fail=True))
tg.create_task(fetch("B", 1.0))
tg.create_task(fetch("C", 2.0))
except* ValueError as eg:
for exc in eg.exceptions:
print("caught:", exc)
asyncio.run(main())
خروجی:
B cancelled
C cancelled
caught: A failed
این بار B و C بلافاصله لغو میشوند و هیچ کاری در پسزمینه رها نمیشود.
مهم
در بلوک except asyncio.CancelledError همیشه با raise استثنا را دوباره بالا بدهید. اگر آن را «قورت» بدهید، مکانیزم لغو TaskGroup درست کار نمیکند.
کار با ExceptionGroup و except* #
از آنجایی که چند task ممکن است همزمان خطا بدهند، TaskGroup یک استثنای واحد بالا نمیدهد، بلکه یک ExceptionGroup میسازد. سینتکس except* (اضافهشده در پایتون ۳.۱۱) برای مدیریت همین گروهها طراحی شده است:
import asyncio
async def job(kind: str):
await asyncio.sleep(0.1)
if kind == "value":
raise ValueError("bad value")
if kind == "key":
raise KeyError("missing key")
async def main():
try:
async with asyncio.TaskGroup() as tg:
tg.create_task(job("value"))
tg.create_task(job("key"))
except* ValueError as eg:
print("value errors:", [str(e) for e in eg.exceptions])
except* KeyError as eg:
print("key errors:", [str(e) for e in eg.exceptions])
asyncio.run(main())
برخلاف except معمولی، چند بلوک except* میتوانند برای یک گروه اجرا شوند؛ هر کدام بخشی از استثناهایی را که با نوعش مطابقت دارد دریافت میکند.
یادداشت
استثناهای KeyboardInterrupt و SystemExit رفتار ویژهای دارند: گروه همچنان بقیهٔ taskها را لغو میکند و منتظر میماند، اما سپس خود همان استثنای اصلی را بالا میدهد، نه ExceptionGroup.
ترکیب با asyncio.timeout #
در دنیای واقعی، هیچ درخواست شبکهای نباید بینهایت منتظر بماند. asyncio.timeout() (پایتون ۳.۱۱ به بعد) یک context manager است که اگر زمان تمام شود، task فعلی را لغو و CancelledError را به TimeoutError تبدیل میکند:

import asyncio
async def call_service(name: str, delay: float) -> str:
await asyncio.sleep(delay)
return f"{name}: ok"
async def main():
try:
async with asyncio.timeout(2):
async with asyncio.TaskGroup() as tg:
fast = tg.create_task(call_service("auth", 0.5))
slow = tg.create_task(call_service("reports", 5))
except TimeoutError:
print("Some services were too slow; all tasks were cancelled.")
else:
print(fast.result(), slow.result())
asyncio.run(main())
ترتیب تودرتو مهم است: timeout بیرونی کل گروه را محدود میکند. اگر بخواهید هر task مهلت جداگانه داشته باشد، asyncio.timeout را داخل خود coroutine قرار دهید.
یک مثال واقعی: دریافت همزمان چند URL با محدودیت #
بیایید یک سناریوی واقعی بسازیم: دریافت تعداد زیادی URL، اما با حداکثر ۵ درخواست همزمان (تا سرور مقصد یا شبکهٔ خودمان را خفه نکنیم) و مهلت زمانی برای هر درخواست. از کتابخانهٔ httpx استفاده میکنیم:
uv add httpx
import asyncio
import httpx
MAX_CONCURRENCY = 5
PER_REQUEST_TIMEOUT = 10
async def fetch_one(client: httpx.AsyncClient, sem: asyncio.Semaphore, url: str) -> tuple[str, int]:
async with sem:
async with asyncio.timeout(PER_REQUEST_TIMEOUT):
response = await client.get(url)
return url, response.status_code
async def fetch_all(urls: list[str]) -> dict[str, int]:
sem = asyncio.Semaphore(MAX_CONCURRENCY)
async with httpx.AsyncClient(follow_redirects=True) as client:
async with asyncio.TaskGroup() as tg:
tasks = [tg.create_task(fetch_one(client, sem, u)) for u in urls]
return dict(t.result() for t in tasks)
if __name__ == "__main__":
urls = [
"https://www.python.org",
"https://docs.python.org/3/",
"https://pypi.org",
]
print(asyncio.run(fetch_all(urls)))
چند نکته در این کد:
Semaphoreتعداد درخواستهای همزمان را محدود میکند.AsyncClientبیرون از گروه ساخته شده تا تا پایان همهٔ taskها باز بماند و اتصالها بین درخواستها بازاستفاده شوند.- اگر یک درخواست خطا بدهد، بقیه لغو میشوند. اگر میخواهید خطای یک URL باعث توقف بقیه نشود، خطا را داخل
fetch_oneبگیرید و بهعنوان نتیجه برگردانید.
الگوی «تحمل خطا» #
async def safe_fetch(client, sem, url):
try:
return await fetch_one(client, sem, url)
except (httpx.HTTPError, TimeoutError) as exc:
return url, f"error: {type(exc).__name__}"
به این ترتیب تصمیم دربارهٔ اینکه کدام خطا «کشنده» است و کدام قابل تحمل، صریحاً در کد شما گرفته میشود؛ نه بهصورت تصادفی.
مقایسهٔ gather و TaskGroup #
| معیار | asyncio.gather |
asyncio.TaskGroup |
|---|---|---|
| نسخهٔ پایتون | قدیمی | ۳.۱۱ به بعد |
| لغو بقیه هنگام خطا | خیر (پیشفرض) | بله |
| گزارش چند خطا | فقط اولین خطا (یا لیست با return_exceptions=True) |
همه در ExceptionGroup |
| اضافه کردن task پویا | ندارد | با tg.create_task تا پایان بلوک |
| ترتیب نتایج | به ترتیب ورودی | از طریق شیء task هر کار |
| سبک کد | تابعی | ساختاریافته با async with |
gather با return_exceptions=True هنوز برای حالتهایی که میخواهید همهٔ نتایج و خطاها را بدون لغو جمع کنید کاربرد دارد، اما برای بیشتر کدهای جدید TaskGroup انتخاب امنتر است.
بهترین روشها #
- برای کدهای جدید بهجای
create_taskبیصاحب، از TaskGroup استفاده کنید. -
CancelledErrorرا هرگز بدونraiseدوباره نگیرید. - برای هر عملیات شبکهای مهلت زمانی تعیین کنید.
- تعداد کارهای همزمان را با
Semaphoreمحدود کنید. - تصمیم بگیرید کدام خطاها باید کل گروه را متوقف کنند و بقیه را داخل coroutine مدیریت کنید.
- برای دیباگ گلوگاههای async، از پروفایلر جدید پایتون ۳.۱۵ با گزینهٔ
--async-awareاستفاده کنید.
آیا TaskGroup کار را موازی (parallel) اجرا میکند؟
خیر. asyncio روی یک thread اجرا میشود و taskها همزمان (concurrent) هستند، نه موازی. برای کارهای سنگین CPU از ProcessPoolExecutor یا بیلد free-threaded پایتون استفاده کنید. TaskGroup برای کارهای I/O-bound مثل شبکه و دیتابیس عالی است.
چطور کل گروه را دستی متوقف کنم؟
در نسخههای جدید پایتون میتوانید tg.cancel() را صدا بزنید؛ مستندات رسمی این روش را برای درخواست توقف گروه ذکر میکند. در نسخههای قدیمیتر رایجترین روش بالا دادن یک استثنای سفارشی در یکی از taskها و گرفتن آن بیرون از گروه است.
آیا میتوانم TaskGroupها را تودرتو کنم؟
بله. هر گروه داخلی خطاهای خودش را ابتدا پردازش میکند و سپس گروه بیرونی خطاهای خودش را. این همان ساختار درختی است که در تصویر بالا دیدید.
جمعبندی #
asyncio.TaskGroup روش مدرن و ایمن اجرای همزمان کارها در پایتون است. با محدود کردن عمر taskها به یک بلوک async with، دیگر نگران taskهای یتیم، خطاهای گمشده یا لغوهای غیرقابل پیشبینی نخواهید بود. اگر هنوز در کدهایتان از gather بدون مدیریت خطا استفاده میکنید، همین امروز آنها را بازبینی کنید. برای مطالعهٔ بیشتر، مستندات Coroutines and Tasks را بخوانید و اگر میخواهید بدانید پایتون در زمینهٔ همزمانی واقعی به کجا میرود، مطلب پایان دوران GIL در پایتون ۳.۱۴ را از دست ندهید.