Async Programming with asyncio

Asyncio is a library to write concurrent code using the async/await syntax. It is the foundation of multiple Python asynchronous frameworks that provide high-performance network and web-servers, database connection libraries, distributed task queues, etc.

Coroutines and the Event Loop

A coroutine is a function you define with async def. Calling it does not run it — it hands you an object that only makes progress when something awaits it. That is the whole trick behind asyncio: your code decides exactly where it is willing to pause.

asyncio.run() is the doorway from ordinary synchronous Python into that world. It starts an event loop, runs your top-level coroutine to completion, and shuts the loop down again. You call it once, at the entry point — never inside another coroutine.

Basic coroutine execution

import asyncio

async def say_hello():
    print("Hello")
    await asyncio.sleep(0)
    print("Async World!")

asyncio.run(say_hello())

Hello
Async World!

Awaiting Coroutines

You can await other coroutines inside an async function to get their return values.

Awaiting another coroutine

import asyncio

async def get_greeting():
    return "Hello from coroutine"

async def main():
    greeting = await get_greeting()
    print(greeting)

asyncio.run(main())

Hello from coroutine

Tasks and Cooperative Scheduling

Awaiting a coroutine directly runs it to completion before moving on. Wrapping it in a Task schedules it instead, so the loop can start it and immediately go do something else. Tasks are how you get concurrency rather than just asynchronous-looking sequential code.

The scheduling is cooperative, and that word is doing a lot of work. One task runs at a time; the loop can only switch when a task hits an await and voluntarily yields. A task that never awaits — a long calculation, say — blocks everything else, because nothing can interrupt it.

Running tasks concurrently with gather

import asyncio

async def worker(name, delay):
    print(f"{name} started")
    await asyncio.sleep(delay)
    print(f"{name} finished")

async def main():
    await asyncio.gather(
        worker("Task A", 0.02),
        worker("Task B", 0.01)
    )

asyncio.run(main())

Task A started
Task B started
Task B finished
Task A finished

Gather preserves order

import asyncio

async def fetch_data(id, delay):
    await asyncio.sleep(delay)
    return f"Data {id}"

async def main():
    results = await asyncio.gather(
        fetch_data(1, 0.02),
        fetch_data(2, 0.01)
    )
    print(results)

asyncio.run(main())

['Data 1', 'Data 2']

Modern Concurrency: TaskGroups

asyncio.TaskGroup (Python 3.11+) is the modern way to run several tasks together. It waits for all of them, and if any one fails it cancels the rest and propagates the error — no silently-abandoned tasks, which was easy to end up with using bare gather().

Using a TaskGroup context manager

import asyncio

async def worker(name):
    print(f"Working on {name}")

async def main():
    async with asyncio.TaskGroup() as tg:
        tg.create_task(worker("A"))
        tg.create_task(worker("B"))
    print("All tasks completed")

asyncio.run(main())

Working on A
Working on B
All tasks completed

Concurrent execution visualization

You can spawn hundreds of tasks instantly. The total time depends only on the longest individual delay, because all waiting happens concurrently!

import asyncio

async def process_item(item_id):
    await asyncio.sleep(0.01 * (5 - item_id))
    print(f"Processed item {item_id}")

async def main():
    tasks = 3
    print(f"Starting {tasks} tasks")
    async with asyncio.TaskGroup() as tg:
        for i in range(1, tasks + 1):
            tg.create_task(process_item(i))
    print("All done")

asyncio.run(main())

Starting 3 tasks
Processed item 3
Processed item 2
Processed item 1
All done