在 VS Code 中尝试

在 VS Code 中格式化 Python

格式化使源代码更易于人类阅读。通过强制执行特定的规则和约定(例如行距、缩进和运算符周围的间距),代码在视觉上变得更有条理,更容易理解。你可以在 autopep8 页面上查看示例。请记住,格式化本身不影响代码的功能。

代码检查 (Linting) 通过分析代码中的常见语法、样式和功能错误以及非常规编程实践来帮助预防错误。尽管格式化和代码检查之间有一些重叠,但这两项功能是互补的。

选择格式化程序

VS Code Marketplace 中搜索你选择的格式化程序扩展。

Microsoft 发布以下格式化程序扩展

格式化程序 扩展
autopep8 https://marketplace.visualstudio.com/items?itemName=ms-python.autopep8
Black 格式化程序 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

注意:如果在上表中或 Marketplace 中找不到首选的格式化程序,可以通过扩展添加支持。你可以使用 Python 扩展模板 将新的 Python 工具集成到 VS Code 中。

设置默认格式化程序

安装格式化程序扩展后,可以按照以下步骤将其选为 VS Code 中 Python 文件的默认格式化程序

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

或者,你可以在用户 settings.json 文件中的 [python] 范围内设置 "editor.defaultFormatter",将其设置为所有 Python 文件的默认格式化程序。你可以使用首选项:打开用户设置 (JSON) 命令打开 settings.json

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

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

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

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

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

格式化代码

你可以通过右键单击编辑器并选择格式化文档,或者使用键盘快捷方式 ⇧⌥F (Windows Shift+Alt+F, Linux Ctrl+Shift+I) 来格式化代码。

你还可以将以下设置添加到用户 settings.json 文件中,以启用代码保存时格式化

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

常规格式化设置

你可以参考每个格式化程序扩展的 README 以获取有关支持的设置的更多详细信息。大多数格式化程序扩展支持以下设置

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

格式化故障排除

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

问题 解决方案
Python 文件有多个格式化程序可用。 按照上面的部分中的说明设置默认格式化程序。
没有“格式化文档方式...”选项。 如果在上下文菜单中看不到此选项,则可能是你在 VS Code 中没有安装或启用格式化程序扩展。请参阅选择格式化程序部分,了解如何安装 Python 格式化程序扩展。
格式化程序的自定义参数不正确。 检查相应的 <formatter>.path 设置不包含参数,并且 <formatter>.args 包含顶级参数元素的列表。
显示“你有一些已弃用的 linting 或格式化设置”通知。 如果看到此通知,这意味着你在 VS Code 中有诸如 python.lintingpython.formatting 之类的设置。这些设置不再由 Python 扩展支持,因为代码检查和格式化支持已迁移到工具扩展
使用 Black 格式化程序时,格式化选定内容命令失败。 black 不支持格式化代码的选定部分。为了解决此限制,你可以禁用粘贴时格式化,并将 formatOnSave 设置为使用以下设置格式化整个文件:"[python]": {"editor.formatOnPaste": false, "editor.formatOnSaveMode": "file"}
即使安装了格式化程序扩展,格式化也无效。 格式化失败可能出于各种原因,例如代码中的语法问题、使用了不支持的 Python 版本,或者格式化程序配置不正确。检查格式化程序扩展的“输出”通道以了解格式化程序失败的原因(在命令面板中运行输出:焦点在输出命令,然后选择格式化程序扩展通道)。

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

下一步

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