Python Formatting&Linting&isort 以及VSCode中的使用

0. 前言

• 概念简单介绍
  • isort：一个工具的名字，对Python中的 import 相关语句进行处理。
    • 将 import 的内容分为标准库、第三方库、本地库三种类型，每一类中，都是按字母顺序排序。
  • 代码格式化（Fomratting）：不分析代码如何运行，只管一些格式问题，如行间距、缩进、操作符前后的空格数量等。
    • 常见工具包括 yapf/black/autopep8。
    • Python中经常提到的PEP8规范，这类工具可以使得代码符合PEP8规范。
    • 这类工具的命令行结果一般会直接修改文件本身内容（修改后不影响运行结果）。
  • 代码检查（Linting）：不仅检查代码格式，也分析代码是如何运行的，并检测会遇到的问题。
    • 常见工具包括 flake8/pylint。
    • 会检查函数、变量是否定义、是否使用。
    • 此类命令执行后不会修改文件内容，而会指出某个文件某行出现XXX错误。
• 本文内容：
  • 第一章：Formatting与Linting工具介绍，即flake8/yapf/black/isort命令介绍。
  • 第二章：flake8/yapf/black/isort 在 VSCode 中的使用。

1. Formatting与Linting工具介绍

1.1. flake8

• 官方文档
• 主要作用：集成了三类任务
  • PyFlakes：静态检查Python代码逻辑错误，如没有使用的变量
  • PEP8：静态检查PEP8]编码风格，使用了 pycodestyle。
  • Ned Batchelder’s McCabe[10] script：好像是代码复杂性相关。
• 本插件中有很多类似 W503, E123, F811 这些。
  • 具体定义可以参考 pycodestyle Error codes 和 Flake8 Error/Violation Codes
• 配置文件
  • 详细信息可以参考 官方文档
  • 主要思路就是，包含用户级别配置文件以及项目级别配置文件。
    • 用户级别配置文件在用户目录下。
      • Windows系统的路径是 ~\.flake8 。
      • Linux系统的路径是 ~/.config/flake8 。
    • 项目目录下可以放在 tox.ini setup.cfg .flake8 三个文件中。
• 命令行
  • 直接运行 flake8 . 不会修改文档内容，会返回出错文件/行/错误类型。
  • 相关文档可以参考这里。

1.2. yapf

• 官方文档
• 配置文件
  • 默认情况下
    • 首先，寻找当前目录以及父亲目录（所有父亲目录，直到根节点） .style.yapf 文件。
    • 其次，寻找当前目录以及父亲目录（所有父亲目录，直到根节点） setup.cfg 文件。
    • 最后，在用户目录下寻找 ~/.config/yapf/style 文件。
  • 可通过命令行 --style 指定配置文件。
  • 所有配置文件参数可以参考 这里。
  • 注意：配置文件中大小写不敏感。
• 命令行会
  • 直接运行 yapf ./test.py 返回格式化后文档内容。注意，就算没有修改也会返回文档内容。
  • 运行 yapf --diff ./test.py 返回修改内容。没有修改则没有返回值。
  • 更多请参考官方文档。

1.3. black

• 官方文档
• 配置文件
  • 可通过命令行 --config 设置配置文件。
  • 需要的配置文件名为 pyproject.toml 。
• 命令行相关文档

1.4. isort

• isort 官方文档
• 作用：对import信息进行整理、排序。
• 配置文件：
  • 相关文档
  • 注意：不会合并配置文件，只会选择其中一个使用。
  • 会选择根据下面顺序依次寻找每个配置文件
    • 配置文件顺序 .isort.cfg -> pyproject.toml -> setup.cfg -> tox.ini -> .editorconfig
    • 对于每个配置文件，会寻找当前目录以及最多25级父目录。
    • 如果找到了，就不再继续。
  • 可通过 --settings-path 来指定配置文件。
• 命令行
  • 直接运行 isort ./setup.py
    • 如果有需要修改的则会直接修改文档，并在命令行中显示 Fixing /path/to/setup.py 。
    • 如果没有要修改的，那就什么都不输出。
  • 所有可选项可以参考文档。
• 补充一个工具 seed-isort-config
  • 作用是：在命令行中执行 seed-isort-config 就会在 isort 的配置文件中补全所有 known_third_party 信息。
    • 如果没有 isort 配置文件就新建一个 .isort.cfg 。

2. VSCode 中的使用

• 需求：希望在写代码的过程中，可以快速通过 Fomatting 工具修改当前文档格式，通过 Linting 工具实时查看文档是否出现相关错误。

2.1. isort

• VSCode中Python插件支持isort功能。
• 默认情况下，isort没有绑定快捷键，可以通过在python文件右键列表中的 排序 import 语句 来实现。
• 相关的配置只有两个，一是选择isort路径，而是设置isort命令行配置。

{
	// Arguments passed in. Each argument is a separate item in the array.
	"python.sortImports.args": [],

	// Path to isort script, default using inner version
	"python.sortImports.path": "",
}

