Last Updated on November 6, 2022

You can define an asyncio coroutine using the async def expression.

In this tutorial, you will discover asyncio async def expressions in Python.

Let’s get started.

What is async def

The “async def” expression defines a coroutine.

Functions defined with async def syntax are always coroutine functions, even if they do not contain await or async keywords.

— Python Compound statements

A coroutine is a function or routine that can be suspended and resumed. As such it has more than one entry point.

Coroutines are a more generalized form of subroutines. Subroutines are entered at one point and exited at another point. Coroutines can be entered, exited, and resumed at many different points.

— Python Glossary

The async def defines a coroutine expression that returns a coroutine object.

A coroutine function can be used to create a coroutine that may be used as the entry point for an asyncio program by passing it to the asyncio.run() function.

A coroutine may also be scheduled and awaited by another coroutine or wrapped in a Task object and scheduled independently.

Now that we know what async def is, let’s look at how we might use it.

How to Use async def

We can use the async def to define a coroutine function.

For example:

This is just like defining a function using the def expression.

For example:

A defined coroutine may take arguments and return values, just like a function.

For example:

Calling the defined coroutine will create a coroutine object.

It does not call the coroutine.

For example:

The coroutine can be executed by using it as the entry point to an asyncio program via the asyncio.run() function.

For example:

A coroutine object may also be scheduled for execution within another coroutine, suspending the execution of the calling coroutine until the called coroutine is done.

This can be achieved with the await expression.

For example:

You can learn more about how to execute a coroutine in the tutorial:

• How to Run an Asyncio Coroutine in Python

Next, let’s consider why we would define a coroutine.

Why use async def

We use async def to define a coroutine.

The async def expression is the way to define custom coroutines for asyncio programs.

Coroutines declared with the async/await syntax is the preferred way of writing asyncio applications.

— Coroutines and Tasks

Coroutines are central to asynchronous programming in Python using the asyncio framework. They are the unit of concurrency.

Additionally, coroutines are the only place we are able to use the await expression to suspend the execution of a coroutine, and one of the few places where we can schedule and run new coroutines and tasks.

Next, let’s consider the definition of coroutines compared to the definition of routines.

async def vs def

The def and async def expressions have a lot in common.

A function (routine or subroutine) is defined using the def expression.

A coroutine is defined in the same way as a function, with the addition of the async modifier. This signals that an asynchronous coroutine has been defined instead of a subroutine.

• def: Defines a subroutine (a function).
• async def: Defines a coroutine (an asynchronous function).

An important difference is that a coroutine can use the await expression, whereas a subroutine cannot.

• def: Cannot use await.
• async def: Can use await.

Another important difference is the effect of calling a coroutine vs a subroutine.

Calling a function will execute that function definition.

The function definition does not execute the function body; this gets executed only when the function is called.

— Python Compound statements

A similar call to a coroutine definition does not execute the coroutine but instead creates a coroutine object that is returned.

Note that simply calling a coroutine will not schedule it to be executed

— Coroutines and Tasks

• def: Calling a defined subroutine will execute it.
• async def: Calling a defined coroutine will create a coroutine object.

Further Reading

This section provides additional resources that you may find helpful.

Python Asyncio Books

• Python Asyncio Mastery, Jason Brownlee (my book!)
• Python Asyncio Jump-Start, Jason Brownlee.
• Python Asyncio Interview Questions, Jason Brownlee.
• Asyncio Module API Cheat Sheet

I also recommend the following books:

• Python Concurrency with asyncio, Matthew Fowler, 2022.
• Using Asyncio in Python, Caleb Hattingh, 2020.
• asyncio Recipes, Mohamed Mustapha Tahrioui, 2019.

Guides

• Python Asyncio: The Complete Guide
• Python Asynchronous Programming

APIs

• asyncio — Asynchronous I/O
• Asyncio Coroutines and Tasks
• Asyncio Streams
• Asyncio Subprocesses
• Asyncio Queues
• Asyncio Synchronization Primitives

References

• Asynchronous I/O, Wikipedia.
• Coroutine, Wikipedia.

Takeaways

You now know asyncio async def expressions in Python.

Do you have any questions?
Ask your questions in the comments below and I will do my best to answer.

Photo by Erik Mclean on Unsplash