Skip to content

Python async/await: Asynchronous Programming with asyncio

  • How async def and await define coroutines and how asyncio.run drives them.
  • How asyncio.gather runs several awaitables concurrently and asyncio.create_task schedules one to run in the background.
  • Why async helps I/O-bound work and starves CPU-bound work.
  • How to add timeouts, cancellation, and a concurrency limit with a semaphore.
  • How async generators stream results without buffering everything in memory.

async/await is Python’s syntax for cooperative concurrency, built on the asyncio module. An async def function is a coroutine that runs until it hits an await, then yields control so other coroutines can run on the same event loop. This lets a single thread handle thousands of simultaneous I/O operations by switching whenever one of them waits. The feature arrived with async/await keywords in Python 3.5 and has been the standard way to write concurrent I/O ever since. It does not create new threads and does not speed up CPU-bound code.

The problem is latency hidden behind blocking calls. OrdersPortal needs to fetch several orders from a warehouse service before it can render a page. Fetched one at a time, each call blocks the whole process until its response arrives, so ten calls that each take 100 milliseconds take a full second. Concurrency lets those waits overlap.

Sequential, blocking code:

import time
def fetch_order(order_id):
time.sleep(0.1) # simulate a 100 ms network call
return {"id": order_id, "total": order_id * 10}
def fetch_all(order_ids):
return [fetch_order(i) for i in order_ids]
start = time.perf_counter()
results = fetch_all(range(1, 6))
elapsed = time.perf_counter() - start
print(f"{len(results)} orders in {elapsed:.3f}s")
# 5 orders in 0.500s <- waits stack end to end

The five calls take about half a second because each time.sleep blocks the next from starting. The same work, written to overlap the waits, finishes in roughly the time of a single call.

An async def function returns a coroutine object instead of running immediately. You run it on an event loop, most simply with asyncio.run. Inside a coroutine, await suspends until the awaited awaitable finishes, handing control back to the loop so other tasks can progress.

import asyncio
async def fetch_order(order_id):
await asyncio.sleep(0.1) # simulate an awaitable network call
return {"id": order_id, "total": order_id * 10}
async def fetch_all(order_ids):
# gather runs the coroutines concurrently and preserves order
return await asyncio.gather(*(fetch_order(i) for i in order_ids))
async def main():
start = time.perf_counter()
results = await fetch_all(range(1, 6))
elapsed = time.perf_counter() - start
print(f"{len(results)} orders in {elapsed:.3f}s")
import time
asyncio.run(main())
# 5 orders in 0.100s <- waits overlap

The key change is asyncio.gather, which schedules every fetch_order coroutine at once. The loop runs them all, and each await asyncio.sleep yields, so the five 100-millisecond waits run together and the total drops to about 100 milliseconds.

asyncio.create_task schedules a coroutine to run on the loop without awaiting it right away. Use it when you want a coroutine to start working in the background while you do something else, then await the task later to collect its result. If you never await or cancel a task, the loop warns about a never-awaited coroutine.

Async generators, declared with async def and yield, produce values lazily and can await between yields. They are the streaming counterpart to regular generators: you consume them with async for.

import asyncio
async def order_stream(count):
for i in range(1, count + 1):
await asyncio.sleep(0.05)
yield {"id": i}
async def main():
async for order in order_stream(3):
print(order)
asyncio.run(main())
# {'id': 1}
# {'id': 2}
# {'id': 3}

The generator emits each order as soon as it is ready, so the caller can begin processing before the whole batch is fetched. The values are never all held in memory at once.

OrdersPortal renders a customer page by fetching the customer record, their orders, and their shipping history from three services. Fetched sequentially the page is slow; fetched concurrently with asyncio.gather it is fast, and a timeout keeps one slow service from stalling the whole page.

import asyncio
async def fetch_customer(customer_id):
await asyncio.sleep(0.05)
return {"id": customer_id, "name": "Acme"}
async def fetch_orders(customer_id):
await asyncio.sleep(0.08)
return [{"id": 1023, "total": 1500.0}, {"id": 1024, "total": 800.0}]
async def fetch_shipping(customer_id):
await asyncio.sleep(0.06)
return [{"order_id": 1023, "carrier": "FedEx"}]
async def load_page(customer_id):
# run all three fetches concurrently, cap total wait at 0.5 s
customer, orders, shipping = await asyncio.wait_for(
asyncio.gather(
fetch_customer(customer_id),
fetch_orders(customer_id),
fetch_shipping(customer_id),
),
timeout=0.5,
)
return {"customer": customer, "orders": orders, "shipping": shipping}
async def main():
page = await load_page(1)
print(f"{page['customer']['name']}: {len(page['orders'])} orders, {len(page['shipping'])} shipments")
asyncio.run(main())
# Acme: 2 orders, 1 shipments

