使用PyLint分析评估代码质量

时间:2022-12-08 15:14:36

PyLint是一款用于评估Python代码质量的分析工具,它诞生于2003年,其最初十年的主要作者和维护者是Sylvain Thénault。PyLint可以用来检查代码是否错误、是否符合编码规范(它默认使用的编码规范是PEP 8),在分析代码后PyLint将会输出一段信息,内容包括在代码中检查到的警告和错误,如果运行两次,它将会输出两次的统计信息,以便使用者分析代码是否得到改进。PyLint的特性是报告尽可能少的错误,但是它会输出非常多的警告信息,所以建议在程序提交之前或者想要整理代码时使用PyLint,这样可以忽略掉大量的无效警告。

自PyLint 1.4起,PyLint只支持Python 2.7+和Python 3.3+。

安装PyLint

在命令行界面执行如下代码,即可安装PyLint:

pip install pylint

在命令行界面执行如下代码,即可查询PyLint的安装路径:

where pylint

调用PyLint

在命令行中调用

分析Python包或者Python模块

pylint [options] module_or_package

分析Python文件

pylint [options] mymodule.py

并行分析Python文件

pylint -j 4 mymodule1.py mymodule2.py mymodule3.py mymodule4.py

上述语句将产生4个并行的PyLint子进程来对所需的四个文件并行检查,PyLint发现问题后不会立即显示,待所有模块检查完毕后才会显示。其中,参数-j用于指定所需的PyLint子进程数量,默认值为1。

常用的命令行选项

  • --version:显示PyLint以及Python的版本;

    使用示例:

    pylint --version
    
  • -h, --help :显示帮助信息;

    使用示例:

    示例一:
    pylint -h
    示例二:
    pylint --help
    
  • -ry:显示各项信息的报表统计;

    使用示例:

    pylint -ry mymodule.py
    
  • --generate-rcfile:生成配置信息示例;

    使用示例:

    ## 将persistent修改为n,并将配置信息保存至pylint.conf文件中
    pylint --persistent=n --generate-rcfile > pylint.conf 
    
  • --rcfile=<file> :指定所使用的的配置文件;

    使用示例:

    pylint --rcfile=pylint.conf mymodule.py 
    
  • --persistent=y_or_n:是否使用Pickle存储上次结果;

    使用示例:

    pylint --persistent=y mynodule.py
    
  • --output-format=<format>:指定输出格式( parseable, colorized, msvs);

    使用示例:

    pylint --output-format=parseable mymodule.py
    
  • --msg-template=<template>:指定输出内容;

    template参数包括:

    • path:文件的相对路径;
    • abspath:文件的绝对路径;
    • line:输出行数;
    • column:输出列数;
    • module:模块名;
    • obj : 模块中的对象(如果有的话) ;
    • msg :信息文本;
    • msg_id :信息编号;
    • symbol :信息的符号名称;
    • C:信息类别;

    使用示例:

    pylint --msg-template='{msg_id}:{line:3d}:{msg}' mymodule.py
    
  • --list-msgs:生成pylint的警告列表;

    使用示例:

    pylint --list-msgs
    
  • --full-documentation : 以reST格式生成pylint的完整文档。

    使用示例:

    pylint --full-documentation
    

在Python程序中调用PyLint

方法一

from pylint import epylint as lint
lint.py_run("mymodule.py --msg-template='{line:3d}:{msg}'")
# 注意,先写文件名,再写命令选项,文件名和命令选项通过空格隔开。

方法二

from pylint import epylint as lint
(pylint_stdout, pylint_stderr) = lint.py_run('mymodule.py', return_std=True)
# 注意,返回值类型为StringIO,可以通过read()方法进行读取。
print(pylint_stdout.read())

关联PyLint与PyCharm

方法一

  • 进入PyCharm,依次点击: File -> Settings -> Tools -> External Tools,进入下图页面;

    使用PyLint分析评估代码质量

  • 点击加号,在弹窗中填写下图红色方框中的字段后,点击OK;

    • Name参数可以填写pylint;
    • Program参数选择pylint.exe的路径,选择后,Working directory参数将自动补全;
    • Arguments参数根据实际需求点击右侧Inser Macros进行选择即可,示例中选择检查当前路径下的文件。

    使用PyLint分析评估代码质量

  • 依次点击Tools->External Tools->pylint,即可运行PyLint。

方法二

  • 进入PyCharm,依次点击: File -> Settings -> Plugins,进入下图页面;

    使用PyLint分析评估代码质量

  • 点击Browse repositories,进入下图页面;

    使用PyLint分析评估代码质量

  • 在左上角搜索框中搜索pylint,右击安装,点击Yes开始下载,之后点击Close,重启PyCharm后即安装成功;

    使用PyLint分析评估代码质量

  • 依次点击: File -> Settings -> pylint,可根据实际需求进行配置;

    使用PyLint分析评估代码质量

  • 运行时,点击左下角pylint即可查看PyLint输出,单击具体输出内容,可跳转到相关代码行。

    使用PyLint分析评估代码质量

