It looks so puuurrtyy! 👀

[rating: beginner]

A couple of weeks ago I wrote about the PEP-8 Python style guide. Trying to keep track of all your code & making sure it is style aligned can be overwhelming.

So don’t do that!

Use tools that apply the formatting for you.

Fortunately Python’s formatting tools are very simple to use, and nominally there’s only two of them - isort & black . This means that it’s very easy to integrate them into a developers desktop environment, or into a pipeline run.

What’s the point?

Having uniform code style really does help everyone become familiar with what reading the code should look like. There is a flow state where the code can be skimmed to quickly acquire a sense of what the code is doing, & where to find relevant information. Maintaining code is typically a combination of this flow state - quickly acquiring information & then slowing down to think carefully about specific sections.

Code that is inconsistent in style breaks that flow & forces the reader to think consciously & slowly about all of it, instead of just some of it.

The cognitive load of trying to maintain consistent style is really high, & cognitive load is the development killer. So using tools to take care of style formatting is important.

How does it work?

Because black isn’t so picky about organization & formatting of import statements, I always recommend using the isort tool as well.

And herein lie some of the subtleties. You know, There be Dragons & all that.

Not all that complicated once you know about them. But important to know, to avoid annoying errors.

With default settings, isort & black will compete over import statement formatting. Overwriting changes of the other. So the order & configuration options of the tools becomes important.

Here’s my recommendation:

# on desktop to actually *apply* formatting changes before commit/push
isort \\
  --profile black \\
  build_harness/ \\
  src/
black \\
  build_harness/ \\
  src/

# in a pipeline to *check* if formatting changes are needed
# note the `--check` option for each command.
isort \\
  --check \\
  --profile black \\
  build_harness/ \\
  src/
black \\
  --check \\
  build_harness/ \\
  src/

• Use isort first because its changes are not as extensive as black , plus it has an option to better accommodate black . black does not have a similar option to support isort .

• Use the tools with as little customization as possible. Customization is simply a maintenance issue to be avoided. Someone will forget to replicate custom configuraiton accurately between projects, or simply decide they don’t like one of them, or add their own.

• For pipeline automation, only check if formatting is needed. The pipeline fails if it is because this means the developer needs to make a change.

Finally, thinking ahead a little to using static analysis tools:

• Always apply formatting before static analysis as some of these tools also check formatting

• The static analysis tool flake8 support plugins & has one for black. The flake8-black plugin applies different formatting than default black & they interfere with each. So I recommend using either black or flake8-black , not both. And preferably black , not the plugin.

References

https://pycqa.github.io/isort/

https://black.readthedocs.io/en/stable/index.html

I'm Russell 🐿️. A long time engineer discovering new life as a first-time solopreneur.

I build software delivery systems using Docker & Python automation that increase speed & reduce errors - saving money & improving profitability.