Hello, Blog!

If you have just stumbled upon my OSD600 series of blog posts, it has been created to document and share my learnings as I progress through my Open Source Development college course.

In today's post, I am going to share how I integrated Black for formatting and Ruff for linting in my python project.

If you want to see the final setup, feel free to check out my project repository here. + I welcome feedback/contributions, so don’t hesitate to dive in and get involved :)

pip install .

Why even use static analysis tools?

Static analysis tools inspect our code ensuring high code quality by fixing the formatting issues and common errors. They help manage the complexities of coding, and enhance consistency (which is especially important in collaborative environments).

Adding code formatting with Black

Black is an "uncompromising code formatter" that adheres to PEP 8 guidelines (style guidelines for Python code). I chose it because of its deterministic nature: maximum consistency with minimum configurations.

Please, read the docs before starting out with the tool!

I have installed Black using pip:

pip install black

I configured Black in the pyproject.toml file located at the root of my repository following the instructions in the config section of the docs. The documentation strongly suggests using the default settings,

so I made only two adjustments: I set the line length to 90 (vs. the default 88) because I tend to prefer slightly longer lines (and also out of my liking for even numbers). Additionally, I excluded the folder containing sample files to limit formatting to the main source code.

# Black - source code formatter configurations
[tool.black]
line-length = 90
# 'extend-exclude' excludes files or directories in addition to the defaults
extend-exclude = '''
    /examples/  # exclude sample test files
'''

I also created a simple python script format.py , to format the entire repository from the project root. Running this script resulted in:

Fortunately, formatting the docs didn’t affect my code’s functionality, as most changes were simply adjustments to line length and converting single quotes (' ') to double quotes (" ").

Adding linting with Ruff

Ruff is an "extremely fast Python linter and code formatter, written in Rust." I chose it as I was intrigued to see its speed in action + I was also drawn to its out-of-the-box compatibility with Black.

I set up the tool by following the official tutorial, referring to other sections of the docs as needed.

I installed Ruff using pip:

pip install ruff

As with Black, I configured Ruff by adding its settings to pyproject.toml. Since I haven’t used Python linting tools before and don’t have any strong preferences, I decided to stick with the default settings, only adding an option to ignore the sample files. (By default, Ruff omits stylistic rules that overlap with Black, ensuring compatibility between the two tools.)

Ruff section of my pyproject.toml:

# Ruff - linting configs
[tool.ruff]
# 'extend-exclude' excludes files or directories in addition to the defaults
extend-exclude = ["examples"]

I completed the initial setup by writing a lint.py script to run Ruff on the entire project with autofix enabled. When I executed the script, it produced only one warning:

How I integrated these tools in VSCode

After adding and configuring the tools, I set up IDE integration for ease of use to enable automatic formatting. I reviewed the IDE integration sections of both tools' docs, downloaded the necessary extensions, and created a settings.json file in the .vscode folder to configure automatic formatting and linting on save. I took the appropriate settings from the Ruff extension for Visual Studio Code README.md, using Black as the formatter and Ruff as the linter.

My settings.json:

{
    "[python]": {
      "editor.formatOnSave": true,
      "editor.codeActionsOnSave": {
        "source.fixAll": "explicit"
      },
      "editor.defaultFormatter": "ms-python.black-formatter"
    }
 }

• Black IDE Integration - Black VSCode extension
• Ruff IDE Integration - Ruff VSCode extension

Afterthoughts

Integrating static analysis tooling into my project has been a positive experience. Although I didn’t previously have the habit of using the formatting & linting tools to maintain code cleanliness, I will definitely do so from now on! The ability to automatically format and lint code on save is a game changer + Ruff’s linting did not disappoint - it is incredibly fast!

Doing the tools' setup was rather straightforward: after carefully reading the documentation, I was able to integrate both Black and Ruff with relative ease. Additionally, I learnt more about the PEP 8 guidelines in the process.