Pylint Quickstart

 

Pylint Quickstart

This document is meant to get you started with Pylint. It assumes that you have installed pylint following the instructions in the README document found in the source documentation.

1. What is pylint?

Pylint is a tool that checks for errors in python code, and tries to check that a given coding standard is respected by the coders. This is similar but nevertheless different from what pychecker provides, especially since pychecker explicitely does not bother with coding style. The default coding style used by pylint is close to Guido's style guide.

Pylint will display a number of errors and warnings as it analyzes the code, as well as some statistics about the number of warnings and errors found in different files. 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.

2. Invoking pylint

Pylint is meant to be called from the commant 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 works 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 FAQ.

3. Pylint output

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

There are several sections in pylint's output.

3.1. Source code analysis section

For each python module, pylint will first display a few '*' characters followed by the name of the module. Then, a number of messages with the following format:

MESSAGE_TYPE: LINE_NUM:[OBJECT:] MESSAGE

The message type can be:

  • [W]arning for stylistinc problems, or minor programming issues

  • [E]rror for important programming issues

  • [F]atal for errors which prevented further processing of the module

Sometimes the line of code which caused the error is displayed with a caret pointing to the error. This should be generalized in furure versions of pylint.

Example (extracted from a run of pylint on itself...):

************* Module logilab.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 branchs (13/12)

3.2. Metrics section

The metrics section displays summaries gathered from the current run.

  • the number of processed modules

  • for each module, the percentage of errors and warnings

  • the total number of errors and warnings

  • percentage of classes, functions and modules with docstrings, and a comparison from the previous run

  • percentage of classes, functions and modules with correct name

  • (according the the coding standard), and a comparison from the previous run

  • a list of external dependencies found in the code, and where they appear

Finally, a global evaluation for the code is computed, and an optional witty comment is displayed (if --comment=y was specified on the command line).

4. Command line options

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

Option Description
--version

show program's version number and exit

-h , --help

show help about the command line options

Pylint is architectured around several checkers. By default all checkers are enabled. You can disable a specific checker by specifying --enable-<checker>=n, or disable all checkers using --disable-all and afterwards enable specific checkers with --enable-<checker>=y. Available checkers are:

basic

checks for :

  • doc strings

  • modules / classes / functions / methods / arguments / variables name

  • number of arguments, local variables, branchs, returns and statements in functions, methods

  • required module attributes

  • dangerous default values as arguments

  • redefinition of function / method / class

  • uses of the global statement

classes

checks for :

  • methods without self as first argument

  • overriden methods signature

  • access only to existant members via self

  • attributes not defined in the __init__ method

  • supported interfaces implementation

  • unreachable code

format

checks for :

  • unauthorized constructions

  • strict indentation

  • line length

imports

checks for

  • external modules dependancies

  • relative / wildcard imports

  • cyclic imports

  • uses of deprecated modules

metrics

does not check anything but gives some raw metrics :

  • total number of lines

  • total number of code lines

  • total number of docstring lines

  • total number of comments lines

  • total number of empty lines

variables

checks for

  • unused variables / imports

  • undefined variables

  • redefinition of variable from builtins or from an outer scope

  • use of variable before assigment

miscellaneous

checks for:

  • source code with non ascii characters but no encoding declaration (PEP 263)

  • warning notes in the code like FIXME, XXX

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:

Option Description
--html

Use HTML as output format instead of text

--zope

Initialize Zope products before starting

--ignore=file

Add <file> (may be a directory) to the black list. It should be a base name, not a path. You may set this option multiple times.

--statistics=y_or_n

Compute statistics on collected data.

--persistent=y_or_n

Pickle collected data for later comparisons.

--comment=y_or_n

Add a comment according to your evaluation note.

5. Bug reports

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. This mailing list is also a nice place to discuss Pylint issues.