flake8-black
Introduction
This is an MIT licensed flake8 plugin for validating Python code style with the command line code formatting tool black. It is available to install from the Python Package Index (PyPI):
Black, "The Uncompromising Code Formatter", is normally run to edit your Python code in place to match their coding style, a strict subset of the PEP 8 style guide.
The point of this plugin is to be able to run black --check ...
from
within the flake8
plugin ecosystem. You might use this via a git
pre-commit hook, or as part of your continuous integration testing.
Flake8 Validation codes
Early versions of flake8 assumed a single character prefix for the validation
codes, which became problematic with collisions in the plugin ecosystem. Since
v3.0, flake8 has supported longer prefixes, therefore this plugin uses BLK
as its prefix.
Code | Description (and notes) |
BLK100 | Black would make changes. |
BLK9## | Internal error (various, listed below): |
BLK900 | Failed to load file: ... |
BLK901 | Invalid input. |
BLK998 | Could not access flake8 line length setting (no longer used). |
BLK999 | Unexpected exception. |
Note that if your Python code has a syntax error, black --check ...
would
report this as an error. Likewise flake8 ...
will by default report the
syntax error, but importantly it does not seem to then call the plugins, so
you will not get an additional BLK
error.
Installation
Python 3.6 or later is required to run black
, so that is recommended, but
black
can be used on Python code written for older versions of Python.
You can install flake8-black
using pip
, which should install flake8
and black
as well if not already present:
$ pip install flake8-black
Alternatively, if you are using the Anaconda packaging system, the following command will install the plugin with its dependencies:
$ conda install -c conda-forge flake8-black
The new validator should be automatically included when using flake8
which
may now report additional validation codes starting with BLK
(as defined
above). For example:
$ flake8 example.py
You can request only the BLK
codes be shown using:
$ flake8 --select BLK example.py
Configuration
We assume you are familiar with flake8 configuration and black configuration.
We recommend using the following settings in your flake8
configuration,
for example in your .flake8
, setup.cfg
, or tox.ini
file:
[flake8] # Recommend matching the black line length (default 88), # rather than using the flake8 default of 79: max-line-length = 88 extend-ignore = # See https://github.com/PyCQA/pycodestyle/issues/373 E203,
Note currently pycodestyle
gives false positives on the spaces black
uses for slices, which flake8
reports as E203: whitespace before ':'
.
Until pyflakes issue 373
is fixed, and flake8
is updated, we suggest disabling this style check.
If a pyproject.toml
file is found, the plugin will look at the following
black
settings:
target_version
skip_string_normalization
line_length
Ignoring validation codes
Using the flake8 no-quality-assurance pragma comment is not recommended
(e.g. adding # noqa: BLK100
to the first line black would change).
Instead use the black pragma comments # fmt: off
at the start, and
# fmt: on
at the end, of any region of your code which should not be
changed.
Ignoring files
The plugin does NOT currently consider the black
settings include
and exclude
, so if you have certain Python files which you do not use
with black
and have told it to ignore, you will also need to tell
flake8
to ignore them (e.g. using exclude
or per-file-ignores
).
Version History
Version | Release date | Changes |
v0.1.0 | 2019-06-03 |
|
v0.0.4 | 2019-03-15 |
|
v0.0.3 | 2019-02-21 |
|
v0.0.2 | 2019-02-15 |
|
v0.0.1 | 2019-01-10 |
|
Developers
This plugin is on GitHub at https://github.com/peterjc/flake8-black
To make a new release once tested locally and on TravisCI:
$ git tag vX.Y.Z $ python setup.py sdist --formats=gztar $ twine upload dist/flake8-black-X.Y.Z.tar.gz $ git push origin master --tags
The PyPI upload should trigger an automated pull request updating the flake8-black conda-forge recipe.