path: root/doc/FAQ.txt

.. class:: article

==========================
Frequently Asked Questions
==========================

.. contents::

1. About Pylint
===============

1.1 What is Pylint?
--------------------

Pylint is a `static code checker`_, meaning it can analyse your code without
actually running it. Pylint checks for errors, tries to enforce a coding
standard, and tries to enforce a coding style.

.. _`static code checker`: http://en.wikipedia.org/wiki/Static_code_analysis

1.2 How is Pylint different from Pychecker?
-------------------------------------------

A major difference between Pylint and Pychecker_ is that Pylint checks for
style issues, while Pychecker explicitly does not. There are a few other
differences, such as the fact that Pylint does not import live modules while
Pychecker does (see `6.2 Why does Pychecker catch problems with imports that
Pylint doesn't?`_).

1.3 Who wrote Pylint?
---------------------

Pylint's main author and maintainer is Sylvain Thénault. Pylint's development
is funded by Logilab_. For a full list of contributors, see the "Contributors"
section of Pylint's README file.

.. _Logilab: http://www.logilab.fr/

1.4 Who uses Pylint?
--------------------

In addition to many individuals, the following projects are known to use pylint
to help develop better
code:

* OSAF Chandler (http://www.osafoundation.org/)
* Xen (http://www.xensource.com/)
* CPS (http://www.nuxeo.org)
* ERP5 (http://www.erp5.org/)
* pyxmpp (http://pyxmpp.jabberstudio.org/)
* mercurial
* eXe (http://exelearning.org/)
* PrimaGIS (http://www.primagis.org)
* python-cdd (http://projetos.ossystems.com.br/python-cdd/)
* CDSWare (http://cdsware.cern.ch/)
* ASE (http://dcwww.camp.dtu.dk/campos/ASE/intro.html)
* RunJob (http://projects.fnal.gov/runjob/)
* Slugathon (http://slugathon.python-hosting.com/)
* Topographica (http://topographica.org/Home/index.html) (at least
  they intend to do so)
* http://browsershots.org


2. Installation
===============

2.1 How do I install Pylint?
----------------------------

The easiest way to install Pylint, if you have the setuptools_ package, is to
invoke ::

    easy_install pylint

Otherwise, you'll have to download the source for Pylint and its dependencies
from the Logilab site, or through Pylint's repository. See the user manual for
detailed installation instructions.

.. _setuptools: http://pypi.python.org/pypi/setuptools

2.2 What kind of versioning system does Pylint use?
---------------------------------------------------

Pylint uses the Mercurial_ distributed version control system. The URL of the
repository is:	https://bitbucket.org/logilab/pylint. To get the latest version of
Pylint from the repository, simply invoke ::

    hg clone http://www.logilab.org/hg/pylint

.. _Mercurial: http://mercurial.selenic.com/

2.3 What are Pylint's dependencies?
-----------------------------------

Pylint requires the latest `logilab-astng`_ and `logilab-common`_
packages. It should be compatible with any python version greater than
2.2.0.

.. _`logilab-astng`: http://www.logilab.org/project/logilab-astng
.. _`logilab-common`: http://www.logilab.org/project/logilab-common


3. Running Pylint
=================

3.1 Can I give pylint a file as an argument instead of a module?
-----------------------------------------------------------------

Pylint expects the name of a package or module as its argument. As a
convenience,
you can give 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 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.

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

3.2 Where is the persistent data stored to compare between successive runs?
----------------------------------------------------------------------------

Analysis data are stored as a 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

3.3 How do I find the option name (for pylintrc) corresponding to a specific command line option?
--------------------------------------------------------------------------------------------------------

You can always generate a sample pylintrc file with --generate-rcfile
Every option present on the command line before this will be included in
the rc file

For example::

	pylint --disable=W0702,C0103 --class-rgx='[A-Z][a-z]+' --generate-rcfile

3.4 I'd rather not run Pylint from the command line. Can I integrate it with my editor?
---------------------------------------------------------------------------------------

Yes! Pylint can be integrated with many popular editors and IDEs. The following
include Pylint by default:

* emacs (of course)
* eric3
* eclipse (using the pydev_ plugin, see also
  http://msdl.cs.mcgill.ca/MSDL/people/denis/meetings/pythonDev)

To use pylint from within vim, see
http://www.gonzo.kiev.ua/projects/pylint.vim

To use pylint from within komodo_, see
http://mateusz.loskot.net/2006/01/15/running-pylint-from-komodo/

To use pylint from within gedit_, see
http://live.gnome.org/Gedit/PylintPlugin

To use pylint from within WingIDE_, see
http://www.wingware.com/doc/edit/pylint

.. _pydev: http://pydev.sourceforge.net
.. _komodo: http://www.activestate.com/Products/Komodo/
.. _gedit: http://www.gnome.org/projects/gedit/
.. _WingIDE: http://www.wingware.com/

4. Message Control
==================

4.1 Is it possible to locally disable a particular message?
-----------------------------------------------------------

Yes, this feature has been added in pylint 0.11. This may be done by
adding "#pylint: disable=W0123,E4567" at the desired block level
or at the end of the desired line of code


4.2 Why do I get a lot of spurious "unused variables messages" when using psyobj from psyco_?
----------------------------------------------------------------------------------------------

This is 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 occur with pylint >= 0.5 since from
this version pylint is not looking anymore for information in living
objects (i.e. it no longer imports analysed modules)

.. _psyco: http://psyco.sf.net

4.3 I have a callback function where I have no control over received arguments. How do I avoid getting unused argument warnings?
----------------------------------------------------------------------------------------------------------------------------------

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 names defined in the "dummy-variables" configuration
variable for unused argument ("_" and "dummy" by default).

4.4 Is there a way to disable a message for a particular module only?
---------------------------------------------------------------------

Yes, you can disable or enable (globally disabled) messages at the
module level by adding the corresponding option in a comment at the
top of the file: ::

	# pylint: disable=W0401, E0202
	# pylint: enable=C0302

4.5 What is the format of the configuration file?
---------------------------------------------------

pylint uses ConfigParser from the standard library to parse the configuration file.
It means that if you need to disable a lot of messages, you can use tricks like: ::

    disable= W0401, # because I do not want it
     E0202, # I have a good reason, trust me
     C0302  # that's it

4.6 Do I have to remember all these numbers?
--------------------------------------------

No, starting from 0.25.3, you can use symbolic names for messages::

    # pylint: disable=fixme, line-too-long

You can show these symbols in the output with the `-sy` option.

4.7 How can I tell Pylint to never check a given module?
--------------------------------------------------------

With pylint < 0.25, add "#pylint: disable-all" at the beginning of the
module. Pylint 0.26.1 and up have renamed that directive to
"#pylint: skip-file" (but the first version will be kept for backward
compatibility).

In order to ease finding which modules are ignored a Information-level
message I0013 is emited. With recent versions of Pylint, if you use
the old syntax, an additional I0014 message is emited.



5. Classes and Inheritance
==========================

5.1 When is pylint considering a class as an interface?
-------------------------------------------------------

A class is considered as an interface if there is a class named "Interface"
somewhere in its inheritance tree.

5.2 When is pylint considering that a class is implementing a given interface?
--------------------------------------------------------------------------------

Pylint is using the Zope 2 interfaces conventions, and so is
considering that a class is implementing interfaces listed in its
__implements__ attribute.


5.3 When is pylint considering a class as an abstract class?
-------------------------------------------------------------

A class is considered as an abstract class if at least one of its
methods is doing nothing but raising NotImplementedError.

5.4 How do I avoid "access to undefined member" messages in my mixin classes?
-------------------------------------------------------------------------------

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


6. Troubleshooting
==================

6.1 Pylint gave my code a negative rating out of ten. That can't be right!
--------------------------------------------------------------------------

Even though the final rating Pylint renders is nominally out of ten, there's no
lower bound on it. By default, the formula to calculate score is ::

    10.0 - ((float(5 * error + warning + refactor + convention) / statement) * 10)

However, this option can be changed in the pylint rc file. If having negative
values really bugs you, you can set the formula to be the minimum of 0 and the
above expression.


6.2 Why does Pychecker catch problems with imports that Pylint doesn't?
------------------------------------------------------------------------

pychecker and pylint use different approaches.  pychecker
imports the modules and rummages around in the result, hence it sees my
mangled sys.path.  pylint doesn't import any of the candidate modules and
thus doesn't include any of import's side effects (good and bad).  It
traverses an AST representation of the code.

6.3 I think I found a bug in Pylint. What should I do?
-------------------------------------------------------

First, you might wish to check Pylint's ticketing system (the 'Issues' tab at
https://bitbucket.org/logilab/pylint), to make sure it hasn't been reported
already. If it hasn't, please create a new issue there.

6.4 I have a question about Pylint that isn't answered here.
------------------------------------------------------------

The python-projects@logilab.org mailing list is a great place to discuss and
ask questions about Pylint. 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
http://lists.logilab.org/mailman/listinfo/python-projects

Archives are available at
http://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: http://lists.logilab.org/mailman/listinfo/forum-fr
* archives: http://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.

.. _pychecker: http://pychecker.sf.net