开发工具构建工具【免费下载链接】hatchModern, extensible Python project management项目地址https://gitcode.com/gh_mirrors/ha/hatch点击查看免费下载导读Hatch 的环境Environment是其开箱即用体验的核心它为测试、文档构建、代码格式化、静态检查等各类项目任务提供彼此隔离的工作区并在创建时自动以开发模式dev mode安装项目本身。本文以官方文档 docs/environment.md 为骨架结合仓库内 CLI 源码与配置文档完整讲解环境从创建、进入、执行命令、依赖同步、锁定PEP 751、选择、矩阵到移除的完整生命周期并给出可复制运行的配置与命令示例。读完本文你将掌握 Hatch 环境管理的全部日常操作并理解其底层实现逻辑。环境是什么环境 被设计为可供项目使用的隔离工作区无论是跑测试、构建文档还是执行其他任意任务都可以在独立的环境中完成互不干扰。所有环境都定义在pyproject.toml的tool.hatch.envs表下的各个 section 中[tool.hatch.envs.ENV_NAME]除非在命令行中 显式选择 某个环境否则 Hatch 一律使用default环境。default环境的类型type默认为virtual即使用 Python 虚拟环境来管理这也是内置的唯一环境类型详见 虚拟环境插件文档。环境的存储位置本身也是完全可配置的相关说明见 配置文档的环境小节。提示环境目录名若以hatch-开头则被 Hatch 保留用于特殊用途例如内部测试见 内部测试文档。另外如需一份更完整的逐步演练可参考 基础用法教程。创建环境使用env create命令即可创建环境。假设你已经完成了 setup 阶段的新项目创建进入项目目录后执行$ hatch env create Creating environment: default Installing project in development mode Syncing dependencies从源码看create命令 的实际流程是先通过app.project.expand_environments(env_name)展开目标环境若目标是矩阵则展开为矩阵产物环境再逐个执行environment.check_compatibility()做平台/解释器兼容性检查最后调用app.project.prepare_environment(environment, ...)完成环境的创建、项目安装与依赖同步。若环境已存在会显示Environment ... already exists的警告并跳过若矩阵中的部分环境不兼容则会列出Skipped N incompatible environments警告而不是中断整个命令。你完全不需要手动创建环境——在环境中 [启动 shell](#进入环境) 或 [执行命令](#命令执行) 都会自动触发创建。进入环境使用shell命令可以在环境中启动一个 shell$ hatch shell (hatch-demo) $进入后确认项目已被安装(hatch-demo) $ pip show hatch-demo Name: hatch-demo Version: 0.0.1 ...再查看当前环境的 Python 解释器 位于何处(hatch-demo) $ python -c import sys;print(sys.executable) ...输入exit即可退出环境。如果你只想进入某个特定环境而非默认的default可以使用-e选项指定环境名hatch -e test shell进入之后你可以像在任何 Python 环境中一样执行命令。例如在test环境中执行pip list可以看到项目以 editable 模式安装、且环境中同时包含pytest与pytest-cov这两个在配置中声明的依赖。查看环境位置若想知道某个环境在磁盘上的具体位置可以使用env find命令$ hatch env find test /your/path/Application Support/hatch/env/virtual/yourproject/twO2iQR3/test该路径随平台不同而不同且 可以被配置。命令执行run命令允许你在环境中执行命令效果等同于先进入环境再执行hatch run python -c import sys;print(sys.executable)上面这条命令输出的路径与进入环境后执行的结果完全一致。这种免激活的用法是 Hatch 环境的一大特色——与需要手动activate的 venv/conda 不同hatch run ENV_NAME:command可以精准地把某条命令投放到指定环境中执行例如$ hatch run test:pytest test session starts platform darwin -- Python 3.12.1, pytest-7.4.4, pluggy-1.3.0 rootdir: /your/path/to/yourproject collected 0 items其中test:pytest的前半部分是环境名test后半部分是命令pytest。在run命令源码 中可以看到更丰富的选项-e/--env指定目标环境、-i/--include与-x/--exclude用于包含/排除矩阵变量、-f/--filter以 JSON 数据筛选环境、--force-continue让所有命令都执行完再以首个错误码退出、--ignore-compat跳过兼容性检查。例如对矩阵test执行hatch env run -i py3.10 -x version9000 test:pytest就只会把pytest投放到test.py3.10-42与test.py3.10-3.14这两个环境。提示务必了解如何为项目定义 scripts 脚本让常用命令以命名脚本的形式被hatch run直接调用。依赖管理Hatch 保证环境始终与当前定义的 项目依赖前提是 已安装 且处于 开发模式以及 环境依赖 保持同步。例如要把cowsay加入依赖打开pyproject.toml将其添加到dependencies数组[project] ... dependencies [ cowsay ]该依赖会在你下一次 启动 shell 或 执行命令 时被自动安装$ hatch run cowsay -t Hello, world! Syncing dependencies _____________ | Hello, world! | \ \ ^__^ (oo)\_______ (__)\ )\/\ ||----w | || ||当 Hatch 检测到你修改了依赖定义并需要更新环境时Syncing dependencies 状态会短暂显示。环境专属依赖除了项目元数据中的依赖你还可以为每个环境声明额外依赖支持 上下文格式化[tool.hatch.envs.test] dependencies [ coverage[toml], pytest, pytest-cov, pytest-mock, ]如果某个环境的依赖与继承环境见下文继承只有细微差别可以使用extra-dependencies避免重复声明dependencies[tool.hatch.envs.default] dependencies [ foo, bar, ] [tool.hatch.envs.experimental] extra-dependencies [ baz, ]Hatch 使用 pip 安装依赖因此 pip 支持的一切配置如私有源Hatch 同样支持——例如可以通过设置PIP_INDEX_URL环境变量强制只使用私有仓库。若希望把依赖重定向到本地路径、Git 仓库、URL、备用索引或 workspace 成员而不影响发布元数据可参考 sources 文档所有 sources 可通过HATCH_NO_SOURCES环境变量一次性禁用。继承、开发模式与跳过安装继承所有环境都从template选项指定的环境继承配置template默认为default。例如下面的bar会是baz类型且skip-install false[tool.hatch.envs.foo] type baz skip-install true [tool.hatch.envs.bar] template foo skip-install false注意环境不继承矩阵。若将template设为环境自身名称如[tool.hatch.envs.foo] template foo可禁用继承而detached true则同时使环境自引用并跳过项目安装特别适合 lint 这类既不需要继承、也不需要安装项目的独立环境。开发模式默认情况下环境始终反映项目在磁盘上的当前状态即以 editable 模式安装。设置dev-mode false后项目只在环境新建时安装一次之后需手动管理项目安装。跳过安装默认环境创建时会安装你的项目设置skip-install true可跳过此步骤[tool.hatch.envs.lint] skip-install true锁定LockingHatch 可以为环境生成符合 PEP 751 规范的锁文件pylock.toml锁定所有解析出的依赖精确版本保证安装的可复现性。使用方式在环境配置中开启locked true然后执行env lock命令对于当前活动环境也可以使用dep lock或lock$ hatch env lock Locking environment: default Wrote lockfile: /path/to/project/pylock.toml不传参数调用时所有配置了locked true的环境都会被锁定。环境在创建时或依赖发生变化时也会自动锁定。从env/lock.py源码 可以看到更多细节锁文件命名遵循 PEP 751 约定default环境为pylock.toml其他环境为pylock.ENV_NAME.toml可用lock-filename覆盖--upgrade/-U升级全部包、--upgrade-package/-P升级指定包、--export path导出锁文件到自定义路径、--export-all dir把所有环境的锁文件导出到目录、--check检查锁文件是否最新锁文件内容由 locker 插件 生成默认跟随环境安装器用 UV 则为uv否则为pip内置piplocker 目前不实现apply_lock因此用dep sync应用锁文件需要uvlocker全局可通过顶层[tool.hatch] lock-envs true一次性为所有环境开启锁定个别环境仍可用locked false退出。更完整的实战用法见 锁文件 how-to 指南。环境选择Selection你可以通过-e/--env这个 root 选项 来选择要进入或运行命令的环境也可以设置HATCH_ENV环境变量。在仓库的 constants.py 中可以看到这一族环境变量HATCH_ENV用于选择默认环境HATCH_ENV_ACTIVE永远被设置为当前活动环境名HATCH_ENV_TYPE_PLUGIN_NAME_option前缀则用于向环境类型插件传递配置。此外run命令支持更显式的选择方式——在命令前加ENV_NAME:前缀。例如有如下配置[tool.hatch.envs.docs] dependencies [ mkdocs ] [tool.hatch.envs.docs.scripts] build mkdocs build --clean --strict serve mkdocs serve --dev-addr localhost:8000就可以直接运行hatch run docs:serve提示如果你已经 进入了 某个环境命令默认就会在该环境中执行。用env show查看环境env show命令可以列出所有已定义环境及其依赖。其源码show.py支持--ascii纯 ASCII 表格、--json输出 JSON 以便程序化消费、--internal显示内部环境等选项表格列包括 Name、Type、Features、Dependencies、Environment variables、Scripts、Description 等环境配置中的description选项就是纯信息性的用于显示在该命令输出中。$ hatch env show Standalone ┏━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━┓ ┃ Name ┃ Type ┃ Dependencies ┃ ┡━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━┩ │ default │ virtual │ │ ├─────────┼─────────┼──────────────┤ │ test │ virtual │ pytest │ │ │ │ pytest-cov │ └─────────┴─────────┴──────────────┘输出列数取决于你的环境配置可能更多。矩阵Matrix每个环境都可以定义自己的 矩阵[tool.hatch.envs.test] dependencies [ pytest ] [[tool.hatch.envs.test.matrix]] python [3.10, 3.11] version [42, 3.14] [[tool.hatch.envs.test.matrix]] python [3.11, 3.12] version [9000] feature [foo, bar]矩阵会把每组变量取值组合的笛卡尔积展开为独立环境。用env show命令即可看到展开结果$ hatch env show --ascii Standalone ------------------ | Name | Type | | default | virtual | ------------------ Matrices --------------------------------------------------- | Name | Type | Envs | Dependencies | | test | virtual | test.py3.10-42 | pytest | | | | test.py3.10-3.14 | | | | | test.py3.11-42 | | | | | test.py3.11-3.14 | | | | | test.py3.11-9000-foo | | | | | test.py3.11-9000-bar | | | | | test.py3.12-9000-foo | | | | | test.py3.12-9000-bar | | ---------------------------------------------------矩阵环境的命名规则详见 advanced.md 的 Naming 小节由各变量取值以连字符连接并整体加上ENV_NAME.前缀。若含py/python变量它会在乘积结果中排第一位且值若不是py开头会被补上py前缀如test.py3.9-42、test.pypy3-42该变量的值同时决定了环境的 Python 版本。还可以用matrix-name-format选项自定义每个变量段的格式其中可识别{variable}与{value}占位符。在run命令源码 中矩阵环境下会用select_environments(...)结合-i/--include交集与-x/--exclude并集筛选出目标环境子集--filter/-f则可用 JSON 映射按配置键值精确挑选环境如{python: 3.10}。移除环境使用env remove命令可以移除单个环境或某个环境矩阵使用env prune命令可以移除项目的全部环境。从 remove.py 源码 看env remove默认移除default环境会先展开目标矩阵会展开为矩阵产物并且拒绝移除当前活动环境会报Cannot remove active environment: ENV_NAME只有当目标环境真实存在时才执行environment.remove()。底层实现一览围绕本文涉及的几项核心能力可以在仓库中按图索骥阅读对应实现功能命令入口源码配置文档环境创建src/hatch/cli/env/create.pydocs/config/environment/overview.md运行命令src/hatch/cli/env/run.pydocs/config/environment/overview.md#commands环境展示src/hatch/cli/env/show.pydocs/tutorials/environment/basic-usage.md环境锁定src/hatch/cli/env/lock.pydocs/config/environment/overview.md#locking环境移除src/hatch/cli/env/remove.pydocs/cli/reference.md环境相关环境变量src/hatch/config/constants.pydocs/config/environment/overview.md#environment-variables此外环境配置中的高级特性上下文格式化、矩阵命名、依赖组、pre-install-commands/post-install-commands等详见 高级环境配置 与 环境配置总览环境类型插件的扩展机制见 环境插件参考 与 virtual 插件。总结Hatch 的环境系统把项目级依赖隔离免激活命令执行多版本矩阵测试和可复现锁定整合进了同一条工作流default环境开箱即用hatch run/hatch shell自动按需创建环境tool.hatch.envs下的配置可精确控制依赖、Python 版本、脚本与锁定行为矩阵则把复杂组合测试收敛为一条命令。掌握了本文的创建、进入、执行、依赖同步、锁定、选择、矩阵与移除八类操作即可在日常开发中充分释放 Hatch 环境管理的效率。赞分享开发工具构建工具【免费下载链接】hatchModern, extensible Python project management项目地址https://gitcode.com/gh_mirrors/ha/hatch点击查看免费下载相关推荐teable 表领域事件Domain Events架构深度解析跨边界发布与审计的事件设计teable 表领域事件Domain Events架构深度解析跨边界发布与审计的事件设计 导读 本文围绕 teable 开源仓库中 packages/v2开发工具构建工具Hatch 高级环境配置实战指南矩阵、依赖组与条件化 Option OverridesHatch 高级环境配置实战指南矩阵、依赖组与条件化 Option Overrides 本篇技术指南围绕 HatchModern, extensible P开发工具构建工具Hatch 环境锁定文件pylock.toml完全指南配置、生成、同步与升级Hatch 环境锁定文件pylock.toml完全指南配置、生成、同步与升级 本篇技术指南聚焦 Hatch 的锁文件lockfile能力Hatch开发工具构建工具上一篇AutoGluon终极安装指南从零开始快速部署多模态AI平台下一篇7步构建全球化网站多语言支持完整实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考