pylint & jenkins

利用pylint 检测 python源码。

Pylint 提供了简单的方式来分析 Python 代码，其高可配置性很容易使一个部门的人员使用统一的代码风格。

Pylint 是什么

Pylint 是一个 Python 代码分析工具，它分析 Python 代码中的错误，查找不符合代码风格标准（Pylint 默认使用的代码风格是 PEP 8，具体信息，请参阅参考资料）和有潜在问题的代码。目前 Pylint 的最新版本是 pylint-0.18.1。

• Pylint 是一个 Python 工具，除了平常代码分析工具的作用之外，它提供了更多的功能：如检查一行代码的长度，变量名是否符合命名标准，一个声明过的接口是否被真正实现等等。
• Pylint 的一个很大的好处是它的高可配置性，高可定制性，并且可以很容易写小插件来添加功能。
• 如果运行两次 Pylint，它会同时显示出当前和上次的运行结果，从而可以看出代码质量是否得到了改进。
• 目前在 eclipse 的 pydev 插件中也集成了 Pylint。

Pylint 的最新包下载：http://www.logilab.org/project/pylint

Pylint 的安装

Pylint 可以用于所有高于或者等于 2.2 的 Python 版本兼容。需要 logilab-astng（version >= 0.14）和 logilab-common（version >= 0.13）的包（具体信息，请参阅 参考资料），如果是 Python 版本低于 2.3，那么它还需要 optik 包（本文接下来的示例暂不考虑这种情况）。

Pylint 所用到的所有的包的下载地址

logilab-astng 的最新包下载：http://www.logilab.org/856/

logilab-common 的最新包下载：http://www.logilab.org/848/

optik 的包下载：http://optik.sourceforge.net/

Pylint 的最新包下载：http://www.logilab.org/project/pylint

Pylint 在 Linux 上的安装

1. 在 Linux 上，首先安装 Python 的包（高于版本 2.2），并在环境变量 $PATH 中添加 Python 可执行文件的路径。

2. 下载 Pylint、logilab-astng (version >= 0.14) 和 logilab-common (version >= 0.13) 的包 , 使用 tar zxvf *.tar.gz解压缩这些包。

3. 依次进入 logilab-astng、logilab-common 和 Pylint 解开的文件夹中，运行命令 Python setup.py install来安装。

4. 安装完成后，就可以通过 pylint [options] module_or_package来调用 Pylint 了。

Pylint 在 Windows 上的安装

1. 安装 Python 的包（高于版本 2.2），右键单击桌面上的我的电脑图标，选择属性，高级，环境变量，在 $PATH 中添加 Python 的安装路径，如 C:\Python26\。

2. 使用解压缩工具解压缩所有的包。

3. 打开命令行窗口，使用 cd依次进入 logilab-astng、logilab-common 和 Pylint 解开的文件夹中，运行命令 python setup.py install来安装。

4. 安装完成后，在 Python 的安装路径下出现一个 Scripts 文件夹，里面包含一些 bat 脚本，如 pylint.bat 等。

5. 为了使调用 pylint.bat 的时候不需要输入完整路径，在 Python 的安装目录下创建 pylint.bat 的重定向文件，这是一个纯文本文件 pylint.bat，里面包含 pylint.bat 的实际路径，如：C:\Python26\Scripts\pylint.bat。

6. 安装完成后，可以通过 pylint [options] module_or_package来调用 Pylint 了。

命令

　　使用命令 pylint --help 或 man pylint 查看更详细的用法。

Usage:  pylint [options] module_or_package

  Check that a module satisfies a coding standard (and more !).

    pylint --help

  Display this help message and exit.

    pylint --help-msg <msg-id>[,<msg-id>]

  Display help messages about given message identifiers and exit.

Options:
  --version             show program's version number and exit
  -h, --help            show this help message and exit
　　　　　　　　　　　　　　显示所有帮助信息。
  --long-help           more verbose help.

  Master:
    --rcfile=<file>     Specify a configuration file.
