Auto-fixing annoyances with Black and Pylint

In the previous post, we discussed using Visual Studio Code to enhance Python editing with various features, such syntax highlighting and keyboard shortcuts. This post introduces the tools Pylint and Black for automatically resolving Python code-style problems.

If you’re new to Python, these two pieces of code might seem a bit contrived, but otherwise functional:

However, an experienced Python developer will have a hard time reading it and will find one bug. Luckily, there are tools to give you this same insight!

Auto-formatting with Black

Every Pythonista, left to their own devices, will come up with their own conventions and implement them with copious manual insertion of whitespace. This is tedious as an individual, but disastrous when collaborating with others as formatting preferences clash. Consistent formatting is essential for enabling readers/reviewers to focus on logic, instead of being distracted style.

Luckily, most programming languages have an auto-formatter which inserts the appropriate whitespace in your code. For Python, this is Black.

Black takes awkwardly formatted (but still runnable!) code:

And gives you code with sensible whitespace:

Black also automatically breaks up long or nested lines of code into multiple lines.

You may find Black clashes with the conventions you’ve developed over the years. You will have to get over it. Black is purposely not configurable. If arguing about code style is the most futile conversation one can have, discussing an auto-formatter’s configuration is a close second. Instead, I recommend spending time developing opinions on other matters, such as music or pizza toppings.

Integrating Black with Visual Studio Code

Visual Studio Code’s can be found under File -> Preferences -> Settings. In the top-right corner, there should be an icon to Open Settings (JSON). You should see something that looks like a Python dictionary, but with curly braces:

{
    "editor.formatOnSave": true,
    "editor.renderWhitespace": "all",
    "files.autoSave": "afterDelay",
    "python.analysis.typeCheckingMode": "basic",
    "python.formatting.provider": "black",
    "python.formatting.blackArgs": [
        "--line-length=120"
    ],
}

Although I do personally recommend all of these settings, the most important one is “python.formatting.provider”: “black”, which will allow you to run black with the keyboard shortcut CTRL+SHIFT+I.

Auto-check with Pylint

Python is a big, old language. There are many ways to do things. Some of them are very wrong. Finding out which ones are wrong and why usually involves someone more experienced than you reading over your code.

However, many common mistakes can be detected automatically with Pylint.

For example, if you want to pass a list as a default argument to a function, you may write something like this:

This is a common mistake in Python. If you run Pylint from the command-line:

pylint bad_code.py

It will warn you:

Dangerous default value [] as argument (dangerous-default-value)

Which allows you to implement the following fix:

Pylint has many such code problems it can check for. Some of them are more annoying than helpful, but Pylint lets you ignore many of them.

Here’s an extremely conservative list of ones I ignore, based on my years of working with Python, pastable into your pyproject.toml at the root of your project. Alternatively, you can slowly add to your own list every time you get annoyed.

Integrating Pylint with Visual Studio Code

Linting is turned on by default in Visual Studio Code. Additionally, if you have a pyproject.toml file in the root directory of the project you're working on, it will be detected and use by Pylint automatically, so there's no configuration required.

This post continued on the theme of using tools to make good coding habits painless and automatic. You can learn to do consistent formatting and avoid Python’s pitfalls with hard-earned experience, but using Pylint and Black is so much easier! In addition to reducing individual suffering, these tools allow collaborators of various skill levels to reach a baseline of quality. Similarly, the next post in the series will cover automatically detecting accidental code breakage with Pytest.