在 Visual Studio Code 中整理 Python

在 Visual Studio Code 中整理 Python

原文：https://code.visualstudio.com/docs/python/linting

Linting 会突出显示 Python 源代码中的语法和风格问题，这通常可以帮助您识别和纠正细微的编程错误或可能导致错误的非常规编码实践。例如，linting 检测未初始化或未定义变量的使用、对未定义函数的调用、缺少括号，甚至更微妙的问题，例如尝试重新定义内置类型或函数。因此，linting与格式化不同，因为 linting 分析代码如何运行并检测错误，而格式化仅重组代码的显示方式。

默认情况下，语言服务器启用样式和语法代码检测。但是，如果您需要第三方 linter 进行其他问题检测，则可以通过使用Python: Select Linter命令并选择适当的linter来启用它们。您可以使用Python: Enable Linting命令轻松启用和禁用所有 linting 。

启用 linter #

要启用默认 PyLint 以外的 linter，请打开命令面板 ( Ctrl+Shift+P ) 并选择Python: Select Linter命令。此命令添加"python.linting.<linter>Enabled": true到您的设置中，其中<linter>是所选 linter 的名称。有关详细信息，请参阅特定linters。

启用 linter 会提示您在所选环境中为所选 linter 安装所需的包。

注意：如果您使用的是全局环境并且 VS Code 未提升运行，则 linter 安装可能会失败。在这种情况下，要么运行 VS Code 提升，要么手动运行 Python 包管理器以在相同环境的提升命令提示符下安装 linter：例如sudo pip3 install pylint（macOS/Linux）或pip install pylint（Windows，在提升的提示符下）

禁用 linting #

您可以使用Python: Enable Linting命令禁用所有 Python linting，该命令显示一个下拉列表，其中包含当前 linting 状态和用于将 Python lintingon或off.

运行 linting #

要执行 linting：

• 保存文件时，Linting 会自动运行。
• 打开命令面板 ( Ctrl+Shift+P )，然后输入并选择Python: Run Linting。

问题显示在问题面板中，并在代码编辑器中显示为下划线。将鼠标悬停在带下划线的问题上会显示详细信息：

一般 linting 设置#

本文的其余部分描述了一般的 linting 设置以及特定的 linter。您可以添加任何的设置到用户settings.json文件（打开文件>首选项>设置命令，按Ctrl +， ）。请参阅用户和工作区设置以了解有关在 VS Code 中使用设置的更多信息。

要更改所有启用的 linter 的 linting 行为，请修改以下设置：

特征	设置 (python.linting.)	默认值
Linting in general	enabled	true
Linting on file save	lintOnSave	true
Maximum number of linting messages	maxNumberOfProblems	100
Exclude file and folder patterns	ignorePatterns	[".vscode/*.py", "**/site-packages/**/*.py"]

您可以使用Python: Enable Linting命令轻松更改python.linting.enabled。

启用lintOnSave时，您可能还想启用通用files.autoSave选项（请参阅保存/自动保存）。当您键入时，该组合会在您的代码中提供频繁的 linting 反馈。

特定的linters#

下表提供了可用 Python linter 及其基本设置的摘要。默认情况下仅启用 Pylint。有关各个设置的说明，请参阅Linter 设置参考。

linters	pip install命令的包名	默认状态	真/假启用设置 （python.linting.）	参数设置 (python.linting.)	自定义路径设置 (python.linting.)
Pylint (default)	pylint	Enabled	pylintEnabled	pylintArgs	pylintPath
Flake8	flake8	Disabled	flake8Enabled	flake8Args	flake8Path
mypy	mypy	Disabled	mypyEnabled	mypyArgs	mypyPath
pydocstyle	pydocstyle	Disabled	pydocstyleEnabled	pydocstyleArgs	pydocstylePath
pycodestyle (pep8)	pycodestyle	Disabled	pycodestyleEnabled	pycodestyleArgs	pycodestylePath
prospector	prospector	Disabled	prospectorEnabled	prospectorArgs	prospectorPath
pylama	pylama	Disabled	pylamaEnabled	pylamaArgs	pylamaPath
bandit	bandit	Disabled	banditEnabled	banditArgs	banditPath

要选择不同的linter，请使用Python: Select Linter命令。您还可以手动编辑设置以启用多个 linter。但是请注意，使用Select Linter命令会覆盖这些编辑。

自定义参数在每个 linter 的适当参数设置中指定。在命令行上由空格分隔的参数字符串的每个顶级元素必须是 args 列表中的一个单独项目。例如：

