基于pyright的开发者指南：如何贡献代码和理解项目内部架构

基于pyright的开发者指南如何贡献代码和理解项目内部架构【免费下载链接】basedpyrightpyright fork with various type checking improvements, improved vscode support and pylance features built into the language server项目地址: https://gitcode.com/gh_mirrors/ba/basedpyrightbasedpyright是pyright的一个分支它在类型检查方面进行了各种改进提供了更好的VSCode支持并将Pylance功能内置到语言服务器中。对于想要参与这个开源项目的开发者来说了解如何贡献代码以及项目的内部架构是非常重要的。准备开发环境要开始为basedpyright贡献代码首先需要准备好开发环境。虽然pyright是用TypeScript编写的但basedpyright为不熟悉TypeScript/Node.js的Python开发者改进了开发体验。你不需要自己安装Node.jsNode安装由pypi包管理并安装到项目的虚拟环境中。你只需要安装Python任何3.9的版本都可以。推荐使用VSCode因为仓库中有项目配置文件可以正确设置所有内容如linters、formatters、调试配置等。安装依赖按F1Tasks: Run taskinstall dependencies或者运行以下命令./pw uv sync这将安装项目所需的所有依赖pyprojectx、uv、node、typescript等。所有依赖都安装在本地的./.venv和./node_modules目录中。当VSCode提示使用新创建的虚拟环境时按Yes。现在你可以在venv中运行任何node/npm命令了。项目内部架构了解项目的内部架构对于有效贡献代码至关重要。basedpyright的代码结构如下packages/vscode-pyright/src/extension.tsVS Code扩展的语言服务器协议LSP客户端入口点。packages/pyright-internal/typeshed-fallback/Python标准库的最新Type Shed类型存根文件副本。packages/pyright-internal/src/pyright.ts命令行工具的主要入口点。packages/pyright-internal/src/server.tsLSP服务器的主要入口点。packages/pyright-internal/src/analyzer对Python解析树执行分析的模块。packages/pyright-internal/src/common解析器和分析器通用的模块。packages/pyright-internal/src/parser执行Python源代码的标记化和解析的模块。packages/pyright-internal/src/tests解析器和分析器的测试。packages/pyrightbasedpyright npm包供pypi包内部使用。packages/browser-pyright可以在浏览器中运行的basedpyright构建供playground内部使用。basedpyrightnpm包的pypi包包装器因此用户不需要自己安装nodejs。docstubs带有已编译模块文档字符串的存根在构建pypi包时从packages/pyright-internal/typeshed-fallback/生成。核心概念Pyright实现了一个service这是一个持久的内存对象控制分析顺序并为语言服务器提供接口。对于多根工作区每个工作区都有自己的服务实例。服务拥有program的实例它跟踪配置文件和构成要分析的源代码库的所有源文件。如果源文件a)被配置文件引用b)当前在编辑器中打开或c)被另一个源文件直接或间接导入则可以将其添加到程序中。程序对象负责设置文件系统观察器并在添加、删除或编辑文件时更新程序。程序还负责为所有文件的所有分析阶段确定优先级优先处理在编辑器中打开的文件及其导入依赖项。程序跟踪多个sourceFile对象。每个源文件代表磁盘上一个Python源文件的内容。它跟踪文件的分析状态包括分析的任何中间或最终结果以及产生的诊断信息错误和警告。程序使用importResolver来解析每个源文件中引用的导入模块。分析阶段Pyright为每个源文件执行以下分析阶段tokenizer负责将文件的字符串内容转换为令牌流。空格、注释和一些行结束字符被忽略因为解析器不需要它们。parser负责将令牌流转换为解析树。通用的parseTreeWalker提供了一种方便的遍历解析树的方法。所有后续分析阶段都利用parseTreeWalker。binder负责构建作用域并填充每个作用域的符号表。它不执行任何类型检查但会检测并报告一些会导致意外运行时异常的语义错误。它还检测并报告不一致的名称绑定例如在同一作用域中同时使用全局和非局部绑定的变量。binder还为每个作用域构建“反向代码流图”允许类型分析器根据符号的前因确定代码流中任何点的符号类型。checker负责检查源文件中的所有语句和表达式。它严重依赖typeEvaluator模块该模块执行大部分繁重的工作。检查器不会在所有文件上运行只在需要完整诊断输出的文件上运行。例如如果源文件不是程序的一部分但被程序导入则不需要在其上运行检查器。调试项目调试是开发过程中不可或缺的一部分basedpyright提供了多种调试方式。CLI调试要调试pyright在VS Code中打开根源代码目录。打开调试子面板从调试目标菜单中选择“Pyright CLI”。点击绿色的“运行”图标或按F5以在VS Code调试器中构建并启动命令行版本。还有一个类似的选项可以提供稍微更快的构建/调试循环确保你已经构建了pyright-internal项目例如通过终端运行构建任务tsc: watch然后选择“Pyright CLI (pyright-internal)”。VSCode扩展调试要调试VS Code扩展从调试目标菜单中选择“Pyright extension”。点击绿色的“运行”图标或按F5以构建并启动第二个VS Code副本与扩展。在第二个VS Code实例中打开一个Python源文件以便加载pyright扩展。返回VS Code的第一个实例从调试目标菜单中选择“Pyright extension attach server”然后点击绿色的“运行”图标。这将把调试器附加到托管类型检查器的进程。现在你可以设置断点等。要在监视模式下调试VS Code扩展你可以执行上述操作但选择“Pyright extension (watch mode)”。当保存pyright的源时将进行增量构建你可以重新加载第二个VS Code窗口或重新启动它以开始使用更新的代码。请注意调试停止时观察程序保持打开状态因此如果你想执行打包步骤而输出不会被覆盖可能需要停止它或关闭VS Code。检查LSP消息当VSCode扩展在这种模式下运行时你可以运行npm: lsp-inspect任务来启动LSP inspector它允许你浏览在客户端和服务器之间发送的所有消息。注意这在Windows上不起作用参见this issue。作为解决方法你可以使用客户端。语言服务器调试你可能希望在没有VSCode扩展的情况下调试语言服务器当调查似乎只在其他编辑器中发生的问题时这很有用。你可以通过运行npm: lsp-client任务或“LSP client”启动配置使用LSP-inspector的客户端来做到这一点。对于Windows用户如果从VSCode的任务运行器运行npm脚本将不起作用。改用启动配置。贡献代码GitHub Issues与上游pyright仓库不同我们非常开放地接受改进想法和错误报告。如果你在上游pyright仓库上提出的问题被关闭而没有解决方案请随时在这里再次提出。请使用反应为你认为重要的问题投票。我们不会关闭没有获得足够票数的问题或类似的问题。这只是为了帮助我们优先处理哪些问题首先解决。提交代码在提交代码之前确保你的代码符合项目的编码规范。可以通过运行项目的lint工具来检查代码风格问题。./pw run lint然后运行测试以确保你的更改没有破坏现有功能。./pw run test如果所有测试都通过你就可以提交你的代码并创建一个拉取请求了。创建类型存根在开发过程中你可能会遇到需要为某个模块创建类型存根的情况。basedpyright提供了方便的功能来创建类型存根。当你看到类似“No type stub found for this module”的错误时可以使用“Create Type Stub For”功能来生成类型存根。配置开发环境PyCharm配置如果你使用PyCharm作为开发工具可以按照以下步骤配置basedpyright打开设置导航到Tools Pyright Project。在“Language server executable”字段中输入“basedpyright-langserv”并勾选“Override”。确保“Resolve against interpreter directory, ignoring extension”也被勾选并“Override”。同时建议安装一些推荐的插件打开设置导航到Appearance Behavior Required Plugins。添加以下插件com.koxudaxi.ruff、LSP4IJ、Prettier。总结通过本文你应该已经了解了如何为basedpyright贡献代码以及项目的内部架构。从准备开发环境到调试项目再到提交代码每个步骤都至关重要。希望这篇指南能帮助你顺利参与到basedpyright的开发中为这个优秀的开源项目贡献自己的力量【免费下载链接】basedpyrightpyright fork with various type checking improvements, improved vscode support and pylance features built into the language server项目地址: https://gitcode.com/gh_mirrors/ba/basedpyright创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考