Async Python

Key features

• async def defines a coroutine function; calling it returns a coroutine object immediately
• A coroutine object does nothing until awaited — calling the function alone runs no code
• asyncio.run(main()) creates an event loop, runs main() to completion, then closes the loop
• Only one coroutine runs Python code at a time — the loop is cooperative, not preemptive
• A coroutine created but never awaited triggers a "was never awaited" RuntimeWarning

Command

async def fetch(url):
    ...            # a coroutine function

coro = fetch(url)  # builds a coroutine object -- nothing has run yet
result = await coro  # runs it, suspends the caller until it finishes

asyncio.run(main())  # the only place a loop is created from ordinary code

Key features

• Awaitable = anything valid after await: a coroutine, a Task, or a Future
• asyncio.create_task(coro()) schedules coro to start now, returns a Task immediately
• A Task keeps running even if you never await it again — it is not paused waiting for you
• task.done() reports whether it finished; awaiting a Task blocks until it does
• A Future is a lower-level awaitable — most code uses Task, not Future, directly

Command

task = asyncio.create_task(fetch(url))  # starts running NOW, in the background
# ... do other work here while it runs ...
result = await task                     # wait for it, get the result

Key features

• asyncio.gather(*coros) schedules every coroutine concurrently, waits for all to finish
• Results come back in the SAME ORDER passed in, regardless of which finished first
• By default, the first raised exception propagates and cancels the other coroutines
• return_exceptions=True collects exceptions as results instead, so one failure isn't fatal

Command

results = await asyncio.gather(fetch("a"), fetch("b"), fetch("c"))
# results == [result_of_a, result_of_b, result_of_c] -- order preserved

Key features

• task.cancel() schedules a CancelledError to be raised inside the task at its next await
• A cancelled coroutine can catch CancelledError to clean up, but should re-raise it
• asyncio.timeout(seconds) (3.11+) raises TimeoutError if the with block runs too long
• asyncio.wait_for(coro, timeout) is the older equivalent for a single awaitable
• A task with no await points cannot actually be interrupted until it reaches one

Command

task = asyncio.create_task(long_job())
task.cancel()
try:
    await task
except asyncio.CancelledError:
    ...   # the task was cancelled

async with asyncio.timeout(2):
    await slow_operation()   # raises TimeoutError if it takes over 2s

Key features

• async with obj: needs obj to define async __aenter__(self) and async __aexit__(self, ...)
• __aenter__'s return value becomes the as target, exactly like __enter__
• contextlib.asynccontextmanager turns an async generator into an async context manager
• Fits resources whose open/close step is itself I/O — a DB connection, an HTTP session

Command

class AsyncResource:
    async def __aenter__(self):
        await self.open()
        return self

    async def __aexit__(self, exc_type, exc, tb):
        await self.close()
        return False

async with AsyncResource() as r:
    await r.use()

Key features

• async for x in obj: needs obj to define __aiter__(self) and async __anext__(self)
• __anext__ raises StopAsyncIteration — the async equivalent of StopIteration
• An async def function containing yield is an async generator, built automatically
• [x async for x in gen] is an async comprehension, like a list comprehension

Command

async def countdown(start):
    while start > 0:
        await asyncio.sleep(0.01)
        yield start
        start -= 1

async for n in countdown(3):
    print(n)

values = [n async for n in countdown(3)]  # async comprehension

Key features

• asyncio.Semaphore(n) allows up to n concurrent async with sem: blocks; the rest wait
• asyncio.Lock() is equivalent to Semaphore(1) — only one coroutine holds it at a time
• Both are used with async with, which acquires on entry and releases on exit automatically
• Both protect shared state or a rate-limited resource from too much concurrent access
• Neither is safe across threads — they coordinate coroutines on one event loop only

Command

sem = asyncio.Semaphore(2)  # at most 2 concurrent

async def fetch_page(n):
    async with sem:
        return await do_request(n)

