How to Use the "async def" Expression in Python

November 1, 2022 Python Asyncio

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:

# define a coroutine
async def custom_coroutine():
	# ...

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

For example:

# define a function
def custom_coroutine():
	# ...

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

For example:

# define a coroutine with arguments and a return value
async def custom_coroutine(arg1, arg2, arg3):
	# ...
	return 100

Calling the defined coroutine will create a coroutine object.

It does not call the coroutine.

For example:

# create a coroutine
coro = custom_coroutine()

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

For example:

...
# create a coroutine
coro = custom_coroutine()
# execute a coroutine program
asyncio.run(coro)

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:

...
# create a coroutine
coro = custom_coroutine()
# schedule coroutine and wait for it to be done
await coro

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.

Takeaways

You now know asyncio async def expressions in Python.

If you enjoyed this tutorial, you will love my book: Python Asyncio Jump-Start. It covers everything you need to master the topic with hands-on examples and clear explanations.