What is Black

Black is an opinionated code formatter for Python. It automatically reformats your code to make it consistent and readable, adhering to the PEP 8 style guide with some deviations.

For example, suppose you have the following code:

#comment
'''
hello world
'''

a = [1, 2, 3,      4,
5]
print(a)

After applying Black, the code is formatted as follows:

# comment
"""
hello world
"""

a = [1, 2, 3, 4, 5]
print(a)

Black is called "The Uncompromising Code Formatter" because it doesn’t allow much configurability regarding the formatting rules; it has a style, and it sticks to it. The tradeoff, however, is that when you use Black, you don’t need to spend time tweaking the formatting style.

Installation

Installing Black is a simple process, and can be done through pip, which is Python’s package manager. If you have Python 3.6 or newer, installation is as easy as running this command:

$ pip install black

Using Black for Code Formatting

I will explain how to use Black to format Python code. I will cover how to format a single file, an entire project, and how to make exceptions for specific files or directories.

Formatting a Python File

Formatting a single Python file with Black is simple. After you have installed Black, navigate to the directory where your Python file is located, and run the following command:

$ black myfile.py

Replace myfile.py with the name of your Python file. Black will automatically reformat your file according to its style rules.

reformatted myfile.py
All done! ✨ 🍰 ✨

Formatting a Project

If you are working on a larger project with multiple Python files, you might want to format all of them at once. To do this, navigate to the root directory of your project and run the Black command followed by a period:

$ black .

This tells Black to reformat all Python files in the current directory and its subdirectories.

Customizing Line Length

By default, Black formats code with a maximum line length of 88 characters. However, you might have a different preference or project requirement. Black allows you to set a custom line length using the --line-length option.

For instance, if you want to set a maximum line length of 100 characters, use the following command:

$ black --line-length 100 myfile.py

Similarly, you can apply this option when formatting an entire project:

$ black --line-length 100 .

Ignoring Specific Files or Directories

In some cases, you might not want Black to format certain files or directories. You can use the --exclude option when running Black to exclude files or directories that match a given regular expression pattern. For example:

$ black . --exclude '/migrations/'

This will format all Python files in the current directory and its subdirectories, excluding any in the migrations directory.

References

https://pypi.org/project/black/