Formatting your code
One key insight from the Python programming language is that code is read more often than it is written. Hence, writing code in a fashion that makes it easy to read is something that can only be beneficial.
But formatting code is a nit-picky and tedious matter, isn't it? Moreover, code style is one of those things that are not substantive enough to engage in flame wars. It really is one of those things we should just get over with, right?
Yes, and it is possible to be "just over and done with it" if we use automation tools to help us take care of code formatting so that we don't have to think about it.
black is an opinionated code formatter for the Python programming language.
It comes with sane defaults,
and produces consistently formatted code with a single command at the terminal.
To install it, we can either use
# for pip users pip install black # for conda users conda install black
We can use black directly at the command line in our project directory, with configurations called at the command line for convenience.
# Format all .py files within and underneath current working directory. black -l 79 .
isort is a package for sorting your imports in a source
Once again, this is the sort of thing
you definitely don't want to do by hand.
isort is also conda- and pip-installable.
# pip users pip install isort # conda users conda install isort
Just like with black, we can use
isort to automagically sort our imports.
As an example we will call it at the command line with certain options enabled.
# -r: recurses down below the current working directory. # -y: automatically overwrite original source file with sorted imports. isort -r -y .
Building automation for code formatting
Automatically executing automagic commands is pretty awesome. Let's see how we can enable this.
I also place
black as part of a series of commands used in code style checking
in a Makefile, to run all of those commands together.
format: isort -r -y . black -l 79 .
With that Makefile command, we can now execute all code formatting commands with a single call.
Side note: I usually do
black will make detect
isort-ed code as not properly formatted,
hence I defer to
black to make the final changes.
We can also use pre-commit hooks to catch non-properly-formatted code, and run the code formatters over the code, preventing them from being merged if any formatting has to take place. This ensures thatwe never commit code that is incorrectly formatted.
Getting set up with pre-commit hooks is another topic, but there are already great resources that can be searched for online on how to get setup.
I hope this short essay gives you an overview of the tools that you can use to format your code automatically. Code formatting is important for readability, but isn't worth the tedium. Letting automation save your time is the wise thing to do.
Thank you for reading!
If you enjoyed this essay and would like to receive early-bird access to more, please support me on Patreon! A coffee a month sent my way gets you early access to my essays on a private URL exclusively for my supporters as well as shoutouts on every single essay that I put out.
Also, I have a free monthly newsletter that I use as an outlet to share programming-oriented data science tips and tools. If you'd like to receive it, sign up on TinyLetter!