在 Visual Studio Code 中编辑 Python

Visual Studio Code 是一款功能强大的 Python 源代码编辑工具。该编辑器包含了多种功能，可帮助您提高代码编写效率。有关在 Visual Studio Code 中进行编辑的更多信息，请参阅基础编辑和代码导航。

在本概述中，我们将介绍 Python 扩展提供的特定编辑功能，包括如何通过用户和工作区设置自定义这些功能的步骤。

自动补全与 IntelliSense

IntelliSense 是与代码补全相关的代码编辑功能的通用术语。请花点时间查看下面的示例。当键入 print 时，请注意 IntelliSense 如何填充自动补全选项。当用户开始输入名为 greeting 的变量时，也会看到一个选项列表。

当前工作文件夹中的所有文件都支持自动补全和 IntelliSense。它们也适用于安装在标准位置的 Python 包。

Pylance 是 VS Code 中 Python 的默认语言服务器，它随 Python 扩展一起安装，以提供 IntelliSense 功能。

Pylance 基于微软的 Pyright 静态类型检查工具，利用类型存根（.pyi 文件）和惰性类型推断来提供高性能的开发体验。

有关 IntelliSense 的更多通用信息，请参阅 IntelliSense。

提示：请查看 VS Code 的 IntelliCode 扩展。IntelliCode 为 Python 中的 IntelliSense 提供了一套人工智能辅助功能，例如根据当前代码上下文推断最相关的自动补全内容。有关详细信息，请参阅 IntelliCode for VS Code 常见问题解答。

自定义 IntelliSense 行为

默认启用全套 IntelliSense 功能可能会让您的开发体验变慢，因此 Python 扩展默认启用了一组最基本的功能，让您在保持高效工作的同时也能获得高性能的体验。不过，您可以通过多种设置来根据自己的喜好自定义分析引擎的行为。

启用自动导入

Pylance 为您工作区中的模块以及您在环境中安装的包提供自动导入建议。当您在编辑器中输入代码时，可能会获得补全建议。当您接受建议时，自动导入功能会自动将相应的导入语句添加到您的文件中。

您可以通过在设置中将 python.analysis.autoImportCompletions 设置为 true 来启用自动导入。默认情况下，自动导入处于禁用状态。

为自定义包路径启用 IntelliSense

要为安装在非标准位置的包启用 IntelliSense，请将这些位置添加到 settings.json 文件中的 python.analysis.extraPaths 集合中（默认集合为空）。例如，如果您使用 Flask，可能会在 app.yaml 中指定 Google App Engine 的安装位置。在这种情况下，您可以按如下方式指定这些位置：

Windows

"python.analysis.extraPaths": [
    "C:/Program Files (x86)/Google/google_appengine",
    "C:/Program Files (x86)/Google/google_appengine/lib/flask-0.12"]

macOS/Linux

"python.analysis.extraPaths": [
    "~/.local/lib/Google/google_appengine",
    "~/.local/lib/Google/google_appengine/lib/flask-0.12" ]

有关可用 IntelliSense 控件的完整列表，请参考 Python 扩展的代码分析设置和自动补全设置。

您还可以自定义自动补全和 IntelliSense 的常规行为，甚至完全禁用这些功能。您可以在自定义 IntelliSense 中了解更多信息。

使用 AI 增强补全

GitHub Copilot 是一款由 AI 驱动的代码补全工具，可以帮助你更快、更智能地编写代码。你可以在 VS Code 中使用 GitHub Copilot 扩展来生成代码，或从其生成的代码中学习。

GitHub Copilot 为多种语言和各种框架提供建议，在 Python、JavaScript、TypeScript、Ruby、Go、C# 和 C++ 方面表现尤为出色。

你可以在Copilot 文档中了解更多关于如何开始使用 Copilot 的信息。

导航

在编辑过程中，您可以右键点击不同的标识符来利用一些便捷命令：

• 转到定义 (F12) 可以从代码跳转到定义对象的地方。当您使用库时，此命令非常有用。

• 速览定义 (⌥F12 (Windows Alt+F12, Linux Ctrl+Shift+F10)) 与之类似，但会在编辑器中直接显示定义（在编辑器窗口中腾出空间，以免遮挡代码）。按 Escape 或点击右上角的 x 可关闭“速览”窗口。

• 转到声明 可以跳转到代码中声明变量或其他对象的位置。

• 速览声明 与此类似，但会在编辑器中直接显示声明。同样，使用 Escape 或右上角的 x 来关闭“速览”窗口。

快速修复

添加导入

使用 Pylance 时，“添加导入”快速修复功能使您可以快速补全环境中已安装模块的导入语句。当您在编辑器中开始输入包名时，会出现代码操作（Code Action）来自动补全该行源代码。将鼠标悬停在文本上（带有波浪线标记），然后选择代码操作灯泡图标。随后，您可以从潜在导入列表中进行选择。

此代码操作还识别以下常见 Python 包的一些常用缩写：numpy 为 np，tensorflow 为 tf，pandas 为 pd，matplotlib.pyplot 为 plt，matplotlib 为 mpl，math 为 m，scipi.io 为 spio，scipy 为 sp，panel 为 pn，以及 holoviews 为 hv。

导入建议列表显示前 3 个高置信度的导入选项，其优先级顺序为：最近使用的导入、来自同一模块的符号、来自标准库的符号、来自用户模块的符号、来自第三方包的符号，最后按模块和符号名称排序。

搜索更多导入匹配项

默认情况下，“添加导入”快速修复仅显示 3 个高置信度的导入选项。如果其中没有您想要的内容，您可以使用 Pylance 的“搜索更多导入匹配项”快速修复功能来处理缺失的导入错误。此快速修复会显示一个快速选择菜单，使您可以搜索前缀匹配缺失导入符号的导入选项。

