path: root/doc/features.txt

PyLint features
===============

.. contents::

Master
------

Description
~~~~~~~~~~~
lint Python modules using external checkers.

This is the main checker controling the other ones and the reports
generation. It is itself both a raw checker and an astng checker in order
to:
* handle message activation / deactivation at the module level
* handle some basic but necessary stats'data (number of classes, methods...)

This checker also defines the following reports:
* R0001: Total errors / warnings
* R0002: % errors / warnings by module
* R0003: Messages
* R0004: Global evaluation

Messages
~~~~~~~~
I0001:
  Used to inform that a built-in module has not been checked using the raw
  checkers. This message belongs to the master checker.

I0010:
  Used when an inline option is either badly formatted or can't be used inside
  modules. This message belongs to the master checker.

I0011:
  Used when an inline option disable a message or a messages category. This
  message belongs to the master checker.

I0012:
  Used when an inline option enable a message or a messages category. This
  message belongs to the master checker.

E0001:
  Used when a syntax error is raised for a module. This message belongs to the
  master checker.

E0011:
  Used when an unknown inline option is encountered. This message belongs to the
  master checker.

E0012:
  Used when an bad value for an inline option is encountered. This message
  belongs to the master checker.

F0001:
  Used when an error occured preventing the analyzing of a module (unable to
  find it for instance). This message belongs to the master checker.

F0002:
  Used when an unexpected error occured while building the ASTNG representation.
  This is usually accomopagned by a traceback. Please report such errors ! This
  message belongs to the master checker.

F0003:
  Used to indicate that the user asked to analyze a builtin module which has
  been skipped. This message belongs to the master checker.



Variables
---------

Description
~~~~~~~~~~~
checks for
* unused variables / imports
* undefined variables
* redefinition of variable from builtins or from an outer scope
* use of variable before assigment


Messages
~~~~~~~~
W0601:
  Used when a variable is defined through the "global" statement but the
  variable is not defined in the module scope. This message belongs to the
  variables checker.

W0602:
  Used when a variable is defined through the "global" statement but no
  assigment to this variable is done. This message belongs to the variables
  checker.

W0603:
  Used when you use the "global" statement to update a global variable. PyLint
  just try to discourage this usage. That doesn't mean you can not use it ! This
  message belongs to the variables checker.

W0604:
  Used when you use the "global" statement at the module level since it has no
  effect This message belongs to the variables checker.

W0611:
  Used when an imported module or variable is not used. This message belongs to
  the variables checker.

W0612:
  Used when a variable is defined but not used. This message belongs to the
  variables checker.

W0613:
  Used when a function or method argument is not used. This message belongs to
  the variables checker.

W0621:
  Used when a variable's name hide a name defined in the outer scope. This
  message belongs to the variables checker.

W0622:
  Used when a variable or function override a built-in. This message belongs to
  the variables checker.

W0631:
  Used when an loop variable (i.e. defined by a for loop or a list comprehension
  or a generator expression) is used outside the loop. This message belongs to
  the variables checker.

E0601:
  Used when a local variable is accessed before it's assignment. This message
  belongs to the variables checker.

E0602:
  Used when an undefined variable is accessed. This message belongs to the
  variables checker.

E0611:
  Used when a name cannot be found in a module. This message belongs to the
  variables checker.



Typecheck
---------

Description
~~~~~~~~~~~
try to find bugs in the code using type inference


Messages
~~~~~~~~
W1111:
  Used when an assigment is done on a function call but the infered function
  returns nothing but None. This message belongs to the typecheck checker.

E1101:
  Used when a class is accessed for an unexistant member. This message belongs
  to the typecheck checker.

E1102:
  Used when an object being called has been infered to a non callable object
  This message belongs to the typecheck checker.

E1111:
  Used when an assigment is done on a function call but the infered function
  doesn't return anything. This message belongs to the typecheck checker.



Basic
-----

Description
~~~~~~~~~~~
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

This checker also defines the following reports:
* R0101: Statistics by type

Messages
~~~~~~~~
C0102:
  Used when the name is listed in the black list (unauthorized names). This
  message belongs to the basic checker.

C0103:
  Used when the name doesn't match the regular expression associated to its type
  (constant, variable, class...). This message belongs to the basic checker.

C0111:
  Used when a module, function, class or method has no docstring. Some special
  methods like __init__ doesn't necessary require a docstring. This message
  belongs to the basic checker.

C0112:
  Used when a module, function, class or method has an empty docstring (it would
  be to easy ;). This message belongs to the basic checker.

C0121:
  Used when an attribute required for modules is missing. This message belongs
  to the basic checker.

W0101:
  Used when there is some code behind a "return" or "raise" statement, which
  will never be accessed. This message belongs to the basic checker.

W0102:
  Used when a mutable value as list or dictionary is detected in a default value
  for an argument. This message belongs to the basic checker.

W0104:
  Used when a statement doesn't have (or at least seems to) any effect. This
  message belongs to the basic checker.

W0122:
  Used when you use the "exec" statement, to discourage its usage. That doesn't
  mean you can not use it ! This message belongs to the basic checker.

