Pylint User Manual

What is pylint?

Pylint is a tool that checks for errors in python code, tries to enforce a coding standard and looks for smelling code. This is similar but nevertheless different from what pychecker provides, especially since pychecker explicitly does not bother with coding style. The default coding style used by pylint is close to PEP 008 (aka Guido's style guide). For more information about code smells, refer to Martin Fowler's refactoring book

One important thing to note is that Pylint isn't smarter than you are: it may warn you about things that you have conscientiously done. That's for example because it tries to detect things that may be dangerous in a context, but maybe not in others, or because it checks for some things that you don't care about. Generally, you shouldn't expect pylint to be totally quiet about your code, so don't necessarily be alarmed if it gives you a hell lot of messages for your proudly(XXX) project ;)

Pylint will display a number of messages as it analyzes the code, as well as some statistics about the number of warnings and errors found in different files. The messages are classified under various categories such as errors and warnings (more below). If you run pylint twice, it will display the statistics from the previous run together with the ones from the current run, so that you can see if the code has improved or not.

Last but not least, the code is given an overall mark, based on the number an severity of the warnings and errors. This has proven to be very motivating for programmers.

Installation

deb download.logilab.org/production unstable/
deb download.logilab.org/production sid/
deb download.logilab.org/production squeeze/
deb download.logilab.org/production lenny/

python setup.py install

pylint.bat [options] module_or_package

pylint [options] module_or_package

C:\PythonDirectory\Scripts\pylint.bat

Invoking pylint

Pylint is meant to be called from the command line. The usage is

pylint [options] module_or_package

You should give pylint the name of a Python package or module. Pylint will import this package or module, so you should pay attention to your PYTHONPATH, since it is a common error to analyze an installed version of a module instead of the development version.

It is also possible to analyze python files, with a few restriction. The thing to keep in mind is that pylint will try to convert the file name to a module name, and only be able to process the file if it succeeds.

pylint mymodule.py

should always work since the current working directory is automatically added on top of the python path

pylint directory/mymodule.py

will work if "directory" is a python package (i.e. has an __init__.py file) or if "directory" is in the python path.

For more details on this see the Frequently Asked Questions.

You can also start a thin gui around pylint (require TkInter) by typing

pylint-gui

This should open a window where you can enter the name of the package or module to check, at pylint messages will be displayed in the user interface.

It is also possible to call Pylint from an other Python program, thanks to py_run() function in lint module, assuming Pylint options are stored in pylint_options string, as

from pylint import lint
lint.py_run( pylint_options)

To silently run Pylint on a module_name.py module, and get its standart output and error:

from pylint import lint
(pylint_stdout, pylint_stderr) = lint.py_run( 'module_name.py', True)

Pylint output

The default format for the output is raw text. But passing pylint the --output-format=html or -h y or -o html option will produce an HTML document.

There are several sections in pylint's output.

MESSAGE_TYPE: LINE_NUM:[OBJECT:] MESSAGE

************* Module pylint.checkers.format
W: 50: Too long line (86/80)
W:108: Operator not followed by a space
     print >>sys.stderr, 'Unable to match %r', line
            ^
W:141: Too long line (81/80)
W: 74:searchall: Unreachable code
W:171:FormatChecker.process_tokens: Redefining built-in (type)
W:150:FormatChecker.process_tokens: Too many local variables (20/15)
W:150:FormatChecker.process_tokens: Too many branches (13/12)

Command line options

First of all, we have two basic (but useful) options.

Pylint is architectured around several checkers. By default all checkers are enabled. You can disable a specific checker or some of its messages or messages categories by specifying --disable=<id>. A more general disable can be enabled with or disable all checkers using --enable=w<id>. See the list of available features for a description of provided checkers with their functionalities. The --disable and --enable options can be used with comma separated lists mixing checkers, message ids and categories like -d C,W,E0611,design

Each checker has some specific options, which can take either a yes/no value, an integer, a python regular expression, or a comma separated list of values (which are generally used to override a regular expression in special cases). For a full list of options, use --help

Specifying all the options suitable for your setup and coding standards can be tedious, so it is possible to use a rc file to specify the default values. Pylint looks for /etc/pylintrc and ~/.pylintrc. The --generate-rcfile option will generate a commented configuration file according to the current configuration on standard output and exit. You can put other options before this one to use them in the configuration, or start with the default values and hand tune the configuration.

Other useful global options include:

Daily pylint usage

What pylint says is not to be taken as gospel. While getting as few false positives for errors as possible is a goal for us -- and python makes it hard enough, it is not the case for warnings.

Bug reports, feedback

You think you have found a bug in Pylint? Well, this may be the case since Pylint is under development. Please take the time to send a bug report to python-projects@logilab.org if you've not found it already reported on the tracker page. This mailing list is also a nice place to discuss Pylint issues, see below for more information about pylint's related lists.

You can check for already reported bugs, planned features on pylint's tracker web page: www.logilab.org/project/name/pylint

Notice that if you don't find something you have expected in pylint's tracker page, it may be on the tracker page of one of its dependencies, namely astng and common:

• www.logilab.org/project/name/logilab-astng
• www.logilab.org/project/name/logilab-common

Mailing lists

Use the python-projects@logilab.org mailing list for anything related to Pylint. This is in most cases better than sending an email directly to the author, since others will benefit from the exchange, and you'll be more likely answered by someone subscribed to the list. This is a moderated mailing list, so if you're not subscribed email you send will have to be validated first before actually being sent on the list.

You can subscribe to this mailing list at lists.logilab.org/mailman/listinfo/python-projects

Archives are available at lists.logilab.org/pipermail/python-projects/

If you prefer speaking french instead of english, you can use the generic forum-fr@logilab.org mailing list:

• (un)subscribe: lists.logilab.org/mailman/listinfo/forum-fr
• archives: lists.logilab.org/pipermail/forum-fr

Notice though that this list has a very low traffic since most pylint related discussions are done on the python-projects mailing list.

Base configuration

To be written...

Environment

To be written...

Messages control

An example available from the examples directory:

"""pylint option block-disable"""

__revision__ = None

class Foo(object):
    """block-disable test"""

    def __init__(self):
        pass

    def meth1(self, arg):
        """this issues a message"""
        print self

    def meth2(self, arg):
        """and this one not"""
        # pylint: disable=W0613
        print self\
              + "foo"

    def meth3(self):
        """test one line disabling"""
        # no error
        print self.bla # pylint: disable=E1101
        # error
        print self.blop

    def meth4(self):
        """test re-enabling"""
        # pylint: disable=E1101
        # no error
        print self.bla
        print self.blop
        # pylint: enable=E1101
        # error
        print self.blip

    def meth5(self):
        """test IF sub-block re-enabling"""
        # pylint: disable=E1101
        # no error
        print self.bla
        if self.blop:
            # pylint: enable=E1101
            # error
            print self.blip
        else:
            # no error
            print self.blip
        # no error
        print self.blip

    def meth6(self):
        """test TRY/EXCEPT sub-block re-enabling"""
        # pylint: disable=E1101
        # no error
        print self.bla
        try:
             pylint: enable=E1101
            # error
            print self.blip
        except UndefinedName: # pylint: disable=E0602
            # no error
            print self.blip
        # no error
        print self.blip

    def meth7(self):
        """test one line block opening disabling"""
        if self.blop: # pylint: disable=E1101
            # error
            print self.blip
        else:
            # error
            print self.blip
        # error
        print self.blip


    def meth8(self):
        """test late disabling"""
        # error
        print self.blip
        # pylint: disable=E1101
        # no error
        print self.bla
        print self.blop

Pylint heuristics

To be written...

About astng inference

To be written...

Writing your own checker

You can find some simple examples in the examples directory of the distribution (custom.py and custom_raw.py). I'll try to quickly explain the essentials here.

First, there are two kinds of checkers : * raw checkers, which are analysing each module as a raw file stream * ast checkers, which are working on an ast representation of the module

The ast representation used is an extension of the one provided with the standard python distribution in the compiler package. The extension adds additional information and methods on the tree nodes to ease navigation and code introspection.

An AST checker is a visitor, and should implement visit_<lowered class name> leave_<lowered class name> methods for the nodes it's interested in. To get description of the different classes used in an ast tree, look at the compiler.ast documentation. Checkers are ordered by priority. For each module, pylint's engine:

1. give the module source file as a stream to raw checkers
2. get an ast representation for the module
3. make a depth first descent of the tree, calling visit_<> on each AST checker when entering a node, and living_<> on the back traversal

Notice that the source code is probably the best source of documentation, it should be clear and well documented. Don't hesitate to ask for any information on the python-projects mailing list.

Contribute !

All our software is developped using the mercurial version control system. This is a very cool distributed vcs and its usage is very similar to other ones such as cvs or subversion (though the distributed feature introduced some different usage patterns).