microsoft/pylance-release

来源: https://github.com/microsoft/pylance-release

Pylance

快速、功能丰富的 Python 语言支持

本仓库用于提供 Pylance 语言服务器扩展（https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance）在 Visual Studio Code 中的反馈和文档。您可以使用本仓库报告问题或提交功能请求。

Pylance 的代码库并非开源，但您可以参与 Pyright（https://github.com/microsoft/pyright）的贡献，为支撑 Pylance 体验的核心类型引擎做出改进。

Pylance 是 Visual Studio Code（https://marketplace.visualstudio.com/items?itemName=ms-python.python）中 Python 的默认语言支持，作为该扩展的可选依赖项随扩展一起发布。

Pylance 这个名字是对 Monty Python 中 Lancelot（兰斯洛特）的小致敬，他是《圣杯》中第一个回答守桥人问题的骑士。

快速入门

1. 从市场安装 Python 扩展（https://marketplace.visualstudio.com/items?itemName=ms-python.python）。Pylance 将作为可选扩展自动安装。
2. 打开一个 Python（.py）文件，Pylance 扩展将自动激活。

注意：如果您之前已设置过语言服务器并希望尝试 Pylance，请确保在 settings.json 文件中使用文本编辑器或设置编辑器 UI 将 "python.languageServer" 设置为 "Default" 或 "Pylance"。

功能

features

Pylance 为 Python 3 提供了一些出色的功能，包括：

• 文档字符串（Docstrings）
• 签名帮助，包含类型信息
• 参数建议
• 代码补全
• 自动导入（以及添加和移除导入的代码操作）
• 输入时实时报告代码错误和警告（诊断）
• 代码大纲
• 代码导航
• 类型检查模式
• 原生多根工作区支持
• Jupyter Notebooks 兼容性
• 语义高亮
• 为工作区根目录、资源管理器文件夹和 Python 脚本生成依赖文件命令（Pylance: Generate Dependency File）
• Python 块注释切换命令（Pylance: Toggle Block Comment）
• 安装匹配的类型存根命令，查找并为您已安装的依赖项安装类型存根包（Pylance: Install Matching Type Stubs）
• Copilot Chat 技能，提供基于事实的 Python 帮助、类型推断、内联类型注解、查找已审核的第三方存根、存根编写、Pylance 文档、重构、性能分析、提升 Pylance 类型求值性能，以及添加或移除 Python 版本支持

有关最新版本，请参阅更新日志。

设置与自定义

Pylance 通过一系列设置为用户提供自定义 Python 语言支持的能力，这些设置可以放在工作区的 settings.json 文件中，也可以通过设置编辑器 UI 进行编辑。

• python.analysis.languageServerMode — 提供预定义配置，帮助用户根据开发需求优化 Pylance 的性能。它控制 Pylance 提供多少 IntelliSense 功能，让您可以在完整的语言服务功能和为性能优化的轻量级体验之间做出选择。
  • 默认值：default
  • 可用值：
    • light
    • default（默认）
    • full
  • 描述：
    • default：提供平衡的体验，默认启用许多有用的功能。确保语言服务器为大多数用户提供足够的功能，而不会使系统过载。高级功能可以根据需要启用，以牺牲性能为代价进行进一步自定义。
    • light：专为寻求轻量级、内存高效设置的用户设计。此模式禁用各种功能，使 Pylance 的行为更像一个精简的文本编辑器。适合不需要全部 IntelliSense 功能并希望 Pylance 尽可能节省资源的用户。
    • full：专为寻求最广泛功能集的用户设计。此模式启用 Pylance 的大多数功能，提供最丰富的 IntelliSense 体验。适合希望使用全部可用功能的用户。
  • 单个设置可以配置为覆盖 languageServerMode 设置的默认值。
  • 各模式的默认设置如下：

• python.analysis.typeCheckingMode — 用于指定执行的类型检查分析级别。

  • 默认值：off。

  注意：此设置的值可以被 pyrightconfig.json 或 pyproject.toml 覆盖。更多信息请参阅此链接（https://aka.ms/AArua4c）。

  • 可用值：
    • off：禁用大多数类型检查诊断；仅产生未解析的导入/变量诊断。
    • basic：off 的所有规则 + basic 类型检查规则。
    • standard：basic 的所有规则 + standard 类型检查规则。
    • strict：standard 的所有规则 + strict 类型检查规则。

  您可以参考 pyright（https://microsoft.github.io/pyright/#/configuration?id=diagnostic-settings-defaults）文档来查看每种类型检查模式的默认类型检查规则。

  • 性能考虑：
    • 将 python.analysis.typeCheckingMode 设置为 off 可以通过减少诊断检查来提高性能，尤其在大型代码库中效果明显。

