5
:Author: Sylvain Th�nault
6
:Author: Alexandre Fayolle
7
:Organization: Logilab:Version: $Revision: 1.10 $
8
:Date: $Date: 2005-04-15 10:40:17 $
13
This document is meant to be the reference user manual for Pylint_.
14
This is a work in progress so some sections or parts may be missing
15
(sometimes marked by a XXX). If you think it's lacking some important
16
information, please talk about it on the python-projects mailing list.
18
.. _Pylint: http://www.logilab.org/projects/pylint
26
Pylint is a tool that checks for errors in python code, tries to
27
enforce a coding standard and looks for smelling code . This is
28
similar but nevertheless different from what pychecker_ provides,
29
especially since pychecker explicitely does not bother with coding
30
style. The default coding style used by pylint is close to `PEP 008`_
31
(aka `Guido's style guide`_). For more information about code smells,
32
refer to Martin Fowler's `refactoring book`_
34
One important thing to note is that Pylint isn't smarter than you are:
35
it may warn you about things that you have consciensiously
36
done. That's for example because it tries to detect things that may be
37
dangerous in a context, but maybe not in others, or because it checks
38
for some things that you don't care about. Generally, you shouldn't
39
expect to be pylint totally quiet about your code, so don't
40
necessarily be alarmed if it give you a hell lot of messages for your
41
proudly(XXX) project ;)
43
Pylint will display a number of messages as it analyzes the code, as
44
well as some statistics about the number of warnings and errors found
45
in different files. The messages are classified under various
46
categories such as errors and warnings (more below). If you run pylint
47
twice, it will display the statistics from the previous run together
48
with the ones from the current run, so that you can see if the code
51
Last but not least, the code is given an overall mark, based on the
52
number an severity of the warnings and errors. This has proven to
53
be very motivating for programmers.
55
.. _pychecker: http://pychecker.sf.net
56
.. _`PEP 008`: http://www.python.org/dev/peps/pep-0008/
57
.. _`Guido's style guide`: http://www.python.org/doc/essays/styleguide.html
58
.. _`refactoring book`: http://www.refactoring.com/
65
Pylint requires the latest `logilab-astng`_ and `logilab-common`_
66
packages. It should be compatible with any python version greater than
67
2.2.0 (python 2.2 users will have to install the optik_ package).
69
.. _`logilab-astng`: http://www.logilab.org/projects/astng
70
.. _`logilab-common`: http://www.logilab.org/projects/common
71
.. _optik: http://optik.sourceforge.net/
76
The source tarball is available at ftp://ftp.logilab.fr/pub/pylint.
78
You may apt-get a debian package by adding ::
80
deb ftp://ftp.logilab.org/pub/debian unstable/
82
to your */etc/apt/sources.list* file. Pylint is also available in the
83
standard Debian distribution (but add our public debian repository
84
anyway if you want to get the latest releases and upgrades earlier)
86
Contributed RPM packages for pylint and logilab-common are available at
87
ftp://ftp.nest.pld-linux.org/test.
89
Pylint is also available in Gentoo, Fedora 4, Ubuntu, FreeBSD, Darwin
90
(and maybe other, if si drop us a note please!).
93
Source distribution installation
94
''''''''''''''''''''''''''''''''
95
From the source distribution, extract the tarball, go to the extracted
96
directory and simply run ::
98
python setup.py install
100
You'll have to install dependancies in a similar way.
103
Note for Windows users
104
''''''''''''''''''''''
105
On Windows, once you have installed pylint, the command line usage is
108
pylint.bat [options] module_or_package
110
But this will only work if *pylint.bat* is either in the current
111
directory, or on your system path. (*setup.py* install install *python.bat*
112
to the *Scripts* subdirectory of your Python installation -- e.g.
113
C:\Python24\Scripts.) You can do any of the following to solve this:
115
1. change to the appropriate directory before running pylint.bat
117
2. add the Scripts directory to your path statement in your autoexec.bat
118
file (this file is found in the root directory of your boot-drive)
120
3. create a 'redirect' batch file in a directory actually on your
123
To effect (2), simply append the appropriate directory name to the PATH=
124
statement in autoexec.bat. Be sure to use the Windows directory
125
separator of ';' between entries. Then, once you have rebooted (this is
126
necessary so that the new path statement will take effect when
127
autoexec.bat is run), you will be able to invoke PyLint with
128
pylint.bat on the command line.
130
(3) is the best solution. Once done, you can call pylint at the command
131
line without the .bat, just as do non-Windows users by typing: ::
133
pylint [options] module_or_package
135
To effect option (3), simply create a plain text file pylint.bat with
138
C:\PythonDirectory\Scripts\pylint.bat
140
(where PythonDirectory is replaced by the actual Python installation
141
directory on your system -- e.g. C:\Python24\Scripts\pylint.bat).
147
Pylint is meant to be called from the commant line. The usage is ::
149
pylint [options] module_or_package
151
You should give pylint the name of a Python package or module. Pylint
152
will ``import`` this package or module, so you should pay attention to
153
your ``PYTHONPATH``, since it is a common error to analyze an
154
installed version of a module instead of the development version.
156
It is also possible to analyze python files, with a few
157
restriction. The thing to keep in mind is that pylint will try to
158
convert the file name to a module name, and only be able to process
159
the file if it succeeds. ::
163
should always works since the current working
164
directory is automatically added on top of the python path ::
166
pylint directory/mymodule.py
168
will work if "directory" is a python package (i.e. has an __init__.py
169
file) or if "directory" is in the python path.
171
For more details on this see the FAQ_.
173
You can also start a thin gui around pylint (require TkInter) by
178
This should open a window where you can enter the name of the package
179
or module to check, at pylint messages will be displayed in the user
186
The default format for the output is raw text. But passing pylint the
187
``--html`` option will produce an HTML document.
189
There are several sections in pylint's output.
191
Source code analysis section
192
''''''''''''''''''''''''''''
193
For each python module,
194
pylint will first display a few '*' characters followed by the name
195
of the module. Then, a number of messages with the following
198
MESSAGE_TYPE: LINE_NUM:[OBJECT:] MESSAGE
200
You can get another output format, useful since it's recognized by
201
most editors or other development tools using the ``--parseable=y``
204
The message type can be:
206
* [R]efactor for a "good practice" metric violation
207
* [C]onvention for coding standard violation
208
* [W]arning for stylistic problems, or minor programming issues
209
* [E]rror for important programming issues (i.e. most probably bug)
210
* [F]atal for errors which prevented further processing
212
Sometimes the line of code which caused the error is displayed with
213
a caret pointing to the error. This may be generalized in future
216
Example (extracted from a run of pylint on itself...):
220
************* Module pylint.checkers.format
221
W: 50: Too long line (86/80)
222
W:108: Operator not followed by a space
223
print >>sys.stderr, 'Unable to match %r', line
225
W:141: Too long line (81/80)
226
W: 74:searchall: Unreachable code
227
W:171:FormatChecker.process_tokens: Redefining built-in (type)
228
W:150:FormatChecker.process_tokens: Too many local variables (20/15)
229
W:150:FormatChecker.process_tokens: Too many branchs (13/12)
234
Following the analysis message, pylint will display a set of report,
235
each one focusing on a particular aspect of the project, such as number
236
of messages by categories, modules dependancies...
238
For instance, the metrics report displays summaries gathered from the
242
* the number of processed modules
243
* for each module, the percentage of errors and warnings
244
* the total number of errors and warnings
245
* percentage of classes, functions and modules with docstrings, and
246
a comparison from the previous run
247
* percentage of classes, functions and modules with correct name
248
* (according the the coding standard), and a comparison from the
250
* a list of external dependencies found in the code, and where they appear
252
Also, a global evaluation for the code is computed, and an
253
optional witty comment is displayed (if ``--comment=y`` was
254
specified on the command line).
261
First of all, we have two basic (but useful) options.
263
--version show program's version number and exit
264
-h, --help show help about the command line options
266
Pylint is architectured around several checkers. By default all
267
checkers are enabled. You can disable a specific checker by specifying
268
``--enable-<checker>=n``, or disable all checkers using
269
``--disable-all`` and afterwards enable specific checkers with
270
``--enable-<checker>=y``. See the list of available features_ for a
271
description of provided checkers with their functionalities.
273
Each checker has some specific options, which can take either a yes/no
274
value, an integer, a python regular expression, or a comma separated
275
list of values (which are generally used to override a regular
276
expression in special cases). For a full list of options, use ``--help``
278
Specifying all the options suitable for your setup and coding
279
standards can be tedious, so it is possible to use a rc file to
280
specify the default values. Pylint looks for /etc/pylintrc and
281
~/.pylintrc. The ``--generate-rcfile`` option will generate a
282
commented configuration file according to the current configuration on
283
standard output and exit. You can put other options before this one to
284
use them in the configuration, or start with the default values and
285
hand tune the configuration.
287
Other useful global options include:
289
--zope Initialize Zope products before starting
290
--ignore=file Add <file> (may be a directory) to the black
291
list. It should be a base name, not a path.
292
You may set this option multiple times.
293
--statistics=y_or_n Compute statistics on collected data.
294
--persistent=y_or_n Pickle collected data for later comparisons.
295
--comment=y_or_n Add a comment according to your evaluation note.
296
--parseable=y_or_n Use a parseable output format.
297
--html=y_or_n Use HTML as output format instead of text.
298
--enable-msg=msgids Enable the given messages.
299
--disable-msg=msgids Disable the given messages.
300
--enable-msg-cat=cats Enable all messages in the given categories.
301
--disable-msg-cat=cats Disable all messages in the given categories.
302
--errors-only Enable only checkers from the error category.
304
.. _features: features.html
309
You think you have found a bug in Pylint? Well, this may be the case
310
since Pylint is under development. Please take the time to send a bug
311
report to python-projects@logilab.org. This mailing list is also a
312
nice place to discuss Pylint issues.
315
Comments, feedback, support...
316
------------------------------
317
Use the python-projects@logilab.org mailing list for anything related
318
to Pylint. This is in most case better than sending an email directly
319
to the author, since others will benefit from the exchange, and you'll
320
be more likely answered by someone subscribed to the list.
322
You can subscribe to this mailing list at
323
http://www.logilab.org/mailinglists/python_projects/mailinglist_register_form
325
Archives are available at
326
http://lists.logilab.org/pipermail/python-projects/
328
If you prefer speaking french instead of english, you can use the
329
generic forum-fr@logilab.org mailing list.
344
An example available from the examples directory::
346
"""pylint option block-disable-msg"""
351
"""block-disable-msg test"""
356
def meth1(self, arg):
357
"""this issues a message"""
360
def meth2(self, arg):
361
"""and this one not"""
362
# pylint: disable-msg=W0613
367
"""test one line disabling"""
369
print self.bla # pylint: disable-msg=E1101
374
"""test re-enabling"""
375
# pylint: disable-msg=E1101
379
# pylint: enable-msg=E1101
384
"""test IF sub-block re-enabling"""
385
# pylint: disable-msg=E1101
389
# pylint: enable-msg=E1101
399
"""test TRY/EXCEPT sub-block re-enabling"""
400
# pylint: disable-msg=E1101
404
# pylint: enable-msg=E1101
407
except UndefinedName: # pylint: disable-msg=E0602
414
"""test one line block opening disabling"""
415
if self.blop: # pylint: disable-msg=E1101
426
"""test late disabling"""
429
# pylint: disable-msg=E1101
443
About astng inference
444
---------------------
451
Writing your own checker
452
------------------------
453
You can find some simple examples in the examples
454
directory of the distribution (custom.py and custom_raw.py). I'll try to
455
quickly explain the essential here.
457
First, there is two kinds of checker :
458
* raw checkers, which are analysing each module as a raw file stream
459
* ast checkers, which are working on an ast representation of the module
461
The ast representation used is an extension of the one provided with the
462
standard python distribution in the `compiler package`_. The extension
463
adds additional information and methods on the tree nodes to ease
464
navigation and code introspection.
466
An AST checker is a visitor, and should implements
467
visit_<lowered class name>
468
leave_<lowered class name>
469
methods for the nodes it's interested in. To get description of the different
470
classes used in an ast tree, look at the `compiler.ast documentation`.
471
Checkers are ordered by priority. For each module, pylint's engine:
473
1. give the module source file as a stream to raw checkers
474
2. get an ast representation for the module
475
3. make a depth first descent of the tree, calling visit_<> on each AST
476
checker when entering a node, and living_<> on the back traversal
478
Notice that the source code is probably the best source of
479
documentation, it should be clear and well documented. Don't hesitate to
480
ask for any information on the python-projects mailing list.
482
.. _`compiler package`: http://python.org/doc/current/lib/module-compiler.html
483
.. _`compiler.ast documentation`: http://www.python.org/doc/current/lib/module-compiler.ast.html
488
feedback, bug reports, patch, svn...
496
Pylint is integrated in the following editors/IDEs:
500
* eclipse (using the pydev_ plugin, see also
501
http://msdl.cs.mcgill.ca/MSDL/people/denis/meetings/pythonDev)
503
To use pylint from within vim, see
504
http://www.gonzo.kiev.ua/projects/pylint.vim
506
.. _pydev: http://pydev.sourceforge.net
509
Some projects using Pylint
510
--------------------------
511
The following projects are known to use pylint to help develop better
514
* OSAF Chandler (http://www.osafoundation.org/)
515
* Xen (http://www.xensource.com/)
516
* CPS (http://www.nuxeo.org)
517
* ERP5 (http://www.erp5.org/)
518
* pyxmpp (http://pyxmpp.jabberstudio.org/)
520
* eXe (http://exelearning.org/)
521
* PrimaGIS (http://www.primagis.org)
522
* python-cdd (http://projetos.ossystems.com.br/python-cdd/)
523
* CDSWare (http://cdsware.cern.ch/)
524
* ASE (http://dcwww.camp.dtu.dk/campos/ASE/intro.html)
525
* RunJob (http://projects.fnal.gov/runjob/)
526
* Slugathon (http://slugathon.python-hosting.com/)
527
* Topographica (http://topographica.org/Home/index.html) (at least they intend to do so)
528
* http://browsershots.org
531
Also notice that the CheeseCake_ kwalitee reporting tool uses pylint to
532
analyze the source code.
534
.. _CheeseCake: http://cheesecake.sourceforge.net/
added
removed
doc/manual.txt
