unittest_generator 2023.12.18

新的介绍内容：

unittest_generator模板为您提供了构建VS Code Python工具扩展的起点，无论您是开发林特、格式化工具还是代码分析工具，本模板都为您提供了必要的构建模块，帮助您快速上手。

编程语言和框架：

该扩展模板分为两部分：扩展部分和语言服务器部分。扩展部分使用TypeScript编写，而语言服务器部分则使用Python和pygls（Python语言服务器）库开发。主要的开发工作将集中在Python部分，通过语言服务器协议（LSP）将您的工具与扩展部分整合。pygls支持LSP的3.16版本。

TypeScript部分负责与VS Code及其UI的交互，模板预设了一些设置，供您的工具使用。如果需要添加新设置以支持您的工具，您将需要进行一些TypeScript开发。模板中包含了几个设置示例，您可以参考这些示例。此外，您还可以查看我们团队开发的其他流行工具扩展作为参考。

要求：

1. VS Code 1.64.0或更高版本
2. Python 3.7或更高版本
3. Node.js >= 14.19.0
4. npm >= 8.3.0（npm与Node.js一起安装，检查npm版本，使用npm install -g npm@8.3.0更新）
5. VS Code的Python扩展

您需要了解如何创建和使用Python虚拟环境。

开始使用：

1. 使用此模板创建您的仓库。
2. 在您的开发机器上本地检出您的仓库。
3. 为此项目在终端中创建并激活Python虚拟环境。确保使用适合您的工具的最低Python版本。本模板支持Python 3.7及更高版本。
4. 在激活的环境中安装nox：python -m pip install nox。
5. 将您喜欢的工具添加到requirements.in。
6. 运行nox --session setup。
7. 可选 安装测试依赖项：python -m pip install -r src/test/python_tests/requirements.txt。您需要安装这些依赖项才能从测试浏览器中运行测试。
8. 打开package.json，查找并更新以下内容：
   1. 查找并替换<pytool-module>为您的工具的模块名称。这将用于内部创建设置命名空间、注册命令等。建议使用小写名称，不包含空格，允许使用-。例如，将<pytool-module>替换为pylint将导致设置看起来像pylint.args。另一个例子，将<pytool-module>替换为black-formatter将使设置看起来像black-formatter.args。
   2. 查找并替换<pytool-display-name>为您的工具的显示名称。这将用作市场中扩展的标题、扩展视图、输出日志等。例如，对于black扩展，这将是Black Formatter。
9. 使用npm install安装Node.js包。
10. 前往https://marketplace.visualstudio.com/vscode并创建发布者账户（如果您还没有）。
    1. 在package.json中使用已发布的名称，将<my-publisher>替换为您在市场中注册的名称。

本模板的功能：

完成入门部分后，本模板将添加以下功能。假设<pytool-module>已替换为mytool，<pytool-display-name>已替换为My Tool：

1. 命令My Tool: Restart Server（命令ID：mytool.restart）。
2. 以下设置：
   • mytool.args
   • mytool.path
   • mytool.importStrategy
   • mytool.interpreter
   • mytool.showNotification
3. 以下触发器用于扩展激活：
   • 在Python语言上。
   • 在打开的工作区中发现.py扩展名的文件。
4. 注册以下命令：
   • mytool.restart：重启语言服务器。
5. 用于记录输出的输出通道Output > My Tool。

添加您的工具功能：

打开bundled/tool/lsp_server.py，这里是您将进行大部分更改的地方。查找其中的TODO注释以获取更多详情。

此外，还要查找模板中其他位置的TODO：

• bundled/tool/lsp_runner.py：在某些特殊情况下，您可能需要更新此文件。
• src/test/python_tests/test_server.py：这是您编写测试的地方。提供了两个不完整的示例供您参考。
• 模板中的所有markdown文件都有一些TODO项，请务必检查这些文件。这包括更新LICENSE文件，即使您想保留MIT许可证。

参考我们团队使用该模板创建的其他扩展：

• 协议参考：https://microsoft.github.io/language-server-protocol/specifications/specification-3-16/
• 显示如何处理文件打开、保存和关闭时的Linting。Pylint
• 显示如何处理格式化。Black Formatter
• 显示如何处理代码操作。isort

