Async Python and asyncio

A synchronous web handler that opens a database query and waits 50 ms for a result spends those 50 ms doing nothing. The CPU is idle. Other connections sit in the accept queue. Multiply by every concurrent request and the worker process has effectively serialized them.

Python's answer is cooperative concurrency: one thread, one event loop, and a way for code to say I'm waiting on I/O, give the loop back to someone else. That word is await. When you write await query() you are not blocking — you are yielding control until the I/O finishes.

This is not parallelism. It is overlap. One thread, one core, but the loop multiplexes thousands of connections because none of them ever waits on the CPU. Web servers, brokers, and proxies are almost pure I/O — which is why modern backend Python defaults to this model.

async def fetch(url: str) -> str:
    ...

x = fetch("https://example.com")   # x is a coroutine object, NOT the result
result = await fetch("https://example.com")  # await drives it; this is the result

The first line allocates a coroutine object — the function body has not yet executed. The only way to actually run that body is to await it (or schedule it with asyncio.create_task / asyncio.run). Forget the await and the body never runs; CPython emits a RuntimeWarning: coroutine was never awaited at GC time but does not raise.

This is why time.sleep(1) is dangerous inside an async handler. time.sleep is a synchronous, blocking syscall — it freezes the entire thread for one second. The event loop cannot schedule any other task during that second. One slow handler stalls every other request on the worker. The async-safe equivalent is await asyncio.sleep(1), which yields control back to the loop.

The loop is a scheduler over a ready queue. Tasks run until they hit an await; awaiting on I/O parks them with the OS selector until the kernel signals the file descriptor is ready.

asyncio.TaskGroup (3.11+) supersedes asyncio.gather for new code. The difference is cancellation safety: if any child raises, the group cancels its siblings and re-raises an ExceptionGroup. gather leaves siblings running in the background after the first failure unless you pass return_exceptions=True and audit every result yourself.

import asyncio
import httpx

async def fetch(client: httpx.AsyncClient, url: str, sem: asyncio.Semaphore) -> int:
    async with sem:
        r = await client.get(url, timeout=5.0)
        return r.status_code

async def main(urls: list[str]) -> list[int]:
    sem = asyncio.Semaphore(20)
    async with httpx.AsyncClient() as client:
        async with asyncio.TaskGroup() as tg:
            tasks = [tg.create_task(fetch(client, u, sem)) for u in urls]
    return [t.result() for t in tasks]

The Semaphore bounds in-flight concurrency to 20 — without it you would open all N sockets at once and the kernel would shed them. The httpx.AsyncClient is held open across the whole group so the connection pool is reused.

Async multiplexes I/O on one thread. It does not run CPU work in parallel — the GIL still serializes Python bytecode across threads on a standard CPython build. (PEP 703 ships an experimental free-threaded build from 3.13, but production deployments are still GIL'd.)

The decision:

• I/O-bound (DB queries, HTTP, file I/O) → asyncio. One worker handles thousands of sockets.
• CPU-bound (image processing, parsing, ML inference in Python) → multiprocessing.Pool or concurrent.futures.ProcessPoolExecutor. Each worker has its own interpreter and its own GIL.
• Short blocking calls inside async code (a sync driver you can't replace, Pillow.resize) → await asyncio.to_thread(blocking_fn, args). The call runs on a thread-pool worker; the loop stays free.

threading rarely wins in pure Python because of the GIL. It still helps when the C extension releases the GIL (most stdlib I/O does), but asyncio.to_thread is the modern wrapper for that case.

Sync and async functions have different calling conventions — the coloured functions problem. A sync function returns a value; an async function returns a coroutine that must be awaited. You cannot transparently call one from the other.

import asyncio
from asgiref.sync import sync_to_async

# Sync entrypoint launching async code — only at the top level.
asyncio.run(main())  # nested asyncio.run() raises RuntimeError

# Inside async code: offload a slow sync call to a thread.
result = await asyncio.to_thread(slow_blocking_call, arg)

# Django ORM calls are sync — bridge them explicitly.
user = await sync_to_async(User.objects.get)(id=42)

The bridges: asyncio.run() starts a loop for a top-level entry point. Inside a running loop, asyncio.to_thread() (or anyio.to_thread.run_sync()) offloads sync work to a thread pool so the call site can await it. FastAPI auto-detects sync vs async handlers and applies the wrapper for you — but you still need to know it is happening, or one slow sync handler will saturate the thread pool.

Every await is a potential cancellation point. The loop can kill a task at any await by raising asyncio.CancelledError from within the awaited expression. Your code must let that exception propagate — or do cleanup in finally and then re-raise.

async def handler() -> dict | None:
    conn = await pool.acquire()
    try:
        return await conn.fetch("SELECT 1")
    except asyncio.CancelledError:
        # WRONG: swallowing cancellation breaks structured concurrency.
        # The parent TaskGroup now thinks this task finished successfully.
        return None
    finally:
        await pool.release(conn)  # cleanup always runs

If a critical section truly must not be cancelled mid-way — finishing a payment write, say — wrap it with asyncio.shield:

await asyncio.shield(finalize_payment(tx_id))

shield allows the outer task to be cancelled while the inner task keeps running. This is the only idiomatic way to delay cancellation; catching CancelledError and continuing is a bug, not a pattern.

The list of things that bite real backends, in rough order of frequency:

• Never call sync-blocking APIs in an async handler. time.sleep, requests.get, the standard psycopg2 cursors, Pillow.open — all stall the loop for every concurrent request. Use asyncio.sleep, httpx.AsyncClient, asyncpg / psycopg[async], or wrap in asyncio.to_thread.
• Always timeout external I/O. A hung TCP connection without a timeout pins a Task forever. httpx.AsyncClient(timeout=5.0) or async with asyncio.timeout(10): ....
• Watch the unawaited-coroutine warning. loop.run_until_complete(some_async_fn) — note: passing the function, not a call — does nothing useful and warns at GC. The bug already shipped.
• Set PYTHONASYNCIODEBUG=1 in staging. It logs any task that holds the thread longer than 100 ms — fastest way to find the one sync call you forgot to wrap.
• Don't share httpx.AsyncClient / aiohttp.ClientSession across event loops. They bind to the loop that created them; reusing across asyncio.run calls leaks connections and produces cryptic RuntimeError: Event loop is closed.