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: about 2 months ago
JSON representation

flake8 plugin to run black for checking Python coding style

Lists

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

`_.