"python.linting.pylintArgs": ["--reports", "12", "--disable", "I0011"],
"python.linting.flake8Args": ["--ignore=E24,W504", "--verbose"]
"python.linting.pydocstyleArgs": ["--ignore=D400", "--ignore=D4"]

请注意，如果顶级元素是单个值（由引号或大括号划定），即使该值本身包含空格，它仍会显示为列表中的单个项目。

自定义路径通常是不必要的，因为 Python 扩展会根据正在使用的 Python 解释器解析 linter 的路径（请参阅环境）。要使用不同版本的 linter，请在适当的自定义路径设置中指定其路径。例如，如果您选择的解释器是虚拟环境，但您想使用安装在全局环境中的 linter，则设置适当的路径设置以指向全局环境的 linter。

以下部分提供了表中链接的那些单个linters的更多详细信息。通常，必须根据您使用的 linter 的要求在单独的文件中指定自定义规则。

Pylint#

Pylint 消息属于下表中的类别，并指定了到 VS Code 类别的映射。您可以更改设置以更改映射。

Pylint类	描述	VS Code 类别映射	适用设置 (python.linting.)
公约 ©	违反编程标准	信息（绿色下划线）	pylintCategorySeverity.convention
重构 ®	糟糕的代码味道	提示（灯泡）	pylintCategorySeverity.refactor
警告 (W)	特定于 Python 的问题	警告	pylintCategorySeverity.warning
错误 (E)	可能的代码错误	错误（红色下划线）	pylintCategorySeverity.error
致命 (F)	一个错误阻止了进一步的 Pylint 处理	错误	pylintCategorySeverity.fatal

默认 Pylint 规则#

Visual Studio 代码中的 Python 默认配置为使用一组对最多 Python 开发人员友好的 linting 规则：

• 启用所有错误 (E) 和致命 (F) 消息。
• 禁用所有约定 © 和重构 ® 消息。
• 禁用所有警告 (W) 消息，但以下消息除外：
  • 无法访问 (W0101)：无法访问的代码
  • 重复键 (W0109)：字典中的重复键 %r
  • 不必要的分号 (W0301)：不必要的分号
  • global-variable-not-assigned (W0602)：对 %r 使用 global 但未完成分配
  • 未使用的变量 (W0612)：未使用的变量 %r
  • 二进制操作异常 (W0711)：要捕获的异常是二进制“%s”操作的结果
  • 错误格式字符串 (W1302)：格式字符串无效
  • 字符串中的异常反斜杠 (W1401)：字符串中的异常反斜杠
  • bad-open-mode (W1501): “%s” 不是有效的打开模式

这些规则通过传递给 Pylint 的以下默认参数来应用：

--disable=all --enable=F,E,unreachable,duplicate-key,unnecessary-semicolon,global-variable-not-assigned,unused-variable,binary-op-exception,bad-format-string,anomalous-backslash-in-string,bad-open-mode

只要将python.linting.pylintUseMinimalCheckers设置为true（默认值），就会传递这些参数。如果您在pylintArgsPylint 配置文件中指定值或使用 Pylint 配置文件（请参阅下一节），则pylintUseMinimalCheckers隐式设置为false.

有关Pylint 消息的完整列表，请参阅readable-pylint-messages (GitHub)。

命令行参数和配置文件#

有关通用开关，请参阅Pylint 命令行参数。命令行参数可用于加载 Pylint 插件，例如 Django 插件：

"python.linting.pylintArgs": ["--load-plugins", "pylint_django"]

也可以在工作区文件夹中的pylintrc或.pylintrc选项文件中指定选项，如Pylint 命令行参数 中所述。

要控制显示哪些 Pylint 消息，请将以下内容添加到选项文件中：

[MESSAGES CONTROL]

# 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.
#enable=

# Disable 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).
#disable=

您可以使用 Pylint 本身轻松生成选项文件：

# Using an *nix shell or cmd on Windows
pylint --generate-rcfile > .pylintrc

对于 PowerShell，您必须明确指定 UTF-8 输出编码：

pylint --generate-rcfile | Out-File -Encoding utf8 .pylintrc

生成的文件包含所有 Pylint 选项的部分，以及注释中的文档。

pydocstyle #

命令行参数和配置文件#

有关一般选项，请参阅pydocstyle 命令行界面。例如，要忽略错误 D400（第一行应以句点结尾），请将以下行添加到您的settings.json文件中：

"python.linting.pydocstyleArgs": ["--ignore=D400"]

代码前缀还指示 pydocstyle 忽略特定类别的错误。例如，要忽略所有 Docstring 内容问题（D4XXX 错误），请将以下行添加到settings.json：

"python.linting.pydocstyleArgs": ["--ignore=D4"]

更多细节可以在pydocstyle 文档中找到。

