🎓 A1Learner
🔍

Python Asyncio Tasks & Gather

A task is a coroutine that the loop has scheduled to run. gather() runs coroutines together and collects every result.

Schedule a task

create_task() schedules the coroutine at once. await then collects the result.

import asyncio

async def job():
    await asyncio.sleep(0)
    return "job done"

async def main():
    task = asyncio.create_task(job())
    print(await task)

asyncio.run(main())

Gather results in order

gather() runs coroutines together. It returns a list in call order.

import asyncio

async def fetch(name):
    await asyncio.sleep(0)
    return name

async def main():
    results = await asyncio.gather(fetch("a"), fetch("b"))
    print(results)

asyncio.run(main())

Set a time limit

wait_for() gives a coroutine a deadline. It raises TimeoutError when the deadline passes.

import asyncio

async def slow():
    await asyncio.sleep(10)
    return "done"

async def main():
    try:
        await asyncio.wait_for(slow(), timeout=0.01)
    except TimeoutError:
        print("Too slow")

asyncio.run(main())

Cancel a task

cancel() asks a task to stop at its next await point.

task = asyncio.create_task(job())
task.cancel()

Example

import asyncio

async def download(name):
    await asyncio.sleep(0)
    return f"{name} done"

async def slow_page():
    await asyncio.sleep(10)
    return "slow done"

async def main():
    results = await asyncio.gather(
        download("page-a"),
        download("page-b"),
        download("page-c"),
    )
    for result in results:
        print(result)
    try:
        await asyncio.wait_for(slow_page(), timeout=0.01)
    except TimeoutError:
        print("slow page timed out")

asyncio.run(main())

Key points

  • Task: a coroutine wrapped so the loop can run it.
  • Use asyncio.create_task() to schedule a coroutine as a task.
  • Use await on a task to collect its result.
  • Use asyncio.gather() to run coroutines and collect every result.
  • gather() returns results in the order you passed them.
  • Use asyncio.wait_for() to give a coroutine a time limit.
  • wait_for() raises TimeoutError when the time limit passes.
  • Use task.cancel() to ask a running task to stop.
  • gather() orders results by call order.

In this example, gather() runs three download coroutines. Each one sleeps for zero seconds and returns a label. gather() returns the labels in call order. The loop prints them in that same order. Then wait_for() gives slow_page() a short time limit. slow_page() sleeps far longer than the limit. wait_for() raises TimeoutError and the except block prints the last line.

Note

It does not order them by finish order.

Try it Yourself

Edit the code, then press Run.

Running is simulated · Python Playground

Exercise

What does asyncio.gather() return?