1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
|
.. _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://github.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 :: 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 two groups:
- ``flake8.extension``
- ``flake8.report``
If your plugin is one that adds checks to |Flake8|, you will use
``flake8.extension``. 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. Selecting an entry point that is already used can
cause plugins to be deactivated without warning!
**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`` *).*
.. _Entry Points:
https://setuptools.readthedocs.io/en/latest/pkg_resources.html#entry-points
|
