You can identify common problems in asyncio programs using popular Python static analysis tools such as pylint and flake8.

In this tutorial, you will discover how to lint python code for common asyncio problems.

Let’s get started.

What is Lint or Linting?

Linting refers to tools for performing a static analysis check of code.

Lint is the computer science term for a static code analysis tool used to flag programming errors, bugs, stylistic errors and suspicious constructs.

— Lint (software), Wikipedia.

It is a helpful check of Python code to check for common programming errors that can be performed regularly and automatically, such as each time new code is committed as part of a continuous integration system.

In computer science, static program analysis (or static analysis) is the analysis of computer programs performed without executing them …

— Static program analysis, Wikipedia.

Linting Python code involves using a tool (a linter) to analyze and check the source code for adherence to coding standards, style guidelines, and potential programming errors. Linting tools review the code without executing it, highlighting issues such as syntax errors, coding style violations, and potential bugs.

Linting is essential for several reasons:

1. Consistency: Linting enforces coding standards and style guidelines, ensuring that code across a project or team follows a consistent and readable format. This improves code maintainability and readability.
2. Error Prevention: Linters identify potential bugs, such as syntax errors, undefined variables, and other common mistakes. By catching these issues early in the development process, developers can prevent runtime errors and improve code reliability.
3. Coding Standards: Linters enforce coding standards and best practices. They help developers write code that is in line with community-accepted conventions, which makes it easier for others to understand and contribute to the codebase.

Linting Python code is a vital practice that promotes code consistency, identifies potential errors, enforces coding standards and style guidelines, and ultimately leads to more readable, reliable, and maintainable code.

Next, let’s consider linting asyncio programs.

Need to Lint For Common Asyncio Errors

We can use static analysis to check for common errors in asyncio programs.

There are three common errors that we may see in an asyncio program, they are:

1. Never retrieved exceptions.
2. Never awaited coroutine.
3. Calls that block the event loop.

Generally, these are runtime errors.

The first two, never retrieved exceptions and never awaited coroutines typically result in a RuntimeWarning, and therefore are often easy to identify and repair.

For example, you can learn more about never-retrieved exceptions in the tutorial:

• Log All Silent Exceptions in Asyncio

You can learn more about never-awaited coroutines in the tutorial:

• RuntimeWarning: Coroutine Was Never Awaited

The last error does not result in a runtime warning, but we may be able to identify examples of calls that block the event loop using static analysis.

There are also other errors that we may be able to identify. These are errors that are also likely to result in a syntax error, causing the program to fail to execute.

Such as:

• Using an await expression outside of a coroutine.
• Using an async context manager outside of a coroutine.
• Using an async generator outside of a coroutine.

Next, let’s explore how we might lint our asyncio programs.

How to Lint Asyncio Programs

Perhaps two of the most common Python linters are:

1. Pylint
2. Flake8

Let’s take a closer look at asyncio support for each.

How to Use Pylint For Asyncio Programs

Pylint is a popular and simple-to-use static analysis tool for Python.

Pylint analyses your code without actually running it. It checks for errors, enforces a coding standard, looks for code smells, and can make suggestions about how the code could be refactored.

— Pylint, GitHub.

We can install Pylint using our favorite Python package manager, such as pip.

For example:

We can then apply pylint to a project or a file by invoking it directly.

For example:

It will then identify issues identified with the program.

By default, pylint can identify three types of errors in asyncio programs, they are:

• await-outside-async / E1142
• not-async-context-manager / E1701
• yield-inside-async-function / E1700

These are reasonable, but I would argue that running the program will cause a syntax error and identify these issues for us.

Helpfully, there is a plugin for pylint called “pylint-blocking-calls” that can be used to identify blocking calls made in the event loop.

This is a pylint plugin that checks for blocking calls in your async python code.

— Pylint Blocking Calls Checker, GitHub.

We can install this plugin using our favorite package manager, such as pip.

For example:

Using the plugin is cumbersome.

We must define a variable named BLOCKING_FUNCTION_NAMES that specifies all of the locking functions to look for.

This can be achieved using an environment variable or programmatically.

For example:

We then must start pylint and specify to load the plugin via the flag:

A call to check a program for calls to the time.sleep() blocking function may look like:

It might be helpful if someone comes along and defines a long list of offending blocking calls in the standard library.

How to Use Flake8 For Asyncio Programs

Flake8 is another widely used static analysis tool for Python.

flake8 is a python tool that glues together pycodestyle, pyflakes, mccabe, and third-party plugins to check the style and quality of some python code.

— flake8, GitHub.

Many other tools build on top of the flake8 ecosystem (the rules specifically), such as the popular ruff linter.

We can install Flake8 using our favorite Python package manager, such as pip.

For example:

We can then apply flake8 to a project or a file by invoking it directly.

For example:

It will then identify issues identified with the program.

By default, it does not appear that flake8 has rules to identify problems specific to asyncio programs.

