拓冰网站定制 ![Hatch 项目模板配置完全指南：用 `hatch new` 与 `[template]` 配置文件定制新项目骨架](http://pic.xiahunao.cn/yaotu/Hatch 项目模板配置完全指南：用 `hatch new` 与 `[template]` 配置文件定制新项目骨架)
开发工具构建工具【免费下载链接】hatchModern, extensible Python project management项目地址https://gitcode.com/gh_mirrors/ha/hatch点击查看免费下载Hatch 的hatch new命令可以一键创建结构完整的 Python 项目而项目的默认形态作者信息、许可证、测试环境、CI 工作流、目录布局、CLI 脚手架全部由 Hatch 配置文件中的[template]表控制。本文以 docs/config/project-templates.md 为骨架结合 src/hatch/cli/new/init.py 与 src/hatch/config/model.py 等源码系统讲解每个配置项的含义、默认值、底层行为读完即可按团队规范定制统一的项目初始化模板。配置文件的位置与作用域hatch new的行为受 Hatch 配置文件 控制。配置查找遵循 Hatch 的全局配置机制默认写入用户级配置文件例如 Linux/macOS 下的~/.config/hatch/config.tomlWindows 下位于用户配置目录也可以使用HATCH_CONFIG环境变量指定自定义路径。与项目模板相关的全部内容都位于[template]表之下。从源码看RootConfig 在解析配置时会把template键交给独立的TemplateConfig类见 TemplateConfig处理TemplateConfig负责校验name、email、licenses、plugins四个字段的类型与取值。Author作者信息的配置与默认值来源[template] name ... email ...这两个字段会被写入新项目的pyproject.toml的authors列表。它们的默认值并非硬编码在配置中而是按以下优先级推导见 TemplateConfig.name 与 TemplateConfig.email若配置文件中显式给出直接采用否则读取环境变量GIT_AUTHOR_NAME/GIT_AUTHOR_EMAIL仍缺失时回退到git config --get user.name/user.email最终兜底值分别为U.N. Owen和voidsome.where。因此只要本机 git 配置了user.name与user.email即使完全不写[template]表生成的项目也能带上正确的作者信息。该值同时会用于生成的许可证文件见下文中的版权声明例如MIT许可证模板中的copyright holders会被替换为{name} {email}见 default.py 的 get_license_text。Licenses许可证的 SPDX 标识、版权头与多许可布局[template.licenses] headers true default [ MIT, ][template.licenses]表由 LicensesConfig 解析包含两个字段headers布尔默认true是否在新生成的.py源文件顶部插入 SPDX 版权头。版权头格式为# SPDX-FileCopyrightText: {创建年份}-present {name} {email} # # SPDX-License-Identifier: {SPDX 表达式}该头部由 DefaultTemplate.initialize_config 生成并在 finalize_files 阶段统一拼接到所有 Python 模板文件开头。default字符串数组默认[MIT]项目默认采用的许可证列表列表项必须是 SPDX 标识符。许可证的处理逻辑值得展开说明见 default.py若default为空数组则项目不携带任何许可证license_expression为空、不生成许可证文件、不生成版权头。许可证全文通过packaging.licenses._spdx.VERSION定位 SPDX license-list-data 版本从官方数据源下载{license_id}.txt到 Hatch 缓存目录{cache_dir}/licenses之后复用缓存失败时最多重试 5 次。单许可证时写入根目录的LICENSE.txtpyproject.toml中通过license SPDX 表达式声明多许可证时按 REUSE 多许可规范。license_expression由多个标识符以OR连接例如MIT OR Apache-2.0作为[project] license字段写入 pyproject.toml 模板。对MIT与BSD-3-Clause许可证模板中的year会被替换为{创建年份}-present版权持有人被替换为配置的作者信息使生成的许可证文件立即可用。在tests开启的情况下生成的pyproject.toml还会在 README 的目录中追加 License 章节链接。Options默认插件template.plugins.default的三个开关[template.plugins.default]对应内置的default模板插件实现类为 DefaultTemplate插件接口定义在 src/hatch/template/plugin/interface.py。它的三个开关在配置未给出时都有默认值见 DefaultTemplate.init与 TemplateConfig.plugins配置键默认值作用teststrue添加tests目录及测试、类型检查相关环境cifalse添加 GitHub Actions 工作流src-layouttrue采用src目录布局三个开关在 get_files 中分别决定是否追加对应的文件集合互不冲突。Tests测试与静态检查环境[template.plugins.default] tests true开启后会生成tests/__init__.py见 files_feature_tests.py并在pyproject.toml中追加[tool.hatch.envs.types]环境内置mypy1.0.0并提供check脚本执行mypy --install-types --non-interactive对源码与测试做类型检查[tool.coverage.run]/[tool.coverage.paths]/[tool.coverage.report]三组覆盖率配置默认把__about__.py排除在覆盖率统计之外并忽略no cov、if __name__ __main__:、if TYPE_CHECKING:等行见 PyProject 模板的 tests_section。这使得新建项目开箱即支持hatch test与类型检查。CIGitHub Actions 多平台测试工作流[template.plugins.default] ci false开启后生成.github/workflows/test.yml见 files_feature_ci.py。该工作流在main/master分支的 push 与 pull_request 时触发特性包括三平台矩阵ubuntu-latest、windows-latest、macos-latestPython 版本矩阵3.8至3.13concurrency分组与cancel-in-progress: true同一 PR 的新提交会取消旧的运行通过pip install --upgrade hatch安装 Hatch依次执行hatch fmt --check格式与静态检查与hatch test --python ${{ matrix.python-version }} --cover --randomize --parallel --retries 2 --retry-delay 1跨版本并行测试、覆盖率、随机化与失败重试。srclayout目录布局[template.plugins.default] src-layout truesrc布局把包代码放在src/下避免测试直接导入源码产生测试通过但安装失败的假象也是 Hatch 官方推荐的布局。其实现位于 finalize_files所有以包名开头的模板文件路径统一加上src/前缀同时package_metadata_file_path相应调整为src/{package_name}/__about__.py并同步影响pyproject.toml中[tool.hatch.version] path与覆盖率配置的路径见 default.py 与 files_default.py。关闭后这些路径恢复为包根目录{package_name}/__about__.py。Feature flags--cli命令行接口脚手架与前面通过配置文件控制的选项不同--cli是hatch new命令的运行时参数属于功能标记feature flaghatch new --cli 项目名该标记在 cli/new/init.py 中定义为--cli对应内部变量feature_cli通过default_config[args][cli]传入模板。开启后会追加两组文件见 files_feature_cli.py{package_name}/__main__.py入口文件调用from {package_name}.cli import {package_name}并sys.exit({package_name}())因此项目可以通过python -m PKG_NAME启动{package_name}/cli/__init__.py基于 Click 的click.group命令组注册-h/--help帮助选项与--version版本选项版本取自__about__.py的__version__默认输出Hello world!。同时 PyProject 模板 会在pyproject.toml中追加[project.scripts]将命令名映射到{package_name}.cli:{package_name}使安装后即可在终端直接执行该命令。此外 DefaultTemplate.initialize_config 会自动把click加入项目的dependencies。完整工作流配置文件如何驱动hatch new将上述配置串起来hatch new的执行流程如下见 new 命令收集name项目名与location创建位置。非交互模式下缺少项目名会直接报错提示使用-i/--interactive。规范化包名Project.canonicalize_name将项目名转为标准化形式包名中的-替换为_。读取并深度拷贝app.config.template.raw_data用TemplateConfig(...).parse_fields()校验与补全默认值name、email、licenses、plugins默认项都会在此补齐见 TemplateConfig。通过插件收集机制加载模板类app.plugins.template.collect()按PRIORITY排序实例化配置中出现的插件多余的插件名会报错。依次执行initialize_config计算许可证、版权头、元数据路径等、get_files生成文件列表、finalize_files拼接版权头、调整src布局最后逐个write写出文件。完成后用 rich Tree 在终端打印新项目的目录结构。hatch new还支持--init为已有项目生成/更新pyproject.toml存在setup.py/setup.cfg时可通过 migrate.py 从 setuptools 自动迁移元数据迁移逻辑在临时虚拟环境中执行与-i/--interactive交互式问答确定描述等细节它们与模板配置相互配合适合不同场景。总结模板配置与生成产物的对应关系配置/参数位置默认值主要影响[template] name/email配置文件git 用户信息pyproject.toml的authors、许可证版权声明、SPDX 版权头[template.licenses] headers配置文件true.py文件头部是否插入 SPDX 版权头[template.licenses] default配置文件[MIT]许可证文件与license字段多许可写入LICENSES/[template.plugins.default] tests配置文件truetests/目录、types环境、覆盖率配置[template.plugins.default] ci配置文件false.github/workflows/test.yml多平台 CI[template.plugins.default] src-layout配置文件truesrc/目录布局及相关路径--cliCLI 参数关闭Click CLI、python -m入口、[project.scripts]按以上配置组合即可在团队内统一新项目的初始形态。所有模板文件的实际生成逻辑均可在本仓库的 src/hatch/template/files_default.py、src/hatch/template/files_feature_tests.py、src/hatch/template/files_feature_ci.py 与 src/hatch/template/files_feature_cli.py 中查看测试用例可参考 tests/cli/new/test_new.py 与 tests/helpers/templates/new/便于深入验证每个开关的实际效果。赞分享开发工具构建工具【免费下载链接】hatchModern, extensible Python project management项目地址https://gitcode.com/gh_mirrors/ha/hatch点击查看免费下载相关推荐解决ZoomTransitioning集成难题常见问题与解决方案汇总解决ZoomTransitioning集成难题常见问题与解决方案汇总 ZoomTransitioning是一款为iOS应用提供图片缩放动画和屏幕边缘滑动效果的数据工程工作流自动化Qwen3.5-27B-Claude-4.6-Opus-Distilled-MLX-4bit苹果M芯片上最强大的本地推理AI模型Qwen3.5 27B Claude 4.6 Opus Distilled MLX 4bit苹果M芯片上最强大的本地推理AI模型 Qwen3.5 27B Cl3分钟上手Hatch配置从零基础到项目实战完全指南3分钟上手Hatch配置从零基础到项目实战完全指南 你还在为Python项目配置繁琐的环境变量、依赖管理和多环境切换而头疼吗作为一款现代化、可扩展的Pyth开发工具构建工具上一篇Comprehensive Rust 教程精讲用泛型 Typestate 模式实现 Serializer 的 Struct 状态下一篇LeetCode-Go 题解223. Rectangle Area 矩形面积计算创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Hatch 项目模板配置完全指南：用 `hatch new` 与 `[template]` 配置文件定制新项目骨架
开发工具构建工具【免费下载链接】hatchModern, extensible Python project management项目地址https://gitcode.com/gh_mirrors/ha/hatch点击查看免费下载Hatch 的hatch new命令可以一键创建结构完整的 Python 项目而项目的默认形态作者信息、许可证、测试环境、CI 工作流、目录布局、CLI 脚手架全部由 Hatch 配置文件中的[template]表控制。本文以 docs/config/project-templates.md 为骨架结合 src/hatch/cli/new/init.py 与 src/hatch/config/model.py 等源码系统讲解每个配置项的含义、默认值、底层行为读完即可按团队规范定制统一的项目初始化模板。配置文件的位置与作用域hatch new的行为受 Hatch 配置文件 控制。配置查找遵循 Hatch 的全局配置机制默认写入用户级配置文件例如 Linux/macOS 下的~/.config/hatch/config.tomlWindows 下位于用户配置目录也可以使用HATCH_CONFIG环境变量指定自定义路径。与项目模板相关的全部内容都位于[template]表之下。从源码看RootConfig 在解析配置时会把template键交给独立的TemplateConfig类见 TemplateConfig处理TemplateConfig负责校验name、email、licenses、plugins四个字段的类型与取值。Author作者信息的配置与默认值来源[template] name ... email ...这两个字段会被写入新项目的pyproject.toml的authors列表。它们的默认值并非硬编码在配置中而是按以下优先级推导见 TemplateConfig.name 与 TemplateConfig.email若配置文件中显式给出直接采用否则读取环境变量GIT_AUTHOR_NAME/GIT_AUTHOR_EMAIL仍缺失时回退到git config --get user.name/user.email最终兜底值分别为U.N. Owen和voidsome.where。因此只要本机 git 配置了user.name与user.email即使完全不写[template]表生成的项目也能带上正确的作者信息。该值同时会用于生成的许可证文件见下文中的版权声明例如MIT许可证模板中的copyright holders会被替换为{name} {email}见 default.py 的 get_license_text。Licenses许可证的 SPDX 标识、版权头与多许可布局[template.licenses] headers true default [ MIT, ][template.licenses]表由 LicensesConfig 解析包含两个字段headers布尔默认true是否在新生成的.py源文件顶部插入 SPDX 版权头。版权头格式为# SPDX-FileCopyrightText: {创建年份}-present {name} {email} # # SPDX-License-Identifier: {SPDX 表达式}该头部由 DefaultTemplate.initialize_config 生成并在 finalize_files 阶段统一拼接到所有 Python 模板文件开头。default字符串数组默认[MIT]项目默认采用的许可证列表列表项必须是 SPDX 标识符。许可证的处理逻辑值得展开说明见 default.py若default为空数组则项目不携带任何许可证license_expression为空、不生成许可证文件、不生成版权头。许可证全文通过packaging.licenses._spdx.VERSION定位 SPDX license-list-data 版本从官方数据源下载{license_id}.txt到 Hatch 缓存目录{cache_dir}/licenses之后复用缓存失败时最多重试 5 次。单许可证时写入根目录的LICENSE.txtpyproject.toml中通过license SPDX 表达式声明多许可证时按 REUSE 多许可规范。license_expression由多个标识符以OR连接例如MIT OR Apache-2.0作为[project] license字段写入 pyproject.toml 模板。对MIT与BSD-3-Clause许可证模板中的year会被替换为{创建年份}-present版权持有人被替换为配置的作者信息使生成的许可证文件立即可用。在tests开启的情况下生成的pyproject.toml还会在 README 的目录中追加 License 章节链接。Options默认插件template.plugins.default的三个开关[template.plugins.default]对应内置的default模板插件实现类为 DefaultTemplate插件接口定义在 src/hatch/template/plugin/interface.py。它的三个开关在配置未给出时都有默认值见 DefaultTemplate.init与 TemplateConfig.plugins配置键默认值作用teststrue添加tests目录及测试、类型检查相关环境cifalse添加 GitHub Actions 工作流src-layouttrue采用src目录布局三个开关在 get_files 中分别决定是否追加对应的文件集合互不冲突。Tests测试与静态检查环境[template.plugins.default] tests true开启后会生成tests/__init__.py见 files_feature_tests.py并在pyproject.toml中追加[tool.hatch.envs.types]环境内置mypy1.0.0并提供check脚本执行mypy --install-types --non-interactive对源码与测试做类型检查[tool.coverage.run]/[tool.coverage.paths]/[tool.coverage.report]三组覆盖率配置默认把__about__.py排除在覆盖率统计之外并忽略no cov、if __name__ __main__:、if TYPE_CHECKING:等行见 PyProject 模板的 tests_section。这使得新建项目开箱即支持hatch test与类型检查。CIGitHub Actions 多平台测试工作流[template.plugins.default] ci false开启后生成.github/workflows/test.yml见 files_feature_ci.py。该工作流在main/master分支的 push 与 pull_request 时触发特性包括三平台矩阵ubuntu-latest、windows-latest、macos-latestPython 版本矩阵3.8至3.13concurrency分组与cancel-in-progress: true同一 PR 的新提交会取消旧的运行通过pip install --upgrade hatch安装 Hatch依次执行hatch fmt --check格式与静态检查与hatch test --python ${{ matrix.python-version }} --cover --randomize --parallel --retries 2 --retry-delay 1跨版本并行测试、覆盖率、随机化与失败重试。srclayout目录布局[template.plugins.default] src-layout truesrc布局把包代码放在src/下避免测试直接导入源码产生测试通过但安装失败的假象也是 Hatch 官方推荐的布局。其实现位于 finalize_files所有以包名开头的模板文件路径统一加上src/前缀同时package_metadata_file_path相应调整为src/{package_name}/__about__.py并同步影响pyproject.toml中[tool.hatch.version] path与覆盖率配置的路径见 default.py 与 files_default.py。关闭后这些路径恢复为包根目录{package_name}/__about__.py。Feature flags--cli命令行接口脚手架与前面通过配置文件控制的选项不同--cli是hatch new命令的运行时参数属于功能标记feature flaghatch new --cli 项目名该标记在 cli/new/init.py 中定义为--cli对应内部变量feature_cli通过default_config[args][cli]传入模板。开启后会追加两组文件见 files_feature_cli.py{package_name}/__main__.py入口文件调用from {package_name}.cli import {package_name}并sys.exit({package_name}())因此项目可以通过python -m PKG_NAME启动{package_name}/cli/__init__.py基于 Click 的click.group命令组注册-h/--help帮助选项与--version版本选项版本取自__about__.py的__version__默认输出Hello world!。同时 PyProject 模板 会在pyproject.toml中追加[project.scripts]将命令名映射到{package_name}.cli:{package_name}使安装后即可在终端直接执行该命令。此外 DefaultTemplate.initialize_config 会自动把click加入项目的dependencies。完整工作流配置文件如何驱动hatch new将上述配置串起来hatch new的执行流程如下见 new 命令收集name项目名与location创建位置。非交互模式下缺少项目名会直接报错提示使用-i/--interactive。规范化包名Project.canonicalize_name将项目名转为标准化形式包名中的-替换为_。读取并深度拷贝app.config.template.raw_data用TemplateConfig(...).parse_fields()校验与补全默认值name、email、licenses、plugins默认项都会在此补齐见 TemplateConfig。通过插件收集机制加载模板类app.plugins.template.collect()按PRIORITY排序实例化配置中出现的插件多余的插件名会报错。依次执行initialize_config计算许可证、版权头、元数据路径等、get_files生成文件列表、finalize_files拼接版权头、调整src布局最后逐个write写出文件。完成后用 rich Tree 在终端打印新项目的目录结构。hatch new还支持--init为已有项目生成/更新pyproject.toml存在setup.py/setup.cfg时可通过 migrate.py 从 setuptools 自动迁移元数据迁移逻辑在临时虚拟环境中执行与-i/--interactive交互式问答确定描述等细节它们与模板配置相互配合适合不同场景。总结模板配置与生成产物的对应关系配置/参数位置默认值主要影响[template] name/email配置文件git 用户信息pyproject.toml的authors、许可证版权声明、SPDX 版权头[template.licenses] headers配置文件true.py文件头部是否插入 SPDX 版权头[template.licenses] default配置文件[MIT]许可证文件与license字段多许可写入LICENSES/[template.plugins.default] tests配置文件truetests/目录、types环境、覆盖率配置[template.plugins.default] ci配置文件false.github/workflows/test.yml多平台 CI[template.plugins.default] src-layout配置文件truesrc/目录布局及相关路径--cliCLI 参数关闭Click CLI、python -m入口、[project.scripts]按以上配置组合即可在团队内统一新项目的初始形态。所有模板文件的实际生成逻辑均可在本仓库的 src/hatch/template/files_default.py、src/hatch/template/files_feature_tests.py、src/hatch/template/files_feature_ci.py 与 src/hatch/template/files_feature_cli.py 中查看测试用例可参考 tests/cli/new/test_new.py 与 tests/helpers/templates/new/便于深入验证每个开关的实际效果。赞分享开发工具构建工具【免费下载链接】hatchModern, extensible Python project management项目地址https://gitcode.com/gh_mirrors/ha/hatch点击查看免费下载相关推荐解决ZoomTransitioning集成难题常见问题与解决方案汇总解决ZoomTransitioning集成难题常见问题与解决方案汇总 ZoomTransitioning是一款为iOS应用提供图片缩放动画和屏幕边缘滑动效果的数据工程工作流自动化Qwen3.5-27B-Claude-4.6-Opus-Distilled-MLX-4bit苹果M芯片上最强大的本地推理AI模型Qwen3.5 27B Claude 4.6 Opus Distilled MLX 4bit苹果M芯片上最强大的本地推理AI模型 Qwen3.5 27B Cl3分钟上手Hatch配置从零基础到项目实战完全指南3分钟上手Hatch配置从零基础到项目实战完全指南 你还在为Python项目配置繁琐的环境变量、依赖管理和多环境切换而头疼吗作为一款现代化、可扩展的Pyth开发工具构建工具上一篇Comprehensive Rust 教程精讲用泛型 Typestate 模式实现 Serializer 的 Struct 状态下一篇LeetCode-Go 题解223. Rectangle Area 矩形面积计算创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考