Python async/await: The Mental Model That Finally Clicked

TL;DR: async functions don't run concurrently by being async. They run concurrently when you await them inside an event loop. That distinction is everything.

The short version

async functions don't run concurrently by being async. They run concurrently when you await them inside an event loop. That distinction is everything.

This guide covers the mental model, the patterns that pay off, and the trade-offs that decide whether a technique fits your code.

Working example

Here's a minimal example you can run as-is. Drop it in a fresh file, run it, and trace through it once before reading the rest.

from typing import Iterator

def chunked(items: list, size: int) -> Iterator[list]:
    """Yield successive size-chunks from items."""
    for i in range(0, len(items), size):
        yield items[i:i + size]

for batch in chunked(list(range(10)), 3):
    print(batch)
# [0, 1, 2]
# [3, 4, 5]
# [6, 7, 8]
# [9]

Why this pattern

The shape above shows up in real Python codebases because it satisfies three constraints at once: it stays type-safe, it composes with the rest of the language's idioms, and it leaves a clear trail for the next developer (which, in six months, is you).

When you write the same pattern three times in a project, extract it. When you write it three times across projects, extract it into a shared library.

A common variant

The same idea adapted for a different shape. Notice how the structure stays the same — only the specifics change.

from dataclasses import dataclass, field
from datetime import datetime

@dataclass(slots=True, frozen=True)
class Event:
    name: str
    payload: dict = field(default_factory=dict)
    ts: datetime = field(default_factory=datetime.now)

e = Event("user.signup", {"email": "a@b.co"})
print(e.name, e.ts.isoformat())

Trade-offs to watch

Every pattern has a failure mode. The most common one here is over-application: developers who learn a technique apply it everywhere, including places where simpler code would have been clearer.

Rule of thumb: if the abstraction takes more lines to describe than it saves, the abstraction is wrong.

A more involved example

Once the basic pattern is clear, here's how it composes with surrounding code. Read this one slowly.

import logging

log = logging.getLogger(__name__)

def safe_divide(a: float, b: float) -> float | None:
    try:
        return a / b
    except ZeroDivisionError:
        log.warning("divide by zero: %s / %s", a, b)
        return None

When to skip it

If the surrounding code is already simple, don't reach for Python-specific cleverness. Boring code is a feature. Save the patterns for places where they actually pay off — usually at module boundaries, in shared libraries, or where the alternative would be 50 lines of repetition.

FAQ

Related reading

• Pytest Fixtures: A Deep Dive Most Tutorials Skip
• dataclasses vs pydantic vs attrs
• Python Decorators Explained With Real Code
• Multi-Cursor Tricks That Save Hours
• Reading EXPLAIN ANALYZE Without Going Insane