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/workflow/status/peterjc/flake8-black/test?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 <https://gitlab.com/pycqa/flake8>`_ plugin
for validating Python code style with the command line code formatting tool
`black <https://github.com/python/black>`_. It is available to install from
the `Python Package Index (PyPI) <https://pypi.org/project/flake8-black/>`_.
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 <https://www.python.org/dev/peps/pep-0008/>`_.
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 <https://pre-commit.com/>`_ 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.7 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
-------------------------
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
<https://www.python.org/dev/peps/pep-0440/#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
<http://flake8.pycqa.org/en/latest/user/configuration.html>`_ and
`black configuration
<https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#configuration-via-a-file>`_.
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 <https://github.com/PyCQA/pycodestyle/issues/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.6 2022-12-13 - Use standard library ``tomllib`` on Python 3.11 onwards,
contribution from
`Ganden Schaffner <https://github.com/gschaffner>`_.
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 <https://github.com/brianhelba>`_.
- 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 <https://github.com/ferdynice>`_.
v0.2.4 2022-01-30 - Support black v22.1.0 which changed a function call,
contribution from
`Raffaele Salmaso <https://github.com/rsalmaso>`_.
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
<https://github.com/pypa/pipenv/issues/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 <https://github.com/098799>`_.
- 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 <https://github.com/ADKosm>`_.
- 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 <https://github.com/sapphire-janrain>`_.
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
<https://github.com/conda-forge/flake8-black-feedstock/blob/master/recipe/meta.yaml>`_.
Raw data
{
"_id": null,
"home_page": "",
"name": "flake8-black",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": "\"Peter J. A. Cock\" <p.j.a.cock@googlemail.com>",
"keywords": "black,formatting,style,flake8",
"author": "Peter J. A. Cock",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/2f/52/dfb29b60cf14ae2d5b6119733b60fb32dc1ce0b35746f53b8dcc92d21f5c/flake8-black-0.3.6.tar.gz",
"platform": null,
"description": "flake8-black\n============\n\n.. image:: https://img.shields.io/pypi/v/flake8-black.svg\n :alt: Released on the Python Package Index (PyPI)\n :target: https://pypi.org/project/flake8-black/\n.. image:: https://img.shields.io/conda/vn/conda-forge/flake8-black.svg\n :alt: Released on Conda\n :target: https://anaconda.org/conda-forge/flake8-black\n.. image:: https://results.pre-commit.ci/badge/github/peterjc/flake8-black/master.svg\n :target: https://results.pre-commit.ci/latest/github/peterjc/flake8-black/master\n :alt: pre-commit.ci status\n.. image:: https://img.shields.io/github/workflow/status/peterjc/flake8-black/test?logo=github-actions\n :alt: GitHub workflow status\n :target: https://github.com/peterjc/flake8-black/actions\n.. image:: https://img.shields.io/pypi/dm/flake8-black.svg\n :alt: PyPI downloads\n :target: https://pypistats.org/packages/flake8-black\n.. image:: https://img.shields.io/badge/code%20style-black-000000.svg\n :alt: Code style: black\n :target: https://github.com/python/black\n\nIntroduction\n------------\n\nThis is an MIT licensed `flake8 <https://gitlab.com/pycqa/flake8>`_ plugin\nfor validating Python code style with the command line code formatting tool\n`black <https://github.com/python/black>`_. It is available to install from\nthe `Python Package Index (PyPI) <https://pypi.org/project/flake8-black/>`_.\n\nBlack, *\"The Uncompromising Code Formatter\"*, is normally run to edit your\nPython code in place to match their coding style, a strict subset of the\n`PEP 8 style guide <https://www.python.org/dev/peps/pep-0008/>`_.\n\nThe point of this plugin is to be able to run ``black --check ...`` from\nwithin the ``flake8`` plugin ecosystem. You might use this via a ``git``\npre-commit hook, or as part of your continuous integration testing.\n\nIf you are using `pre-commit <https://pre-commit.com/>`_ configure it to call\nblack and/or flake8 directly - you do not need flake8-black at all.\n\nFlake8 Validation codes\n-----------------------\n\nEarly versions of flake8 assumed a single character prefix for the validation\ncodes, which became problematic with collisions in the plugin ecosystem. Since\nv3.0, flake8 has supported longer prefixes, therefore this plugin uses ``BLK``\nas its prefix.\n\n====== =======================================================================\nCode Description (*and notes*)\n------ -----------------------------------------------------------------------\nBLK100 Black would make changes.\nBLK9## Internal error (*various, listed below*):\nBLK900 Failed to load file: ...\nBLK901 Invalid input.\nBLK997 Invalid TOML file: ...\nBLK998 Could not access flake8 line length setting (*no longer used*).\nBLK999 Unexpected exception.\n====== =======================================================================\n\nNote that if your Python code has a syntax error, ``black --check ...`` would\nreport this as an error. Likewise ``flake8 ...`` will by default report the\nsyntax error, but importantly it does not seem to then call the plugins, so\nyou will *not* get an additional ``BLK`` error.\n\n\nInstallation\n------------\n\nPython 3.7 or later is required, but ``black`` can be used on Python code\nwritten for older versions of Python.\n\nYou can install ``flake8-black`` using ``pip``, which should install ``flake8``\nand ``black`` as well if not already present::\n\n $ pip install flake8-black\n\nAlternatively, if you are using the Anaconda packaging system, the following\ncommand will install the plugin with its dependencies::\n\n $ conda install -c conda-forge flake8-black\n\nThe new validator should be automatically included when using ``flake8`` which\nmay now report additional validation codes starting with ``BLK`` (as defined\nabove). For example::\n\n $ flake8 example.py\n\nYou can request only the ``BLK`` codes be shown using::\n\n $ flake8 --select BLK example.py\n\nPython package management\n-------------------------\n\nWe covered using pip or conda by hand above. If you are using a PyPI based\nPython dependency system like pipenv or poetry, you may run into complications\nbecause at the time of writing all the black releases to PyPI have been tagged\nas pre-releases (beta code). `PEP440 Handling of pre-releases\n<https://www.python.org/dev/peps/pep-0440/#handling-of-pre-releases>`_\ncould be more explicit here.\n\nFor pipenv, flake8-black v0.2.0 onwards should just work.\n\nFor poetry, include this in your ``pyproject.toml`` configuration file::\n\n [tool.poetry.dev-dependencies]\n ...\n black = { version = \"*\", allow-prereleases = true }\n ...\n\nIn either case, for large projects you should consider pinning the exact\nversion of black you want to use as their updates do sometimes introduce\nchanges which would show up as new ``BLK100`` violations via flake8.\n\nConfiguration\n-------------\n\nWe assume you are familiar with `flake8 configuration\n<http://flake8.pycqa.org/en/latest/user/configuration.html>`_ and\n`black configuration\n<https://black.readthedocs.io/en/stable/usage_and_configuration/the_basics.html#configuration-via-a-file>`_.\n\nWe recommend using the following settings in your ``flake8`` configuration,\nfor example in your ``.flake8``, ``setup.cfg``, or ``tox.ini`` file::\n\n [flake8]\n # Recommend matching the black line length (default 88),\n # rather than using the flake8 default of 79:\n max-line-length = 88\n extend-ignore =\n # See https://github.com/PyCQA/pycodestyle/issues/373\n E203,\n\nNote currently ``pycodestyle`` gives false positives on the spaces ``black``\nuses for slices, which ``flake8`` reports as ``E203: whitespace before ':'``.\nUntil `pyflakes issue 373 <https://github.com/PyCQA/pycodestyle/issues/373>`_\nis fixed, and ``flake8`` is updated, we suggest disabling this style check.\n\nSeparately ``pyproject.toml`` is used for ``black`` configuration - if this\nfile is found, the plugin will look at the following ``black`` settings:\n\n* ``target_version``\n* ``skip_string_normalization``\n* ``line_length``\n\nYou can specify a particular path for the ``pyproject.toml`` file (e.g.\nglobal development settings) using ``--black-config FILENAME`` at the\ncommand line, or using ``black-config = FILENAME`` in your ``flake8``\nconfiguration file.\n\nIgnoring validation codes\n-------------------------\n\nUsing the flake8 no-quality-assurance pragma comment is not recommended (e.g.\nadding ``# noqa: BLK100`` to the first line black would change). Instead use\nthe black pragma comments ``# fmt: off`` at the start, and ``# fmt: on`` at\nthe end, of any region of your code which should not be changed. Or, add\n``# fmt: skip`` to single lines. Or, exclude the entire file by name (see\nbelow).\n\nIgnoring files\n--------------\n\nThe plugin does *NOT* currently consider the ``black`` settings ``include``\nand ``exclude``, so if you have certain Python files which you do not use\nwith ``black`` and have told it to ignore, you will *also* need to tell\n``flake8`` to ignore them (e.g. using ``exclude`` or ``per-file-ignores``).\n\n\nVersion History\n---------------\n\n======= ============ ===========================================================\nVersion Release date Changes\n------- ------------ -----------------------------------------------------------\nv0.3.6 2022-12-13 - Use standard library ``tomllib`` on Python 3.11 onwards,\n contribution from\n `Ganden Schaffner <https://github.com/gschaffner>`_.\nv0.3.5 2022-11-21 - Fix regression clashing with ``flake8-rst-docstrings``.\nv0.3.4 2022-11-17 - Replaces ``setup.py`` with ``pyproject.toml`` for build.\nv0.3.3 2022-05-16 - Cope with line-length as string in pyproject.toml config.\nv0.3.2 2022-02-25 - Use ``tomli`` library to match black, contribution from\n `Brian Helba <https://github.com/brianhelba>`_.\n - Adopted GitHub Actions to replace TravisCI testing.\n - Python 3.7 or later required.\nv0.3.0 2022-02-25 - Requires black v22.1.0 (first non-beta release) or later.\n - Support options \"preview\", \"skip-magic-trailing-comma\"\n in the black TOML file, contribution from\n `Ferdy <https://github.com/ferdynice>`_.\nv0.2.4 2022-01-30 - Support black v22.1.0 which changed a function call,\n contribution from\n `Raffaele Salmaso <https://github.com/rsalmaso>`_.\nv0.2.3 2021-07-16 - Made ``toml`` dependency explicit in ``setup.py``.\nv0.2.2 2021-07-16 - Declared ``toml`` dependency (for black 21.7b0).\nv0.2.1 2020-07-25 - Detect ``*.pyi`` files via extension.\nv0.2.0 2020-05-20 - Minimum requirement on black 19.3b0 or later is now\n implicit. This is a workaround for `pipenv issue 3928\n <https://github.com/pypa/pipenv/issues/3928>`_. Upgrade\n black if running flake8 gives an error like this:\n ``Flake8 failed to load plugin \"BLK\" due to __call__()\n got an unexpected keyword argument 'target_versions'.``\nv0.1.2 2020-05-18 - Removed test broken by flake8 v3.8 change to resolve\n configuration files relative to current directory.\nv0.1.1 2019-08-26 - Option to use a (global) black configuration file,\n contribution from\n `Tomasz Grining <https://github.com/098799>`_.\n - New ``BLK997`` if can't parse ``pyproject.toml`` file.\n - Logs configuration files, use ``-v`` or ``--verbose``.\n - Fixed flake8 \"builtins\" parameter warning.\n - Now requires black 19.3b0 or later.\nv0.1.0 2019-06-03 - Uses main black settings from ``pyproject.toml``,\n contribution from `Alex <https://github.com/ADKosm>`_.\n - WARNING: Now ignores flake8 ``max-line-length`` setting.\nv0.0.4 2019-03-15 - Supports black 19.3b0 which changed a function call.\nv0.0.3 2019-02-21 - Bug fix when ``W292 no newline at end of file`` applies,\n contribution from\n `Sapphire Becker <https://github.com/sapphire-janrain>`_.\nv0.0.2 2019-02-15 - Document syntax error behaviour (no BLK error reported).\nv0.0.1 2019-01-10 - Initial public release.\n - Passes flake8 ``max-line-length`` setting to black.\n======= ============ ===========================================================\n\n\nDevelopers\n----------\n\nThis plugin is on GitHub at https://github.com/peterjc/flake8-black\n\nDevelopers may install the plugin from the git repository with optional build\ndependencies::\n\n $ pip install -e .[develop]\n\nTo make a new release once tested locally and online::\n\n $ git tag vX.Y.Z\n $ python -m build\n $ git push origin master --tags\n $ twine upload dist/flake8?black-X.Y.Z*\n\nThe PyPI upload should trigger an automated pull request updating the\n`flake8-black conda-forge recipe\n<https://github.com/conda-forge/flake8-black-feedstock/blob/master/recipe/meta.yaml>`_.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "flake8 plugin to call black as a code style validator",
"version": "0.3.6",
"split_keywords": [
"black",
"formatting",
"style",
"flake8"
],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "919bbeb47144ff13583105d91b552325",
"sha256": "fe8ea2eca98d8a504f22040d9117347f6b367458366952862ac3586e7d4eeaca"
},
"downloads": -1,
"filename": "flake8_black-0.3.6-py3-none-any.whl",
"has_sig": false,
"md5_digest": "919bbeb47144ff13583105d91b552325",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 9898,
"upload_time": "2022-12-20T09:29:29",
"upload_time_iso_8601": "2022-12-20T09:29:29.272425Z",
"url": "https://files.pythonhosted.org/packages/d3/89/0b4551179632da06da3770047fdfd927abe9e3c9f45182d216d5d177cfb3/flake8_black-0.3.6-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "c327349cf66d2a46302629c22f9c4f29",
"sha256": "0dfbca3274777792a5bcb2af887a4cad72c72d0e86c94e08e3a3de151bb41c34"
},
"downloads": -1,
"filename": "flake8-black-0.3.6.tar.gz",
"has_sig": false,
"md5_digest": "c327349cf66d2a46302629c22f9c4f29",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 14565,
"upload_time": "2022-12-20T09:29:30",
"upload_time_iso_8601": "2022-12-20T09:29:30.834369Z",
"url": "https://files.pythonhosted.org/packages/2f/52/dfb29b60cf14ae2d5b6119733b60fb32dc1ce0b35746f53b8dcc92d21f5c/flake8-black-0.3.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-12-20 09:29:30",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "flake8-black"
}
JSON