Python · Lesson 11

Async and await

How asyncio runs many I/O-bound tasks on one thread: coroutines and the event loop, gather and create_task, TaskGroup, timeouts and cancellation, Semaphore and Queue, async generators and context managers, the classic mistakes, and how it maps to JavaScript promises and C# Task.

12 min read

In short

  • One thread; tasks switch at await
  • Coroutines run only when awaited or wrapped in a task
  • gather and TaskGroup for concurrency
  • Timeouts cancel; CancelledError must propagate
  • Semaphore and Queue to control load

Most backend work is waiting: for a database, an HTTP API, a file, a message queue. A thread that waits does nothing for hundreds of milliseconds. asyncio lets one thread juggle thousands of those waits: while one task waits for the network, another runs. It's how FastAPI, aiohttp, and most modern Python network code work, and "fetch these 50 URLs, at most 10 at a time, with a timeout" is a standard interview task.

asyncio is cooperative concurrency on a single thread. Tasks take turns, and a task only gives up its turn at an await. That makes it a great fit for I/O-bound work and no help for CPU-bound work (crunching numbers still uses one core; use processes for that).

If you know JavaScript, you already know the shape: async def is async function, await is await, a Task is roughly a promise, and asyncio.gather is Promise.all. The differences are in the details, and this lesson points them out.

Every python snippet below has a ▶ Try button. In the browser there's already an event loop running, so the snippets use top-level await main(). In a normal script you write asyncio.run(main()) instead, which starts the event loop, runs main() to completion, and shuts the loop down.

Coroutines: async def

A function defined with async def is a coroutine function. Calling it doesn't run its body: it returns a coroutine object, a paused computation. The body runs when something awaits it.

▶ Try
import asyncio


async def fetch_user(user_id: int) -> dict:
    print("fetching", user_id)
    await asyncio.sleep(0.01)          # stands in for a network call
    return {"id": user_id, "name": "ann"}


coro = fetch_user(1)
print(type(coro).__name__)             # nothing printed "fetching" yet
user = await coro                      # now the body runs
print(user)

That's the first difference from JavaScript, where calling an async function starts it immediately. In Python, a coroutine that is never awaited never runs at all, and Python warns coroutine ... was never awaited when it's garbage collected.

await and the event loop

await x means "pause this coroutine until x is done, and let the event loop run something else meanwhile". You can await a coroutine, a Task, or a Future. You can only use await inside an async def (or at the top level of a snippet here, or in the python -m asyncio REPL).

The event loop is the scheduler. It keeps a list of tasks that are ready to run and of timers and sockets it's waiting on. It runs one ready task until that task hits an await on something that isn't ready, then switches to the next. await asyncio.sleep(0) yields to the loop without waiting for anything.

▶ Try
import asyncio


async def work(name: str) -> None:
    print("start", name)
    await asyncio.sleep(0)             # give the other task a turn
    print("end", name)


async def main() -> None:
    task = asyncio.create_task(work("a"))   # scheduled, not started yet
    print("created")
    await work("b")
    await task


await main()

create_task puts work("a") on the loop, but it can't start until main yields. main then runs work("b") directly until its sleep(0). Only then does task a get its first turn.

Sequential or concurrent

Awaiting one call after another runs them one after the other, exactly like synchronous code. To run them at the same time, start them all, then wait for all of them. asyncio.gather does both:

▶ Try
import asyncio


async def fetch(name: str, delay: float) -> str:
    print("start", name)
    await asyncio.sleep(delay)
    print("end", name)
    return name.upper()


async def main() -> None:
    a = await fetch("a", 0.02)          # sequential: b doesn't start until a is done
    b = await fetch("b", 0.01)
    print([a, b])
    print("---")
    results = await asyncio.gather(fetch("a", 0.02), fetch("b", 0.01))
    print(results)                      # in argument order, not finishing order


await main()

Sequential, the total time is the sum of the waits; concurrent, it's the longest one. gather returns the results in the order you passed the awaitables, whatever order they finished in, just like Promise.all.