　　　　　　　　　　　　　　指定一个配置文件。把使用的配置放在配置文件中，这样不仅规范了自己代码，也可以方便地和别人共享这些规范。
    --init-hook=<code>  Python code to execute, usually for sys.path manipulation such as pygtk.require().
    -E, --errors-only   In error mode, checkers without error messages are
                        disabled and for others, only the ERROR messages are
                        displayed, and no reports are done by default
    --py3k              In Python 3 porting mode, all checkers will be
                        disabled and only messages emitted by the porting
                        checker will be displayed
    --ignore=<file>[,<file>...]
                        Add files or directories to the blacklist. They should
                        be base names, not paths. [current: CVS]
    --ignore-patterns=<pattern>[,<pattern>...]
                        Add files or directories matching the regex patterns
                        to the blacklist. The regex matches against base
                        names, not paths. [current: none]
    --persistent=<y_or_n>
                        Pickle collected data for later comparisons. [current:
                        yes]
    --load-plugins=<modules>
                        List of plugins (as comma separated values of python
                        modules names) to load, usually to register additional
                        checkers. [current: none]
    -j <n-processes>, --jobs=<n-processes>
                        Use multiple processes to speed up Pylint. [current:
                        1]
    --extension-pkg-whitelist=<pkg[,pkg]>
                        A comma-separated list of package or module names from
                        where C extensions may be loaded. Extensions are
                        loading into the active Python interpreter and may run
                        arbitrary code [current: none]
    --optimize-ast=<yn>
                        Allow optimization of some AST trees. This will
                        activate a peephole AST optimizer, which will apply
                        various small optimizations. For instance, it can be
                        used to obtain the result of joining multiple strings
                        with the addition operator. Joining a lot of strings
                        can lead to a maximum recursion error in Pylint and
                        this flag can prevent that. It has one side effect,
                        the resulting AST will be different than the one from
                        reality. This option is deprecated and it will be
                        removed in Pylint 2.0. [current: no]

  Commands:
    --help-msg=<msg-id>
                        Display a help message for the given message id and
                        exit. The value may be a comma separated list of
                        message ids.
    --list-msgs         Generate pylint's messages.
    --list-conf-levels  Generate pylint's messages.
    --full-documentation
                        Generate pylint's full documentation.
    --generate-rcfile   Generate a sample configuration file according to the
                        current configuration. You can put other options
                        before this one to get them in the generated
                        configuration.
　　　　　　　　　　　　　　可以使用 pylint --generate-rcfile 来生成一个配置文件示例。可以使用重定向把这个配置文件保存下来用做以后使用。也可以在前面加上其它选项，使这些选项的值被包含在这个产生的配置文件里。如：pylint --persistent=n --generate-rcfile > pylint.conf，查看 pylint.conf，可以看到 persistent=no，而不再是其默认值 yes。

  Messages control:
    --confidence=<levels>
                        Only show warnings with the listed confidence levels.
                        Leave empty to show all. Valid levels: HIGH,
                        INFERENCE, INFERENCE_FAILURE, UNDEFINED [current:
                        none]
    -e <msg ids>, --enable=<msg ids>
                        Enable the message, report, category or checker with
                        the given id(s). You can either give multiple
                        identifier separated by comma (,) or put this option
                        multiple time (only on the command line, not in the
                        configuration file where it should appear only once).
                        See also the "--disable" option for examples.
    -d <msg ids>, --disable=<msg ids>
                        Disable the message, report, category or checker with
                        the given id(s). You can either give multiple
                        identifiers separated by comma (,) or put this option
                        multiple times (only on the command line, not in the
                        configuration file where it should appear only
                        once).You can also use "--disable=all" to disable
                        everything first and then reenable specific checks.
                        For example, if you want to run only the similarities
                        checker, you can use "--disable=all
                        --enable=similarities". If you want to run only the
                        classes checker, but have no Warning level messages
                        displayed, use"--disable=all --enable=classes
                        --disable=W"