• python.analysis.diagnosticMode — 用于指定哪些文件接受完整的诊断分析。

  • 可用值：
    • workspace
    • openFilesOnly（默认）
  • 性能考虑：
    • 将 python.analysis.diagnosticMode 设置为 openFilesOnly 可将完整诊断限制在已打开的文件上，减少大型工作区中的检查量。已导入的依赖项仍会被分析。

• python.analysis.include — 应包含的目录或文件路径。如果未指定任何路径，Pylance 默认使用工作区根目录。路径可以包含通配符 **（一个目录或多级目录）、*（零个或多个字符的序列）或 ?（单个字符）。

  • 默认值：空数组

• python.analysis.exclude — 不应包含的目录或文件路径。这些路径会覆盖 include 目录，允许排除特定的子目录。注意，排除路径中的文件如果被未被排除的源文件引用（导入），仍可能被包含在分析中。路径可以包含通配符 **（一个目录或多级目录）、*（零个或多个字符的序列）或 ?（单个字符）。如果未指定排除路径，Pylance 会自动排除以下内容：**/node_modules、**/__pycache__、.git 以及所有虚拟环境目录。

  • 默认值：空数组（或 light 模式下的 ["**"]）
  • 性能考虑：
    • 排除不必要的文件或目录可以通过减少工作区发现来显著提高性能。例如，将 python.analysis.exclude 设置为 ["**"] 可禁用工作区文件的发现；已打开的文件及其所需的导入仍可被分析。

• python.analysis.useDefaultExcludes — 启用时（默认），Pylance 会在 python.analysis.exclude 中列出的路径之外，添加一组内置默认排除项：**/node_modules、**/__pycache__、**/__editable__.*、隐藏目录（dotfiles）以及自动检测到的虚拟环境目录。这些默认值优先于 python.analysis.include，因此即使某个目录被自动检测为虚拟环境并被显式包含，它仍会被排除。

  • 将此项设置为 false 可禁用所有这些内置排除项——包括虚拟环境的自动检测——使排除仅限于 python.analysis.exclude 中列出的路径。如果您的工作区包含大型依赖或环境目录，禁用此选项可能会显著减慢分析速度。
  • 默认值：true

• python.analysis.useNearestConfiguration（实验性）— 启用后，Pylance 将在子目录中搜索并使用 pyrightconfig.json 或 pyproject.toml 文件，为每个配置创建虚拟工作区。这允许代码库的不同部分使用不同的类型检查设置。

  • 默认值：false

  • 可用值：

    • true
    • false（默认）

  • 注意：

    • 此功能为实验性功能，在大型工作区中可能影响性能。
    • 虚拟工作区遵循 python.analysis.exclude 的模式。
    • 仅发现包含 [tool.pyright] 部分的 pyproject.toml 文件。
    • 重要：虚拟工作区之间的导入使用正常的导入解析。当另一个工作区的源目录无法被找到时，请在 pyrightconfig.json 或 pyproject.toml 中配置 extraPaths。例如：

    {
      "extraPaths": ["../other-workspace"]
    }
    

• python.analysis.usePerProjectEnvironments — 启用后，Pylance 将为通过 python-envs.pythonProjects 声明的每个项目使用独立的 Python 环境（解释器）。这确保单根工作区中的每个子项目都使用其自身的解释器进行类型检查。

  • 默认值：false
  • 可用值：
    • true
    • false（默认）
  • 注意：
    • 每个子项目可能还需要自己的 extraPaths 配置，以确保跨项目导入正确解析。要让 Pylance 自动配置这些，请启用 python.analysis.addExtraPathsForPythonProjects。
    • 此设置取代了已弃用的 python.analysis.addFoldersForPythonProjects，后者仍可向后兼容使用。

