mirror of
https://github.com/PyCQA/flake8.git
synced 2026-03-31 03:06:53 +00:00
236 lines
9.5 KiB
ReStructuredText
236 lines
9.5 KiB
ReStructuredText
.. _register-a-plugin:
|
|
|
|
==================================
|
|
Registering a Plugin with Flake8
|
|
==================================
|
|
|
|
To register any kind of plugin with |Flake8|, you need:
|
|
|
|
#. A way to install the plugin (whether it is packaged on its own or
|
|
as part of something else). In this section, we will use a ``setup.py``
|
|
written for an example plugin.
|
|
|
|
#. A name for your plugin that will (ideally) be unique.
|
|
|
|
#. A somewhat recent version of setuptools (newer than 0.7.0 but preferably as
|
|
recent as you can attain).
|
|
|
|
|Flake8| relies on functionality provided by setuptools called
|
|
`Entry Points`_. These allow any package to register a plugin with |Flake8|
|
|
via that package's ``setup.py`` file.
|
|
|
|
Let's presume that we already have our plugin written and it's in a module
|
|
called ``flake8_example``. We might have a ``setup.py`` that looks something
|
|
like:
|
|
|
|
.. code-block:: python
|
|
|
|
import setuptools
|
|
|
|
requires = [
|
|
"flake8 > 3.0.0",
|
|
]
|
|
|
|
flake8_entry_point = # ...
|
|
|
|
setuptools.setup(
|
|
name="flake8_example",
|
|
license="MIT",
|
|
version="0.1.0",
|
|
description="our extension to flake8",
|
|
author="Me",
|
|
author_email="example@example.com",
|
|
url="https://gitlab.com/me/flake8_example",
|
|
packages=[
|
|
"flake8_example",
|
|
],
|
|
install_requires=requires,
|
|
entry_points={
|
|
flake8_entry_point: [
|
|
'X = flake8_example:ExamplePlugin',
|
|
],
|
|
},
|
|
classifiers=[
|
|
"Framework :: Flake8",
|
|
"Environment :: Console",
|
|
"Intended Audience :: Developers",
|
|
"License :: OSI Approved :: MIT License",
|
|
"Programming Language :: Python",
|
|
"Programming Language :: Python :: 2",
|
|
"Programming Language :: Python :: 3",
|
|
"Topic :: Software Development :: Libraries :: Python Modules",
|
|
"Topic :: Software Development :: Quality Assurance",
|
|
],
|
|
)
|
|
|
|
Note specifically these lines:
|
|
|
|
.. code-block:: python
|
|
|
|
flake8_entry_point = # ...
|
|
|
|
setuptools.setup(
|
|
# snip ...
|
|
entry_points={
|
|
flake8_entry_point: [
|
|
'X = flake8_example:ExamplePlugin',
|
|
],
|
|
},
|
|
# snip ...
|
|
)
|
|
|
|
We tell setuptools to register our entry point ``X`` inside the specific
|
|
grouping of entry-points that flake8 should look in.
|
|
|
|
|Flake8| presently looks at three groups:
|
|
|
|
- ``flake8.extension``
|
|
|
|
- ``flake8.listen``
|
|
|
|
- ``flake8.report``
|
|
|
|
If your plugin is one that adds checks to |Flake8|, you will use
|
|
``flake8.extension``. If your plugin automatically fixes errors in code, you
|
|
will use ``flake8.listen``. Finally, if your plugin performs extra report
|
|
handling (formatting, filtering, etc.) it will use ``flake8.report``.
|
|
|
|
If our ``ExamplePlugin`` is something that adds checks, our code would look
|
|
like:
|
|
|
|
.. code-block:: python
|
|
|
|
setuptools.setup(
|
|
# snip ...
|
|
entry_points={
|
|
'flake8.extension': [
|
|
'X = flake8_example:ExamplePlugin',
|
|
],
|
|
},
|
|
# snip ...
|
|
)
|
|
|
|
The ``X`` in checking plugins define what error codes it is going to report.
|
|
So if the plugin reports only the error code ``X101`` your entry-point would
|
|
look like::
|
|
|
|
X101 = flake8_example.ExamplePlugin
|
|
|
|
If your plugin reports several error codes that all start with ``X10``, then
|
|
it would look like::
|
|
|
|
X10 = flake8_example.ExamplePlugin
|
|
|
|
If all of your plugin's error codes start with ``X1`` then it would look
|
|
like::
|
|
|
|
X1 = flake8_example.ExamplePlugin
|
|
|
|
Finally, if all of your plugin's error codes start with just ``X`` then it
|
|
would look like the original example.
|
|
|
|
|Flake8| requires each entry point to be unique amongst all plugins installed
|
|
in the users environment. Before defining your set of error codes, please
|
|
check the list below and select a unique entry point for your plugin.
|
|
|
|
+--------+-------------+---------------------------------+
|
|
| Letter | Entry Point | Project |
|
|
+--------+-------------+---------------------------------+
|
|
| A | A00x | flake8-builtins |
|
|
+--------+-------------+---------------------------------+
|
|
| | A40x | flake8-author |
|
|
+--------+-------------+---------------------------------+
|
|
| B | Bxxx | flake8-bugbear |
|
|
+--------+-------------+---------------------------------+
|
|
| C | C001 | flake8-confusables |
|
|
+--------+-------------+---------------------------------+
|
|
| | C10x | flake8-coding |
|
|
+--------+-------------+---------------------------------+
|
|
| | C81x | flake8-commas |
|
|
+--------+-------------+---------------------------------+
|
|
| | C90x | mccabe |
|
|
+--------+-------------+---------------------------------+
|
|
| | CNL100 | flake8-class-newline |
|
|
+--------+-------------+---------------------------------+
|
|
| D | Dxxx | flake8-docstring (pydocstyle) |
|
|
+--------+-------------+---------------------------------+
|
|
| | D001 | flake8-deprecated |
|
|
+--------+-------------+---------------------------------+
|
|
| E | Exxx | pycodestyle |
|
|
+--------+-------------+---------------------------------+
|
|
| F | Fxxx | pyflakes |
|
|
+--------+-------------+---------------------------------+
|
|
| | FI10-FI90 | flake8-future-import |
|
|
+--------+-------------+---------------------------------+
|
|
| I | Ixxx | flake8-import-order |
|
|
+--------+-------------+---------------------------------+
|
|
| | I00x | flake8-isort |
|
|
+--------+-------------+---------------------------------+
|
|
| | I20x | flake8-tidy-imports |
|
|
+--------+-------------+---------------------------------+
|
|
| | IESxxx | flake8-invalid-escape-sequences |
|
|
+--------+-------------+---------------------------------+
|
|
| M | M001 | flake8-mock |
|
|
+--------+-------------+---------------------------------+
|
|
| | M90x | mutable-defaults |
|
|
+--------+-------------+---------------------------------+
|
|
| | M90x | flake8-mutable |
|
|
+--------+-------------+---------------------------------+
|
|
| N | N8xx | flake8-naming |
|
|
+--------+-------------+---------------------------------+
|
|
| | N999 | flake8-module-name |
|
|
+--------+-------------+---------------------------------+
|
|
| O | O100-O102 | flake8-ownership |
|
|
+--------+-------------+---------------------------------+
|
|
| P | Pxxx | flake8-string-format |
|
|
+--------+-------------+---------------------------------+
|
|
| Q | Q0xx | flake8-quotes |
|
|
+--------+-------------+---------------------------------+
|
|
| | Q1xx | flake8-quotes2 |
|
|
+--------+-------------+---------------------------------+
|
|
| | Q4xx | flake8-sql |
|
|
+--------+-------------+---------------------------------+
|
|
| R | Rxxx | flake8-regex |
|
|
+--------+-------------+---------------------------------+
|
|
| | R70x | radon |
|
|
+--------+-------------+---------------------------------+
|
|
| | RSTxxx | flake8-rst-docstrings |
|
|
+--------+-------------+---------------------------------+
|
|
| S | Sxxx | flake8-strict |
|
|
+--------+-------------+---------------------------------+
|
|
| | Sxxx | flake8-snippets |
|
|
+--------+-------------+---------------------------------+
|
|
| | Sxxx | flake8-bandit |
|
|
+--------+-------------+---------------------------------+
|
|
| | S00x | flake8-sorted-keys |
|
|
+--------+-------------+---------------------------------+
|
|
| | S001 | flake8-prep3101 |
|
|
+--------+-------------+---------------------------------+
|
|
| T | Txxx | flake8-pytest |
|
|
+--------+-------------+---------------------------------+
|
|
| | T000 | flake8-todo |
|
|
+--------+-------------+---------------------------------+
|
|
| | T00x | flake8-print |
|
|
+--------+-------------+---------------------------------+
|
|
| | T004 | flake8-libfaketime |
|
|
+--------+-------------+---------------------------------+
|
|
| | T005 | flake8-module-import |
|
|
+--------+-------------+---------------------------------+
|
|
| | T006 | flake8-ugettext-alias |
|
|
+--------+-------------+---------------------------------+
|
|
| | T006 | flake8-translation-activate |
|
|
+--------+-------------+---------------------------------+
|
|
| | T007 | flake8-user-model |
|
|
+--------+-------------+---------------------------------+
|
|
| | T100 | flake8-debugger |
|
|
+--------+-------------+---------------------------------+
|
|
| | T4xx | flake8-mypy |
|
|
+--------+-------------+---------------------------------+
|
|
| | T80x | flake8-tuple |
|
|
+--------+-------------+---------------------------------+
|
|
| W | Wxxx | pycodestyle |
|
|
+--------+-------------+---------------------------------+
|
|
|
|
|
|
.. _Entry Points:
|
|
https://pythonhosted.org/setuptools/pkg_resources.html#entry-points
|