flake8 plugin to call black as a code style validator
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: …|
|BLK998||Could not access flake8 line length setting (no longer used).|
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.
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.
Install flake8-black using pip, which should install flake8 and black as well if not already present:
$ pip install 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
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:
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.
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).
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