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.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, 若是不但願它在輸出中出現，可使用 

  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 --persistent=n --generate-rcfile > pylint.conf--disable-msg= W0402

　　

配置

　　使用以下命令　

#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