构建和运行扩展：

从VS Code中运行调试扩展和Python配置。这将在主机窗口中构建并调试扩展。

注意：如果您只想构建，可以在VS Code中运行构建任务（ctrl shift B）。

调试：

要调试TypeScript和Python代码，请使用调试扩展和Python调试配置。这是推荐的方式。此外，停止时，请确保停止TypeScript和Python调试会话。否则，可能会无法重新连接到Python会话。

要仅调试TypeScript代码，请使用调试扩展调试配置。

要调试已运行的服务器或生产服务器，请使用Python附加，并选择运行lsp_server.py的进程。

日志记录和日志：

模板创建了一个日志输出通道，可以在Output > mytool面板中找到。您可以通过从命令面板运行开发人员：设置日志级别...命令，并从列表中选择您的扩展来控制日志级别。您的工具的显示名称将用于列出它。您还可以设置全局日志级别，这将应用于所有扩展和编辑器。

如果您需要涉及语言客户端和语言服务器之间消息的日志，您可以设置"mytool.server.trace": "verbose"，以获取消息日志。这些日志也可在Output > mytool面板中找到。

添加新设置或命令：

您可以通过在package.json文件中添加设置详细信息来添加新设置。为了将此配置传递给您的Python工具服务器（即lsp_server.py），请根据需要更新settings.ts。该文件中包含了不同类型的设置示例，您可以基于这些示例创建新的设置。

您可以参考package.json和extension.ts中如何实现重启命令来添加命令。您还可以通过语言服务器协议从Python中贡献命令。

测试：

参见src\test\python_tests\test_server.py作为起点。参考这里列出的其他项目，了解如何测试通过LSP运行工具的各个方面。

如果您已安装测试要求，您应该能够在测试浏览器中看到测试。

您还可以使用nox --session tests命令运行所有测试。

林特：

运行nox --session lint以对Python和TypeScript代码进行林特。请更新nox文件，如果您想使用不同的林特和格式化工具。

打包和发布：

1. 更新package.json中的各个字段。至少检查并相应更新以下字段。查看扩展清单参考以添加更多字段：
   • "publisher": 更新为您在https://marketplace.visualstudio.com/的发布者ID。
   • "version": 查看https://semver.org/了解此字段的要求和限制。
   • "license": 根据您的项目更新许可证。默认为MIT。
   • "keywords": 更新您的项目的关键字，这些将在VS Code市场中搜索时使用。
   • "categories": 更新您的项目的类别，以便在VS Code市场中更容易过滤。
   • "homepage", "repository", 和 "bugs" : 更新这些字段的URL以指向您的项目。
   • 可选 添加"icon"字段，并使用图像文件的相对路径作为此项目的图标。
2. 务必检查以下markdown文件：
   • 必需 首次：CODE_OF_CONDUCT.md, LICENSE, SUPPORT.md, SECURITY.md
   • 每次发布：CHANGELOG.md
3. 使用nox --session build_package构建包。
4. 将生成的.vsix文件上传到您的扩展管理页面https://marketplace.visualstudio.com/manage。

要从命令行执行此操作，请查看此处https://code.visualstudio.com/api/working-with-extensions/publishing-extension。

升级依赖项：

提供了Dependabot yml文件，以便于设置升级此扩展的依赖项。请确保将dependabot中使用的标签添加到您的仓库。

要手动升级您的本地项目：

1. 创建一个新分支
2. 运行npm update以更新Node.js模块。
3. 运行nox --session setup以升级Python包。

故障排除：

更改lsp_server.py的路径或名称

如果您想将lsp_server.py的名称更改为其他名称，您可以这样做。请务必更新constants.ts和src\test\python_tests\lsp_test_client\session.py。

此外，请确保lsp_server.py中插入的路径指向正确的文件夹以拾取依赖包。

模块未找到错误

如果bundled/libs为空，可能会发生此错误。这是我们放置您的工具和其他依赖项的文件夹。请务必遵循创建和打包所需libs的构建步骤。

常见的一个是pygls模块未找到。

TODO：仓库维护者尚未编辑此文件

仓库所有者请确保您更新此文件。作为仓库所有者，您需要使用特定于您的扩展的指令更新此文件。