Asyncio Coroutine Function and Coroutine Types

You can programmatically identify coroutine functions and coroutines using the inspect module API.

Coroutines have a specific “coroutine” type that shares methods with generators as well as the awaitable interface.

In this tutorial, you will discover coroutine functions and coroutine types in Python.

Let’s get started.

Asyncio Coroutine Types

Modern Python includes changes to the language to support coroutines for asynchronous programming.

This includes a coroutine function type and a coroutine type for creating coroutines.

For example, the typing.Coroutine class.

As such, Python provides tools for inspecting the coroutine type.

For example, the inspect.iscoroutinefunction(), inspect.iscoroutine(), and inspect.isawaitable() functions.

These functions can be helpful to better understand coroutine functions and coroutines themselves in asynchronous programming.

Let’s take a closer look at the coroutine function and coroutine types and how to identify them.

What is the Coroutine Function Type

A coroutine function is a function defined using the “async def” expression.

It is a function that when called will create and return a coroutine.

You can learn more about the async def expression in the tutorial:

• What is Asyncio async def

How to Check The Type of a Coroutine Function

The first check we might perform on a coroutine function is to report its type.

The example below defines a coroutine function, then reports its type directly using the type() built-in function.

Running the example defines the coroutine function and then reports its type.

In this case, we can see that a coroutine function has the type of function, the same as a regular function.

This highlights that the type directly does not provide sufficient information to identify a coroutine function.

Next, let’s look at introspection.

How to Identify a Coroutine Function

Python provides the “inspect” module that contains many tools for introspection.

This includes the inspect.iscoroutinefunction() function that will return true if the provided Python object is a coroutine function, or false otherwise.

Return True if the object is a coroutine function (a function defined with an async def syntax).

— inspect — Inspect live objects

The example below defines both a coroutine function and a regular Python function, then checks each if they are coroutine functions using the introspection function.

Running the example first checks if our custom coroutine function can be identified as a coroutine function.

In this case, it can and the inspect.iscoroutinefunction() function returns True.

Next, the same procedure is tested on the regular Python function, which is correctly identified as not being a coroutine function.

This highlights that we can use the inspection.iscoroutinefunction() function to identify coroutine functions.

Next, let’s look at the coroutine type.

What is the Coroutine Type

Coroutines have a specific object type called “coroutine”.

In this section, we will explore the coroutine type and how to identify a coroutine object programmatically.

you can learn more about coroutines in the tutorial:

• What is a Coroutine in Python

How to Check The Type of a Coroutine

We can report the type of a coroutine.

In the example below, we define a custom coroutine, then create a coroutine object by calling the coroutine function and report its type using the built-in type() function.

Running the example first creates the coroutine, then reports its type.

We can see that indeed coroutine objects have the type “coroutine”.

The example also raises a RuntimeWarning as we never await (execute) the coroutine that we created.

Next, let’s explore how we might identify a coroutine programmatically.

How to Identify a Coroutine

We can identify a coroutine object programmatically.

This can be achieved using the inspect.iscoroutine() function that will return true if the provided Python object is a coroutine, or false otherwise.

Return True if the object is a coroutine created by an async def function.

— inspect — Inspect live objects

A coroutine is awaitable. That is, it can be scheduled for execution in the asyncio runtime using the “await” expression.

Other objects are awaitable that are not coroutine, including asyncio.Future and asyncio.Task. An awaitable object implements the __await__() method.

The “inspect” module also provides the inspect.isawaitable() function to check if a Python object is awaitable.

Return True if the object can be used in await expression.

— inspect — Inspect live objects

The example below creates a coroutine and first confirms that it is a coroutine object and then that it is an awaitable object.

Running the example first creates the coroutine.

It then uses introspection to check if the coroutine object is indeed a coroutine type via the inspect.iscoroutine() function. As expected, the coroutine is correctly identified.

The example then checks if the coroutine is an awaitable via the inspect.isawaitable() function, which is also confirmed.

A warning is raised because we did not explicitly execute the coroutine that we created.

Next, let’s explore the capabilities of a coroutine object.

What are the Methods on a Coroutine

A coroutine object has an API.

Although we never need to explicitly use it.

We can create a coroutine object and then report all of the methods on the object to get a sense of the available API.

The example below creates a coroutine and then reports all of the methods available.

We can see a number of coroutine-specific methods, such as the throw(), close(), and send() that come from the generator heritage.

Coroutines are based on generators internally, thus they share the implementation. Similarly to generator objects, coroutines have throw(), send() and close() methods.

— PEP 492 – Coroutines with async and await syntax

We can also see that the coroutine implements the __await__() method, required by awaitables.

Finally, a warning is raised again because we did not explicitly execute the coroutine that we created.

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 about coroutine functions and coroutine types in Python.

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

Photo by Rowan Heuvel on Unsplash