在 VS Code 中格式化 Python

格式化使源代码更容易被人类阅读。通过强制执行特定的规则和约定（例如行间距、缩进和运算符周围的间距），代码变得更加直观且易于理解。您可以在autopep8页面上查看示例。请记住，格式化不会影响代码本身的功能。

Linting通过分析代码中常见的语法、风格和功能错误以及非常规编程实践来帮助防止错误。尽管格式化和 linting 之间有一点重叠，但这两种功能是互补的。

选择格式化程序

从 VS Code Marketplace安装您选择的格式化工具。

Microsoft 发布了以下格式扩展：

格式化程序 扩大
autopep8 https://marketplace.visualstudio.com/items?itemName=ms-python.autopep8
Black formatter https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter

社区提供的格式化程序扩展：

格式化程序 扩大
Ruff https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff
yapf https://marketplace.visualstudio.com/items?itemName=eeyore.yapf

此外，以下是支持导入排序的格式化程序扩展：

格式化程序 扩大
Ruff https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff
isort https://marketplace.visualstudio.com/items?itemName=ms-python.isort

注意：如果您在上表或市场中找不到您喜欢的格式化程序，您可以通过扩展添加对其的支持。您可以使用Python 扩展模板将新的 Python 工具集成到 VS Code 中。

设置默认格式化程序

安装格式化程序扩展后，您可以按照以下步骤选择它作为 VS Code 中 Python 文件的默认格式化程序：

  1. 在 VS Code 中打开 Python 文件。
  2. 右键单击编辑器以显示上下文菜单。
  3. 选择文档格式...。
  4. 从下拉菜单中选择配置默认格式化程序...。
  5. 从列表中选择您喜欢的格式化程序扩展。

"editor.defaultFormatter"或者，您可以通过在用户settings.json文件中的某个范围下进行设置，将其设置为所有 Python 文件的默认格式化程序[python]。您可以settings.json使用首选项：打开用户设置 (JSON)命令打开。

例如，要将 Black Formatter 设置为默认格式化程序，请将以下设置添加到您的用户settings.json文件中：

  "[python]": {
    "editor.defaultFormatter": "ms-python.black-formatter"
  }

为了将格式化程序扩展设置为导入排序器，您可以"editor.codeActionsOnSave"在用户settings.json文件或工作区settings.json文件的[python]范围下设置您的首选项。您可以分别使用首选项：打开用户设置 (JSON)和首选项：打开工作区设置 (JSON)命令打开这些settings.json文件。这将为所有 Python 文件启用保存时导入排序。

例如，要将 Ruff 设置为您的首选导入排序器，您可以将以下设置添加到您的用户settings.json或工作区settings.json文件中：

{
  "[python]": {
    "editor.codeActionsOnSave": {
      "source.organizeImports.ruff": true
    }
  }
}

设置代码格式

您可以通过右键单击编辑器并选择Format Document或使用⇧⌥F（Windows Shift+Alt+F、Linux Ctrl+Shift+I）键盘快捷键来格式化代码。

您还可以将以下设置添加到您的用户settings.json文件中，以便在保存代码时启用格式设置：

  "[python]": {
    "editor.formatOnSave": true
  }

常规格式设置

每个格式化程序扩展可能有自己的设置，但autopep8和Black Formatter都支持以下设置：

设置后缀
 默认值 描述
args [] 要传递给格式化程序的参数。每个参数都应作为数组中的单独字符串传递。
例如：
black-formatter.args: ["--line-length", "100"]
importStrategy useBundled 当设置为 时useBundled，扩展使用其附带的工具版本。当设置为 时fromEnvironment，它会首先尝试从您选择的 Python 环境加载，否则它将回退到捆绑版本。
path "" 用于格式化的格式化程序二进制文件的路径。注意：使用此选项可能会减慢格式化速度。
interpreter [] 当设置为 Python 可执行文件的路径时，扩展将使用它来启动格式化程序服务器及其子进程。
showNotifications off 控制此扩展程序何时显示通知。支持的值为off、always、onError和onWarning。

格式化疑难解答

如果格式化失败，请排查以下可能原因：

问题 解决方案
There are multiple formatters available for Python files. 按照上一节中的说明设置默认格式化程序。
Custom arguments for the formatter are incorrect. 检查适当的<formatter>.path设置是否不包含参数，并且<formatter>.args包含各个顶级参数元素的列表。
The Format Selection command fails when using Black Formatter. black不支持格式化代码部分。要解决此限制，您可以禁用粘贴格式并设置formatOnSave为使用以下设置格式化整个文件："[python]": {"editor.formatOnPaste": false, "editor.formatOnSaveMode": "file"}。
The document isn't formatted. 检查格式化程序扩展的输出通道以了解格式化程序失败的原因（运行“输出：命令面板中的聚焦输出”命令，然后选择格式化程序扩展通道）。

注意：如果您没有找到上面列出的首选格式化程序，您可以通过扩展添加支持。Python 扩展模板可以轻松地将新的 Python 工具集成到 VS Code 中。

下一步

  • 调试- 学习本地和远程调试 Python。
  • 测试- 配置测试环境并发现、运行和调试测试。
  • 基本编辑- 了解强大的 VS Code 编辑器。
  • 代码导航- 快速浏览源代码。
  • Python 扩展模板- 创建一个扩展以将您喜欢的 linter 集成到 VS Code 中。
2023年8月7日