async and await in Plain Words

Most of a back end's time goes on waiting, so an async def function can pause at each await and let other work run, asyncio.gather waits for two things at once instead of one after the other, and time.sleep inside async def holds up everything else.

Journeyman · Python · FastAPI · Updated

By

After this lesson you can

  • Write async def functions that await, run them with asyncio.run, and explain what a coroutine is
  • Run two waits at once with asyncio.gather, and explain why time.sleep inside async def makes every other task wait

Key takeaways

  • A back end spends most of a request waiting on another service, a disk or a database, and plain code waits for each thing in turn.
  • async def makes a function that can pause at each await and let other work run meanwhile. Calling it gives back a coroutine, which runs only when it's awaited.
  • Awaiting two things one after the other still takes as long as both together. asyncio.gather waits for both at once, so two one-second waits take about one second.
  • asyncio.run(main()) starts the event loop, which switches to another task whenever the one it's running is waiting.
  • Inside async def, wait with await asyncio.sleep, never time.sleep. A blocking call holds the whole event loop, so every other task waits too.

A weather app asks one service for the forecast and another for the air quality. A checkout asks the payment company and the shipping company. A lot of back-end work is asking other programs and waiting for their answers, and how a program waits decides how fast it feels. This lesson shows Python's way of waiting for two things at once, which the next lesson puts into a FastAPI route.

The example is Movie Night Picker, an API for a group of friends that asks a showtimes service and a reviews service before it suggests tonight's film.

Waiting, one thing after another

Each service takes about a second to answer. Here the two calls are stood in for by functions that wait a second with time.sleep(1), then return what the service would send:

import time


def get_showtimes():
    time.sleep(1)  # the showtimes service takes a second to answer
    return ["Paper Comets", "Robot Garden"]


def get_reviews():
    time.sleep(1)  # so does the reviews service
    return {"Paper Comets": 4.2, "Robot Garden": 4.7}


start = time.perf_counter()
showtimes = get_showtimes()
reviews = get_reviews()
print(f"Took {time.perf_counter() - start:.1f} seconds")
Took 2.0 seconds

time.perf_counter() is a stopwatch: the difference between two readings is the seconds in between. The program spends those two seconds doing nothing at all. It doesn't need the showtimes before it asks for the reviews, yet it waits for one answer before it asks the next question.

The cook and the rice

A good cook doesn't stand and watch the rice boil. They start the rice, chop the vegetables while it cooks, and come back when the timer goes. Nothing gets faster; the waits overlap.

Python's word for this is async, short for asynchronous (not at the same time). async def, read "async def", makes a function that can pause partway and let other work run. await, read "await", marks the place where it pauses: "wait for this, and do something else meanwhile". asyncio is the standard library module that runs these functions, and asyncio.sleep(1) is a wait that can be paused:

import asyncio
import time


async def get_showtimes():
    await asyncio.sleep(1)  # waits a second, and lets other work run meanwhile
    return ["Paper Comets", "Robot Garden"]


async def get_reviews():
    await asyncio.sleep(1)
    return {"Paper Comets": 4.2, "Robot Garden": 4.7}


async def main():
    start = time.perf_counter()
    showtimes = await get_showtimes()
    reviews = await get_reviews()
    print(f"Took {time.perf_counter() - start:.1f} seconds")


asyncio.run(main())
Took 2.0 seconds

Still two seconds. Two things to notice:

  • Calling an async function doesn't run it. get_showtimes() gives back a coroutine: a function call that's ready to run and can pause partway. await is what runs it. Print get_showtimes() without the await and you see <coroutine object get_showtimes at 0x...>, then a warning that it was never awaited.
  • asyncio.run(main()), read "asyncio dot run", starts the event loop, the cook of the picture: it runs one task until that task waits, then switches to another that's ready. It runs main() until it finishes.

The code awaits the showtimes, then the reviews, so the second question still isn't asked until the first answer is in. The cook started the rice and stood watching it.

asyncio.gather: two waits at once

asyncio.gather, read "asyncio dot gather", takes several coroutines, starts them all, and waits until every one has finished. It gives back their results in the order you passed them in, so they unpack into two names. Here is the new main(); the two functions stay as they were:

async def main():
    start = time.perf_counter()
    showtimes, reviews = await asyncio.gather(get_showtimes(), get_reviews())
    print(f"Took {time.perf_counter() - start:.1f} seconds")
    print(showtimes)
    print(reviews)
Took 1.0 seconds
['Paper Comets', 'Robot Garden']
{'Paper Comets': 4.2, 'Robot Garden': 4.7}

Both questions go out at once and both waits overlap, so the whole thing takes as long as the slower one. With five services of a second each, it's still about one second, not five.

time.sleep holds up everything

Change both functions' await asyncio.sleep(1) to time.sleep(1), keep asyncio.gather, and run it again:

async def get_showtimes():
    time.sleep(1)  # blocks: nothing else runs during this second
    return ["Paper Comets", "Robot Garden"]
Took 2.0 seconds
['Paper Comets', 'Robot Garden']
{'Paper Comets': 4.2, 'Robot Garden': 4.7}

Back to two seconds. time.sleep blocks: it holds the event loop until it's done, so the loop can't switch to the other task. The event loop can only switch at an await. The rule inside async def: wait with await, never with a call that blocks. In the next lesson the blocking call is a database query or an ordinary web request, and inside an API it holds up every request at once.

Do it: ask both services at once

Movie Night Picker's starter has two async functions that stand in for the services. Each takes 0.4 seconds to answer:

  • get_showtimes(): tonight's films in the order they start, as a list of (title, time) pairs: [("Paper Comets", "19:00"), ("The Lighthouse Choir", "19:30"), ("Robot Garden", "20:15")].
  • get_reviews(): each film's stars, as a dictionary: {"Paper Comets": 4.2, "The Lighthouse Choir": 3.9, "Robot Garden": 4.7}.

Your job: write async def movie_night().

  • Ask both services at the same time with asyncio.gather.
  • Return a list with one line of text per film, in the showtimes' order, written like 19:00 Paper Comets, 4.2 stars: the time, the title, a comma, then the stars.
  • Asking at the same time means it finishes in about 0.4 seconds; one after the other takes 0.8. The tests allow anything under 0.7 seconds.

Worked through: the first pair is ("Paper Comets", "19:00"), and get_reviews() gives 4.2 for "Paper Comets", so the first line is 19:00 Paper Comets, 4.2 stars. The whole list movie_night() returns is:

['19:00 Paper Comets, 4.2 stars', '19:30 The Lighthouse Choir, 3.9 stars', '20:15 Robot Garden, 4.7 stars']

The tests await movie_night() for you, so your code doesn't call asyncio.run.

Practiced live on the lesson page: write the Python right there and check it.

Check yourself

2 questions to try on the lesson page.

So what

A program that waits for its answers one at a time is slow for no reason, and async def, await and asyncio.gather let it wait for all of them at once, as long as nothing inside blocks.

Key terms

Related