禁止指定 id 的 message. 比如说输出中包含了 W0402 这个 warning 的 message, 如果不希望它在输出中出现，可以使用 --disable-msg= W0402

  Reports:
    -f <format>, --output-format=<format>
                        Set the output format. Available formats are text, parseable, colorized, msvs (visual studio) and html. You can also give a reporter class, eg mypackage.mymodule.MyReporterClass. [current: text]
　　　　　　　　　　　　　　设置输出格式。可以选择的格式有 text, parseable, colorized, msvs (visual studio) 和 html, 默认的输出格式是 text。
    --files-output=<y_or_n>
                        Put messages in a separate file for each module / package specified on the command line instead of printing them on stdout. Reports (if any) will be written in a file name "pylint_global.[txt|html]".
                        This option is deprecated and it will be removed in Pylint 2.0. [current: no]
　　　　　　　　　　　　　　将每个 module /package 的 message 输出到一个以 pylint_module/package. [txt|html] 命名的文件中，如果有 report 的话，输出到名为 pylint_global.[txt|html] 的文件中。默认是输出到屏幕上不输出到文件里。
    -r <y_or_n>, --reports=<y_or_n>
                        Tells whether to display a full report or only the messages [current: yes]
　　　　　　　　　　　　　　默认是 y, 表示 Pylint 的输出中除了包含源代码分析部分，也包含报告部分。
    --evaluation=<python_expression>
                        Python expression which should return a note less than
                        10 (10 is the highest note). You have access to the
                        variables errors warning, statement which respectively
                        contain the number of errors / warnings messages and
                        the total number of statements analyzed. This is used
                        by the global evaluation report (RP0004). [current:
                        10.0 - ((float(5 * error + warning + refactor +
                        convention) / statement) * 10)]
    --msg-template=<template>
                        Template used to display messages. This is a python
                        new-style format string used to format the message
                        information. See doc for all details

　　

配置

　　使用如下命令　

#pylint --generate-rcfile  > pylint.conf  

　　生成一个配置文件模板，然后可以根据这个模板作个性化修改以适应具体项目的需求。

　　配置文件的模板参见pylint.conf 。 可以在模板文件上定制相关的统一的配置文件。配置文件中包含了master， message control， reports， typecheck， similarities， basic， variables， format， design， classes， imports， exception相关的lint配置信息，用户可以进行私人订制。

　　

　　修改部分说明：

　　disable=I0011

　　禁止 locally-disabled 类型的消息输出。

　　output-format=colorized 

　　配置输出着色。

　　reports=no  

　　不显示完整的报告，只显示消息。

　　const-rgx=[a-z_][a-z0-9_]{2,30}$  

　　配置模块级别的常量和变量的命名规则（以小写字母或下划线开头后续跟着小写字母或数字或下划线，2到30个字符）。

　　good-names=i,j,k,n,ex,Run,_  

　　添加一个总是接受的命名 “n”。

　　最新版的pylint已经废弃 --include-ids=<y_or_n>, -i <y_or_n> 选项，可在配置文件里修改输出消息的格式：

　　msg-template='{msg_id}:{line:3d}, {column}: {msg} ({symbol})'

Pylint 的输出

　　Pylint的默认输出格式是原始文本（raw text）格式 ，可以通过 -f <format>，--output-format=<format> 来指定别的输出格式如html等等。在Pylint的输出中有如下两个部分：源代码分析部分和报告部分。

源代码分析部分：

　　对于每一个 Python 模块，Pylint 的结果中首先显示一些"*"字符 , 后面紧跟模块的名字，然后是一系列的 message, message 的格式如下：

MESSAGE_TYPE: LINE_NUM:[OBJECT:] MESSAGE

　　MESSAGE_TYPE 有如下几种：

　　(C) convention 惯例。违反了编码风格标准

　　(R) refactor 重构。写得非常糟糕的代码。

　　(W) warning 警告。某些 Python 特定的问题。

