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
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
|
.. -*- coding: utf-8 -*-
==============
Contributing
==============
.. _bug reports, feedback:
Bug reports, feedback
---------------------
You think you have found a bug in Pylint? Well, this may be the case
since Pylint is under heavy development!
Please take the time to check if it is already in the issue tracker at
https://github.com/PyCQA/pylint
If you cannot find it in the tracker, create a new issue there or discuss your
problem on the code-quality@python.org mailing list or using the discord server https://discord.gg/kFebW799.
The code-quality mailing list is also a nice place to provide feedback about
Pylint, since it is shared with other tools that aim at improving the quality of
python code.
Note that if you don't find something you have expected in Pylint's issue
tracker, it may be because it is an issue with one of its dependencies, namely
astroid:
* https://github.com/PyCQA/astroid
.. _Mailing lists:
Discord server
--------------
https://discord.gg/kFebW799
Mailing lists
-------------
You can subscribe to this mailing list at
https://mail.python.org/mailman/listinfo/code-quality
Archives are available at
https://mail.python.org/pipermail/code-quality/
Archives before April 2013 are available at
https://lists.logilab.org/pipermail/python-projects/
.. _repository:
Repository
----------
Pylint is developed using the git_ distributed version control system.
You can clone Pylint and its dependencies from ::
git clone https://github.com/PyCQA/pylint
git clone https://github.com/PyCQA/astroid
.. _git: https://git-scm.com/
Got a change for Pylint? Below are a few steps you should take to make sure
your patch gets accepted.
- Test your code
* Pylint is very well tested, with a high code coverage.
It has two types of tests, usual unittests and functional tests.
The usual unittests can be found under `/pylint/test` directory and they can
be used for testing almost anything Pylint related. But for the ease
of testing Pylint's messages, we also have the concept of functional tests.
* You should also run all the tests to ensure that your change isn't a
breaking one. You can run the tests using the tox_ package, as in::
python -m tox
python -m tox -epy36 # for Python 3.6 suite only
python -m tox -epylint # for running Pylint over Pylint's codebase
python -m tox -eformatting # for running formatting checks over Pylint's codebase
* It's usually a good idea to run tox_ with ``--recreate``. This is needed because
the tox environment might use an older version of astroid_, which can cause various failures
when you are running against the latest pylint::
python -m tox --recreate # The entire tox environment is going to be recreated
* To run only a specific test suite, use a pattern for the test filename
(**without** the ``.py`` extension), as in::
python -m tox -e py36 -- -k test_functional
python -m tox -e py36 -- -k \*func\*
* Since we just use pytest_ to run the tests, you can also use it as well,
although we highly recommend using tox_ instead::
pytest pylint -k test_functional
* ``pylint`` uses black_ and isort_ among other Python autoformatters.
We have a pre-commit hook which should take care of the autoformatting for
you. To enable it, do the following:
* install ``pre-commit`` using ``pip install pre-commit``
* then run ``pre-commit install`` in the ``pylint`` root directory to enable the git hooks.
- Add a short entry to the ChangeLog describing the change, except for internal
implementation only changes. Not usually required, but for changes other than small
bugs we also add a couple of sentences in the release document for that release,
(`What's New` section). For the release document we usually write some more details,
and it is also a good place to offer examples on how the new change is supposed to work.
- Add a short entry in :file:`doc/whatsnew/VERSION.rst`.
- Add yourself to the `CONTRIBUTORS` file, flag yourself appropriately
(if in doubt, you're a ``contributor``).
- Write a comprehensive commit message
- Relate your change to an issue in the tracker if such an issue exists (see
`Closing issues via commit messages`_ of the GitHub documentation for more
information on this)
- Document your change, if it is a non-trivial one.
- Send a pull request from GitHub (see `About pull requests`_ for more insight
about this topic)
.. _functional_tests:
Functional Tests
----------------
These are residing under '/pylint/test/functional' and they are formed of multiple
components. First, each Python file is considered to be a test case and it
should be accompanied by a .txt file, having the same name, with the messages
that are supposed to be emitted by the given test file.
In the Python file, each line for which Pylint is supposed to emit a message
has to be annotated with a comment in the form ``# [message_symbol]``, as in::
a, b, c = 1 # [unbalanced-tuple-unpacking]
If multiple messages are expected on the same line, then this syntax can be used::
a, b, c = 1.test # [unbalanced-tuple-unpacking, no-member]
You can also use ``# +n: [`` with n an integer if the above syntax would make the line too long or other reasons::
# +1: [empty-comment]
#
If you need special control over Pylint's flag, you can also create a .rc file, which
can have sections of Pylint's configuration.
During development, it's sometimes helpful to run all functional tests in your
current environment in order to have faster feedback. Run from Pylint root directory with::
python tests/test_functional.py
You can use all the options you would use for pytest, for example `-k "test_functional[len_checks]"`.
If required the .txt file can be re-generated from the current output by appending
`--update-functional-output` to the command line::
python tests/test_functional.py --update-functional-output -k "test_functional[len_checks]"
.. _`Closing issues via commit messages`: https://help.github.com/articles/closing-issues-via-commit-messages/
.. _`About pull requests`: https://help.github.com/articles/using-pull-requests/
.. _tox: https://tox.readthedocs.io/en/latest/
.. _pytest: https://pytest.readthedocs.io/en/latest/
.. _black: https://github.com/ambv/black
.. _isort: https://github.com/timothycrosley/isort
.. _astroid: https://github.com/pycqa/astroid
Tips for Getting Started with Pylint Development
------------------------------------------------
* Read the :ref:`technical-reference`. It gives a short walk through of the pylint
codebase and will help you identify where you will need to make changes
for what you are trying to implement.
* :func:`astroid.extract_node` is your friend. Most checkers are AST based,
so you will likely need to interact with :mod:`astroid`.
A short example of how to use :func:`astroid.extract_node` is given
:ref:`here <astroid_extract_node>`.
* When fixing a bug for a specific check, search the code for the warning
message to find where the warning is raised,
and therefore where the logic for that code exists.
Building the documentation
----------------------------
We use **tox** for building the documentation::
$ tox -e docs
|