create_task, and keeping a reference

asyncio.create_task(coro) schedules a coroutine to run in the background as soon as the current task yields, and returns a Task. You can await the task later to get its result (or its exception).

▶ Try
import asyncio


async def send_email(to: str) -> str:
    await asyncio.sleep(0.01)
    return f"sent to {to}"


async def main() -> None:
    task = asyncio.create_task(send_email("ann@example.com"))
    print("doing other work while the email sends")
    print(await task)
    print(task.done(), task.result())


await main()

The event loop only keeps a weak reference to tasks. A task you create and never store can be garbage collected before it finishes, so "fire and forget" needs somewhere to keep the task:

▶ Try
import asyncio

background: set[asyncio.Task] = set()


async def audit(event: str) -> None:
    await asyncio.sleep(0.01)
    print("audited", event)


def fire_and_forget(event: str) -> None:
    task = asyncio.create_task(audit(event))
    background.add(task)                          # keep it alive
    task.add_done_callback(background.discard)    # and forget it when it's done


fire_and_forget("login")
fire_and_forget("logout")
print(len(background), "running")
await asyncio.gather(*background)
print(len(background), "running")

gather and errors

By default, if one awaitable passed to gather raises, gather raises that exception straight away. The others keep running (they aren't cancelled), and their results are lost to you. With return_exceptions=True, gather waits for everything and puts exceptions in the result list instead, like Promise.allSettled:

▶ Try
import asyncio


async def ok(n: int) -> int:
    await asyncio.sleep(0.01)
    return n


async def broken() -> int:
    await asyncio.sleep(0.01)
    raise ValueError("service down")


try:
    await asyncio.gather(ok(1), broken(), ok(3))
except ValueError as e:
    print("gather raised:", e)

results = await asyncio.gather(ok(1), broken(), ok(3), return_exceptions=True)
print(results)
print([r for r in results if not isinstance(r, Exception)])

TaskGroup (Python 3.11+)

asyncio.TaskGroup is structured concurrency: tasks started in an async with block all finish before the block exits. If any task fails, the group cancels the others, waits for them, and raises all the failures together as an ExceptionGroup, which you catch with except*.

▶ Try
import asyncio


async def load(name: str, delay: float) -> str:
    await asyncio.sleep(delay)
    return name


async def main() -> None:
    async with asyncio.TaskGroup() as tg:
        profile = tg.create_task(load("profile", 0.02))
        orders = tg.create_task(load("orders", 0.01))
    print(profile.result(), orders.result())      # both are done here


await main()
▶ Try
import asyncio


async def slow() -> None:
    try:
        await asyncio.sleep(1)
    except asyncio.CancelledError:
        print("slow was cancelled")
        raise


async def fail() -> None:
    await asyncio.sleep(0.01)
    raise ValueError("boom")


async def main() -> None:
    try:
        async with asyncio.TaskGroup() as tg:
            tg.create_task(slow())
            tg.create_task(fail())
    except* ValueError as group:
        print("caught", [str(e) for e in group.exceptions])


await main()

Prefer TaskGroup for new code: no task outlives the block, and no failure goes unnoticed. Use gather when you want return_exceptions=True, or on Python older than 3.11.

Timeouts

Anything that waits on the network needs a timeout. asyncio.timeout(seconds) (3.11+) is a context manager that cancels the work inside it when time runs out and raises TimeoutError. asyncio.wait_for(aw, seconds) does the same for a single awaitable.

▶ Try
import asyncio


async def slow_api() -> str:
    await asyncio.sleep(1)
    return "data"


try:
    async with asyncio.timeout(0.02):
        await slow_api()
except TimeoutError:
    print("timed out (timeout block)")

try:
    await asyncio.wait_for(slow_api(), timeout=0.02)
except TimeoutError:
    print("timed out (wait_for)")

print(await asyncio.wait_for(asyncio.sleep(0.01, "fast enough"), timeout=1))

Since 3.11, asyncio.TimeoutError is the built-in TimeoutError. Unlike Promise.race in JavaScript, the timed-out work is cancelled, not left running in the background.

Cancellation and CancelledError

task.cancel() asks a task to stop: at its next await, the task gets an asyncio.CancelledError raised inside it. That's how timeouts and TaskGroup stop work. The task can clean up in finally (or except), and then it must let the error propagate.

▶ Try
import asyncio


async def download() -> None:
    try:
        print("downloading")
        await asyncio.sleep(1)
    finally:
        print("closing the connection")   # runs on cancel too


async def main() -> None:
    task = asyncio.create_task(download())
    await asyncio.sleep(0.01)
    task.cancel()
    try:
        await task
    except asyncio.CancelledError:
        print("cancelled:", task.cancelled())


await main()

CancelledError inherits from BaseException, not Exception, so except Exception: doesn't swallow it by accident. Catching it on purpose and not re-raising breaks timeouts, TaskGroup and shutdown. If a piece of work must not be interrupted by a caller's cancellation, wrap it in asyncio.shield(...).

Limiting concurrency with Semaphore

gather over 10,000 URLs opens 10,000 connections at once, and the API you're calling will rate-limit you or fall over. An asyncio.Semaphore(n) lets at most n tasks into a block at a time; the rest wait at async with:

▶ Try
import asyncio

running = 0
peak = 0


async def fetch(url: str, limit: asyncio.Semaphore) -> str:
    global running, peak
    async with limit:
        running += 1
        peak = max(peak, running)
        await asyncio.sleep(0.01)
        running -= 1
        return f"ok {url}"


async def main() -> None:
    limit = asyncio.Semaphore(3)
    results = await asyncio.gather(*(fetch(f"/item/{i}", limit) for i in range(10)))
    print(len(results), "fetched, at most", peak, "at once")


await main()

Producer and consumer with asyncio.Queue

An asyncio.Queue hands work from producers to a fixed number of worker tasks. await queue.get() waits for an item, queue.task_done() marks one finished, and await queue.join() waits until every item put on the queue has been marked done.

▶ Try
import asyncio


async def worker(name: str, queue: asyncio.Queue, results: list) -> None:
    while True:
        job = await queue.get()
        try:
            await asyncio.sleep(0.01)
            results.append(f"{name}:{job}")
        finally:
            queue.task_done()


async def main() -> None:
    queue: asyncio.Queue[int] = asyncio.Queue(maxsize=10)
    results: list[str] = []
    workers = [asyncio.create_task(worker(f"w{i}", queue, results)) for i in range(2)]
    for job in range(5):
        await queue.put(job)          # waits if the queue is full: backpressure
    await queue.join()                # every job processed
    for w in workers:
        w.cancel()                    # the workers loop forever: stop them
    await asyncio.gather(*workers, return_exceptions=True)
    print(sorted(results, key=lambda r: r.split(":")[1]))


await main()

maxsize gives you backpressure: a fast producer waits at put instead of filling memory. The workers never exit on their own, so main cancels them once the queue is drained.

Async generators and async context managers

An async def with yield is an async generator, and you consume it with async for. It's the shape of paginated APIs and streams: each page needs an await, and the caller just loops.

▶ Try
import asyncio


async def pages(total: int, size: int):
    for start in range(0, total, size):
        await asyncio.sleep(0.01)                    # fetch one page
        yield list(range(start, min(start + size, total)))


async def main() -> None:
    async for page in pages(7, 3):
        print("page", page)
    print([n async for page in pages(4, 2) for n in page])


await main()

An async context manager has async def __aenter__ and __aexit__, and you use it with async with. Database connections, HTTP sessions and locks are async context managers. The easy way to write one is contextlib.asynccontextmanager:

▶ Try
import asyncio
from contextlib import asynccontextmanager


@asynccontextmanager
async def connection(name: str):
    await asyncio.sleep(0.01)
    print("open", name)
    try:
        yield f"<conn {name}>"
    finally:
        await asyncio.sleep(0.01)
        print("close", name)


async def main() -> None:
    async with connection("db") as conn:
        print("using", conn)


await main()

The classic mistakes

Forgetting await. Without it, you get a coroutine object instead of a result, and the work never runs:

▶ Try
import asyncio


async def get_balance() -> int:
    await asyncio.sleep(0.01)
    return 100


balance = get_balance()               # forgot await
print(balance == 100, type(balance).__name__)
balance.close()                       # silence the "never awaited" warning
print(await get_balance() == 100)

Blocking the event loop. Everything runs on one thread, so a synchronous call that waits (time.sleep, requests.get, a slow CPU loop) freezes every task until it returns:

▶ Try
import asyncio
import time


async def heartbeat() -> None:
    for i in range(3):
        print("beat", i)
        await asyncio.sleep(0.01)


async def blocking_work() -> None:
    time.sleep(0.05)                  # blocks the whole loop
    print("blocking work done")


async def friendly_work() -> None:
    await asyncio.sleep(0.05)         # gives the loop back while it waits
    print("friendly work done")


await asyncio.gather(heartbeat(), blocking_work())
print("---")
await asyncio.gather(heartbeat(), friendly_work())

With time.sleep, the heartbeat stops for the whole 50 ms. Use the async version of the library (httpx or aiohttp instead of requests, asyncpg instead of psycopg2), or push the blocking call to a thread:

# asyncio.to_thread needs real threads (not runnable here)
import asyncio
import requests

async def fetch_status(url: str) -> int:
    response = await asyncio.to_thread(requests.get, url, timeout=5)
    return response.status_code

Sequential awaits that should be concurrent. A loop of awaits over independent calls takes the sum of their times:

▶ Try
import asyncio


async def price(sku: str) -> int:
    await asyncio.sleep(0.01)
    return len(sku) * 100


async def slow_total(skus: list[str]) -> int:
    total = 0
    for sku in skus:
        total += await price(sku)      # one at a time
    return total


async def fast_total(skus: list[str]) -> int:
    return sum(await asyncio.gather(*(price(s) for s in skus)))


print(await slow_total(["mug", "tea"]), await fast_total(["mug", "tea"]))

Both give the same answer; the second takes about as long as the slowest single call. Keep the loop when each call depends on the previous one, or when order and rate limits matter.

Coming from JavaScript or C#

Side note
PythonJavaScriptC#
async def f() returns a coroutine (not started)async function returns a promise (already running)async Task<T> (already running)
asyncio.create_task(coro)calling the functionTask.Run, or calling the method
await asyncio.gather(a, b)await Promise.all([a, b])await Task.WhenAll(a, b)
gather(..., return_exceptions=True)Promise.allSettledinspect each task after WhenAll
asyncio.wait(..., return_when=FIRST_COMPLETED)Promise.raceTask.WhenAny
asyncio.timeout(s) / wait_forAbortSignal.timeout(ms)CancellationTokenSource(timeout)
task.cancel() raises CancelledError insideno built-in cancel; AbortController by conventionCancellationToken, cooperative
asyncio.run(main()) starts the loopthe runtime's loop is always therethe thread pool is always there

The two differences that bite: in Python nothing runs until it's awaited or wrapped in a task, and Python tasks really can be cancelled from outside, where JavaScript promises can't.

The exercises

You'll fetch a batch concurrently while keeping the order, add a timeout with a fallback, check a set of services in parallel, retry with backoff, cap concurrency with a semaphore, run a worker pool on a queue, and build a cache that shares one in-flight load between concurrent callers. The tests check concurrency by the order of events and by the largest number of calls running at once, never by timing, so a correct solution passes on any machine.

Practise this lesson

In the app: a short video, 7 exercises checked by real tests and a 12-question concept check. Free with a GitHub account.

Open in the app