forget the past.

forget the past.

4 files changed, 1084 insertions, 0 deletions

diff --git a/doc/FAQ.txt b/doc/FAQ.txt
new file mode 100644
index 000000000..b28f83ef9
--- /dev/null
+++ b/doc/FAQ.txt
@@ -0,0 +1,154 @@
+Frequently Asked Questions / Usage tips for PyLint
+==================================================
+
+
+Question:
+  Is it possible to give file as argument to pylint, instead of module ?
+
+Answer:
+  pylint expects the name of a package or module as argument. As a convenience,
+  you can give to it a file name if it's possible to guess a module name from
+  the file's path, using the python path. Some examples :
+
+  "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.
+
+  "pylint /whatever/directory/mymodule.py" will work if either:
+
+    - "/whatever/directory" is in the python path
+
+    - your cwd is "/whatever/directory"
+
+    - "directory" is a python package and "/whatever" is in the python
+      path
+
+    - "directory" is a python package and your cwd is "/whatever"
+      and so on...
+
+
+
+Question:
+  I'm using psyobj from psyco_ and get a lot of spurious "unused variables
+  messages". Is it normal ?
+
+Answer: 
+  Yes. That's actually due to a bug in psyco, making the locals()
+  function for objects inheriting from *psyobj* returning an empty
+  dictionary. For the moment, the only way to fix this is to use the
+  PYLINT_IMPORT environment variable to not use psyco during pylint
+  checking. Sample code ::
+
+    import os
+    try:
+        if os.environ.has_key('PYLINT_IMPORT'):
+            raise ImportError()
+	from psyco.classes import psyobj
+    except ImportError:
+	    class psyobj:
+	        pass
+
+  NOTICE: this problem should not occurs with pylint >= 0.5 since from
+  this version pylint is not looking anymore for information in living
+  objects (i.e. it doesn't anymore import analysed modules)
+
+
+
+Question:
+  I've a function / method which is a callback where I do not have any
+  control on received argument, and pylint is complaining about unused
+  arguments. What can I do to avoid those warnings ?
+
+Answer:
+  prefix (ui) the callback's name by `cb_`, as in cb_onclick(...). By
+  doing so arguments usage won't be checked. Another solution is to
+  use one of the name defined in the "dummy-variables" configuration
+  variable for unused argument ("_" and "dummy" by default).
+
+
+
+Question:
+  When pylint is considering a class as an interface ?
+
+Answer:
+  A class is considered as an interface if there is a class named
+  "Interface" somewhere in it ancestor's tree.
+
+
+
+Question:
+  When pylint is considering that a class is implementing a given
+  interface ?
+
+Answer:
+  Pylint is using the Zope 2 interfaces conventions, and so is
+  considering that a class is implementing interfaces listed in its
+  __implements__ attribute.
+
+
+
+Question:
+  When pylint is considering a class as an abstract class ?
+
+Answer:
+  A class is considered as an abstract class if at least one of its
+  methods is doing nothing but raising NotImplementedError
+
+
+
+Question:
+  Is there some way to disable some message for a particular module
+  only ?
+
+Answer:
+  Yes, you can disable or enable (globally disabled) message at the
+  module level by adding the corresponding option in a comment at the
+  top of the file: ::
+
+    # pylint: disable-msg=W0401, E0202
+    # pylint: enable-msg=C0302
+
+
+
+Question:
+  I've a mixin class relying on attributes of the mixed class, and I
+  would like to not have the "access to undefined member" message on
+  this class. Is it possible ?
+
+Answer:
+  Yes :o) To do so you have to set the ignore-mixin-members option to
+  "yes" (this is the default value) and to name your mixin class with
+  a name which ends with "mixin" (whatever case)
+
+
+
+Question:
+  Is it possible to locally disabling a particular message for a block
+  of code or for a single line of code ?
+Answer:
+  Yes, this feature has been added in pylint 0.11. This may be done by
+  adding "#pylint: disable-msg=W0123,E4567" at the desired block level
+  or at the end of the desired line of code
+
+
+
+Question:
+  Where are stored persistent data necessary to make comparison between
+   to successive run ?
+
+Answer:
+  Analysis data are stored as pickle file in a directory which is 
+  localized using the following rules:
+
+  * value of the PYLINTHOME environment variable if set
+
+  * ".pylint.d" subdirectory of the user's home directory if it is found
+    (not always findable on Windows platforms)
+
+  * ".pylint.d" directory in the current directory
+
+
+.. _psyco: http://psyco.sf.net
diff --git a/doc/features.txt b/doc/features.txt
new file mode 100644
index 000000000..2cc41e0f8
--- /dev/null
+++ b/doc/features.txt
@@ -0,0 +1,678 @@
+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.
+
+
+
+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.
+
+
+
+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.
+
+
+
+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.
+
+
+
+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.
+
+
+
+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.
+
+
+
+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.
+
+
+
+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
+
diff --git a/doc/makefile b/doc/makefile
new file mode 100644
index 000000000..944893ef8
--- /dev/null
+++ b/doc/makefile
@@ -0,0 +1,36 @@
+MKHTML=mkdoc
+MKHTML_OPT=--doctype article --param toc.section.depth=1  --target html --stylesheet single-file
+
+SRC=.
+
+
+all: quickstart.html features.html FAQ.html examples man
+
+FAQ.html: ${SRC}/FAQ.txt
+	${MKHTML} ${MKHTML_OPT} ${SRC}/FAQ.txt
+
+quickstart.html: ${SRC}/quickstart.txt
+	${MKHTML} ${MKHTML_OPT} ${SRC}/quickstart.txt
+
+features.html:
+	chmod u+w ${SRC}/features.txt
+	echo "PyLint features" > ${SRC}/features.txt
+	echo "===============" >> ${SRC}/features.txt
+	echo "" >> ${SRC}/features.txt
+	echo ".. contents::" >> ${SRC}/features.txt
+	echo "" >> ${SRC}/features.txt
+	pylint --list-msgs >> ${SRC}/features.txt
+	${MKHTML} ${MKHTML_OPT} ${SRC}/features.txt
+
+examples:
+	chmod u+w ../examples/pylintrc
+	pylint --generate-rcfile > ../examples/pylintrc
+
+man:
+	chmod u+w ../man/pylint.1
+	pylint --generate-man > ../man/pylint.1
+
+clean:
+	rm -f *.html
+
+.PHONY: features.html
diff --git a/doc/quickstart.txt b/doc/quickstart.txt
new file mode 100644
index 000000000..042d377cf
--- /dev/null
+++ b/doc/quickstart.txt
@@ -0,0 +1,216 @@
+=================
+Pylint Quickstart
+=================
+
+:Author: Alexandre Fayolle
+:Organization: Logilab
+:Version: $Revision: 1.10 $
+:Date: $Date: 2005-04-15 10:40:17 $
+
+.. contents::
+
+
+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.
+
+
+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 explicitely does not bother with coding
+style. The default coding style used by pylint is close to 
+`Guido's style guide`_. For more information about code smells, refer
+to Martin Fowler's `refactoring book`_
+
+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.
+
+
+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_.
+
+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.
+
+
+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. 
+
+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
+
+You can get another output format, useful since it's recognized by
+most editors or other development tools using the ``--parseable=y``
+option.
+
+The message type can be:
+
+  * [R]efactor for a "good practice" metric violation
+  * [C]onvention for coding standard violation
+  * [W]arning for stylistic problems, or minor programming issues
+  * [E]rror for important programming issues (i.e. most probably bug)
+  * [F]atal for errors which prevented further processing
+
+Sometimes the line of code which caused the error is displayed with
+a caret pointing to the error. This may be generalized in future
+versions of pylint.
+
+Example (extracted from a run of pylint on itself...): 
+
+::
+
+  ************* 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 branchs (13/12)
+
+
+Reports section
+''''''''''''''' 
+
+Following the analysis message, pylint will display a set of report,
+each one focusing on a particular aspect of the project, such as number
+of messages by categories, modules dependancies...
+
+For instance, the metrics report 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
+
+Also, a global evaluation for the code is computed, and an
+optional witty comment is displayed (if ``--comment=y`` was
+specified on the command line).
+
+
+Command line options
+--------------------
+
+First of all, we have two basic (but useful) options. 
+
+--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``. See the list of available features_ for a
+description of provided checkers with their functionalities.
+
+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:
+
+--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.
+--parseable=y_or_n      Use a parseable output format.
+--html=y_or_n           Use HTML as output format instead of text.
+--enable-msg=msgids     Enable the given messages.
+--disable-msg=msgids    Disable the given messages.
+--enable-msg-cat=cats   Enable all messages in the given categories.
+--disable-msg-cat=cats  Disable all messages in the given categories.
+
+
+
+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.
+
+
+.. _pychecker: http://pychecker.sf.net
+.. _features: features.html
+.. _FAQ: FAQ.html
+.. _`Guido's style guide`: http://www.python.org/doc/essays/styleguide.html
+.. _`refactoring book`: http://www.refactoring.com/