也可以从[pydocstyle]以下任何配置文件的一部分中读取选项：

• setup.cfg
• tox.ini
• .pydocstyle
• .pydocstyle.ini
• .pydocstylerc
• .pydocstylerc.ini

有关更多信息，请参阅配置文件。

消息类别映射#

Python 扩展将所有 pydocstyle 错误映射到约定 © 类别。

pycodestyle (pep8) #

命令行参数和配置文件#

有关通用开关，请参阅pycodestyle 示例用法和输出。例如，要忽略错误 E303（空行过多），请将以下行添加到您的settings.json文件中：

"python.linting.pycodestyleArgs": ["--ignore=E303"]

pycodestyle 选项从位于正在处理的路径的任何父文件夹中的或文件的[pycodestyle]部分读取。详情见pycodestyle配置。tox.ini``setup.cfg

消息类别映射#

Python 扩展通过以下设置将 pycodestyle 消息类别映射到 VS Code 类别。如果需要，更改设置以更改映射。

pycodestyle 类别	适用设置 (python.linting.)	VS Code 类别映射
宽	pycodestyleCategorySeverity.W	警告
乙	pycodestyleCategorySeverity.E	错误

Prospector#

命令行参数和配置文件#

有关一般选项，请参阅Prospector 命令行用法。例如，要将严格级别设置为“非常高”，请将以下行添加到您的settings.json文件中：

"python.linting.prospectorArgs": ["-s", "veryhigh"]

Prospector 通常使用配置文件来配置 Prospector 的运行方式。默认情况下，Prospector 从.prospector.yaml当前文件夹中的文件加载配置文件。

由于 Prospector 调用其他工具，例如 Pylint，这些工具的任何配置文件都会覆盖.prospector.yaml. 例如，假设您在 中指定以下内容.prospector.yaml：

pylint:
  disable:
    - too-many-arguments

如果您还有一个.pylintrc启用too-many-arguments警告的文件，您将继续在 VS Code 中看到来自 Pylint 的警告。

消息类别映射#

Python 扩展将所有 Prospector 错误和警告映射到错误 (E) 类别。

Flake8 #

命令行参数和配置文件#

有关通用开关，请参阅调用 Flake8。例如，要忽略错误 E303（空行过多），请使用以下设置：

"python.linting.flake8Args": ["--ignore=E303"]

默认情况下，Flake8 会忽略 E121、E123、E126、E226、E24 和 E704。

Flake8 用户选项从C:\Users\<username>\.flake8(Windows) 或~/.config/flake8(macOS/Linux) 文件中读取。

在项目层面，选项从读[flake8]一节tox.ini，setup.cfg或.flake8文件。

具体参见Flake8 配置。

消息类别映射#

Python 扩展通过以下设置将 flake8 消息类别映射到 VS Code 类别。如果需要，更改设置以更改映射。

Flake8类	适用设置 (python.linting.)	VS Code 类别映射
F	flake8CategorySeverity.F	错误
乙	flake8CategorySeverity.E	错误
宽	flake8CategorySeverity.W	警告

mypy#

消息类别映射#

Python 扩展通过以下设置将 mypy 消息类别映射到 VS Code 类别。如果需要，更改设置以更改映射。

我的类别	适用设置 (python.linting.)	VS Code 类别映射
错误	mypyCategorySeverity.error	错误
笔记	mypyCategorySeverity.note	信息

故障排除 linting #

错误信息	原因	解决方案
… 无法导入 <module_name>	Python 扩展使用了错误版本的 Pylint。	确保pythonPath设置指向安装了 Pylint 的有效 Python 安装。或者，python.linting.pylintPath为正在使用的 Python 解释器设置合适的 Pylint 版本。
使用 进行 Linting 失败…	Python 解释器的路径不正确。	检查pythonPath设置（请参阅环境）。
	当前 Python 环境中尚未安装 linter。	打开命令窗口，导航到pythonPath设置中Python 解释器的位置，然后运行pip installlinter。
	linter 的路径不正确。	确保python.linting.<linter>Pathlinters的适当设置是正确的。
	自定义参数定义不正确。	检查适当的python.linting.<linter>Args设置，并且设置的值是由空格分隔的参数元素的列表。例如，"python.linting.pylintPath": "pylint --load-plugins pylint_django"是不正确的。正确的语法是"python.linting.pylintArgs": ["--load-plugins", "pylint_django"].

下一步#

• 调试- 学习在本地和远程调试 Python。
• 测试- 配置测试环境并发现、运行和调试测试。
• 基本编辑- 了解强大的 VS Code 编辑器。
• 代码导航- 快速浏览源代码。