Black is a really useful code formatting tool maintained by the Python Software Foundation. It reformats files to improve readability.

It can be run in two ways, the first just checks to see if there is any code it would reformat. This is the way we use on all of our CircuitPython repositories. The second way actually reformats the files. This is the way you'll be wanting to use locally.

This page explains how to install and run black, the different ways to run it, and some cases when you may not want to adhere to black's suggestions.

Installing Black

Installing black is super easy. Simply run:

pip install black

pip install black

Note: if you also have a version of python2 installed, you may have to run:

pip3 install black

pip3 install black

Using Black

As I mentioned above, there are two ways to run black. The first way is just checking the code. This is what GitHub actions runs to test commits and pull requests.

This is run by typing in Linux:

black --check --target-version=py35 .

black --check --target-version=py35 .

And for Windows command line (Python 3 must be installed):

python -m black .

python -m black .

You can replace the . with whatever files you want it to check if you don't want it to check every .py file in your current directory.

Here's what that output looks like:

However, most of the time, you're going to want Black to actually reformat the code. This is accomplished by running:

black --target-version=py35 .

black --target-version=py35 .

Here's what running that looks like:

Black isn't always right

Sometimes, Black will make a change that just looks really bad. We've mostly encountered this with longer lists of numbers or short strings. 

For example: Black would make each element of this list have it's own line.

Here's what the list looked like originally:

heatmap_gp = bytes([
    0, 255, 255, 255, # White
    64, 255, 255, 0,  # Yellow
    128, 255, 0, 0,   # Red
    255, 0, 0, 0])    # Black

heatmap_gp = bytes([
    0, 255, 255, 255, # White
    64, 255, 255, 0,  # Yellow
    128, 255, 0, 0,   # Red
    255, 0, 0, 0])    # Black

Here's what the same list looked like after being reformatted by Black:

heatmap_gp = bytes([
	0,
	255,
	255,
	255, # White
	64,
	255,
	255,
	0,  # Yellow
	128,
	255,
	0,
	0,   # Red
	255,
	0,
	0,
	0,
])    # Black

heatmap_gp = bytes([
	0,
	255,
	255,
	255, # White
	64,
	255,
	255,
	0,  # Yellow
	128,
	255,
	0,
	0,   # Red
	255,
	0,
	0,
	0,
])    # Black

You can disable black In that section by adding # fmt: off at the start of the section you don't want Black to reformat and # fmt: on at the end of said section to re-enable it.

Here's how we disabled Black for the list above:

# fmt: off
heatmap_gp = bytes([
    0, 255, 255, 255, # White
    64, 255, 255, 0,  # Yellow
    128, 255, 0, 0,   # Red
    255, 0, 0, 0])    # Black
# fmt: on

# fmt: off
heatmap_gp = bytes([
    0, 255, 255, 255, # White
    64, 255, 255, 0,  # Yellow
    128, 255, 0, 0,   # Red
    255, 0, 0, 0])    # Black
# fmt: on

Lint Black's changes

Make sure that after you run Black, you re-run Pylint. They don't always agree, and their major point of disagreement (Pylint's bad-continuation check) has been dealt with for all of our CircuitPython repositories.

Documentation and Contributing

Check out Black's ReadTheDocs page.

Also, Black's source code is hosted on a public GitHub repository.