diff options
Diffstat (limited to 'doc/run.rst')
-rw-r--r-- | doc/run.rst | 114 |
1 files changed, 114 insertions, 0 deletions
diff --git a/doc/run.rst b/doc/run.rst new file mode 100644 index 000000000..7360c3e92 --- /dev/null +++ b/doc/run.rst @@ -0,0 +1,114 @@ +================ + Running Pylint +================ + +Invoking Pylint +--------------- + +Pylint is meant to be called from the command 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 +restrictions. 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 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. + +For more details on this see the Frequently Asked Questions. + +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. + +It is also possible to call Pylint from an other python program, +thanks to ``py_run()`` function in ``lint`` module, +assuming Pylint options are stored in ``pylint_options`` string, as: + +.. sourcecode:: python + + from pylint import epylint as lint + lint.py_run(pylint_options) + +To silently run Pylint on a ``module_name.py`` module, +and get its standart output and error: + +.. sourcecode:: python + + from pylint import epylint as lint + (pylint_stdout, pylint_stderr) = lint.py_run('module_name.py', True) + + +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 or some of its +messages or messages categories by specifying +``--disable=<id>``. If you want to enable only some checkers or some +message ids, first use ``--disable=all`` then +``--enable=<id>`` with <id> being a comma separated list of checker +names and message identifiers. See the list of available features for a +description of provided checkers with their functionalities. +The ``--disable`` and ``--enable`` options can be used with comma separated lists +mixing checkers, message ids and categories like ``-d C,W,E0611,design`` + +It is possible to disable all messages with ``--disable=all``. This is +useful to enable only a few checkers or a few messages by first +disabling everything, and then re-enabling only what you need. + +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. +--list-msgs Generate pylint's messages. +--full-documentation Generate pylint's full documentation, in reST format. +--include_ids=y_or_n Show numeric ids of messages (like 'C0301') +--symbols=y_or_n Show symbolic ids of messsages (like 'line-too-long') + + |