在 VS Code 中格式化 Python

格式化使源代码更容易被人读。通过强制执行特定的规则和约定，例如行间距、缩进和运算符周围的空格，代码变得更加视觉上有组织和易懂。您可以在autopep8页面上查看一个例子。请记住，格式化不会影响代码本身的 functionality。

代码检查通过分析代码以防止常见的语法、风格和功能错误以及非标准的编程实践来帮助预防错误。尽管格式化和代码检查之间有一些重叠，但这两个功能是互补的。

选择一个格式化器

搜索VS Code 市场中您选择的格式化扩展。

微软发布了以下格式扩展：

格式化器	扩展
自动 pep8	https://marketplace.visualstudio.com/items?itemName=ms-python.autopep8
黑色格式化器	https://marketplace.visualstudio.com/items?itemName=ms-python.black-formatter

社区提供的格式化扩展：

格式化器	扩展
拉夫	https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff
输入：yapf	https://marketplace.visualstudio.com/items?itemName=eeyore.yapf

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

格式化器	扩展
拉夫	https://marketplace.visualstudio.com/items?itemName=charliermarsh.ruff
排序	https://marketplace.visualstudio.com/items?itemName=ms-python.isort

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

设置默认格式化器

一旦你安装了格式化器扩展，你可以通过以下步骤将其设置为 VS Code 中 Python 文件的默认格式化器：

在 VS Code 中打开一个 Python 文件。
右键单击编辑器以显示上下文菜单。
选择 格式化文档与....
选择 配置默认格式化器... 从下拉菜单中。
从列表中选择您偏好的格式化扩展。

或者，您可以通过设置将其设置为所有Python文件的默认格式化程序"editor.defaultFormatter"在你的用户settings.json文件，根据[Python]范围。您可以打开settings.json 使用 偏好设置：打开用户设置 (JSON) 命令。

例如，要将 Black Formatter 设置为默认格式化程序，请在你的用户设置中添加以下内容settings.json文件:

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

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

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

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

格式化你的代码

您可以通过在编辑器上右键单击并选择格式化文档，或使用⇧⌥F（WindowsShift+Alt+F，LinuxCtrl+Shift+I）键盘快捷键来格式化您的代码。

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

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

常规格式设置

您可以参考每个格式化器扩展的README，以获取有关支持的设置的更多详细信息。以下设置由大多数格式化器扩展支持：

设置后缀	默认值	描述
参数	`[]`	传递给格式化器的参数。每个参数应作为数组中的一个单独字符串传递。例如： `black-formatter.args: ["--line-length", "100"]`
导入策略	`使用捆绑`	当设置为`使用捆绑`该扩展使用的是它自带的工具版本。当设置为`来自环境`它首先尝试从您选择的Python环境中加载，否则会回退到捆绑版本。
路径	`"`	用于格式化的格式化二进制文件的路径。注意：使用此选项可能会减慢格式化速度。
解释器	`[]`	当设置为Python可执行文件的路径时，该扩展将使用该路径启动格式化服务器及其子进程。
显示通知	`关`	控制扩展何时显示通知。支持的值是`关`，`总是`，`错误处理`，和`onWarning`输入：.

故障排除格式化

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

问题	解决方案
有多种格式化工具可用于Python文件。	按照上文中的说明设置默认格式化器.
没有“用...格式化文档”的选项。	如果在上下文菜单中看不到此选项，很可能是您没有在 VS Code 中安装或启用格式化扩展。请参考选择格式化器部分，了解如何安装 Python 格式化器扩展。
格式化器的自定义参数不正确。	检查适当的`<formatter>.路径`设置不包含参数，并且`<formatter>.args`包含一个顶级参数元素的列表。
显示“您已弃用 linting 或格式化设置”的通知。	如果您看到此通知，这意味着您的设置为`python.静态代码分析`或`python.格式化`在 VS Code 中。这些设置不再被 Python 扩展支持，因为代码检查和格式化支持已迁移到工具扩展。
当使用Black格式化器时格式选择命令失败。	`黑色`不支持格式化代码部分。为了绕过这个限制，您可以禁用粘贴时的格式并设置`保存时格式化`格式化整个文件，设置如下：`"[python]": {"editor.formatOnPaste": false, "editor.formatOnSaveMode": "file"}`输入：.
格式化即使我安装了格式化扩展也不起作用。	格式化可能会因各种原因失败，例如代码中的语法问题、使用了不支持的Python版本，或者格式化器没有正确配置。检查格式化扩展的输出通道以了解格式化器失败的原因（在命令面板中运行输出：聚焦输出命令，然后选择格式化器扩展通道）。

注意：如果您没有在上面找到您喜欢的格式化器，您可以添加支持扩展。 Python 扩展模板使将新的 Python 工具集成到 VS Code 中变得容易。

下一步

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