修改拼写

当未解析的变量或缺失的导入很可能是由拼写错误引起时，Pylance 会在诊断信息中显示“修改拼写”快速修复。此代码操作会根据在工作区中找到的最相似匹配项，建议符号的正确拼写。

注意：对于用户符号，这些快速修复仅建议从定义它们的源文件中导入。不支持从用户符号为外部/导入来源的文件中进行导入建议。

另请注意，对于来自已安装包（通常位于 Python 环境的 site-packages 文件夹下）的符号，这些快速修复仅建议定义在包根目录（例如其 __init__.py 文件中）下的符号。您可以通过 python.analysis.packageIndexDepths 设置针对特定包自定义此行为，但请注意这可能会影响 Pylance 的性能。

重构

Python 扩展通过 Pylance 扩展添加了以下重构功能：提取变量、提取方法、重命名模块、移动符号以及实现所有继承的抽象类。它还支持实现额外重构功能的扩展，例如排序导入。

提取变量

提取当前作用域内所选文本的所有相似出现，并将其替换为新变量。

您可以通过选择想要提取为变量的代码行来调用此命令，然后选择旁边显示的灯泡图标即可。

提取方法

提取当前作用域内所选表达式或代码块的所有相似出现，并将其替换为方法调用。

您可以通过选择想要提取为方法的代码行来调用此命令，然后选择旁边显示的灯泡图标即可。

重命名模块

在重命名 Python 文件/模块后，Pylance 可以找到所有可能需要更新的实例，并为您提供所有更改的预览。

要自定义需要更新的引用，您可以在重构预览中切换行级别或文件级别的复选框。做出选择后，您可以选择应用重构或放弃重构。

移动符号

Pylance 扩展提供了两个代码操作来简化将符号移动到不同文件的过程：

• 移动符号到...：显示一个文件选择器，用于选择移动符号的目标文件。
• 移动符号到新文件：创建一个以符号命名的新文件，位于调用该代码操作的源文件所在的同一目录中。

您可以将鼠标悬停在要移动的符号上，然后选择动作旁边出现的灯泡图标来访问这些代码操作。或者，您可以右键点击该符号，然后从上下文菜单中选择重构...。

实现所有继承的抽象类

在 Python 中，抽象类充当其他类的“蓝图”，通过提倡明确的结构和子类必须遵守的要求，帮助构建模块化、可重用的代码。要在 Python 中定义抽象类，您可以创建一个继承自 abc 模块中 ABC 类的类，并使用 @abstractmethod 装饰器对其方法进行注解。然后，您可以创建继承自此抽象类的新类，并为基础方法定义实现。

Pylance 提供了一个代码操作来简化创建这些类的过程。当您定义一个继承自抽象类的新类时，现在可以使用“实现所有继承的抽象类”代码操作，自动实现父类中的所有抽象方法和属性。

排序导入

Python 扩展支持诸如 isort 和 Ruff 等实现排序导入功能的扩展。此命令将来自同一模块的特定导入合并为单个 import 语句，并按字母顺序组织 import 语句。

您可以通过安装支持排序导入的扩展来调用此功能，然后打开命令面板（⇧⌘P (Windows, Linux Ctrl+Shift+P)）并运行组织导入 (Organize Imports)。

提示：您可以为 editor.action.organizeImports 命令分配键盘快捷键。

故障排除

有关常见的 IntelliSense 和 Python 编辑问题的帮助，请查看下表：

Pylance 诊断

默认情况下，Pylance 会在“问题”面板中为 Python 文件提供诊断信息。

以下列表是 Pylance 提供的一些最常见的诊断及其解决方法。

importResolveSourceFailure

当 Pylance 能够找到已导入包的类型存根，但找不到包本身时，会出现此错误。当您尝试导入的包未安装在所选 Python 环境中时，可能会发生这种情况。

如何修复

• 如果包已安装在不同的解释器或内核中，请选择正确的解释器。
• 如果尚未安装该包，您可以通过在激活的终端中运行以下命令来安装它：python -m pip install {package_name}。

importResolveFailure

当 Pylance 找不到您正在导入的包或模块，也找不到其类型存根时，会出现此错误。

如何修复

• 如果您正在导入一个模块，请确保它存在于您的工作区中或存在于 python.autoComplete.extraPaths 设置包含的位置中。
• 如果您正在导入一个未安装的包，您可以通过在激活的终端中运行以下命令来安装它：python -m pip install {package_name}。
• 如果您正在导入一个已安装在不同解释器或内核中的包，请选择正确的解释器。
• 如果您正在使用可编辑安装，并且目前设置为使用导入钩子（import hooks），请考虑改用仅包含文件路径的 .pth 文件，以增强兼容性并确保更顺畅的导入行为。在 Pyright 文档中了解更多信息。

importCycleDetected

当 Pylance 检测到两个或多个模块之间存在循环依赖时，会出现此错误。

如何修复

尝试重新排序您的导入语句以打破循环依赖。

Pylance 诊断的严重性可以通过 python.analysis.diagnosticSeverityOverrides 设置进行自定义。有关更多信息，请查看设置参考。

后续步骤

• Linting - 启用、配置和应用各种 Python linter。
• 调试 - 了解如何在本地和远程调试 Python。
• 测试 - 配置测试环境以及发现、运行和调试测试。
• 基本编辑 - 了解功能强大的 VS Code 编辑器。
• 代码导航 - 快速浏览您的源代码。
• IntelliSense - 了解有关 IntelliSense 功能的信息。
• Jupyter 支持 - 了解如何开始使用 Jupyter Notebook。
• Python 扩展模板 - 创建一个扩展以集成您最喜欢的 Python 工具。