How to use Black and pre-commit for auto text-formatting on commit [setup] [python]

Hello👋.

Today we are going to look at how to setup Black (a python code formatter) and pre-commit (a package for handling git hooks in python) to automatically format you code on commit.

All the Code used in this article can be found on this GitHub repo here

Benefits

Setting up your project with this (automatic code formatting on every commit) can be very useful and helpful especially when setting up a GitHub repository you expect other contributors. This enforces coding formatting and fosters consistency in coding style.

Let's get right to it

• Installing Black and pre-commit

First of all, we need to install these packages to our projects. You can use the following command to install them:

pip install black pre-commit

You might also need to add these packages to your requirements.txt file so other contributors can install the need packages by running pip install -r requirements.txt. You can do this by running pip freeze, and the coping the output to your requirements.txt file.

• Configure pre-commit

The next step is configuring pre-commit. To do this, create a file called .pre-commit-config.yaml:

touch .pre-commit-config.yaml

Then copy the following configurations to this file.

repos:
  - repo: https://github.com/psf/black
    rev: 22.3.0
    hooks:
      - id: black
        args: [--line-length=88]
        language_version: python3.11

This tells Pre-Commit to use Black version 22.3.0 and format all Python files with a line length of 88 characters (you can adjust this to your preference).

• Run pre-commit

Now we have our configurations ready, make sure that the current folder you are in is a git/github project (With the .git folder)
Now, run the following command:

pre-commit install

This installs pre-commit hooks to .git\hooks\pre-commit.

Note: you need an internet commit for the first commit you make. This is to enable pre-commit initialize the environment for black, but once the environment is setup, it'd be reused.

$ git commit -m "add pre-commit configuration"
[INFO] Initializing environment for https://github.com/psf/black.      
[INFO] Installing environment for https://github.com/psf/black.        
[INFO] Once installed this environment will be reused.
[INFO] This may take a few minutes...
black................................................(no files to check)Skipped
[main 6e21eab] add pre-commit configuration
 1 file changed, 7 insertions(+)

That's it, you are ready to use the automatic code formatter. Just create a python file, run git add ., and then run git commit -m "Commit message". You'd notice that black attempts to format the file you just created. If you get the following message:

black....................................................................Failed
- hook id: black
- files were modified by this hook

reformatted test.py

All done! \u2728 \U0001f370 \u2728
1 file reformatted.

Just run git add and git commit again.

Enjoy autoformatted code from now on😅. Bye👋

Comments

[rrakso]

Can I use my black settings from pyproject.toml?

Update:
I found that black is searching for the pyproject.toml at the project root.

That means that we can have formatting set like this:

(Content of the pyproject.toml)

# Could be helpful for someone: https://dev.to/adamlombard/vscode-setting-line-lengths-in-the-black-python-code-formatter-1g62
[tool.black]
line-length = 120