lock = asyncio.Lock()

async def increment(counter):
    async with lock:
        counter["value"] += 1

Key features

• time.sleep() or a synchronous requests.get() freezes the whole event loop while it runs
• await asyncio.sleep() yields control back; time.sleep() blocks the loop's thread instead
• asyncio.to_thread(fn, *args) runs a blocking call in a thread without freezing the loop
• Mixing a sync ORM/driver into async code is a common production async mistake

Command

# BAD -- blocks the whole event loop
def handler():
    time.sleep(1)

# GOOD -- yields control, other coroutines keep running
async def handler():
    await asyncio.sleep(1)

# GOOD -- for a genuinely blocking call you cannot avoid
async def handler():
    result = await asyncio.to_thread(blocking_function, arg)

Key features

• httpx.AsyncClient() is a common async HTTP client — like requests, but awaited
• asyncpg and SQLAlchemy's async engine are async database clients, for Postgres and others
• A connection pool keeps open connections ready, avoiding a handshake cost per request
• Reusing one AsyncClient/pool is far cheaper than opening a connection each call
• A pool has a max size — beyond it, requests wait for a connection, like a semaphore

Command

import httpx

async def fetch_all(urls):
    async with httpx.AsyncClient() as client:   # one pooled client, reused
        responses = await asyncio.gather(*(client.get(u) for u in urls))
    return [r.json() for r in responses]

# asyncpg -- an async Postgres client with a built-in pool
pool = await asyncpg.create_pool(dsn, min_size=5, max_size=20)
async with pool.acquire() as conn:
    rows = await conn.fetch("SELECT * FROM orders WHERE id = $1", order_id)

Key features

• Backpressure = deliberately limiting how fast work is produced, to match the consumer
• asyncio.Semaphore(n) is the simplest way to enforce a hard concurrency cap
• asyncio.Queue(maxsize=n) blocks put() once full, until get() removes an item
• Without a limit, unlimited concurrent requests can exhaust memory or overwhelm a service
• A concurrency limit is a capacity decision — match it to what downstream can handle

Command

queue = asyncio.Queue(maxsize=100)   # producer blocks once 100 items are pending

async def producer():
    for item in source():
        await queue.put(item)   # blocks here if the queue is full -- backpressure

async def consumer():
    while True:
        item = await queue.get()
        await process(item)
        queue.task_done()

Key features

• A try/finally around awaiting code runs cleanup on cancellation, like any exception
• Catching CancelledError for cleanup is fine, but it must be re-raised, not swallowed
• asyncio.shield(coro) protects a coroutine from an outer cancellation reaching it
• A Task's .cancelled() is True only if CancelledError actually propagated out of it

Command

async def worker():
    resource = await acquire()
    try:
        await do_work(resource)
    finally:
        await resource.release()   # runs on success, error, AND cancellation

# or, if cleanup needs to distinguish cancellation specifically:
async def worker():
    try:
        await do_work()
    except asyncio.CancelledError:
        await cleanup()
        raise   # ALWAYS re-raise -- do not swallow it

Key features

• Threading: mostly I/O-bound synchronous work — existing sync libraries work unmodified
• Multiprocessing: CPU-bound work — separate processes escape the GIL, pickling data across
• AsyncIO: high-concurrency I/O-bound work — many connections on one thread, async libraries
• The GIL makes CPU-bound threading ineffective; it does not slow I/O-bound threading
• Async and threading are usually alternatives, not combined, for the same I/O-bound problem

Command

# The decision, in order:
# 1. Is the work mostly computing (CPU-bound)?
#      -> multiprocessing (ProcessPoolExecutor)
# 2. Is it I/O-bound with a MODERATE number of concurrent operations,
#    using existing synchronous libraries?
#      -> threading (ThreadPoolExecutor)
# 3. Is it I/O-bound with a LARGE number of concurrent operations
#    (thousands), and async-native libraries are available?
#      -> asyncio