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.
In short
- One thread; tasks switch at
await - Coroutines run only when awaited or wrapped in a task
gatherandTaskGroupfor concurrency- Timeouts cancel;
CancelledErrormust propagate SemaphoreandQueueto 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.
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.
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:
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).
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:
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:
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*.
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()
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.
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.
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:
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.
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.
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:
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:
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:
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:
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
| Python | JavaScript | C# |
|---|---|---|
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 function | Task.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.allSettled | inspect each task after WhenAll |
asyncio.wait(..., return_when=FIRST_COMPLETED) | Promise.race | Task.WhenAny |
asyncio.timeout(s) / wait_for | AbortSignal.timeout(ms) | CancellationTokenSource(timeout) |
task.cancel() raises CancelledError inside | no built-in cancel; AbortController by convention | CancellationToken, cooperative |
asyncio.run(main()) starts the loop | the runtime's loop is always there | the 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