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.

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 static global scope. 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.

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

E0602:
  Used when an undefined variable is accessed. This message belongs to the
  variables 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 or 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
~~~~~~~~
C0101:
  Used when a variable has a too short name. This message belongs to the basic
  checker.

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.

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.

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

W0121:
  Used when you use the "global" statement, to discourage its usage. That
  doesn't mean you can not use it ! 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.

W0131:
  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.

W0132:
  Used when a module, function, class or method has an empty docstring (it would
  be to easy ;). 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.



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

E0201:
  Used when an instance member not defined in the instance, its class or its
  ancestors is accessed. This message belongs to the classes checker.

E0202:
  Used when a class defines a method which hide an 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.

E0212:
  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.

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

E0214:
  Used when a metaclass method has an attribute different the "mcs" 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.

F0201:
  Used when PyLint has been unable to fetch a method declared in an interface
  (either in the class or in the interface) and so to check its implementation.
  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.

F0203:
  Used when PyLint has been unable to resolve a name. This message belongs to
  the classes 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.



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.

F0401:
  Used when pylint has been unable to import a module. This message belongs to
  the imports 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.

W0705:
  Used when except clauses are not in the correct order (from the more specific
  to the more generic). 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.



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.



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

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.



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 <> 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.



