Python Coroutines and async/await

Intermediate

A coroutine is Python’s language-level way to describe work that can suspend and resume. You define a coroutine function with async def, call it to create a coroutine object, and use await inside a coroutine to suspend it until another awaitable produces a result.

async def creates a coroutine function

A function defined with async def is a coroutine function even when its body contains no await. Calling the function creates a coroutine object; it does not execute the body to completion by itself.

A coroutine object needs to be driven

The object returned by a coroutine function is awaitable. A top-level program commonly uses asyncio.run() to run an entry-point coroutine and obtain its result. Calling the coroutine function and then forgetting to await or otherwise run the resulting object does not execute its body.

await suspends a coroutine

An await expression suspends the current coroutine until the awaited object produces its result. Control can then continue with the value of that result.

Awaiting composes coroutines

One coroutine can await another and then use the returned value. This gives asynchronous code a direct way to build larger operations from smaller coroutine functions.

Coroutine exceptions propagate through await

An exception raised while a coroutine is running can propagate to the coroutine that awaits it. Ordinary try and except handling still applies.

async def does not require await

An async def function remains a coroutine function even when it never suspends. It can still be awaited and can still be used as an asynchronous entry point.

yield from is not for coroutine functions

Coroutine functions use await to wait for awaitables. A yield from expression is not permitted inside a coroutine function.

Quick check

result = ?(main)  # main is async def main(): ...