Async programming with asyncio
Run many waiting tasks at once with async, await and asyncio: gather, tasks, timeouts, semaphores, queues and threads.
In this lesson you will
- Explain what asynchronous code solves
- Write coroutines with async def and await
- Run tasks together with gather and create_task
- Add timeouts, limits and queues
About 24 minutes
Why wait in line when you can cook while the kettle boils?
Making breakfast, you do not stand and stare at the kettle. You start the water, then toast the bread, then take out the plates, and come back when the kettle clicks. Programs often wait: for a website, a database, a file, a timer. A normal program freezes during each wait. Asynchronous code says “while this waits, go and do something else”. It is the technique behind fast web servers, chat apps and tools that fetch hundreds of web pages at once.
The slow way
import time
def fetch(name, seconds):
time.sleep(seconds) # pretend to wait for a server
return f"{name} done"
start = time.perf_counter()
results = [fetch("A", 0.3), fetch("B", 0.3), fetch("C", 0.3)]
print(results)
print("Total about", round(time.perf_counter() - start, 1), "seconds")
['A done', 'B done', 'C done']
Total about 0.9 seconds
The async way
import asyncio, time
async def fetch(name, seconds):
await asyncio.sleep(seconds) # pause THIS task; let others run
return f"{name} done"
async def main():
start = time.perf_counter()
results = await asyncio.gather(fetch("A", 0.3), fetch("B", 0.3), fetch("C", 0.3))
print(results)
print("Total about", round(time.perf_counter() - start, 1), "seconds")
asyncio.run(main())
['A done', 'B done', 'C done']
Total about 0.3 seconds
The three waits overlapped, so the total was the length of one wait, not three. Four new ideas did that:
async defcreates a coroutine: a function that can pause.awaitmarks a point where it may pause and let something else run. You can only use it insideasync def.asyncio.gather(...)runs several coroutines together and collects their results in order.asyncio.run(main())starts the whole thing; call it once at the top level.
Calling an async function without await. fetch("A", 1) does not run it; it only creates a coroutine object, and Python warns “coroutine was never awaited”. Write await fetch("A", 1).
Watching the tasks interleave
import asyncio
async def worker(name, delay, steps):
for i in range(1, steps + 1):
await asyncio.sleep(delay)
print(f"{name} finished step {i}")
async def main():
await asyncio.gather(worker("fast", 0.1, 3), worker("slow", 0.25, 2))
asyncio.run(main())
fast finished step 1
fast finished step 2
slow finished step 1
fast finished step 3
slow finished step 2
Tasks: start now, collect later
import asyncio
async def download(n):
await asyncio.sleep(0.1 * n)
return n * n
async def main():
task1 = asyncio.create_task(download(3)) # starts running right away
task2 = asyncio.create_task(download(1))
print("Both started; doing other work meanwhile")
print(await task1, await task2)
asyncio.run(main())
Both started; doing other work meanwhile
9 1
Timeouts, errors and limits
import asyncio
async def slow():
await asyncio.sleep(5)
async def broken():
raise ValueError("bad data")
async def main():
try:
await asyncio.wait_for(slow(), timeout=0.2)
except asyncio.TimeoutError:
print("Gave up waiting")
results = await asyncio.gather(asyncio.sleep(0.1, "ok"), broken(), return_exceptions=True)
print(results)
asyncio.run(main())
Gave up waiting
['ok', ValueError('bad data')]
import asyncio
async def job(n, limit):
async with limit: # only a few at a time
await asyncio.sleep(0.1)
return n
async def main():
limit = asyncio.Semaphore(2)
done = await asyncio.gather(*(job(n, limit) for n in range(6)))
print(done)
asyncio.run(main())
[0, 1, 2, 3, 4, 5]
When you fetch hundreds of pages, do not launch them all at once: you may overload the server or your own connection. A Semaphore keeps only a chosen number running at a time.
A producer and a consumer with a queue
import asyncio
async def producer(queue):
for n in range(1, 5):
await queue.put(n)
await asyncio.sleep(0.05)
await queue.put(None) # tells the consumer to stop
async def consumer(queue):
while True:
item = await queue.get()
if item is None:
break
print("Processing", item)
async def main():
queue = asyncio.Queue()
await asyncio.gather(producer(queue), consumer(queue))
asyncio.run(main())
Processing 1
Processing 2
Processing 3
Processing 4
Real use: many web requests
With a library such as aiohttp or httpx, the same pattern fetches many pages at once. This needs the internet and an extra package, so it is shown as a pattern, not run output.
import asyncio
import httpx # pip install httpx
async def get_title(client, url):
response = await client.get(url, timeout=10)
return url, response.status_code
async def main():
urls = ["https://example.com", "https://example.org", "https://example.net"]
async with httpx.AsyncClient() as client:
results = await asyncio.gather(*(get_title(client, u) for u in urls))
for url, status in results:
print(url, status)
asyncio.run(main())
Important: what async is not
- It is for waiting work (network, files, timers), not for heavy calculation. A busy loop still blocks everything.
- Everything runs in one thread. Tasks take turns whenever one hits an
await. - For CPU-heavy work use
multiprocessingor a process pool fromconcurrent.futures. - For blocking libraries that cannot
await, useawait asyncio.to_thread(function, args).
import asyncio, time
def blocking_job():
time.sleep(0.2)
return "blocking job finished"
async def main():
start = time.perf_counter()
results = await asyncio.gather(
asyncio.to_thread(blocking_job),
asyncio.to_thread(blocking_job),
)
print(results)
print("Overlapped:", time.perf_counter() - start < 0.39)
asyncio.run(main())
['blocking job finished', 'blocking job finished']
Overlapped: True
Write a coroutine square(n) that sleeps 0.1 seconds and returns n * n. Use gather to compute the squares of 1 to 5 together and print the list.
Show one possible answer
import asyncio
async def square(n):
await asyncio.sleep(0.1)
return n * n
async def main():
print(await asyncio.gather(*(square(n) for n in range(1, 6))))
asyncio.run(main())
[1, 4, 9, 16, 25]
Make a coroutine that fails after 5 seconds and wrap it so the program gives up after 0.3 seconds and prints a friendly message.
Hint: asyncio.wait_for
Show one possible answer
import asyncio
async def slow_task():
await asyncio.sleep(5)
return "finished"
async def main():
try:
print(await asyncio.wait_for(slow_task(), timeout=0.3))
except asyncio.TimeoutError:
print("That took too long, giving up")
asyncio.run(main())
That took too long, giving up
Ordinary code is simpler to write, read and debug. Use async when you really have many slow waits, such as scraping lots of pages or running a server with many users.
Check what you learned
Five quick questions. Pick an answer and you will see straight away whether it is right and why.
What does await do?
- Stops the program
- Imports a module
- Pauses this task so others can run
- Creates a thread
It hands control back while waiting.
What starts the top-level async function?
asyncio.run(main())main()await main()at top levelstart(main)
asyncio.run creates the event loop.
What does asyncio.gather do?
- Deletes tasks
- Sorts results
- Runs coroutines together and collects results
- Stops tasks
Results come back in the order given.
Async programming helps most with:
- Waiting for I/O such as networks
- Heavy maths
- Drawing
- Typing
CPU-bound work needs processes.
What happens if you call fetch() without await?
- It runs normally
- It only creates a coroutine and does not run
- It crashes the computer
- It runs twice
You must await or schedule it.
Summary
- async def makes coroutines; await pauses them.
- gather runs many waits at once.
- Async helps with waiting, not heavy calculation.
- Use timeouts and semaphores for safety.
Questions
Is async the same as multithreading?
No. Async uses one thread and tasks take turns at each await. Threads run in parallel and need more care.
Why can't I use await in a normal function?
await only works inside async def, because only coroutines can pause.
Do I need to learn async to be a good Python developer?
Not at the start, but it is very useful for web servers and network tools, and you will meet it in modern frameworks.