W0141:
  Used when a black listed builtin function is used (see the bad-function
  option). Usual black listed functions are the ones like map, or filter , where
  Python offers now some cleaner alternative like list comprehension. This
  message belongs to the basic checker.

W0142:
  Used when a function or method is called using `*args` or `**kwargs` to
  dispatch arguments. This doesn't improve readility and should be used with
  care. This message belongs to the basic checker.

E0101:
  Used when the special class method __ini__ has an explicit return value. This
  message belongs to the basic checker.

E0102:
  Used when a function / class / method is redefined. This message belongs to
  the basic checker.

E0103:
  Used when break or continue keywords are used outside a loop. This message
  belongs to the basic checker.



Classes
-------

Description
~~~~~~~~~~~
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


Messages
~~~~~~~~
C0202:
  Used when a class method has an attribute different than "cls" as first
  argument, to easily differentiate them from regular instance methods. This
  message belongs to the classes checker.

C0203:
  Used when a metaclass method has an attribute different the "mcs" as first
  argument. This message belongs to the classes checker.

R0201:
  Used when a method doesn't use its bound instance, and so could be written as
  a function. This message belongs to the classes checker.

W0201:
  Used when an instance attribute is defined outside the __init__ method. This
  message belongs to the classes checker.

W0211:
  Used when a static method has "self" or "cls" as first argument. This message
  belongs to the classes checker.

W0221:
  Used when a method has a different number of arguments than in the implemented
  interface or in an overriden method. This message belongs to the classes
  checker.

W0222:
  Used when a method signature is different than in the implemented interface or
  in an overriden method. This message belongs to the classes checker.

W0223:
  Used when an abstract method (ie raise NotImplementedError) is not overriden
  in concrete class. This message belongs to the classes checker.

W0231:
  Used when an ancestor class method has an __init__ method which is not called
  by a derived class. This message belongs to the classes checker.

W0232:
  Used when a class has no __init__ method, neither its parent classes. This
  message belongs to the classes checker.

W0233:
  Used when an __init__ method is called on a class which is not in the direct
  ancestors for the analysed class. This message belongs to the classes checker.

E0202:
  Used when a class defines a method which is hiden by an instance attribute
  from an ancestor class. This message belongs to the classes checker.

E0203:
  Used when an instance member is accessed before it's actually assigned. This
  message belongs to the classes checker.

E0211:
  Used when a method which should have the bound instance as first argument has
  no argument defined. This message belongs to the classes checker.

E0213:
  Used when a method has an attribute different the "self" as first argument.
  This message belongs to the classes checker.

E0221:
  Used when a class claims to implement an interface which is not a class. This
  message belongs to the classes checker.

E0222:
  Used when a method declared in an interface is missing from a class
  implementing this interface This message belongs to the classes checker.

F0202:
  Used when PyLint has been unable to check methods signature compatibility for
  an unexpected raison. Please report this kind if you don't make sense of it.
  This message belongs to the classes checker.

F0220:
  Used when a PyLint as failed to find interfaces implemented by a class This
  message belongs to the classes checker.



Imports
-------

Description
~~~~~~~~~~~
checks for
* external modules dependencies
* relative / wildcard imports
* cyclic imports
* uses of deprecated modules

This checker also defines the following reports:
* R0401: External dependencies
* R0402: Modules dependencies graph

Messages
~~~~~~~~
R0401:
  Used when a cyclic import between two or more modules is detected. This
  message belongs to the imports checker.

W0401:
  Used when `from module import *` is detected. This message belongs to the
  imports checker.

W0402:
  Used a module marked as deprecated is imported. This message belongs to the
  imports checker.

W0403:
  Used when an import relative to the package directory is detected. This
  message belongs to the imports checker.

W0404:
  Used when a module is reimported multiple times. This message belongs to the
  imports checker.

W0406:
  Used when a module is importing itself. This message belongs to the imports
  checker.

W0410:
  Python 2.5 and greater require __future__ import to be the first non docstring
  statement in the module. This message belongs to the imports checker.

F0401:
  Used when pylint has been unable to import a module. This message belongs to
  the imports checker.



Newstyle
--------

Description
~~~~~~~~~~~
checks for usage of new style capabilities on old style classes and
other new/old styles conflicts problems
* use of property, __slots__, super
* "super" usage
* raising a new style class as exception


Messages
~~~~~~~~
W1001:
  Used when PyLint detect the use of the builtin "property" on an old style
  class while this is relying on new style classes features This message belongs
  to the newstyle checker.

W1010:
  Used when a custom exception class is raised but doesn't inherit from the
  builtin "Exception" class. This message belongs to the newstyle checker.

E1001:
  Used when an old style class use the __slots__ attribute. This message belongs
  to the newstyle checker.

E1002:
  Used when an old style class use the super builtin. This message belongs to
  the newstyle checker.

E1003:
  Used when another argument than the current class is given as first argument
  of the super builtin. This message belongs to the newstyle checker.

E1010:
  Used when a new style class is raised since it's not yet possible. This
  message belongs to the newstyle checker.



Design
------

