flake8 plugin to run black for checking Python coding style

Overview

flake8-black

Released on the Python Package Index (PyPI) Released on Conda Testing with TravisCI PyPI downloads Code style: 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.

If you are using pre-commit configure it to call black and/or flake8 directly - you do not need flake8-black at all.

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.
BLK997 Invalid TOML file: ...
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

Python package management

We covered using pip or conda by hand above. If you are using a PyPI based Python dependency system like pipenv or poetry, you may run into complications because at the time of writing all the black releases to PyPI have been tagged as pre-releases (beta code). PEP440 Handling of pre-releases could be more explicit here.

For pipenv, flake8-black v0.2.0 onwards should just work.

For poetry, include this in your pyproject.toml configuration file:

[tool.poetry.dev-dependencies]
...
black = { version = "*", allow-prereleases = true }
...

In either case, for large projects you should consider pinning the exact version of black you want to use as their updates do sometimes introduce changes which would show up as new BLK100 violations via flake8.

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.

Separately pyproject.toml is used for black configuration - if this file is found, the plugin will look at the following black settings:

  • target_version
  • skip_string_normalization
  • line_length

You can specify a particular path for the pyproject.toml file (e.g. global development settings) using --black-config FILENAME at the command line, or using black-config = FILENAME in your flake8 configuration file.

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. Or, exlude the entire file by name (see below).

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.2.1 2020-07-25
  • Detect *.pyi files via extension.
v0.2.0 2020-05-20
  • Minimum requirement on black 19.3b0 or later is now implicit. This is a workaround for pipenv issue 3928. Upgrade black if running flake8 gives an error like this: Flake8 failed to load plugin "BLK" due to __call__() got an unexpected keyword argument 'target_versions'.
v0.1.2 2020-05-18
  • Removed test broken by flake8 v3.8 change to resolve configuration files relative to current directory.
v0.1.1 2019-08-26
  • Option to use a (global) black configuration file, contribution from Tomasz Grining.
  • New BLK997 if can't parse pyproject.toml file.
  • Logs configuration files, use -v or --verbose.
  • Fixed flake8 "builtins" parameter warning.
  • Now requires black 19.3b0 or later.
v0.1.0 2019-06-03
  • Uses main black settings from pyproject.toml, contribution from Alex.
  • WARNING: Now ignores flake8 max-line-length setting.
v0.0.4 2019-03-15
  • Supports black 19.3b0 which changed a function call.
v0.0.3 2019-02-21
  • Bug fix when W292 no newline at end of file applies, contribution from Sapphire Becker.
v0.0.2 2019-02-15
  • Document syntax error behaviour (no BLK error reported).
v0.0.1 2019-01-10
  • Initial public release.
  • Passes flake8 max-line-length setting to black.

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.

Owner
Peter Cock
Peter Cock
flake8 plugin to run black for checking Python coding style

flake8-black Introduction This is an MIT licensed flake8 plugin for validating Python code style with the command line code formatting tool black. It

Peter Cock 146 Dec 15, 2022
Type annotations builder for boto3 compatible with VSCode, PyCharm, Emacs, Sublime Text, pyright and mypy.

mypy_boto3_builder Type annotations builder for boto3-stubs project. Compatible with VSCode, PyCharm, Emacs, Sublime Text, mypy, pyright and other too

Vlad Emelianov 2 Dec 05, 2022
Flashcards - A flash card application with 2 optional command line arguments

Flashcards A flash card application with 2 optional command line arguments impor

Özgür Yildirim 2 Jul 15, 2022
Mypy stubs, i.e., type information, for numpy, pandas and matplotlib

Mypy type stubs for NumPy, pandas, and Matplotlib This is a PEP-561-compliant stub-only package which provides type information for matplotlib, numpy

Predictive Analytics Lab 194 Dec 19, 2022
A plugin for Flake8 finding likely bugs and design problems in your program. Contains warnings that don't belong in pyflakes and pycodestyle.

flake8-bugbear A plugin for Flake8 finding likely bugs and design problems in your program. Contains warnings that don't belong in pyflakes and pycode

Python Code Quality Authority 869 Dec 30, 2022
flake8 plugin which checks that typing imports are properly guarded

flake8-typing-imports flake8 plugin which checks that typing imports are properly guarded installation pip install flake8-typing-imports flake8 codes

Anthony Sottile 50 Nov 01, 2022
Tool for pinpointing circular imports in Python. Find cyclic imports in any project

Pycycle: Find and fix circular imports in python projects Pycycle is an experimental project that aims to help python developers fix their circular de

Vadim Kravcenko 311 Dec 15, 2022
It's not just a linter that annoys you!

README for Pylint - https://pylint.pycqa.org/ Professional support for pylint is available as part of the Tidelift Subscription. Tidelift gives softwa

Python Code Quality Authority 4.4k Jan 04, 2023
Backport Python 3.8+ typing utils & add issubtype & more

typing-utils Backport Python3.8+ typing utils & issubtype & more Install API issubtype get_origin get_args get_type_hints Install pip install typi

10 Nov 09, 2022
Pymxs, the 3DsMax bindings of Maxscript to Python doesn't come with any stubs

PyMXS Stubs generator What Pymxs, the 3DsMax bindings of Maxscript to Python doe

Frieder Erdmann 19 Dec 27, 2022
👻 Phantom types for Python

phantom-types Phantom types for Python will help you make illegal states unrepresentable and avoid shotgun parsing by enabling you to practice "Parse,

Anton Agestam 118 Dec 22, 2022
Optional static typing for Python 3 and 2 (PEP 484)

Mypy: Optional Static Typing for Python Got a question? Join us on Gitter! We don't have a mailing list; but we are always happy to answer questions o

Python 14.4k Jan 08, 2023
Flake8 plugin that checks import order against various Python Style Guides

flake8-import-order A flake8 and Pylama plugin that checks the ordering of your imports. It does not check anything else about the imports. Merely tha

Python Code Quality Authority 270 Nov 24, 2022
mypy plugin to type check Kubernetes resources

kubernetes-typed mypy plugin to dynamically define types for Kubernetes objects. Features Type checking for Custom Resources Type checking forkubernet

Artem Yarmoliuk 16 Oct 10, 2022
Convert relative imports to absolute

absolufy-imports A tool and pre-commit hook to automatically convert relative imports to absolute. Installation $ pip install absolufy-imports Usage a

Marco Gorelli 130 Dec 30, 2022
Simple Python style checker in one Python file

pycodestyle (formerly called pep8) - Python style guide checker pycodestyle is a tool to check your Python code against some of the style conventions

Python Code Quality Authority 4.7k Jan 01, 2023
A static-analysis bot for Github

Imhotep, the peaceful builder. What is it? Imhotep is a tool which will comment on commits coming into your repository and check for syntactic errors

Justin Abrahms 221 Nov 10, 2022
coala provides a unified command-line interface for linting and fixing all your code, regardless of the programming languages you use.

"Always code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live." ― John F. Woods coala provides a

coala development group 3.4k Dec 29, 2022
Code audit tool for python.

Pylama Code audit tool for Python and JavaScript. Pylama wraps these tools: pycodestyle (formerly pep8) © 2012-2013, Florent Xicluna; pydocstyle (form

Kirill Klenov 967 Jan 07, 2023
Check for python builtins being used as variables or parameters

Flake8 Builtins plugin Check for python builtins being used as variables or parameters. Imagine some code like this: def max_values(list, list2):

Gil Forcada Codinachs 98 Jan 08, 2023