registering-plugins.rst 3.98 KB
Newer Older
1 2
.. _register-a-plugin:

3 4 5 6
==================================
 Registering a Plugin with Flake8
==================================

7
To register any kind of plugin with |Flake8|, you need:
8

9
#. A way to install the plugin (whether it is packaged on its own or
10 11 12 13 14 15 16 17
   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).

18 19 20
|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.
21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49

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: [
50
                'X = flake8_example:ExamplePlugin',
51 52 53
            ],
        },
        classifiers=[
54
            "Framework :: Flake8",
55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75
            "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: [
76
                'X = flake8_example:ExamplePlugin',
77 78 79 80 81
            ],
        },
        # snip ...
    )

82
We tell setuptools to register our entry point ``X`` inside the specific
83 84
grouping of entry-points that flake8 should look in.

85
|Flake8| presently looks at three groups:
86 87 88 89 90

- ``flake8.extension``

- ``flake8.report``

91
If your plugin is one that adds checks to |Flake8|, you will use
92
``flake8.extension``. If your plugin performs extra report
93
handling (formatting, filtering, etc.) it will use ``flake8.report``.
94 95 96 97 98 99 100 101 102 103

If our ``ExamplePlugin`` is something that adds checks, our code would look
like:

.. code-block:: python

    setuptools.setup(
        # snip ...
        entry_points={
            'flake8.extension': [
104
                'X = flake8_example:ExamplePlugin',
105 106 107 108 109
            ],
        },
        # snip ...
    )

110
The ``X`` in checking plugins define what error codes it is going to report.
111 112 113
So if the plugin reports only the error code ``X101`` your entry-point would
look like::

114
    X101 = flake8_example:ExamplePlugin
115 116 117 118

If your plugin reports several error codes that all start with ``X10``, then
it would look like::

119
    X10 = flake8_example:ExamplePlugin
120 121 122 123

If all of your plugin's error codes start with ``X1`` then it would look
like::

124
    X1 = flake8_example:ExamplePlugin
125 126 127

Finally, if all of your plugin's error codes start with just ``X`` then it
would look like the original example.
128

129
|Flake8| requires each entry point to be unique amongst all plugins installed
130 131 132
in the users environment. Selecting an entry point that is already used can
cause plugins to be deactivated without warning!

133 134 135
**Please Note:** Your entry point does not need to be exactly 4 characters
as of |Flake8| 3.0. *Consider using an entry point with 3 letters followed
by 3 numbers (i.e.* ``ABC123`` *).*
136

137 138

.. _Entry Points:
139
    https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points