Description
~~~~~~~~~~~
checks for sign of poor/misdesign:
* number of methods, attributes, local variables...
* size, complexity of functions, methods


Messages
~~~~~~~~
R0901:
  Used when class has too many parent classes. This message belongs to the
  design checker.

R0902:
  Used when class has too many instance attributes. This message belongs to the
  design checker.

R0903:
  Used when class has not enough public methods. This message belongs to the
  design checker.

R0904:
  Used when class has too many public methods. This message belongs to the
  design checker.

R0911:
  Used when a function or method has too many return statement. This message
  belongs to the design checker.

R0912:
  Used when a function or method has too many branches. This message belongs to
  the design checker.

R0913:
  Used when a function or method takes too many arguments. This message belongs
  to the design checker.

R0914:
  Used when a function or method has too many local variables. This message
  belongs to the design checker.

R0915:
  Used when a function or method has too many statements. You should then split
  it in smaller functions / methods. This message belongs to the design checker.

R0921:
  Used when an abstract class is not used as ancestor anywhere. This message
  belongs to the design checker.

R0922:
  Used when an abstract class is used less than X times as ancestor. This
  message belongs to the design checker.

R0923:
  Used when an interface class is not implemented anywhere. This message belongs
  to the design checker.



Exceptions
----------

Description
~~~~~~~~~~~
checks for
* excepts without exception filter
* string exceptions


Messages
~~~~~~~~
W0701:
  Used when a string exception is raised. This message belongs to the exceptions
  checker.

W0702:
  Used when an except clause doesn't specify exceptions type to catch. This
  message belongs to the exceptions checker.

W0703:
  Used when an except catch Exception instances. This message belongs to the
  exceptions checker.

W0704:
  Used when an except clause does nothing but "pass" and there is no "else"
  clause. This message belongs to the exceptions checker.

W0706:
  Used when a variable used to raise an exception is initially assigned to a
  value which can't be used as an exception. This message belongs to the
  exceptions checker.

E0701:
  Used when except clauses are not in the correct order (from the more specific
  to the more generic). If you don't fix the order, some exceptions may not be
  catched by the most specific handler. This message belongs to the exceptions
  checker.

E0702:
  Used when something which is neither a class, an instance or a string is
  raised (i.e. a `TypeError` will be raised). This message belongs to the
  exceptions checker.



Metrics
-------

Description
~~~~~~~~~~~
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

This checker also defines the following reports:
* R0701: Raw metrics

Similarities
------------

Description
~~~~~~~~~~~
checks for similarities and duplicated code. This computation may be
memory / CPU intensive, so you should disable it if you experiments some
problems.

This checker also defines the following reports:
* R0801: Duplication

Messages
~~~~~~~~
R0801:
  Indicates that a set of similar lines has been detected among multiple file.
  This usually means that the code should be refactored to avoid this
  duplication. This message belongs to the similarities checker.



Format
------

Description
~~~~~~~~~~~
checks for :
* unauthorized constructions
* strict indentation
* line length
* use of <> instead of !=


Messages
~~~~~~~~
C0301:
  Used when a line is longer than a given number of characters. This message
  belongs to the format checker.

C0321:
  Used when more than on statement are found on the same line. This message
  belongs to the format checker.

C0322:
  Used when one of the following operator (!= | <= | == | >= | < | > | = | \+= |
  -= | \*= | /= | %) is not preceded by a space. This message belongs to the
  format checker.

C0323:
  Used when one of the following operator (!= | <= | == | >= | < | > | = | \+= |
  -= | \*= | /= | %) is not followed by a space. This message belongs to the
  format checker.

C0324:
  Used when a comma (",") is not followed by a space. This message belongs to
  the format checker.

W0302:
  Used when a module has too much lines, reducing its readibility. This message
  belongs to the format checker.

W0311:
  Used when an unexpected number of indentation's tabulations or spaces has been
  found. This message belongs to the format checker.

W0312:
  Used when there are some mixed tabs and spaces in a module. This message
  belongs to the format checker.

W0331:
  Used when the deprecated "<>" operator is used instead of "!=". This message
  belongs to the format checker.

W0332:
  Used when a lower case "l" is used to mark a long integer. You should use a
  upper case "L" since the letter "l" looks too much like the digit "1" This
  message belongs to the format checker.

F0321:
  Used when an unexpected error occured in bad format detection. Please report
  the error if it occurs. This message belongs to the format checker.



Miscellaneous
-------------

Description
~~~~~~~~~~~
checks for:
* warning notes in the code like FIXME, XXX
* PEP 263: source code with non ascii character but no encoding declaration


Messages
~~~~~~~~
W0511:
  Used when a warning note as FIXME or XXX is detected. This message belongs to
  the miscellaneous checker.

E0501:
  Used when some non ascii characters are detected but now encoding is
  specified, as explicited in the PEP 263. This message belongs to the
  miscellaneous checker.

E0502:
  Used when a known encoding is specified but the file doesn't seem to be
  actually in this encoding. This message belongs to the miscellaneous checker.

E0503:
  Used when an encoding is specified, but it's unknown to Python. This message
  belongs to the miscellaneous checker.