• 概念简单介绍
  • 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 , 文章目录0. 前言1. VSCode 配置 formatting/linting/isort1.1. formatting & isort1.2. linting2. 第三方包的基本使用2.1. flake82.2. mypy2.4. yapf2.5. black2.6. isort3. 开源项目中的应用3.1. Detectron2/SlowFast3.2. mmdetection/mmaction/mmaction20. 前言契机：在很多开源项目中，都对代码的形式有具体要求，有设置 fo 仅更改已更改的内容 与pipenv pipenv install git+https://github.com/luxresearch/yapf-diff.git@master#egg=yapf-diff 带点pip install git+https://github.com/luxresearch/yapf-diff.git@master#egg=yapf-diff 在requirements.txt 中 # requirements.txt: for a fast download https://github.com/luxresearch/yapf-diff/archive/master.tar.gz 我应该 使用 yapf_diff吗？ 仅在格式化修改后的文件 中 的所有行时，会导致修订历史记录 中 的差异大得无法接受。 建议使您的代码与周围的代码保持一致。 yapf-diff仅在diff 中 触及的行内保证一致性。 如果您是选择如何和何时下绒的人，请选择以提高一致性和速度。 如果一次格式化整个文件是一种选择，请 使用 类似 git diff --name-onl