如何使用 Pylint 來規範 Python 程式碼風格(來自IBM)_python

本文透過詳細的理論介紹和簡單易懂的實例全面介紹了 Python 程式碼分析工具 Pylint。相信讀者看完後一定可以輕鬆地將Pylint 運用到自己的開發工程中

Pylint 是什麼

Pylint 是一個Python 程式碼分析工具，它分析Python程式碼中的錯誤，尋找不符合程式碼風格標準（Pylint 預設使用的程式碼風格是PEP 8，具體訊息，請參閱參考資料）和有潛在問題的程式碼。目前 Pylint 的最新版本是 pylint-0.18.1。

• Pylint 是一個Python 工具，除了平常程式碼分析工具的作用之外，它提供了更多的功能：如檢查一行程式碼的長度，變數名稱是否符合命名標準，一個聲明過的介面是否被真正實作等等。

• Pylint 的一個很大的好處是它的高可配置性，高可自訂性，並且可以輕鬆寫入小插件來添加功能。

• 如果執行兩次 Pylint，它會同時顯示出目前和上次的運行結果，從而可以看出程式碼品質是否得到了改進。

• 目前在 eclipse 的 pydev 外掛程式中也整合了 Pylint。

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 的呼叫

清單1. Pylint 的呼叫指令

pylint [options] module_or_package

#使用Pylint 對一個模組module.py 進行程式碼檢查：

• 1. 進入這個模組所在的資料夾，執行

  pylint [options] module.py  這種呼叫方式是一直可以運作的，因為目前的工作目錄會被自動加入 Python 的路徑。
  

• 2. 不進入模組所在的資料夾，執行

  pylint [options] directory/module.py##這種呼叫方式當如下條件滿足的時候是可以工作的：directory 是個Python 套件( 例如包含一個__init__.py 檔案)，或是directory 被加入了Python 的路徑中。 <br>

使用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 中顯示。

Pylint 的常用命令列參數

• #-h,--help

  顯示所有幫助資訊。

• --generate-rcfile

  可以使用 pylint --generate-rcfile 來產生一個設定檔範例。可以使用重定向把這個設定檔保存下來用做以後使用。也可以在前面加上其它選項，使這些選項的值被包含在這個產生的設定檔裡。如：pylint --persistent=n --generate-rcfile > pylint.conf，查看 pylint.conf，可以看到 persistent=no，而不再是其預設值 yes。

• --rcfile=

  指定一個設定檔。把使用的配置放在設定檔中，這樣不僅規範了自己程式碼，也可以方便地和別人分享這些規範。

• -i , --include-ids=

  在輸出中包含message 的id, 然後透過pylint --help- msg=來查看這個錯誤的詳細信息，這樣可以具體地定位錯誤。

• -r , --reports=

  預設是y, 表示Pylint 的輸出中除了包含原始碼分析部分，也包含報告部分。

• --files-output=

  將每個module /package 的message 輸出到一個以pylint_module/package. [txt|html] 命名的檔案中，如果有report 的話，輸出到名為pylint_global.[txt|html] 的檔案中。預設是輸出到螢幕上不輸出到檔案裡。

• -f , --output-format=

  設定輸出格式。可以選擇的格式有 text, parseable, colorized, msvs (visual studio) 和 html, 預設的輸出格式是 text。

• --disable-msg=

  禁止指定id 的message. 例如說輸出包含了W0402 這個warning 的message, 如果不希望它在輸出中出現，可以使用--disable-msg= W0402

Pylint 的輸出

Pylint的預設輸出格式是原始文本（raw text）格式，可以透過-f ，--output-format= 來指定別的輸出格式如html等等。在Pylint的輸出中有以下兩個部分：原始碼分析部分和報告部分。

原始碼分析部分：

對於每一個Python 模組，Pylint 的結果中首先顯示一些"*"字元, 後面緊跟模組的名字，然後是一系列的message, message 的格式如下：

MESSAGE_TYPE: LINE_NUM:[OBJECT:] MESSAGE

