Chapter 1: Introduction to Ruff

In a previous article, I introduced Ruff, a novel Python code formatter developed from the ground up in Rust. Since then, I have been migrating some of our production projects to Ruff. Previously, we utilized Black as our main code formatter and Flake8 as our primary linter across most projects. Although both tools have served us well, I believe there’s always room for improvement.

Why consider a migration? I dislike the notion of complacency. Just because something functions adequately doesn’t imply it cannot be enhanced. My goal with this transition is to replace two separate tools with one, thereby simplifying configuration and improving performance. As this migration poses no risks to our product delivery, it provides us the flexibility to move forward.

In this article, I will detail the migration process, so by the conclusion, you should be well-versed in:

• Understanding Flake8 and its usage
• Steps to transition to Ruff

If you're interested in learning more about Black, please refer to my prior article.

Code Complexity with Flake8

Flake8 identifies complex sections of your code, enabling you to address potential issues before they escalate. It leverages McCabe, a tool named after Thomas J. McCabe, Sr., to measure code complexity using Cyclomatic complexity.

To install McCabe, execute the following command in your virtual environment:

pip install mccabe

For example, consider the following code:

# complex_code.py

def foo():

numbers = list(range(10))

if len(numbers) == 0:

...

elif numbers[1] == 1:

...

elif numbers[-1] == 9:

...

elif isinstance(numbers, list):

...

else:

...

This code may be deemed complex due to its numerous chained conditions. You can check its complexity using:

python -m mccabe complex_code.py

The output will indicate the complexity level.

To enforce complexity thresholds, Flake8 can be used as follows:

flake8 --max-complexity 4 complex_code.py

If configured correctly, this command will flag errors when the complexity exceeds your set limits.

Checking for Code Errors

Flake8 also wraps Pyflakes to analyze your code for errors, such as:

• Import Issues: Detects unused imports.
• Undefined Variables: Identifies references to variables that may not have been defined.
• Unused Variables: Flags variables that are declared but never utilized.

For example, running Pyflakes on the following code:

# foo.py

import os

def foo():

print("os imported but never used")

Will yield:

python -m pyflakes foo.py

This will highlight that 'os' was imported but not used.

Linting Issues with Flake8

Flake8 also incorporates Pycodestyle, which checks code against PEP 8 style guidelines. To install Pycodestyle, use:

pip install pycodestyle

Running Pycodestyle against the following code will reveal style violations:

# foo.py

def foo():

print("Unecessary space above this print.")

This demonstrates excessive whitespace which violates PEP 8 conventions.

Now, let’s see how we can achieve similar results using Ruff.

Chapter 2: Transitioning to Ruff

Ruff is designed to function as a drop-in replacement for both Black and Flake8, promising significantly faster execution of tasks. To get started, ensure Ruff is installed in your virtual environment:

pip install ruff

There are two key components to consider: the linter and the formatter. The formatter is the one we discussed earlier, where Ruff can replace Black as your Python code formatter. The Ruff Linter serves as a direct substitute for Flake8.

Let’s run Ruff on the same code snippet we previously analyzed with Flake8:

# foo_bar_ruff.py

def foo():

...

To execute the Ruff linter, use:

ruff check foo_bar_ruff.py

This will produce output regarding any errors detected.

For fixing issues reported by Ruff, you can run:

ruff check --fix foo_bar_ruff.py

Configuring Ruff

The recommended approach for configuring Ruff is to create a configuration file in your project directory, typically named ruff.toml or pyproject.toml. I prefer ruff.toml for its straightforward configuration style. Here’s a basic setup:

# ruff.toml

target-version = "py312"

exclude = []

[lint]

[format]

#### Exclude Section

This section acts similarly to a .gitignore file where you specify items you don’t want Ruff to track. For example:

exclude = [".venv", "venv", "__pypackages__", "build"]

#### Lint Section

Migrating from Flake8 to Ruff is relatively straightforward. You can copy your linting rules directly into Ruff’s configuration. For example:

[lint]

select = ["E", "F"]

fixable = ["ALL"]

Where E corresponds to Pycodestyle and F relates to Pyflakes.

To manage code complexity, you can include the following configuration:

[lint.mccabe]

max-complexity = 5

#### Format Section

You can also specify formatting styles in the ruff.toml file:

[format]

quote-style = "double"

indent-style = "space"

With these configurations in place, you're ready to run Ruff commands to lint and format your code.

Final Thoughts

Ruff presents an exciting opportunity to streamline your Python development workflow. You can even enable import sorting similar to isort by adding to your linting rules:

[lint]

select = ["E", "F", "I"]

fixable = ["ALL"]

As I continue the migration process, I can confidently say that Ruff is a tool with immense potential, even though it is still in its early stages. In my next article, I will explore how to enhance your configurations further using Makefile in Python to orchestrate multiple commands seamlessly.

After reading this, do you believe migrating to Ruff is worthwhile? If you enjoyed this article, stay tuned for more insights on this topic and others related to Python development.