The three fetches overlap inside asyncio.gather, and asyncio.wait_for raises TimeoutError if the group takes longer than half a second. That bound protects the page from one degraded service.

  • Limit concurrency with a semaphore. Launching a thousand simultaneous HTTP calls can overwhelm the server or exhaust connections. Wrap each call in an asyncio.Semaphore to cap how many run at once.
  • Always set a timeout. An awaited call with no timeout can hang forever and stall the event loop. Use asyncio.wait_for or the timeout argument on the HTTP client.
  • Handle cancellation cleanly. A cancelled coroutine raises asyncio.CancelledError; catch it, release resources, and re-raise so the cancellation propagates. Code that swallows the error breaks the shutdown contract.
  • Drive the loop one way. Call asyncio.run at the top of your program and let everything flow from there. Mixing manual loop.run_until_complete calls with asyncio.run leads to “event loop is closed” errors.
  • Forgetting await. Calling fetch_order(1) without await returns a coroutine object and runs nothing. The bug is silent until you try to use the result.
  • Calling blocking code in a coroutine. A time.sleep or a synchronous requests.get inside an async def blocks the entire loop, freezing every other coroutine. Use await asyncio.sleep or an async HTTP client.
  • Awaiting coroutines sequentially instead of gathering. await a(); await b() runs them one after another. await asyncio.gather(a(), b()) runs them concurrently. The difference is the whole point of async.
  • Creating tasks you never await. asyncio.create_task schedules work, but if you drop the reference the task can be garbage-collected before it finishes. Keep the returned task and await it.
  • Using async for CPU-bound work. Async overlaps waits, not computation. A tight CPU loop never yields, so no other coroutine runs.
Situation Right tool Why
Many simultaneous network or disk calls asyncio One thread overlaps thousands of waits
CPU-heavy computation multiprocessing Async cannot parallelize CPU work on one thread
A few blocking calls in mostly-sync code threads Simpler than rewriting to async
Mixing async and sync libraries threads or run_in_executor Keeps the sync library from blocking the loop

Async is a concurrency model, not a parallelism model. It wins when your program spends its time waiting, and it actively hurts when it spends its time computing.

async/await keywords arrived in Python 3.5. asyncio.run arrived in Python 3.7 and is the supported entry point. Top-level await in the REPL arrived in Python 3.8. Async generators arrived in Python 3.6. The examples here run on Python 3.9 and later. For HTTP, the standard library has no async client; use httpx or aiohttp, both of which require pip install.

1. What does await actually do? It suspends the current coroutine and returns control to the event loop, which can run other ready coroutines. When the awaited awaitable completes, the loop resumes the suspended coroutine with the result. The thread never blocks on the wait.

2. Why does asyncio.gather speed up the fetches? It schedules every coroutine at once, so their waits overlap on the single event loop. Each await inside one coroutine is a chance for the loop to progress another, so five 100-millisecond waits finish in roughly 100 milliseconds instead of 500.

3. What goes wrong if you call a blocking function inside a coroutine? The blocking call does not yield, so the event loop cannot switch to other coroutines while it runs. Every concurrent task stalls until the blocking call returns, defeating the purpose of async and turning concurrency back into sequential execution.

4. Senior scenario: your async service occasionally hangs and never responds. How do you find it? Look for an unbounded await: a network call with no timeout, or a queue the producer fills faster than the consumer drains. Add asyncio.wait_for with a timeout around every external call, log when tasks are created and cancelled, and instrument the loop with asyncio.get_event_loop().set_debug(True) to surface slow callbacks. The usual cause is one coroutine stuck in a blocking call that starves the loop.

  • async def defines a coroutine; await suspends it; asyncio.run drives it.
  • asyncio.gather runs awaitables concurrently; asyncio.create_task runs one in the background.
  • Async overlaps I/O waits on one thread; it does not parallelize CPU work.
  • Never call blocking code in a coroutine, and always set a timeout on external calls.
  • Use httpx or aiohttp for async HTTP; the standard library has no async client.