MESSAGE_TYPE 有以下幾種：

(C) 慣例。違反了編碼風格標準
(R) 重構。寫得非常糟糕的程式碼。
(W) 警告。某些 Python 特定的問題。
(E) 錯誤。很可能是程式碼中的錯誤。
(F) 致命錯誤。阻止 Pylint 進一步運行的錯誤。

清單2. Pylint 中的utils 模組的輸出結果

************* 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:MessaHandlerMix.In_cat_ Missing docstring
R:183:MessaHandlerMix.In_cat_sbe 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 分析Python 程式碼的具體範例

下面是一個從xml 檔案中讀取一些值並顯示出來的一段Python 程式碼dw.py，程式碼如下：

清單3. 原始碼

#

import string 
 #!/usr/bin/env python 
 
 import xml.dom.minidom 
 
 xmlDom=xml.dom.minidom.parse("identity.xml") 
 organizations = xmlDom.getElementsByTagName('DW') 
 for org in organizations: 
  products = org.getElementsByTagName('linux') 
 for product in products: 
  print 'ID: ' + product.getAttribute('id') 
  print 'Name: ' + product.getAttribute('name') 
  print 'Word Count: ' + product.getAttribute('count')

清單4. identity.xml 的內容

<IBM> 
  <DW> 
    <linux id="100" name="python" count="3000" /> 
  </DW> 
</IBM>

這時候使用Pylint 的結果（這是從html 格式的輸出中拷貝的）為：

#清單5. Pylint 的分析結果

************* Module dw
C:1:Missing docstring
C:5:Operator not preceded by a space xmlDom=xml.dom.minidom.parse("identity.xml") ^
C:5:Invalid name "xmlDom" (should match (([A-Z_][A-Z0-9_]*)|(__.*__))$)
C:6:Invalid name "organizations" (should match (([A-Z_][A-Z0-9_]*)|(__.*__))$)

Report 部分省略

输出中第一部分是源代码分析，第二部分是报告。输出结果中有这么多信息，从哪里开始分析呢？首先使用如下的步骤来分析代码：

1. 因为输出结果太长，所以可以先不让它输出报告部分，先根据源代码分析部分来找出代码中的问题。使用选项 "--reports=n"。
2. 使用选项 "--include-ids=y"。可以获取到源代码分析部分每条信息的 ID。

清单 6. 使用 pylint --reports=n --include-ids=y dw.py 的结果

************* Module dw
C0111: 1: Missing docstring
C0322: 5: Operator not preceded by a space xmlDom=xml.dom.minidom.parse("identity.xml") ^
C0103: 5: Invalid name "xmlDom" (should match (([A-Z_][A-Z0-9_]*)|(__.*__))$)
C0103: 6: Invalid name "organizations" (should match (([A-Z_][A-Z0-9_]*)|(__.*__))$)

每个信息前面都会加上一个 id, 如果不理解这个信息的意思，可以通过 pylint --help-msg=id来查看。

清单 7. 使用 pylint --help-msg= C0111 的结果

C0111: *Missing docstring*
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.

3. 开始分析每个源代码中的问题。从上面知道，第一个问题的原因是缺少 docstring，在代码中增加 docstring, 修改后的代码如下：

清单 8. 增加 docstring 修改后的源码

#!/usr/bin/env python 
 
"""This script parse the content of a xml file"""
 
 import xml.dom.minidom 
 
 xmlDom=xml.dom.minidom.parse("identity.xml") 
 organizations = xmlDom.getElementsByTagName('DW') 
 for org in organizations: 
 products = org.getElementsByTagName('linux') 
 for product in products: 
  print 'ID: ' + product.getAttribute('id') 
  print 'Name: ' + product.getAttribute('name') 
  print 'Word Count: ' + product.getAttribute('count')

重新运行 pylint --reports=n --include-ids=y dw.py，结果为：

清单 9. 运行结果

