Enforcing Style in a Python Project

A linter and a styler can help you to write cleaner and more consistent code. In this post we’ll look at how to set up both for a Python project.

What are Pre-Commit Hooks?

Git has the ability to execute specific actions when certain events occur. The connections between the actions and the events are known as hooks. These hooks are configured via files in the .git/hooks folder.

Git hooks provide the perfect mechanism for insuring that the code committed to a repository is clean and consistent. We’ll be setting up pre-commit hooks that will run actions immediately before each commit to the Git repository. A commit will only succeed if all of the associated actions are succesful.

The Pre-Commit Framework

Despite the relative simplicity of their implementation, Git hooks can be somewhat fiddly. The pre-commit framework makes it easier to manage and maintain pre-commit hooks. It eliminates a lot of the fiddliness.

The way that the pre-commit framework replaces a collection of distinct hooks with a single hook (the pre-commit hook) and a configuration file. At commit time the pre-commit hook is triggered and it runs all of the actions specified in the configuration file.

Install

Installing the pre-commit framework is simple. You’ll probably want to do this in a virtual environment.

pip install pre-commit

At this point you should also add pre-commit to your project requirements.txt.

Now add pre-commit as a hook.

pre-commit install

This will create a hook file at .git/hooks/pre-commit.

Configure

The actions run by pre-commit are configured via the .pre-commit-config.yaml file. Run the following to generate a simple default configuration.

pre-commit sample-config >.pre-commit-config.yaml

The contents of the configuration file should look something like this:

repos:
-   repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v3.2.0
    hooks:
    -   id: trailing-whitespace
    -   id: end-of-file-fixer
    -   id: check-yaml
    -   id: check-added-large-files

This configuration will run four distinct actions (trailing-whitespace, end-of-file-fixer, check-yaml and check-added-large-files) against each file in the repository.

Test

You can test the configuration by manually running the hooks against all files.

pre-commit run --all-files

If you then run git status you’ll likely find that one or more of the files in your repository has been modified. In my case this generally involves adding empty lines at the end of various files. Take a look at the changes and if you are happy, stage and commit the changes.

Lint

The Flake8 linter is used to check for syntatic problems in Python code. To enable Flake8 add the following to the .pre-commit-config.yaml file.

  - repo: https://github.com/pycqa/flake8
    rev: 5.0.4
    hooks:
      - id: flake8

You might want to check the Flake8 repository to see if there are more recent releases and update the rev field accordingly.

Configuration

You can tweak some Flake8 options by creating a .flake8 file. Its contents might look something like this:

[flake8]
max-line-length = 120
exclude =
    database/__init__.py

A complete list of available options can be found here.

Ignoring Code

You can tell Flake8 to ignore a specific line of code by adding a noqa hint as a comment at the end of the line.

from .database import * # noqa

You can be more specific by telling Flake8 which errors it should ignore.

from .database import * # noqa: F403
from .database import * # noqa: F401, F403

Style

The Black code formatter will enforce a consistent formatting style on Python code. Add the following to the .pre-commit-config.yaml file.

  - repo: https://github.com/psf/black
    rev: 22.8.0
    hooks:
      - id: black

You might want to check the Black repository to see if there are more recent releases and update the rev field accordingly.

Prosper

With this setup in place your code will be checked every time you commit. Many issues will be automatically fixed. Others will be highlighted and you’ll have to manually intervene.

This works particularly well if you are part of a team because it means that everybody on the team will be committing and pushing code without any syntactic issues and with consistent formatting.