Mastering Python Linters: A Guide for Developers

The article “Mastering Python Linters: A Guide for Developers” first appeared on AlgoTrading101 blog.

What are Python linters?

Python linters are tools for developers that do automated code analysis. They play a crucial role in improving code quality by scanning Python code to identify syntax errors, stylistic issues, and complex constructs that deviate from best coding practices.

What types of Python linters exist?

Types of Python linters can be categorized into two groups which are Code formatting and style and Error Detection.

The first group checks if the code adheres to the stylistic guidelines, such as PEP 8, which is the style guide for Python code. This includes checking indentation, line spacing, and the use of variables and function names.

The second group uncovers potential errors before the code is executed. They pinpoint issues like undeclared variables, possible syntax errors, and other inconsistencies that could lead to bugs.

Sometimes, some linters fall into both groups and we will cover them in this article.

Why should I use Python Linters?

• Python linters make your code cleaner.
• Make your code easier to maintain and read.
• Spot bugs and errors in your code in time.
• Allow for a better collaboration experience.
• It makes you more productive.
• It teaches you to write better code.

Why shouldn’t I use Python Linters?

• Python linters can slow down prototyping and fast iterating.
• Over-reliance leads to a false sense of security.
• Can bring much overhead on small and simple projects.
• Can have a higher learning curve for Python beginners.

How to get started with Python linters?

To get started with Python linters, all you need to do is to install them via pip and configure them if needed. Most linters prefer pure Python files (e.g. ruff) while others can also style your notebooks (e.g. black).

The linters that we will take a look at are the linters I personally use for all my projects which are the following:

• Black
• Pylint
• Ruff
• MyPy
• Bandit
• PyDocstyle

We will look into each one of them and I’ll show you how to work with them. Then, we’ll combine them together into a pre-commit hook that will check all of our files and stop the commit if we have linting errors.

Black Python Linter: What Is It and How Can It Transform Your Code?

Black is a Python code formatter known for its uncompromising approach to code styling. It prioritizes consistency and determinism in code formatting for a uniform style. It aims for simplicity and minimization of diff sizes.

Link to repository: https://github.com/psf/black

How to install Black?

To install Black, all you need to do is write:

pip install black

If you want black to work with your notebook files, you can additionally write:

pip install "black[jupyter]"

How to use Black

Using Black is as simple as running a single command. To format a single Python file:

black your_script.py

To format a directory, you can do:

black my_dir

To format all files at your current location do:

black .

For example, here is a small code block before Black is applied:

def my_function(arg1,arg2):
    print( "arg1:",arg1,"arg2:",arg2)

Here is the after:

def my_function(arg1, arg2):
    print("arg1:", arg1, "arg2:", arg2)

How to configure Black?

Black aims to be an opinionated formatter, so configuration options are minimal. However, you can configure line length (default is 88 characters) and exclude specific files. For example, to set a line length of 100 characters:

black your_script.py -l 100

To exclude a directory or a file, use the --exclude parameter. Here’s how to exclude a directory named migrations:

black your_directory --exclude='/migrations/'

Configuration can also be specified in a pyproject.toml file, which Black will automatically detect and use. For example:

[tool.black]
line-length = 100
exclude = '''
/(
    migrations
)/
'''

The code block above combines the two configuration options we ran manually. This way, you can run black without the need to pass extra arguments.

Pylint Python Linter: Why Is It a Game-Changer for Python Developers?

Pylint is a versatile Python linter for static code analysis. It checks Python code against a wide range of programming standards, highlights errors, and enforces a more explicit coding standard.

It offers detailed reports on code quality, potentially problematic areas, code duplication, styling issues, and more. It is quite customizable and supports plugins.

Link to repository: https://github.com/pylint-dev/pylint

How to install Pylint?

Installing Pylint is straightforward and can be done using pip:

pip install pylint

How to use Pylint?

To use Pylint, simply run it against a Python file or a module. For example, to lint a single file:

pylint your_script.py

For linting an entire Python package:

pylint your_package/

Pylint will analyze the code and output a report detailing various issues, categorized by their nature (e.g., errors, warnings, refactor suggestions).

Here is an example code block before abiding by Pylint:

class my_class:
    def func1(self):
        pass

    def anotherFunction(self, arg1):
        self.myvar = arg1
        print(arg1)

obj = my_class()
obj.func1()
obj.anotherFunction(10)

Here is the code block after cleaning out Pylint errors:

class MyClass:
    """Example class demonstrating Pylint improvements."""

    def __init__(self):
        """Initialize the class."""
        self.my_var = None

    def function_one(self):
        """Example method that does nothing."""
        # Previously had 'pass', removed as it's unnecessary here.

    def another_function(self, arg1):
        """Print the provided argument.

        Args:
            arg1 (int): The argument to be printed.
        """
        self.my_var = arg1
        print(arg1)

obj = MyClass()
obj.function_one()
obj.another_function(10)

Sometimes, Pylint might be wrong in its interpretation. In that case, you can ignore specific Pylint errors either in your entire file, specific line, specific function/class, or more.

For instance, if you want to ignore a particular warning, say line-too-long (C0301), on a specific line, you can do the following:

some_really_long_line = '...'  # pylint: disable=line-too-long

You can also just write the code of the error but that makes your ignored error less explicit. To disable a warning for an entire file, add a comment at the top of the file:

# pylint: disable=line-too-long

How to configure Pylint?

Pylint is highly customizable. You can configure it by creating a .pylintrc file in your project’s root directory. Here’s a simple example of a .pylintrc file:

[MASTER]
disable=
    C0111, # missing-docstring
    C0103  # invalid-name

[MESSAGES CONTROL]
max-line-length=100

Visit AlgoTrading101 blog to read the full article.