开发工具构建工具【免费下载链接】hatchModern, extensible Python project management项目地址https://gitcode.com/gh_mirrors/ha/hatch点击查看免费下载HatchModern, extensible Python project management的插件系统基于 pluggy 为主线结合仓库中 hatchling 与 hatch 两侧的源码实现系统讲解插件的工作原理、项目配置规范、全部插件类型及其接口帮助读者快速掌握开发 Hatch 插件所需的完整知识。插件系统总览注册钩子与接口类Hatch 插件体系的核心约定非常简洁所有插件都通过注册钩子registration hooks返回一个或多个类这些类必须继承自特定类型type对应的接口。从源码可以看到Hatchling 侧的插件管理器在 backend/src/hatchling/plugin/manager.py 中实现其核心机制为每个插件类型对应一个以hatch_register_前缀命名的注册钩子例如hatch_register_builder、hatch_register_version_source这些钩子规格hookspec定义在 backend/src/hatchling/plugin/specs.py构建侧与 src/hatch/plugin/specs.pyHatch 侧中全部由pluggy.HookspecMarker(hatch)装饰每个注册钩子都可以返回单个类或类列表由ClassRegister.collect见 backend/src/hatchling/plugin/manager.py统一收集并强制校验类名唯一性——如果两个插件类声明了相同的PLUGIN_NAME会抛出ValueError。以创建一个新类型的环境为例注册钩子的写法如下沿用原文档示例from hatchling.plugin import hookimpl from .plugin import SpecialEnvironment hookimpl def hatch_register_environment(): return SpecialEnvironment其中hookimpl来自hatchling.plugin其定义见 backend/src/hatchling/plugin/init.py本质是pluggy.HookimplMarker(hatch)的实例import pluggy hookimpl pluggy.HookimplMarker(hatch)PLUGIN_NAME用户选择的唯一标识每个被注册的类必须定义名为PLUGIN_NAME的属性用户以及 Hatch 自身的配置解析正是通过这个名字来选择使用哪个插件。例如上文注册的SpecialEnvironment... class SpecialEnvironment(...): PLUGIN_NAME special ...在ClassRegister.collect的实现中backend/src/hatchling/plugin/manager.py插件类正是通过getattr(registered_class, PLUGIN_NAME, None)读取该属性作为注册名若缺失则直接报错。这也解释了为什么PLUGIN_NAME是强制而非可选的。内置插件的注册方式Hatch 内置插件与第三方插件走的是同一条注册路径。例如 Hatch 侧的管理器 src/hatch/plugin/manager.py 在initialize时先加载 Hatchling 的 hookspec再加载 src/hatch/plugin/specs.py 中定义的额外钩子environment、environment collector、version scheme、publisher、template、locker随后各hatch_register_*方法分别从对应模块如hatch.env.plugin.hooks、hatch.publish.plugin.hooks把内置实现注册进pluggy.PluginManager。这意味着内置插件与第三方插件在底层是完全对等的区别仅在于第三方插件需要额外经过 setuptools entry points 的发现过程。项目配置命名、发现与分类命名规范推荐插件项目的名称以hatch-为前缀。例如为名为foo的产品提供插件功能项目名应写作[project] name hatch-foo插件发现DiscoveryHatch 通过标准的 Python entry points 机制发现第三方插件。需要在pyproject.toml中把项目声明为 Hatch 的 Python 插件[project.entry-points.hatch] foo pkg.hooks这里有两个关键约定entry point 的名字应为插件项目名去掉hatch-前缀后的部分即上面的fooentry point 的值路径应指向包含注册钩子的模块即pkg.hooks。从源码看第三方插件的加载由 backend/src/hatchling/plugin/manager.py 中的ThirdPartyPlugins.load完成核心调用是self.manager.load_setuptools_entrypoints(hatch)即从安装环境中所有声明了hatchentry point group 的包中批量加载插件模块这也是为什么插件必须安装在与 Hatch或 Hatchling可发现的环境里才能被使用。分类器Classifier为了让 Hatch 插件在 PyPI 上更容易被搜索到建议在项目的classifiers见 docs/config/metadata.md中加入Framework :: Hatch[project] classifiers [ ... Framework :: Hatch, ... ]插件类型全景Hatchling 与 Hatch 两大阵营Hatch 的插件被明确划分为两大阵营二者的部署要求完全不同。Hatchling构建期插件Hatchling 侧插件全部参与项目的构建过程因此它们声明的任何依赖都会被自动安装到每个构建环境中。原文档列出了五种类型插件类型参考文档职责Builder构建器决定产出何种制品wheel、sdist、二进制等Build hook构建钩子在构建流程中挂接自定义逻辑Metadata hook元数据钩子动态生成或修改项目元数据Version source版本源从文件、环境变量、正则等来源读取版本Version scheme版本方案定义版本号递增规则以 Builder 为例其接口成员PLUGIN_NAME、app、root、build_config、target_config、config、get_version_api、clean等在 docs/plugins/builder/reference.md 中逐一列出对应的注册钩子为hatch_register_builder定义见 backend/src/hatchling/plugin/specs.py内置实现注册于hatchling.builders.plugin.hooks见 backend/src/hatchling/plugin/manager.py。这一阵营的边界约束是构建环境是隔离的所以这些插件依赖的第三方库必须通过 tool.hatch.build.hooks 的依赖声明 等方式声明才会随构建环境自动安装。Hatch运行时插件Hatch 侧插件必须安装在与 Hatch 本身相同的环境中才能生效。原文档列出了四种类型插件类型参考文档职责Environment环境定义项目的虚拟环境类型如 virtualenv、condaEnvironment collector环境收集器从外部来源收集环境定义Dependency locker依赖锁器生成并管理依赖锁文件Publisher发布器将构建产物发布到制品仓库这些类型的注册钩子hatch_register_environment、hatch_register_environment_collector、hatch_register_publisher、hatch_register_locker以及不在原文档列表中的hatch_register_template全部定义在 src/hatch/plugin/specs.py 中Hatch 侧的内置注册逻辑见 src/hatch/plugin/manager.py。环境插件的安装要求以环境插件为例任何非内置的环境类型都必须满足二选一手动安装在 Hatch 所在环境中或在项目配置中通过tool.hatch.env.requires数组声明交由 Hatch 自动管理[tool.hatch.env] requires [ ..., ]这一配置在 docs/plugins/environment/reference.md 中有明确说明。已知的第三方环境插件包括基于 Conda/Mamba 的 hatch-conda、在容器内运行环境的 hatch-containers、基于 pip-compile 管理锁文件的 hatch-pip-compile 等。环境插件的生命周期与接口每当一个环境被使用时Hatch 会执行完整的准备逻辑对应Project.prepare_environment见 docs/plugins/environment/reference.md。此外所有环境类型都应支持本地文件系统与环境之间的同步存储fs_context能力该功能用于hatch build命令以及当项目依赖被动态设置时读取依赖的命令如hatch dep hash。值得一提的设计是依赖锁器与环境的解耦锁器通过hatch_register_locker注册详见 docs/plugins/locker.md不需要为了修改锁定行为而去子类化EnvironmentInterface而是调用环境的公共 API如command_context与fs_context来在项目工作区与环境之间搬运制品。这一架构让锁定能力可以独立演进也符合原文档强调的decoupled设计原则。插件类型的完整接口清单两类插件阵营的接口成员methods细节可分别查阅Hatchling 构建侧各参考文档中通过::: hatchling.builders.plugin.interface.BuilderInterface等指令渲染出的完整成员清单例如 docs/plugins/builder/reference.mdHatch 运行时侧EnvironmentInterface的完整方法列表find、create、remove、install_project、sync_dependencies、activate、run_shell_command、apply_features、check_compatibility等几十个方法见 docs/plugins/environment/reference.md对应接口的 Python 实现位于仓库源码中Hatchling 侧backend/src/hatchling/builders/plugin/interface.py、backend/src/hatchling/metadata/plugin/interface.py、backend/src/hatchling/version/source/plugin/interface.py、backend/src/hatchling/version/scheme/plugin/interface.py、backend/src/hatchling/builders/hooks/plugin/interface.pyHatch 侧src/hatch/env/plugin/interface.py、src/hatch/publish/plugin/interface.py 等对应目录结构见 src/hatch。插件开发速查从零注册一个插件综合以上规则开发一个 Hatch 插件的完整步骤可归纳为创建项目以hatch-前缀命名例如hatch-foo声明 entry point在pyproject.toml的[project.entry-points.hatch]下以项目名去前缀为键、以包含注册钩子的模块路径为值编写注册钩子在钩子模块中用hookimpl装饰hatch_register_*函数返回单个类或类列表实现接口类让返回的类继承对应类型的接口如EnvironmentInterface、BuilderInterface并强制定义PLUGIN_NAME属性添加分类器在classifiers中加入Framework :: Hatch便于检索按阵营安装构建期插件声明其构建依赖并随构建环境安装运行时插件则须装入 Hatch 所在环境或通过tool.hatch.env.requires自动管理。结语Hatch 插件系统的设计可以用约定精简、机制统一来概括一切扩展都收敛为注册钩子返回接口实现类这一个模式PLUGIN_NAME是唯一的用户可见标识pluggy 负责钩子的收集与调度entry points 负责第三方插件的发现。理解 backend/src/hatchling/plugin/manager.py 中的ClassRegister.collect与ThirdPartyPlugins.load两段核心代码即可把握整个插件体系的运行机理。在此基础上对照本文列出的各类插件参考文档与源码接口即可快速开发出符合 Hatch 生态规范的自定义插件。赞分享开发工具构建工具【免费下载链接】hatchModern, extensible Python project management项目地址https://gitcode.com/gh_mirrors/ha/hatch点击查看免费下载相关推荐Xberg 插件架构与注册机制实战指南八类插件 Trait、类型化注册表与 Alef 桥接Xberg 插件架构与注册机制实战指南八类插件 Trait、类型化注册表与 Alef 桥接 Xberg 是一个以 Rust 为核心的多语言文档智能引擎其插件后端AI 应用NLPKarma 插件开发完全指南依赖注入机制与五种插件类型实战Karma 插件开发完全指南依赖注入机制与五种插件类型实战 本指南以 Karma 官方《Developing Plugins》文档为核心系统讲解 Karma测试开发工具Hydra 插件开发实战指南深入理解插件注册机制与基于示例的完整开发流程Hydra 插件开发实战指南深入理解插件注册机制与基于示例的完整开发流程 本指南以 Hydra 官方文档 develop.md https://link.g开发工具后端CLI上一篇VRCX虚拟社交中枢系统3大核心技术架构解析与高性能部署指南下一篇Starlark 项目使用教程创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考