Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/peterjc/flake8-black
flake8 plugin to run black for checking Python coding style
https://github.com/peterjc/flake8-black
Last synced: 1 day ago
JSON representation
flake8 plugin to run black for checking Python coding style
- Host: GitHub
- URL: https://github.com/peterjc/flake8-black
- Owner: peterjc
- License: mit
- Created: 2019-01-10T14:40:26.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2024-12-16T19:43:13.000Z (about 1 month ago)
- Last Synced: 2025-01-10T21:05:01.479Z (9 days ago)
- Language: Python
- Size: 146 KB
- Stars: 164
- Watchers: 3
- Forks: 10
- Open Issues: 3
-
Metadata Files:
- Readme: README.rst
- License: LICENSE.rst
Awesome Lists containing this project
- awesome-flake8-extensions - flake8-black - Wrapper around [black](https://github.com/psf/black). (Wrappers)
- best-of-python-dev - GitHub - 10% open · ⏱️ 14.05.2024): (Linters & Style Checkers)
README
flake8-black
============
.. image:: https://img.shields.io/pypi/v/flake8-black.svg
:alt: Released on the Python Package Index (PyPI)
:target: https://pypi.org/project/flake8-black/
.. image:: https://img.shields.io/conda/vn/conda-forge/flake8-black.svg
:alt: Released on Conda
:target: https://anaconda.org/conda-forge/flake8-black
.. image:: https://results.pre-commit.ci/badge/github/peterjc/flake8-black/master.svg
:target: https://results.pre-commit.ci/latest/github/peterjc/flake8-black/master
:alt: pre-commit.ci status
.. image:: https://img.shields.io/github/actions/workflow/status/peterjc/flake8-black/test.yml?logo=github-actions
:alt: GitHub workflow status
:target: https://github.com/peterjc/flake8-black/actions
.. image:: https://img.shields.io/pypi/dm/flake8-black.svg
:alt: PyPI downloads
:target: https://pypistats.org/packages/flake8-black
.. image:: https://img.shields.io/badge/code%20style-black-000000.svg
:alt: Code style: black
:target: https://github.com/python/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.8 or later is required, 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
-------------------------
For large projects especially, 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.
You should be able to specify your black version in your conda or pip
requirements or environment, or using using pipenv or poetry etc.
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, add
``# fmt: skip`` to single lines. Or, exclude 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.3.7 *Pending* - Now tested on Python 3.8 though 3.12.
v0.3.6 2022-12-13 - Use standard library ``tomllib`` on Python 3.11 onwards,
contribution from
`Ganden Schaffner `_.
v0.3.5 2022-11-21 - Fix regression clashing with ``flake8-rst-docstrings``.
v0.3.4 2022-11-17 - Replaces ``setup.py`` with ``pyproject.toml`` for build.
v0.3.3 2022-05-16 - Cope with line-length as string in pyproject.toml config.
v0.3.2 2022-02-25 - Use ``tomli`` library to match black, contribution from
`Brian Helba `_.
- Adopted GitHub Actions to replace TravisCI testing.
- Python 3.7 or later required.
v0.3.0 2022-02-25 - Requires black v22.1.0 (first non-beta release) or later.
- Support options "preview", "skip-magic-trailing-comma"
in the black TOML file, contribution from
`Ferdy `_.
v0.2.4 2022-01-30 - Support black v22.1.0 which changed a function call,
contribution from
`Raffaele Salmaso `_.
v0.2.3 2021-07-16 - Made ``toml`` dependency explicit in ``setup.py``.
v0.2.2 2021-07-16 - Declared ``toml`` dependency (for black 21.7b0).
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
Developers may install the plugin from the git repository with optional build
dependencies::
$ pip install -e .[develop]
To make a new release once tested locally and online::
$ git tag vX.Y.Z
$ python -m build
$ git push origin master --tags
$ twine upload dist/flake8?black-X.Y.Z*
The PyPI upload should trigger an automated pull request updating the
`flake8-black conda-forge recipe
`_.