　　(E) error 错误。很可能是代码中的错误。

　　(F) fatal 致命错误。阻止 Pylint 进一步运行的错误。

************* Module utils
 C: 88:Message: Missing docstring
 R: 88:Message: Too few public methods (0/2)
 C:183:MessagesHandlerMixIn._cat_ids: Missing docstring
 R:183:MessagesHandlerMixIn._cat_ids: Method could be a function
 R:282:MessagesHandlerMixIn.list_messages: Too many branches (14/12)

报告部分：

　　在源代码分析结束后面，会有一系列的报告，每个报告关注于项目的某些方面，如每种类别的 message 的数目，模块的依赖关系等等。具体来说，报告中会包含如下的方面：

• 检查的 module 的个数。
• 对于每个 module, 错误和警告在其中所占的百分比。比如有两个 module A 和 B, 如果一共检查出来 4 个错误，1 个错误是在 A 中，3 个错误是在 B 中，那么 A 的错误的百分比是 25%, B 的错误的百分比是 75%。
• 错误，警告的总数量。

使用

　　使用 Pylint 对一个模块 module.py 进行代码检查：

pylint [options] module_or_package

• 1. 进入这个模块所在的文件夹，运行 pylint [options] module.py
  这种调用方式是一直可以工作的，因为当前的工作目录会被自动加入 Python 的路径中。
• 2. 不进入模块所在的文件夹，运行 pylint [options] directory/module.py
  这种调用方式当如下条件满足的时候是可以工作的：directory 是个 Python 包 ( 比如包含一个 __init__.py 文件 )，或者 directory 被加入了 Python 的路径中。

　使用 Pylint 对一个包 pakage 进行代码检查：

• • 1. 进入这个包所在文件夹，运行 pylint [options] pakage。
    这种调用方式是一直可以工作的，因为当前的工作目录会被自动加入 Python 的路径中。
  • 2. 不进入包所在的文件夹，运行 pylint [options] directory/ pakage。
    这种情况下当如下条件满足的时候是可以工作的：directory 被加入了 Python 的路径中。比如在 Linux 上，export PYTHONPATH=$PYTHONPATH: directory。

　　　　此外，对于安装了 tkinter 包的机器，可以使用命令 pylint-gui打开一个简单的 GUI 界面，在这里输入模块或者包的名字 ( 规则同命令行 ), 点击 Run，Pylint 的输出会在 GUI 中显示。

在代码中关闭某个告警消息：

　　　　模块级别：

#! usr/bin/python
#pylint: disable=invalid-name

''' Docstring... '''

　　　　行级别：

def file_travesal(dirtectory='.', file_list=[]): # pylint: disable=W0102
    '''
    Get file list from the directory including files in its subdirectories.
    '''
    file_list += [join(dirtectory, f) for f in listdir(dirtectory)
                if isfile(join(dirtectory, f))]
    for item in listdir(dirtectory):
        if isdir(join(dirtectory, item)):
            file_travesal(join(dirtectory, item), file_list)

　　添加命令别名（配置文件在用户目录“~/”下）：

echo "alias pylt='pylint --rcfile=~/pylint.conf'" >> ~/.bashrc

　　怎么更改pylint的默认配置文件

　　pylint安装成功后，可以通过运行"pylint --help"来快速查看pylint的帮助信息；相关信息基本能够支撑起快速使用起来pylint的基本功能。

　　可以通过"pylint --generate-rcfile"生成配置文件模板，可以在模板文件上定制相关的统一的配置文件。配置文件中包含了master， message control， reports， typecheck， similarities，  basic， variables， format， design， classes， imports， exception相关的lint配置信息，用户可以进行私人订制。

jenkins中的violations插件
　https://wiki.jenkins-ci.org/display/JENKINS/Violations
　　 

参考

　　http://www.ibm.com/developerworks/cn/linux/l-cn-pylint/

　　https://wiki.jenkins-ci.org/display/JENKINS/Violations