Nevertheless, there is a plugin named flake8-async that we can install that provides async-specific rules.

A flake8 plugin that checks for bad async / asyncio practices.

— flake8-async, GitHub.

We can install the plugin using our favorite package manager, such as pip.

For example:

The plugin provides 3 asyncio rules, they are:

• ASYNC100: Warning about the use of a blocking http call inside an async def
• ASYNC101: Warning about the use of open, time.sleep or methods in subprocess, inside an async def.
• ASYNC102: Warning about the use of unsafe methods in os inside an async def.

Using flake8 with the plugin on an asyncio program is straightforward.

For example:

It will report all issues, including asyncio rules directly.

Now that we know how to lint Python code for asyncio issues, let’s look at some worked examples.

Examples of Pylint for Asyncio Code

In this section, we will explore some common errors in asyncio programs that can be identified automatically via pylint.

Specifically, we will at an example of :

1. Pylint reporting on the use of an “await” expression outside of a coroutine.
2. Pylint reporting on a blocking call made in the event loop.

Pylint Async Outside of Coroutine

We can develop a simple asyncio program that uses the await expression outside of a coroutine.

In this example, the program will define a task that sleeps for a moment, runs this task in the background, sleeps in the main coroutine, and then reports a done message.

The error will be that we will forget to define the work() task as a coroutine. Instead, we will define it as a Python function.

This will cause the program to not run with a syntax error, but it is also an error we can detect before running via pylint.

Firstly, we can define the work() task that awaits a call to sleep but is not defined as a coroutine.

Note, this should be defined using the “async def” expression:

Next, we can define the main() coroutine that will report a message, run the work() task in the background, sleep a moment, and then report a done message.

Finally, we can start the event loop.

Tying this together, the complete example is listed below.

Running the program results in a syntax error.

Now we can lint the program using pylint.

This results in one issue reported.

Specifically, we have used an “await” expression outside of a coroutine, in this case, our work() function.

This highlights how we can detect syntax errors in asyncio programs using pylint.

Next, let’s look at how we might detect a blocking call in an asyncio program using pylint.

Pylint Event Loop Blocking Call

We can explore an example of pylint identifying a call that blocks the asyncio event loop.

In this case, we will define a coroutine that calls the time.sleep() function.

This will block the event loop for the duration of the sleep, a bad practice.

We can identify this issue using the pylint_blocking_calls pylint plugin and explicitly check for calls to the time.sleep() function.

We can define the work() coroutine that will make the call to time.sleep().

The complete example is listed below.

Running the program results in a normal execution with two messages reported.

We can now call pylint with the plugin and check for calls to time.sleep within coroutines.

This results in one issue identified, specifically that the time.sleep() blocking call was made within a coroutine.

This highlights how we can explicitly identify blocking calls in coroutines, although we must know what the blocking calls will be beforehand so that we can search for them.

Next, let’s look at examples of linting with flake8.

Examples of Flake8 for Asyncio Code

In this section, we will explore some common errors in asyncio programs that can be identified automatically via Flake8.

Specifically, we will at an example of:

1. Flake8 reporting on opening a file in a coroutine.
2. Flake8 reporting on a blocking call made in the event loop.

Flake8 Opening File in Coroutine

We can explore an example of flake8 identifying an issue with opening a file within a coroutine.

In this case, we can use the open() built-in function that is a blocking call and create a new file. Checking this file with flake8 will identify an issue.

We would prefer to perform blocking file I/O tasks in a separate worker thread that can be awaited.

Firstly, we can define a main() coroutine that opens the file and reports a done message.

We can then start the event loop and run the coroutine.

Tying this together, the complete example is listed below.

Running the program runs normally, creating the file and reporting a done message.

Now we can check the program using flake8 with the plugin installed.

This identifies one issue specifically the blocking file I/O operation is being performed in a coroutine.

This highlights how we can automatically discover and report on file IO tasks in asyncio programs.

Next, let’s look at an example of an explicit blocking call in a coroutine.

Flake8 Event Loop Blocking Call

We can explore an example of Flake8 identifying a call that blocks the asyncio event loop.

In this case, we will define a coroutine that calls the time.sleep() function.

This will block the event loop for the duration of the sleep, a bad practice.

We can identify this issue using the pylint_blocking_calls Flake8 plugin and explicitly check for calls to the time.sleep() function.

We can define the work() coroutine that will make the call to time.sleep().

The complete example is listed below.

Running the program results in a normal execution with two messages reported.

We can now call Flake8 with the plugin installed.

This results in one issue identified, specifically the time.sleep() blocking call was made within a coroutine.

This highlights how we can explicitly identify blocking calls in coroutines using Flake8.

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 how to lint Python code for common asyncio problems.

Did I make a mistake? See a typo?
I’m a simple humble human. Correct me, please!

Do you have any additional tips?
I’d love to hear about them!

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

Photo by Luke Bender on Unsplash