************* Module dw
C0322: 7: Operator not preceded by a space
xmlDom=xml.dom.minidom.parse("identity.xml")
^
C0103: 7: Invalid name "xmlDom" (should match (([A-Z_][A-Z0-9_]*)|(__.*__))$)
C0103: 8: Invalid name "organizations" (should match (([A-Z_][A-Z0-9_]*)|(__.*__))$)

可以看到源代码中的第一个问题已被解决。

4. 关于第二个 C0322 的问题，这里的分析结果说明得比较清楚，是代码第七行中的等号运算符两边没有空格。我们在这里加上空格，重新运行 pylint --reports=n --include-ids=y dw.py，结果为：

清单 10. 运行结果

************* Module dw
C0103: 7: Invalid name "xmlDom" (should match (([A-Z_][A-Z0-9_]*)|(__.*__))$)
C0103: 8: Invalid name "organizations" (should match (([A-Z_][A-Z0-9_]*)|(__.*__))$)

5. 可以看到现在问题只剩下 C0103 了。这里的意思是变量命名规则应该符合后面正则表达式的规定。Pylint 定义了一系列针对变量，函数，类等的名字的命名规则。实际中我们不一定要使用这样的命名规则，我们可以定义使用正则表达式定义自己的命名规则，比如使用选项 --const-rgx='[a-z_][a-z0-9_]{2,30}$'，我们将变量 xmlDom改为 xmldom, 代码如下：

清单 11. 将变量 xmlDom 改为 xmldom 后的源码

#!/usr/bin/env python 
 
"""This script parse the content of a xml file"""
 
 import xml.dom.minidom 
 
 xmldom = xml.dom.minidom.parse("identity.xml") 
 organizations = xmldom.getElementsByTagName('DW') 
 for org in organizations: 
 products = org.getElementsByTagName('linux') 
 for product in products: 
  print 'ID: ' + product.getAttribute('id') 
  print 'Name: ' + product.getAttribute('name') 
  print 'Word Count: ' + product.getAttribute('count')

运行 pylint --reports=n --include-ids=y --const-rgx='[a-z_][a-z0-9_]{2,30}$' dw.py，结果中就没有任何问题了。

6. 如果希望一个组里的人都使用这些统一的规则，来规范一个部门的代码风格。比如说大家都使用 --const-rgx='[a-z_][a-z0-9_]{2,30}$'作为命名规则，那么一个比较便捷的方法是使用配置文件。
使用 pylint --generate-rcfile > pylint.conf来生成一个示例配置文件，然后编辑其中的 --const-rgx选项。或者也可以直接 pylint --const-rgx='[a-z_][a-z0-9_]{2,30}$' --generate-rcfile > pylint.conf，这样生成的配置文件中 --const-rgx选项直接就是 '[a-z_][a-z0-9_]{2,30}$'了。
以后运行 Pylint 的时候指定配置文件：pylint --rcfile=pylint.conf dw.py
这样 Pylint 就会按照配置文件 pylint.conf中的选项来指定参数。在一个部门中，大家可以共同使用同一个配置文件，这样就可以保持一致的代码风格。

7. 如果把 report 部分加上，即不使用 --reports=n，可以看到报告部分的内容。

结束语

本文透過詳細的理論介紹和簡單易懂的實例全面介紹了 Python 程式碼分析工具 Pylint。相信讀者看完後一定可以輕鬆地將 Pylint 運用到自己的開發工程中。

相關主題

• Pylint 官方網站。

• logilab-astng 的最新套件下載。

• logilab-common 的最新套件下載。

• optik 的套件下載。

• Pylint 的最新套件下載。

• 查看 Python 程式碼風格標準 PEP 8 -- Style Guide for Python Code下載。

• 更多關於 Python 內容，請參考 developerWorks 上 Python 專題。

相關推薦：

python程式碼檢查工具pylint 讓你的python更規範

以上是如何使用 Pylint 來規範 Python 程式碼風格(來自IBM)_python的詳細內容。更多資訊請關注PHP中文網其他相關文章！