1. 项目概述与核心价值最近在折腾一个Python项目需要打包发布到PyPI顺手又研究了一下现代Python打包工具链。说实话从早期的distutils、setuptools到后来的poetry、flit再到如今社区里讨论度颇高的hatch这个领域的变化真不小。今天想和大家深入聊聊的就是这个名为hatch3r/hatch3r的项目——它本质上就是hatch一个旨在成为“现代、可扩展、Python项目管理的单一工具”。如果你还在为Python项目的依赖管理、虚拟环境、版本管理、打包发布、测试运行等一系列琐事而头疼或者觉得poetry在某些方面过于“固执己见”那么hatch或许能给你带来一些新的思路和更流畅的体验。简单来说hatch试图用一个统一的命令行工具覆盖Python项目从创建到发布的完整生命周期。它内置了虚拟环境管理、依赖管理、版本控制、构建、发布、测试运行等核心功能并且通过插件系统保持了极高的可扩展性。hatch3r/hatch3r这个仓库就是其官方代码库。我花了一段时间深度使用并对比了其他主流工具发现它在设计理念、灵活性和对现代工作流的支持上确实有不少独到之处。接下来我会从设计思路、核心功能拆解、实战配置到高级技巧为你完整呈现这个工具的全貌。2. 核心设计理念与架构解析2.1 为什么需要另一个项目管理工具在深入hatch之前我们得先看看现有的工具链存在哪些痛点。传统的setuptoolspipvirtualenv组合非常灵活但配置繁琐需要写setup.py、setup.cfg、MANIFEST.in等多个文件依赖管理也分散在requirements.txt里。poetry的出现极大地改善了体验它统一了pyproject.toml管理依赖和发布都很方便。但poetry也有其问题它对pyproject.toml的结构有自己严格的规定插件生态相对封闭并且其依赖解析器在某些复杂场景下可能成为性能瓶颈或冲突源头。hatch的设计目标很明确提供一个功能全面、高度可配置且不“越权”的核心。它不强制你使用特定的依赖解析器虽然默认用pip但可替换不强制特定的文件结构而是通过清晰的约定和强大的插件系统让你可以按需组装自己的工作流。它的核心是一个“项目管理器”而非“依赖解析器”这使其定位与poetry有了微妙的区别。2.2 核心架构可插拔的引擎hatch的架构非常清晰。其核心是一个轻量级的命令行接口和项目管理引擎。所有具体功能如环境管理、构建、发布、测试等都通过插件Plugin实现。这种设计带来了几个显著优势职责分离核心只负责调度和配置管理具体脏活累活由插件完成。这使得核心非常稳定新功能的开发和迭代可以在插件层面独立进行。高度可定制如果你对默认的构建方式如hatchling构建后端不满意可以换用其他构建后端插件。环境管理也可以从默认的virtualenv切换到conda、pipenv模式等。生态友好鼓励社区贡献插件理论上可以扩展出无限可能比如集成特定的云部署、文档生成、代码质量检查等。配置文件pyproject.toml中的[tool.hatch]部分是所有配置的入口。在这里你可以启用/禁用插件配置各个插件的行为。这种集中式的配置管理比分散在多个文件或命令行参数中要清晰得多。3. 从零开始初始化与基础配置实战3.1 安装与项目创建安装hatch非常简单推荐使用pipx这样可以避免污染你的全局Python环境也方便管理独立命令行工具。pipx install hatch安装完成后就可以使用hatch new命令来创建一个新项目。这里我创建一个名为my_awesome_lib的库。hatch new my_awesome_lib cd my_awesome_lib执行后hatch会生成一个标准的项目结构my_awesome_lib/ ├── pyproject.toml ├── README.md ├── src/ │ └── my_awesome_lib/ │ ├── __init__.py │ └── __about__.py └── tests/ └── __init__.py注意默认模板生成的是src-layout源码放在src目录下。这是一种推荐的做法可以避免很多导入路径的混淆问题尤其是在开发期间。如果你偏好扁平结构可以在创建时使用--cli参数创建命令行工具项目或之后手动调整。让我们立刻看看核心的pyproject.toml文件这是hatch的“大脑”。[build-system] requires [hatchling] build-backend hatchling.build [project] name my-awesome-lib dynamic [version] description readme README.md requires-python 3.8 license MIT keywords [] authors [ {name Your Name, email youexample.com}, ] classifiers [ Development Status :: 4 - Beta, Programming Language :: Python, Programming Language :: Python :: 3.8, Programming Language :: Python :: 3.9, Programming Language :: Python :: 3.10, Programming Language :: Python :: 3.11, Programming Language :: Python :: 3.12, ] dependencies [] [project.urls] Homepage [tool.hatch.version] path src/my_awesome_lib/__about__.py [tool.hatch.build.targets.wheel][build-system]: 声明使用hatchling作为构建后端。这是hatch生态中的官方构建工具替代了setuptools。[project]: 这是PEP 621定义的标准元数据表。name、description、dependencies等都在这里定义。注意dynamic [version]这表示版本号是动态获取的具体来源由[tool.hatch.version]指定。[tool.hatch.version]: 配置版本管理。这里指定从src/my_awesome_lib/__about__.py文件的__version__变量中读取版本。这是一种非常清晰的版本管理方式代码和版本信息在同一处。[tool.hatch.build.targets.wheel]: 配置Wheel包的构建行为目前是默认配置。3.2 依赖管理与虚拟环境hatch内置了虚拟环境管理功能无需额外安装virtualenv或venv。它为每个项目维护一个或多个隔离的环境。添加依赖编辑pyproject.toml中的dependencies列表。[project] # ... 其他配置 dependencies [ requests2.28.0, pydantic2.0, rich13.0.0, ]对于开发依赖hatch使用[tool.hatch.envs.default]下的dependencies来定义。默认环境名为default。[tool.hatch.envs.default] dependencies [ pytest7.0.0, pytest-cov4.0.0, black23.0.0, mypy1.0.0, ruff0.1.0, ]同步环境配置好依赖后运行以下命令来创建如果不存在并同步虚拟环境hatch env create这个命令会读取pyproject.toml中的依赖创建一个名为.hatch/envs/default的虚拟环境并安装所有依赖。之后你可以使用hatch shell进入这个环境的shell或者直接用hatch run command来在这个环境中运行命令。实操心得hatch env create命令是幂等的。如果环境已存在且依赖发生变化再次运行它会自动更新环境中的包使其与pyproject.toml声明保持一致。这比手动pip install要可靠得多。4. 进阶功能深度解析与配置4.1 多环境管理与矩阵构建这是hatch非常强大的一个特性。你不仅可以有一个default环境还可以定义任意多个、用于不同目的的环境。假设我们的库需要支持Python 3.8到3.12并且需要在每个版本上进行测试。我们可以定义一个matrix测试环境。[tool.hatch.envs.test] # 这是一个模板环境不会直接创建 dependencies [ pytest7.0.0, pytest-cov4.0.0, pytest-xdist3.0.0, # 并行测试 ] [tool.hatch.envs.test.matrix] # 定义矩阵维度 python [3.8, 3.9, 3.10, 3.11, 3.12] platform [linux, windows] # 示例还可以按平台区分 # 为所有test环境的变体额外添加的依赖 dependencies [ # 可以为特定Python版本添加依赖例如 { “py \3.8\” [importlib-metadata4.0.0] }, ]在这个配置下hatch会根据矩阵组合生成多个具体环境例如test.py3.8.linux、test.py3.9.windows等。要创建所有这些环境可以运行hatch env create test要运行所有测试环境下的测试可以使用hatch run test:all pytesthatch会自动在所有匹配的test环境变体上执行pytest命令。这对于保证跨版本、跨平台兼容性极其有用尤其是在CI/CD流水线中。除了测试你还可以定义其他环境比如用于构建文档的docs环境用于性能分析的bench环境等。[tool.hatch.envs.docs] dependencies [ mkdocs1.4.0, mkdocs-material9.0.0, ] scripts { build mkdocs build, serve mkdocs serve } # 定义环境内脚本 [tool.hatch.envs.bench] dependencies [ pytest-benchmark4.0.0, ]4.2 版本管理与动态版本hatch对版本管理提供了灵活的支持。前面我们看到它可以从__about__.py读取版本。它还支持基于gittag的动态版本生成这对于持续交付非常友好。基于Git的版本方案[tool.hatch.version] source vcs # 从版本控制系统获取配置此选项后hatch会使用setuptools_scm风格的逻辑从git tag推断版本。例如最新的tag是v1.2.3那么版本就是1.2.3。如果当前提交有未提交的更改会自动添加.dev后缀。你还可以组合多种方案。一个常见的模式是在开发时使用__about__.py中的固定版本如0.0.1而在CI构建发布包时通过环境变量覆盖为基于git tag的动态版本。[tool.hatch.version] path src/my_awesome_lib/__about__.py # 定义一个“模式”当HATCH_BUILD_NO_LOCAL_VERSION环境变量为真时使用vcs方案 [[tool.hatch.version.scheme]] name “vcs” trigger { env “HATCH_BUILD_NO_LOCAL_VERSION” }在CI脚本中export HATCH_BUILD_NO_LOCAL_VERSIONtrue hatch build4.3 构建与发布配置详解构建配置在[tool.hatch.build]下。hatchling作为构建后端支持许多高级特性。包含/排除文件默认情况下hatchling会根据pyproject.toml和文件类型自动决定哪些文件该被打包。你也可以通过include和exclude进行精细控制。[tool.hatch.build] include [ “/README.md”, “/LICENSE”, “/pyproject.toml”, ] exclude [ “*.py[cod]”, # 排除字节码文件 “__pycache__/”, “dist/”, “.git/”, “*.egg-info/”, “.ruff_cache/”, ] [tool.hatch.build.targets.wheel] # Wheel包特定配置例如指定构建tag py-limited-api “cp38” # 生成abi3轮子兼容CPython 3.8构建命令配置完成后构建包非常简单。# 构建wheel和sdist hatch build # 只构建wheel hatch build -t wheel # 只构建sdist hatch build -t sdist构建产物会放在dist/目录下。发布到PyPI发布前你需要配置仓库凭证。推荐使用truststore和keyring或者使用令牌。hatch支持通过环境变量或配置文件设置。使用环境变量export HATCH_INDEX_USER__token__ export HATCH_INDEX_AUTH你的PyPI API令牌然后发布hatch publishhatch publish默认会上传到PyPI。你也可以配置上传到TestPyPI或其他私有仓库。[[tool.hatch.publish.repositories]] name “testpypi” url “https://test.pypi.org/legacy/”然后使用hatch publish -r testpypi来发布到测试仓库。5. 插件系统与生态扩展hatch的真正威力在于其插件系统。官方已经提供了一系列高质量的插件社区也在不断贡献。5.1 常用官方插件hatch-vcs: 提供更强大的VCS如git集成用于动态版本管理。hatch-conda: 允许使用conda包管理器来管理环境依赖而不仅仅是pip。hatch-fancy-pypi-readme: 自动从README.md生成漂亮的PyPI项目页面描述支持多种格式。hatch-mypyc: 集成mypyc将Python代码编译成C扩展以提升性能。hatch-nodejs-version: 在环境中管理Node.js版本对于需要构建前端资源的Python项目如Jupyter插件很有用。安装插件非常简单通常使用pip安装到你的用户环境或项目的开发依赖中然后在pyproject.toml中启用。pip install hatch-fancy-pypi-readme[tool.hatch] plugins [“fancy-pypi-readme”] [tool.hatch.metadata.hooks.fancy-pypi-readme] content-type “text/markdown”5.2 自定义脚本与工作流自动化hatch允许你在pyproject.toml中定义自定义脚本scripts这些脚本会在特定的项目环境下运行。这是自动化日常任务的神器。[tool.hatch.envs.default] # 在default环境中定义的脚本 scripts { test “pytest {args}”, lint “ruff check . {args}”, format [ “ruff format . {args}”, “black . {args}”, ], type-check “mypy src/ {args}”, cov “pytest --covsrc/my_awesome_lib --cov-reportterm-missing {args}”, “build-all” [ “hatch run lint”, “hatch run type-check”, “hatch run test”, “hatch build”, ] }定义好后你可以像使用内置命令一样使用它们hatch run lint # 运行代码检查 hatch run format # 格式化代码 hatch run cov # 运行测试并生成覆盖率报告 hatch run build-all # 运行完整的质量检查并构建包{args}是一个占位符允许你向脚本传递额外的命令行参数。例如hatch run test -v -k “test_something”。注意事项脚本命令是在项目环境的上下文中执行的这意味着你无需手动激活虚拟环境。这极大地简化了在IDE终端、编辑器集成或CI脚本中的操作。6. 实战避坑与高级技巧6.1 依赖解析冲突与策略虽然hatch默认使用pip但在复杂依赖场景下你可能会遇到冲突。hatch允许你更换依赖解析器。例如你可以使用uv一个用Rust写的极速Python包安装器和解析器作为后端。首先安装hatch-uv插件如果存在社区版本或者更直接的方式是hatch的环境创建过程本质上是调用virtualenv然后pip install。你可以通过配置改变安装器。一个更实用的技巧是利用hatch的环境隔离性。如果某个开发工具如某个特定版本的black与你的项目运行时依赖冲突不要把它放在default环境的依赖里。而是为它创建一个独立的环境。[tool.hatch.envs.lint] dependencies [“black23.0.0”, “ruff0.1.0”] detached true # “分离”环境不继承项目依赖然后使用hatch run lint:black来运行这个特定环境下的black。这样工具链的依赖就与项目依赖完全解耦了。6.2 与现有项目迁移集成如果你有一个使用传统setuptools或poetry的老项目迁移到hatch可以逐步进行。保留现有setup.py/setup.cfghatchling构建后端完全兼容PEP 517/518。你可以在pyproject.toml中仅配置[build-system]指向hatchling而[project]元数据仍然从setup.cfg或setup.py读取通过配置dynamic字段。这让你可以先替换构建系统再逐步迁移元数据。从poetry迁移poetry的pyproject.toml结构与PEP 621不完全相同但核心内容依赖、元数据可以手动迁移过来。hatch没有poetry.lock的等价物它更倾向于依赖pip的解析结果和可重复的环境创建。对于锁定的需求可以考虑使用pip-tools生成requirements.txt或使用uv的--locked模式如果集成的话。处理数据文件和包资源hatchling通过[tool.hatch.build.targets.wheel]下的artifacts或[tool.hatch.build]下的force-include来包含非代码文件这比旧的MANIFEST.in更声明式、更易管理。6.3 CI/CD集成最佳实践在GitHub Actions、GitLab CI等环境中集成hatch非常顺畅。核心思路利用缓存来加速环境创建。hatch的环境目录.hatch/envs/是可以被缓存的。但由于虚拟环境与Python解释器路径强相关直接缓存整个环境目录在Python版本切换时可能失效。更好的做法是缓存pip的下载缓存目录。这是一个GitHub Actions的示例片段jobs: test: runs-on: ubuntu-latest strategy: matrix: python-version: [“3.8”, “3.9”, “3.10”, “3.11”, “3.12”] steps: - uses: actions/checkoutv4 - name: Install Hatch run: pipx install hatch - name: Cache pip packages uses: actions/cachev3 with: path: ~/.cache/pip key: ${{ runner.os }}-pip-${{ hashFiles(‘pyproject.toml’) }} restore-keys: | ${{ runner.os }}-pip- - name: Create and run tests in matrix env run: hatch run test:py${{ matrix.python-version }} pytest -v --cov这个配置为每个Python版本创建了独立的测试环境并利用pip缓存加速了依赖安装。hatch run test:py3.8会自动选择并激活对应的矩阵环境。6.4 性能调优与问题排查环境创建慢确保使用了pip缓存。可以设置环境变量PIP_DOWNLOAD_CACHE或使用--pip-args传递给hatch env create来配置pip的下载参数例如使用国内镜像源hatch env create --pip-args“-i https://pypi.tuna.tsinghua.edu.cn/simple”。脚本执行找不到命令确保命令在目标环境的PATH中。hatch run会正确设置环境变量。如果问题依旧尝试使用绝对路径或检查该依赖是否确实安装在当前使用的环境中用hatch run which command检查。版本号不更新如果使用文件路径path方式管理版本确保修改了__about__.py中的__version__并保存。如果使用VCS方式确保打了正确的git tag并且工作区是干净的。构建包包含多余文件仔细检查[tool.hatch.build]下的include/exclude模式并使用hatch build --clean在构建前清理缓存然后检查生成的wheel内容unzip -l dist/*.whl。经过一段时间的深度使用我个人认为hatch代表了Python项目管理工具的一个正确演进方向它不试图成为一个垄断一切、自成体系的“王国”而是作为一个高效、可插拔的“协调中心”。它尊重Python生态现有的标准PEP 517, PEP 621并在此基础上提供极大的便利性和自动化能力。对于新项目我几乎会毫不犹豫地推荐从hatch开始。对于老项目也可以考虑逐步迁移尤其是当其复杂的多环境需求或自定义构建流程让现有工具链显得力不从心时。它的学习曲线比纯setuptools平缓又比poetry给予开发者更多的控制权和灵活性这种平衡做得相当出色。
Python项目管理新选择：Hatch工具链深度解析与实战指南
发布时间：2026/5/15 13:32:55
1. 项目概述与核心价值最近在折腾一个Python项目需要打包发布到PyPI顺手又研究了一下现代Python打包工具链。说实话从早期的distutils、setuptools到后来的poetry、flit再到如今社区里讨论度颇高的hatch这个领域的变化真不小。今天想和大家深入聊聊的就是这个名为hatch3r/hatch3r的项目——它本质上就是hatch一个旨在成为“现代、可扩展、Python项目管理的单一工具”。如果你还在为Python项目的依赖管理、虚拟环境、版本管理、打包发布、测试运行等一系列琐事而头疼或者觉得poetry在某些方面过于“固执己见”那么hatch或许能给你带来一些新的思路和更流畅的体验。简单来说hatch试图用一个统一的命令行工具覆盖Python项目从创建到发布的完整生命周期。它内置了虚拟环境管理、依赖管理、版本控制、构建、发布、测试运行等核心功能并且通过插件系统保持了极高的可扩展性。hatch3r/hatch3r这个仓库就是其官方代码库。我花了一段时间深度使用并对比了其他主流工具发现它在设计理念、灵活性和对现代工作流的支持上确实有不少独到之处。接下来我会从设计思路、核心功能拆解、实战配置到高级技巧为你完整呈现这个工具的全貌。2. 核心设计理念与架构解析2.1 为什么需要另一个项目管理工具在深入hatch之前我们得先看看现有的工具链存在哪些痛点。传统的setuptoolspipvirtualenv组合非常灵活但配置繁琐需要写setup.py、setup.cfg、MANIFEST.in等多个文件依赖管理也分散在requirements.txt里。poetry的出现极大地改善了体验它统一了pyproject.toml管理依赖和发布都很方便。但poetry也有其问题它对pyproject.toml的结构有自己严格的规定插件生态相对封闭并且其依赖解析器在某些复杂场景下可能成为性能瓶颈或冲突源头。hatch的设计目标很明确提供一个功能全面、高度可配置且不“越权”的核心。它不强制你使用特定的依赖解析器虽然默认用pip但可替换不强制特定的文件结构而是通过清晰的约定和强大的插件系统让你可以按需组装自己的工作流。它的核心是一个“项目管理器”而非“依赖解析器”这使其定位与poetry有了微妙的区别。2.2 核心架构可插拔的引擎hatch的架构非常清晰。其核心是一个轻量级的命令行接口和项目管理引擎。所有具体功能如环境管理、构建、发布、测试等都通过插件Plugin实现。这种设计带来了几个显著优势职责分离核心只负责调度和配置管理具体脏活累活由插件完成。这使得核心非常稳定新功能的开发和迭代可以在插件层面独立进行。高度可定制如果你对默认的构建方式如hatchling构建后端不满意可以换用其他构建后端插件。环境管理也可以从默认的virtualenv切换到conda、pipenv模式等。生态友好鼓励社区贡献插件理论上可以扩展出无限可能比如集成特定的云部署、文档生成、代码质量检查等。配置文件pyproject.toml中的[tool.hatch]部分是所有配置的入口。在这里你可以启用/禁用插件配置各个插件的行为。这种集中式的配置管理比分散在多个文件或命令行参数中要清晰得多。3. 从零开始初始化与基础配置实战3.1 安装与项目创建安装hatch非常简单推荐使用pipx这样可以避免污染你的全局Python环境也方便管理独立命令行工具。pipx install hatch安装完成后就可以使用hatch new命令来创建一个新项目。这里我创建一个名为my_awesome_lib的库。hatch new my_awesome_lib cd my_awesome_lib执行后hatch会生成一个标准的项目结构my_awesome_lib/ ├── pyproject.toml ├── README.md ├── src/ │ └── my_awesome_lib/ │ ├── __init__.py │ └── __about__.py └── tests/ └── __init__.py注意默认模板生成的是src-layout源码放在src目录下。这是一种推荐的做法可以避免很多导入路径的混淆问题尤其是在开发期间。如果你偏好扁平结构可以在创建时使用--cli参数创建命令行工具项目或之后手动调整。让我们立刻看看核心的pyproject.toml文件这是hatch的“大脑”。[build-system] requires [hatchling] build-backend hatchling.build [project] name my-awesome-lib dynamic [version] description readme README.md requires-python 3.8 license MIT keywords [] authors [ {name Your Name, email youexample.com}, ] classifiers [ Development Status :: 4 - Beta, Programming Language :: Python, Programming Language :: Python :: 3.8, Programming Language :: Python :: 3.9, Programming Language :: Python :: 3.10, Programming Language :: Python :: 3.11, Programming Language :: Python :: 3.12, ] dependencies [] [project.urls] Homepage [tool.hatch.version] path src/my_awesome_lib/__about__.py [tool.hatch.build.targets.wheel][build-system]: 声明使用hatchling作为构建后端。这是hatch生态中的官方构建工具替代了setuptools。[project]: 这是PEP 621定义的标准元数据表。name、description、dependencies等都在这里定义。注意dynamic [version]这表示版本号是动态获取的具体来源由[tool.hatch.version]指定。[tool.hatch.version]: 配置版本管理。这里指定从src/my_awesome_lib/__about__.py文件的__version__变量中读取版本。这是一种非常清晰的版本管理方式代码和版本信息在同一处。[tool.hatch.build.targets.wheel]: 配置Wheel包的构建行为目前是默认配置。3.2 依赖管理与虚拟环境hatch内置了虚拟环境管理功能无需额外安装virtualenv或venv。它为每个项目维护一个或多个隔离的环境。添加依赖编辑pyproject.toml中的dependencies列表。[project] # ... 其他配置 dependencies [ requests2.28.0, pydantic2.0, rich13.0.0, ]对于开发依赖hatch使用[tool.hatch.envs.default]下的dependencies来定义。默认环境名为default。[tool.hatch.envs.default] dependencies [ pytest7.0.0, pytest-cov4.0.0, black23.0.0, mypy1.0.0, ruff0.1.0, ]同步环境配置好依赖后运行以下命令来创建如果不存在并同步虚拟环境hatch env create这个命令会读取pyproject.toml中的依赖创建一个名为.hatch/envs/default的虚拟环境并安装所有依赖。之后你可以使用hatch shell进入这个环境的shell或者直接用hatch run command来在这个环境中运行命令。实操心得hatch env create命令是幂等的。如果环境已存在且依赖发生变化再次运行它会自动更新环境中的包使其与pyproject.toml声明保持一致。这比手动pip install要可靠得多。4. 进阶功能深度解析与配置4.1 多环境管理与矩阵构建这是hatch非常强大的一个特性。你不仅可以有一个default环境还可以定义任意多个、用于不同目的的环境。假设我们的库需要支持Python 3.8到3.12并且需要在每个版本上进行测试。我们可以定义一个matrix测试环境。[tool.hatch.envs.test] # 这是一个模板环境不会直接创建 dependencies [ pytest7.0.0, pytest-cov4.0.0, pytest-xdist3.0.0, # 并行测试 ] [tool.hatch.envs.test.matrix] # 定义矩阵维度 python [3.8, 3.9, 3.10, 3.11, 3.12] platform [linux, windows] # 示例还可以按平台区分 # 为所有test环境的变体额外添加的依赖 dependencies [ # 可以为特定Python版本添加依赖例如 { “py \3.8\” [importlib-metadata4.0.0] }, ]在这个配置下hatch会根据矩阵组合生成多个具体环境例如test.py3.8.linux、test.py3.9.windows等。要创建所有这些环境可以运行hatch env create test要运行所有测试环境下的测试可以使用hatch run test:all pytesthatch会自动在所有匹配的test环境变体上执行pytest命令。这对于保证跨版本、跨平台兼容性极其有用尤其是在CI/CD流水线中。除了测试你还可以定义其他环境比如用于构建文档的docs环境用于性能分析的bench环境等。[tool.hatch.envs.docs] dependencies [ mkdocs1.4.0, mkdocs-material9.0.0, ] scripts { build mkdocs build, serve mkdocs serve } # 定义环境内脚本 [tool.hatch.envs.bench] dependencies [ pytest-benchmark4.0.0, ]4.2 版本管理与动态版本hatch对版本管理提供了灵活的支持。前面我们看到它可以从__about__.py读取版本。它还支持基于gittag的动态版本生成这对于持续交付非常友好。基于Git的版本方案[tool.hatch.version] source vcs # 从版本控制系统获取配置此选项后hatch会使用setuptools_scm风格的逻辑从git tag推断版本。例如最新的tag是v1.2.3那么版本就是1.2.3。如果当前提交有未提交的更改会自动添加.dev后缀。你还可以组合多种方案。一个常见的模式是在开发时使用__about__.py中的固定版本如0.0.1而在CI构建发布包时通过环境变量覆盖为基于git tag的动态版本。[tool.hatch.version] path src/my_awesome_lib/__about__.py # 定义一个“模式”当HATCH_BUILD_NO_LOCAL_VERSION环境变量为真时使用vcs方案 [[tool.hatch.version.scheme]] name “vcs” trigger { env “HATCH_BUILD_NO_LOCAL_VERSION” }在CI脚本中export HATCH_BUILD_NO_LOCAL_VERSIONtrue hatch build4.3 构建与发布配置详解构建配置在[tool.hatch.build]下。hatchling作为构建后端支持许多高级特性。包含/排除文件默认情况下hatchling会根据pyproject.toml和文件类型自动决定哪些文件该被打包。你也可以通过include和exclude进行精细控制。[tool.hatch.build] include [ “/README.md”, “/LICENSE”, “/pyproject.toml”, ] exclude [ “*.py[cod]”, # 排除字节码文件 “__pycache__/”, “dist/”, “.git/”, “*.egg-info/”, “.ruff_cache/”, ] [tool.hatch.build.targets.wheel] # Wheel包特定配置例如指定构建tag py-limited-api “cp38” # 生成abi3轮子兼容CPython 3.8构建命令配置完成后构建包非常简单。# 构建wheel和sdist hatch build # 只构建wheel hatch build -t wheel # 只构建sdist hatch build -t sdist构建产物会放在dist/目录下。发布到PyPI发布前你需要配置仓库凭证。推荐使用truststore和keyring或者使用令牌。hatch支持通过环境变量或配置文件设置。使用环境变量export HATCH_INDEX_USER__token__ export HATCH_INDEX_AUTH你的PyPI API令牌然后发布hatch publishhatch publish默认会上传到PyPI。你也可以配置上传到TestPyPI或其他私有仓库。[[tool.hatch.publish.repositories]] name “testpypi” url “https://test.pypi.org/legacy/”然后使用hatch publish -r testpypi来发布到测试仓库。5. 插件系统与生态扩展hatch的真正威力在于其插件系统。官方已经提供了一系列高质量的插件社区也在不断贡献。5.1 常用官方插件hatch-vcs: 提供更强大的VCS如git集成用于动态版本管理。hatch-conda: 允许使用conda包管理器来管理环境依赖而不仅仅是pip。hatch-fancy-pypi-readme: 自动从README.md生成漂亮的PyPI项目页面描述支持多种格式。hatch-mypyc: 集成mypyc将Python代码编译成C扩展以提升性能。hatch-nodejs-version: 在环境中管理Node.js版本对于需要构建前端资源的Python项目如Jupyter插件很有用。安装插件非常简单通常使用pip安装到你的用户环境或项目的开发依赖中然后在pyproject.toml中启用。pip install hatch-fancy-pypi-readme[tool.hatch] plugins [“fancy-pypi-readme”] [tool.hatch.metadata.hooks.fancy-pypi-readme] content-type “text/markdown”5.2 自定义脚本与工作流自动化hatch允许你在pyproject.toml中定义自定义脚本scripts这些脚本会在特定的项目环境下运行。这是自动化日常任务的神器。[tool.hatch.envs.default] # 在default环境中定义的脚本 scripts { test “pytest {args}”, lint “ruff check . {args}”, format [ “ruff format . {args}”, “black . {args}”, ], type-check “mypy src/ {args}”, cov “pytest --covsrc/my_awesome_lib --cov-reportterm-missing {args}”, “build-all” [ “hatch run lint”, “hatch run type-check”, “hatch run test”, “hatch build”, ] }定义好后你可以像使用内置命令一样使用它们hatch run lint # 运行代码检查 hatch run format # 格式化代码 hatch run cov # 运行测试并生成覆盖率报告 hatch run build-all # 运行完整的质量检查并构建包{args}是一个占位符允许你向脚本传递额外的命令行参数。例如hatch run test -v -k “test_something”。注意事项脚本命令是在项目环境的上下文中执行的这意味着你无需手动激活虚拟环境。这极大地简化了在IDE终端、编辑器集成或CI脚本中的操作。6. 实战避坑与高级技巧6.1 依赖解析冲突与策略虽然hatch默认使用pip但在复杂依赖场景下你可能会遇到冲突。hatch允许你更换依赖解析器。例如你可以使用uv一个用Rust写的极速Python包安装器和解析器作为后端。首先安装hatch-uv插件如果存在社区版本或者更直接的方式是hatch的环境创建过程本质上是调用virtualenv然后pip install。你可以通过配置改变安装器。一个更实用的技巧是利用hatch的环境隔离性。如果某个开发工具如某个特定版本的black与你的项目运行时依赖冲突不要把它放在default环境的依赖里。而是为它创建一个独立的环境。[tool.hatch.envs.lint] dependencies [“black23.0.0”, “ruff0.1.0”] detached true # “分离”环境不继承项目依赖然后使用hatch run lint:black来运行这个特定环境下的black。这样工具链的依赖就与项目依赖完全解耦了。6.2 与现有项目迁移集成如果你有一个使用传统setuptools或poetry的老项目迁移到hatch可以逐步进行。保留现有setup.py/setup.cfghatchling构建后端完全兼容PEP 517/518。你可以在pyproject.toml中仅配置[build-system]指向hatchling而[project]元数据仍然从setup.cfg或setup.py读取通过配置dynamic字段。这让你可以先替换构建系统再逐步迁移元数据。从poetry迁移poetry的pyproject.toml结构与PEP 621不完全相同但核心内容依赖、元数据可以手动迁移过来。hatch没有poetry.lock的等价物它更倾向于依赖pip的解析结果和可重复的环境创建。对于锁定的需求可以考虑使用pip-tools生成requirements.txt或使用uv的--locked模式如果集成的话。处理数据文件和包资源hatchling通过[tool.hatch.build.targets.wheel]下的artifacts或[tool.hatch.build]下的force-include来包含非代码文件这比旧的MANIFEST.in更声明式、更易管理。6.3 CI/CD集成最佳实践在GitHub Actions、GitLab CI等环境中集成hatch非常顺畅。核心思路利用缓存来加速环境创建。hatch的环境目录.hatch/envs/是可以被缓存的。但由于虚拟环境与Python解释器路径强相关直接缓存整个环境目录在Python版本切换时可能失效。更好的做法是缓存pip的下载缓存目录。这是一个GitHub Actions的示例片段jobs: test: runs-on: ubuntu-latest strategy: matrix: python-version: [“3.8”, “3.9”, “3.10”, “3.11”, “3.12”] steps: - uses: actions/checkoutv4 - name: Install Hatch run: pipx install hatch - name: Cache pip packages uses: actions/cachev3 with: path: ~/.cache/pip key: ${{ runner.os }}-pip-${{ hashFiles(‘pyproject.toml’) }} restore-keys: | ${{ runner.os }}-pip- - name: Create and run tests in matrix env run: hatch run test:py${{ matrix.python-version }} pytest -v --cov这个配置为每个Python版本创建了独立的测试环境并利用pip缓存加速了依赖安装。hatch run test:py3.8会自动选择并激活对应的矩阵环境。6.4 性能调优与问题排查环境创建慢确保使用了pip缓存。可以设置环境变量PIP_DOWNLOAD_CACHE或使用--pip-args传递给hatch env create来配置pip的下载参数例如使用国内镜像源hatch env create --pip-args“-i https://pypi.tuna.tsinghua.edu.cn/simple”。脚本执行找不到命令确保命令在目标环境的PATH中。hatch run会正确设置环境变量。如果问题依旧尝试使用绝对路径或检查该依赖是否确实安装在当前使用的环境中用hatch run which command检查。版本号不更新如果使用文件路径path方式管理版本确保修改了__about__.py中的__version__并保存。如果使用VCS方式确保打了正确的git tag并且工作区是干净的。构建包包含多余文件仔细检查[tool.hatch.build]下的include/exclude模式并使用hatch build --clean在构建前清理缓存然后检查生成的wheel内容unzip -l dist/*.whl。经过一段时间的深度使用我个人认为hatch代表了Python项目管理工具的一个正确演进方向它不试图成为一个垄断一切、自成体系的“王国”而是作为一个高效、可插拔的“协调中心”。它尊重Python生态现有的标准PEP 517, PEP 621并在此基础上提供极大的便利性和自动化能力。对于新项目我几乎会毫不犹豫地推荐从hatch开始。对于老项目也可以考虑逐步迁移尤其是当其复杂的多环境需求或自定义构建流程让现有工具链显得力不从心时。它的学习曲线比纯setuptools平缓又比poetry给予开发者更多的控制权和灵活性这种平衡做得相当出色。
![如何高效管理fg-data-profiling版本控制：Git工作流完整指南 [特殊字符]](http://pic.xiahunao.cn/yaotu/如何高效管理fg-data-profiling版本控制：Git工作流完整指南 [特殊字符])
