The Essential Python Auto Code Formatting Guide
Set them up just once and write and auto-format your code upon commits - hassle-free with these tools
👋 Welcome
A warm welcome to the 6 new subscribers joining us this week.
Let me know what you think of this post in a comment, if it’s no trouble. If you prefer Twitter, drop me a DM.
Now, let’s get started with this issue.
This is a detailed post I published on my blog a while back, but never shared it with my subscribers. I hope you enjoy it.
The Essential Python Auto Code Formatting Guide
The easy to read and understand syntax of Python has made it the most popular programming language today — and with good reason. The wide variety of use-cases of Python are so diverse that software engineering, machine learning, and data science with all of having varying and complex usages for it.
One of the most overlooked yet essential areas in writing clean Python code include the murky waters of the need for good formatting and code checks.
Suffice to say, in this day of automation in every aspect of life, this particular step in code reviews can also easily be done without too much manual effort.
There are a few tools that help you save some precious time and mental energy for more important matters than formatting your code each time before a git commit.
Here are some of them:
pre-commit hooks,
black
isort
Let’s go over and learn how to set them up for a Python project, one by one.
Installing and using pre-commit hooks
The pre-commit hooks do exactly as it says on the tin — they run certain scripts that check your code against errors, trailing whitespaced, run some formatting tools, and many other useful checks in a code review process.
For us, we will go through two important hooks excluding some of the usual ones.
Let’s install the library first (I am assuming you’re using a virtual environment already):
pip install pre-commit
Check the version after installing with this and it should output the version for you as a sanity check:
$ pre-commit --version
pre-commit 2.17.0
Here’s the thing: in order to go with the easy way to set up auto-formatting tools, you need a particular git configuration file in your root project directory.
Let’s go make that now.
Setting up the config file
According to the docs, we need a pre-commit config file by the name of “.pre-commit-config.yaml
” in our project.
After making that, let’s introduce the code snippet that informs us of the hooks we want to include. The two hooks we want right now are to run: black and isort on our python files before each and every commit.
This is their setup:
repos:
- repo: https://github.com/pre-commit/pre-commit-hooks
rev: v2.3.0
hooks:
- id: check-yaml
- id: end-of-file-fixer
- id: trailing-whitespace
- repo: https://github.com/psf/black
rev: 21.12b0
hooks:
- id: black
- repo: https://github.com/pycqa/isort
rev: 5.10.1
hooks:
- id: isort
name: isort (python)
So, let’s look at these
lines individually:
lines 5–7: the first three
id
lines do this: the first one attempts to load all yaml files to verify their syntaxes, the next one makes sure files end in a newline and only a single newline, and the final one checks for trailing whitespaces.lines 8–10: This is the hook setup for
black
. It auto-formats your Python code and its usage is now very common in the whole industry.lines 12–16: This is the hook setup for
isort
which is a library for auto-sorting imports in our code so we don’t have to do them manually.
Now, to attach them to our git configuration to have them run everytime before a commit, we run one more command:
$ pre-commit install
pre-commit installed at .git/hooks/pre-commit
And with this done, we have successfully come to the end of setting up the pre-commit hooks for our project! Very simple so far, right?
Let’s go setup black
and isort
now! Fortunately for us, this is possible with just a single config file.
Installing and setting up black and isort
Installing these two libraries is also very simple:
pip install black isort
Black defines its usage as: (from its wonderfully written docs):
Black makes code review faster by producing the smallest diffs possible. Blackened code looks the same regardless of the project you’re reading. Formatting becomes transparent after a while and you can focus on the content instead.
isort also defines its usage simply as:
isort is a Python utility / library to sort imports alphabetically, and automatically separated into sections and by type.
Here’s the only file we need to make for their setup: a pyproject.toml
file.
This the content we want to put in there:
[tool.black]
line-length = 109
target-version = ['py37']
[tool.isort]
profile = "black"
Of course, the line-length is changeable according to your own or your work preferences, as are many other configurable variables offered by black.
Why do we explicitly use this particular file, you may ask? Here’s the reason provided:
PEP 518 defines
pyproject.toml
as a configuration file to store build system requirements for Python projects.
So essentially in practise, this file in the root directory of your project lets you use a “global” code check/revision configuration for your whole project.
Let’s move on to testing them out then!
Testing our pre-commit hooks
When you’ve written or edited some code in a few files, go ahead and follow this simple process to test out that our attached hooks work as expected.
First, we need to add the files with our git add .
in the terminal, or whatever combination of files you want to add.
I am testing this out in one of my existing Django projects.
Now, let’s run git commit -m “a message here”
. You will see something like this:
So this means that our files have been modified by the formatting done by the pre-commit hook.
When you run the command git status
now, you’ll see something like this:
So views.py
file has some lines modified by the hooks executed. Go ahead and look them over.
This makes sure to not auto-commit your modified files and lets you look them over once to make sure all changes are good.
As an intentional step, pre-commit will never modify the staging area of our versioned code. Since any hook we run can be buggy and undoing that is a huge pain after the commits, we get an additional chance to look over and see if everything is alright.
Now, let’s go ahead and add and commit our files again:
git add .
git commit -m "your message here"
You’ll see an output like this now:
This is great! We have successfully committed our code with the applied changes!
A few parting words and some references
I hope this quick tutorial was a good introduction to using pre-commit hooks for auto-formatting your code easily and without manual intervention.
Here are some of the resources I’ve used and I also recommend you to read for more information on everything I’ve mentioned in this article:
Thank you for reading! Find me on Twitter. :)
If you found some value in this article, why not share it with your friends too?