Last year, Black was released as yet another formatter for Python. Since then, Black has been swiftly embraced by the community — it even comes supported with the Python extension for VSCode. This is pretty gravy taking into account that, at the time of this writing, Black is still in Beta!

Why Style Matters

When it comes to Python and code style, you typically look no further than the official PEP8 style guide. However, that leaves it all up to you to make sure your codebase meets the PEP8 standards. This can be very time consuming — especially when you are working under a deadline to ship out a new product or feature.

This is where code formatters come into play. They allow you to focus on shipping great software without sacrificing codestyle. Of course, Black is not the only formatter out there. Other popular formatters are autopep8 or Google’s yapf. To be honest, Black is very similar to yapf when it comes to style. So why stick with Black?

One of the interesting things about Black is that it is very opinionated. The README even states

By using [Black], you agree to cede control over minutiae of hand-formatting. In return, Black gives you speed, determinism, and freedom from pycodestyle nagging about formatting. You will save time and mental energy for more important matters.

If this sounds like a turnoff (as I’m certain it is for some), then Black is not for you! If you’re ready to forget about styling and let Black handle the details, let’s begin.

Installation

First, we must install Black with

$ pip install black

or if you’re using pipenv

$ pipenv install black --dev

Usage

Usage is dead easy. You simply run

$ black <file_name_or_directory> [OPTIONS]

or, alternatively

$ pipenv run black <file_name_or_directory> [OPTIONS]

A few of the most useful options are --diff, which does not make any changes, but instead shows you the proposed output, and --include REGEX or --exclude REGEX which expect a regular expression pattern of files or directories to include/exclude.

Additionally, simply typing

$ black . # or pipenv run black .

will run Black recursively through the current working directory, formatting all files matching the \.pyi?$ expression by default.

What about custom configurations 🧐?

Although Black comes with some pretty sane defaults, you can include a pyproject.toml in your current working directory to make a few changes.

Here is an example pyproject.toml file directly from the docs

[tool.black]
line-length = 88
py36 = true
include = '\.pyi?$'
exclude = '''
/(
    \.git
  | \.hg
  | \.mypy_cache
  | \.tox
  | \.venv
  | _build
  | buck-out
  | build
  | dist

  # The following are specific to Black, you probably don't want those.
  | blib2to3
  | tests/data
)/
'''

Running the same command again with this file present will use the stated defaults to format your code. In this case, this will format all files ending in .py or .pyi.

What about editor integration?

Black has integations across many of the most popular text editors and IDEs including, VSCode, Sublime, and PyCharm, just to name a few.

That’s all I got for now, keep hacking friends!