• python.analysis.addExtraPathsForPythonProjects — 实验性功能。 启用后，Pylance 会自动将通过 python-envs.pythonProjects 声明的每个项目的源根目录添加到 extraPaths 中，使 monorepo 中子项目之间的跨项目导入无需手动配置 extraPaths 即可解析。

  • 源根目录按项目检测：如果存在 src 目录则使用 src；如果项目文件夹本身是一个包（包含 __init__.py），则使用项目文件夹的父目录；否则使用项目文件夹本身。
  • 在每个项目的 pyproject.toml 中声明的可编辑/本地跨包引用会被传递性地追踪，因此如果一个注册的项目以可编辑安装的方式导入同级包，它也会获取这些包的源根目录。这就是像 dagster 这样的 monorepo 无需注册每个包即可解析的原因。识别的依赖管理器格式包括：
    • uv — 包含本地 path 的 [tool.uv.sources] 条目。
    • Poetry — [tool.poetry.dependencies]、[tool.poetry.dev-dependencies] 和 [tool.poetry.group.*.dependencies] 中的 path/develop 条目。
    • PDM / Rye / PEP 508 / PEP 735 — [project].dependencies、[project.optional-dependencies]、[dependency-groups]、[tool.pdm.dev-dependencies] 和 [tool.rye.dev-dependencies] 中的 file: 直接引用（包括 ${PROJECT_ROOT} 和 {root:uri} 根标记，以及 -e/--editable 条目）。
    • 命名依赖、VCS 依赖和远程 URL 依赖会被忽略，指向已构建归档文件（wheels/sdists）的引用会被跳过。
  • 您配置的任何 extraPaths 都会被保留；检测到的源根目录会被追加。
  • 默认值：false
  • 可用值：
    • true
    • false（默认）

• python.analysis.ignore — 应抑制其诊断输出（错误和警告）的目录或文件路径，即使它们是被包含的文件或位于被包含文件的传递闭包中。路径可以包含通配符 **（一个目录或多级目录）、*（零个或多个字符的序列）或 ?（单个字符）。

  • 默认值：空数组

• python.analysis.excludeLibraryDiagnostics — 启用后，抑制来自库文件（site-packages、typeshed、内置存根等）的所有诊断，同时保留用户编写的工作区文件和孤立文件的诊断。适合在打开库源文件进行参考时使用，而不会在“问题“面板中造成混乱。

  • 默认值：false

• python.analysis.stubPath — 用于指定包含自定义类型存根的目录路径。每个包的类型存根文件应位于其自己的子目录中。

  • 默认值：./typings

• python.analysis.autoSearchPaths — 用于根据某些预定义名称（如 src）自动添加搜索路径。

  • 可用值：
    • true（默认）
    • false

• python.analysis.extraPaths — 用于指定导入解析的额外搜索路径。取代了旧的 python.autoComplete.extraPaths 设置。

  • 默认值：空数组

• python.analysis.ignoredPackages — 从类型分析中排除的已安装包列表。请指定可导入的包名（例如 "PIL" 而非 "Pillow"）。被忽略的包中的文件在分析时返回空内容，但目录结构仍保留以用于导入解析。

  • 默认值：空数组

• python.analysis.disableBundledStubs — 禁用 Pylance 的内置类型存根，以便直接分析已安装的包。设置为 true 可禁用所有内置存根，或提供包名列表仅禁用指定的存根。

  • 默认值：false

• python.analysis.includeExtraPathSymbolsInSymbolSearch — 在工作区符号搜索中包含来自 python.analysis.extraPaths 的符号。

  • 默认值：false
  • 性能考虑：
    • 启用此设置可能会减慢工作区符号搜索的速度。
  • 注意：
    • 当 includeAllSymbols 设置为 false 时，非 py.typed 包中的 Python 源文件仅贡献 __all__ 中的符号；存根和类型化包可以贡献其他符号。

• python.analysis.includeVenvInWorkspaceSymbols — 在工作区符号搜索中包含来自已安装第三方包（venv 的 site-packages）的符号。

  • 默认值：false
  • 性能考虑：
    • 对于大型虚拟环境，启用此设置可能会显著减慢工作区符号搜索的速度。
    • 仅在启用 python.analysis.indexing 时生效。
  • 注意：
    • 仅包含安装在 site-packages（或 Debian/Ubuntu 上的 dist-packages）中的包的符号。标准库符号不包含在内。
    • 当 includeAllSymbols 设置为 false 时，非 py.typed 包中的 Python 源文件仅贡献 __all__ 中的符号；存根和类型化包可以贡献其他符号。
    • 当搜索查询为空时，不返回 venv/库的符号（结果集会太大）。用户代码符号始终返回，与查询无关。
    • 搜索的子包深度取决于 python.analysis.packageIndexDepths 的设置。