PyLint的输出

源代码分析

对于每个Python模块,PyLint的输出格式如下:

  • 第一行将在若干' * '字符后显示模块名称;
  • 从第二行起显示PyLint的输出,默认的输出内容格式为——信息类别:行数:信息内容 。

信息类别:

  • R:违反重构标准;
  • C:违反编码规范;
  • W:警告;
  • E:错误;
  • F:致命错误,使PyLint无法进一步处理。

PyLint的输出范例:

************* Module pylint.checkers.format
W: 50: Too long line (86/80)
W:108: Operator not followed by a space
     print >>sys.stderr, 'Unable to match %r', line
            ^
W:141: Too long line (81/80)
W: 74:searchall: Unreachable code
W:171:FormatChecker.process_tokens: Redefining built-in (type)
W:150:FormatChecker.process_tokens: Too many local variables (20/15)
W:150:FormatChecker.process_tokens: Too many branches (13/12)

可以通过pylint --help-msg <msg-id>查询更多信息,使用示例:

pylint --help-msg C0115

检查报告

检查报告在源代码分析的后面,每个报告关注项目的特定方面,比如每种类别的信息数目,模块的依赖关系等等。具体来说,报告中会包含如下的方面:

  • 检查的模块个数;
  • 对于每个模块,其错误和警告在其中所占的百分比;
  • 对于所有模块,其错误和警告的总数量;
  • 文件中带有文档字符串的类、函数和模块所占的百分比;
  • ......

PyLint与PyChecker的区别

PyLint支持PyChecker提供的大部分功能,他们之间一个最主要的区别在于PyLint能够检测编码标准是否规范;其次,PyLint不支持导入活动模块而PyChecker可以。

PEP 8标准

代码布局

  • 每个缩进级别使用4个空格,连续行使用垂直对齐或者使用悬挂式缩进(额外的4个空格缩进);

  • 空格是首选的缩进方法;

  • 每行最多79个字符;

  • 允许在二元运算符前后换行,但代码需保持一致,对于新代码建议在二元运算符前进行换行;

  • 使用两个空白行分隔顶层函数和类定义;

  • 类方法定义使用一个空行分隔;

  • 使用额外的空白行来分隔相关逻辑功能;

  • 文件应该使用UTF-8编码,且不应该有编码声明;

  • 导入多个库函数应该分开依次导入,导入总是放在文件的顶部,在任何模块注释和文档字符串之后,在模块全局变量和常量之前;导入应按以下顺序进行:标准库导入、有关的第三方库导入、本地应用程序/库特定的导入,每组导入直接用空行分隔;避免通配符导入(import *)。

字符串

  • 单引号字符串和双引号字符串相同,但代码需保持一致;

  • 对于三引号字符串,常用三个双引号作文档字符串,文档字符串常用在模块的开端用以说明模块的基本功能,或紧跟函数定义的后面用以说明函数的基本功能。

空格

  • 避免使用无关的空格,包括空格内、逗号分号前面等;

  • 避免在行末使用空格;

  • 二元运算符在两侧使用一个空格;

  • 当用于指示关键字参数或默认参数值时,不要在=符号周围使用空格。

使用尾部逗号(trailing commas)

  • 尾部逗号通常可选,但对于只有一个元素的元组是必选的;

  • 当参数、值等列表期望经常扩展时,通常是每个值一行,再加上一个尾部逗号。

注释

  • 代码更改时,相应的注释也要随之更改;

  • 注释应该是完整的语句,第一个单词应该大写,除非它是特定标识符;

  • 块注释:缩进到与该代码相同的级别,块注释的每一行都以#和一个空格开始;

  • 行注释:对某一语句行进行注释,注释应该与语句至少隔开两个空格,用#和一个空格开始;

  • 对于公共的模块,功能,类和方法需要为其写文档字符串;

  • 注释应该是完整的语句,第一个单词应该大写,除非它是特定标识符。

命名约定

  • 命名应该反映其用途而非实现;

  • 不要将字符’l’(小写字母L),’O’(大写字母O)或’I’(大写字母I)作为单个字符变量名称;

  • 模块名应该使用简短、全小写的名字;

  • 类的命名采用驼峰命名法,即每个单词的首字母大写;

  • 函数名称应该是小写的,为了提高可读性,必须使用由下划线分隔的单词。

参考资料

PyLint官网链接

PEP 8编码规范