2.2. Formatting工具

• 官方文档：Editing Python in Visual Studio Code
• VSCode中Python插件目前支持的第三方包有 [autopep8][2]，[black][3]和[yapf][4]。
  • 一次只能启用一个工具。
• VSCode中使用也非常容易，在python文件中右键选项中的 格式化文档 ，快捷键 Shift+Alt+F 。
• 在VSCode中，formatting相关的配置其实很简单，分两个方面
  • 选择使用哪种formatting方式，即 none/autopep8/black/yapf 四选一。
  • 每一类formatting工具的路径以及参数的设置。

{
	// Arguments passed in. Each argument is a separate item in the array.
	"python.formatting.autopep8Args": [],

	// Path to autopep8, you can use a custom version of autopep8 by modifying this setting to include the full path.
	"python.formatting.autopep8Path": "autopep8",

	// Arguments passed in. Each argument is a separate item in the array.
	"python.formatting.blackArgs": [],

	// Path to Black, you can use a custom version of Black by modifying this setting to include the full path.
	"python.formatting.blackPath": "black",

	// Provider for formatting. Possible options include 'autopep8', 'black', and 'yapf'.
	"python.formatting.provider": "autopep8",

	// Arguments passed in. Each argument is a separate item in the array.
	"python.formatting.yapfArgs": [],

	// Path to yapf, you can use a custom version of yapf by modifying this setting to include the full path.
	"python.formatting.yapfPath": "yapf",
}

2.3. Linting 工具

• 官方文档：Linting Python in Visual Studio Code
• VSCode 中支持多类Lint工具，包括Pylint/Flake8/mypy等。
• 注意：VSCode中可同时激活多个Lint工具，如Pylint/Flake8同时启用。
• 相关设置主要包括两方面：
  • 全局设置：是否使用Lint、是否在保存文件时执行Lint、忽略那些目录等内容。
  • Lint工具配置，主要就是指定 Pylint/Flake8/mypy 等工具的路径以及相关参数（如制定命令行参数、指定错误级别）。
  • 下面就是配置文件举例。

{
    // 全局设置包括以下四个
	// Whether to lint Python files.
	"python.linting.enabled": true,	
	// Patterns used to exclude files or folders from being linted.
	"python.linting.ignorePatterns": [
		".vscode/*.py",
		"**/site-packages/**/*.py"
	],
	// Whether to lint Python files when saved.
	"python.linting.lintOnSave": true,
	// Controls the maximum number of problems produced by the server.
	"python.linting.maxNumberOfProblems": 100,
    
    // 而工具的配置这里就以pylint/flake8/mypy为例罗列一下，其实也没啥花头
	// Arguments passed in. Each argument is a separate item in the array.
	"python.linting.flake8Args": [],

	// Severity of Flake8 message type 'E'.
	"python.linting.flake8CategorySeverity.E": "Error",

	// Severity of Flake8 message type 'F'.
	"python.linting.flake8CategorySeverity.F": "Error",

	// Severity of Flake8 message type 'W'.
	"python.linting.flake8CategorySeverity.W": "Warning",

	// Whether to lint Python files using flake8
	"python.linting.flake8Enabled": false,

	// Arguments passed in. Each argument is a separate item in the array.
	"python.linting.mypyArgs": [
		"--ignore-missing-imports",
		"--follow-imports=silent",
		"--show-column-numbers"
	],

	// Severity of Mypy message type 'Error'.
	"python.linting.mypyCategorySeverity.error": "Error",

	// Severity of Mypy message type 'Note'.
	"python.linting.mypyCategorySeverity.note": "Information",

	// Whether to lint Python files using mypy.
	"python.linting.mypyEnabled": false,

	// Path to mypy, you can use a custom version of mypy by modifying this setting to include the full path.
	"python.linting.mypyPath": "mypy",

	// Arguments passed in. Each argument is a separate item in the array.
	"python.linting.pylintArgs": [],

	// Severity of Pylint message type 'Convention/C'.
	"python.linting.pylintCategorySeverity.convention": "Information",

	// Severity of Pylint message type 'Error/E'.
	"python.linting.pylintCategorySeverity.error": "Error",

	// Severity of Pylint message type 'Fatal/F'.
	"python.linting.pylintCategorySeverity.fatal": "Error",

	// Severity of Pylint message type 'Refactor/R'.
	"python.linting.pylintCategorySeverity.refactor": "Hint",

	// Severity of Pylint message type 'Warning/W'.
	"python.linting.pylintCategorySeverity.warning": "Warning",

	// Whether to lint Python files using pylint.
	"python.linting.pylintEnabled": true,

	// Path to Pylint, you can use a custom version of pylint by modifying this setting to include the full path.
	"python.linting.pylintPath": "pylint",

	// Whether to run Pylint with minimal set of rules.
	"python.linting.pylintUseMinimalCheckers": true,

}