Authoring Python Extensions

注意：如果您是 VS Code 扩展开发新手，建议您先阅读 Your First Extension 教程，并尝试创建一个简单的 Hello World 扩展。

Python 扩展提供了 API，供其他扩展使用用户计算机上的 Python 环境。请查看 @vscode/python-extension npm 模块，其中包含类型和辅助工具，以便从您的扩展中访问这些 API。

Python 扩展模板

Python 扩展模板可帮助您开始为自己喜欢的 Python 工具构建 Visual Studio Code 扩展。它可以是 linter、formatter、代码分析器，或者所有这些功能的组合。该模板将为您提供将工具集成到 VS Code 所需的基本构建块，并且它已经可以访问上述 Python API。

Programming languages and frameworks

扩展模板包含两个部分：扩展部分和语言服务器部分。扩展部分用 TypeScript 编写，而语言服务器部分则基于 pygls (Python language server) 库用 Python 编写。

使用此模板时，您主要会处理代码的 Python 部分。您将使用 Language Server Protocol 将您的工具与扩展部分集成。pygls 目前支持 LSP 3.16 版本。

TypeScript 部分负责与 VS Code 及其 UI 进行交互。扩展模板内置了一些可以由您的工具使用的设置。如果您需要添加新设置来支持您的工具，您将需要编写一些 TypeScript 代码。扩展模板包含一些设置的示例，您也可以查看我们团队为一些流行工具开发的 扩展。

要求

1. VS Code 1.64.0 或更高版本
2. Python 3.7 或更高版本
3. node >= 14.19.0
4. npm >= 8.3.0 (npm 随 node 一起安装，请检查 npm 版本，使用 npm install -g npm@8.3.0 进行更新)
5. VS Code 的 Python 扩展

您应该知道如何创建和使用 Python 虚拟环境。

入门

要开始，请按照模板 README 中的说明进行操作。在那里，您将了解如何使用 模板创建您的存储库，以及如何安装必要的工具（例如，nox 任务运行器）和可选依赖项（测试支持）。

该 README 包含最新的说明，并详细介绍了如何自定义扩展的 package.json 占位符（<pythontool-module>、<pythontool-display-name> 等）。

模板功能

通过模板创建扩展后，它将包含以下扩展贡献。假设 <pytool-module> 已替换为 mytool，<pytool-display-name> 已替换为 My Tool。

1. 一个命令 My Tool: Restart Server (命令 ID: mytool.restart)。
2. 以下设置
   • mytool.logLevel
   • mytool.args
   • mytool.path
   • mytool.importStrategy
   • mytool.interpreter
   • mytool.showNotification
3. 以下触发扩展激活的条件
   • 当语言为 python 时。
   • 当在打开的工作区中找到带有 .py 扩展名的文件时。
   • 当命令 mytool.restart 被执行时。
4. 用于记录的输出频道 Output > My Tool。

集成您的工具

生成的 bundled/tool/server.py 文件是您将进行大部分更改的地方。文件中的 TODO 注释指向各种自定义点。还可以搜索模板中的其他位置（例如其他 Python 和 Markdown 文件）的 TODO 注释。您应该查看 LICENSE 文件，即使您想保留 MIT 许可证。

示例

已经创建了几个使用该模板的示例实现

• Pylint - 在文件 open、save 和 close 时实现 linting 和 Code Actions。
• Flake8 - 实现 linting 和 Code Actions。
• Black Formatter - 集成了 Black 格式化程序。
• autopep8 - 集成了 autopep8 格式化程序。
• isort - 添加了用于排序导入的 Code Actions。

您还可以查看 Language Server Protocol 规范，以更好地理解 pygls 语言服务器集成。

Extension development

模板 README 详细介绍了模板包含的 开发周期支持。模板提供了命令和配置，以便您可以构建、运行、调试和测试您的扩展。

如果在开发过程中遇到问题，有一个 Troubleshooting 部分可以帮助解决常见问题。

Packaging and publishing

在发布您的扩展之前，您需要更新扩展的 package.json 字段（例如 publisher 和 license）以适应您的特定扩展。您还应该更新辅助 Markdown 文件（CODE_OF_CONDUCT.md、CHANGELOG.md 等）。

当您的扩展准备好发布时，有一个 nox build-package 任务可以创建一个 .vsix 文件，然后您可以将其上传到您的扩展 管理页面。

如果您是 VS Code 扩展创建和发布的新手，我们建议您遵循 VS Code 主 扩展开发 主题中概述的最佳实践。在这里，您将找到有关如何让您的扩展在 Marketplace 上看起来很棒的指南，以及如何成为经过验证的发布者，以便用户可以放心地安装您的扩展。