从0到1掌握poetry-dynamic-versioning：新手必备的版本控制技巧

【免费下载链接】poetry-dynamic-versioningPlugin for Poetry to enable dynamic versioning based on VCS tags项目地址: https://gitcode.com/gh_mirrors/po/poetry-dynamic-versioning

poetry-dynamic-versioning是一款专为Poetry设计的插件，能够基于版本控制系统（VCS）标签实现动态版本管理。它支持Git、Mercurial等多种版本控制工具，通过自动化处理版本号，让开发者告别手动修改版本的繁琐流程，专注于代码开发本身。

为什么选择poetry-dynamic-versioning？

在软件开发过程中，版本管理是至关重要的一环。传统的手动版本控制方式不仅效率低下，还容易出现人为错误。poetry-dynamic-versioning的出现，为开发者提供了一种简单、高效的动态版本管理解决方案。

使用该插件后，你只需在版本控制系统中创建标签（如git tag v0.1.0 -m "New release"），插件就会自动将版本号插入到相关文件中（如pyproject.toml或包含__version__的Python文件），并在Poetry命令（如poetry build）执行完毕后自动恢复文件状态，保持仓库的整洁。

快速安装指南

安装poetry-dynamic-versioning非常简单，根据你使用的Poetry版本选择以下方法之一：

方法一：Poetry 2.0.0+

在项目的pyproject.toml文件中添加以下配置，然后运行poetry install：

[tool.poetry.requires-plugins] poetry-dynamic-versioning = { version = ">=1.0.0,<2.0.0", extras = ["plugin"] }

方法二：旧版Poetry

• 大多数情况下：poetry self add "poetry-dynamic-versioning[plugin]"
• 如果使用Pipx安装Poetry：pipx inject poetry "poetry-dynamic-versioning[plugin]"

安装完成后，在项目中运行以下命令启用插件：

poetry dynamic-versioning enable

基础配置步骤

启用插件后，需要对项目进行简单配置。你可以手动编辑pyproject.toml文件，添加以下内容：

[project] dynamic = ["version"] [tool.poetry] version = "0.0.0" [tool.poetry-dynamic-versioning] enable = true

此外，为了确保与PEP 517构建前端的兼容性，还需要在pyproject.toml中添加构建系统配置：

[build-system] requires = ["poetry-core>=1.0.0", "poetry-dynamic-versioning>=1.0.0,<2.0.0"] build-backend = "poetry_dynamic_versioning.backend"

Poetry仍然要求tool.poetry.version字段存在，建议使用version = "0.0.0"作为标准占位符。

核心功能详解

动态版本生成

poetry-dynamic-versioning的核心功能是根据VCS标签动态生成版本号。默认情况下，插件会使用Dunamai库来解析版本控制历史，生成符合PEP 440标准的版本号。

你可以通过配置[tool.poetry-dynamic-versioning]部分来自定义版本生成规则，例如：

[tool.poetry-dynamic-versioning] enable = true vcs = "git" style = "semver" metadata = true dirty = true

文件内容替换

插件不仅会更新pyproject.toml中的版本号，还会自动替换项目中其他文件的版本占位符。默认情况下，它会查找并替换以下文件中的版本信息：

• *.py
• */__init__.py
• */__version__.py
• */_version.py

替换的模式包括：

• __version__ = "0.0.0"
• __version_tuple__ = (0, 0, 0)

你可以通过[tool.poetry-dynamic-versioning.substitution]配置来自定义替换规则和文件列表。

命令行模式

除了作为Poetry插件自动运行外，poetry-dynamic-versioning还提供了命令行模式，允许你按需执行版本更新：

# 使用Poetry插件命令 poetry dynamic-versioning # 或使用独立脚本 poetry-dynamic-versioning

这种模式会将动态版本应用到所有相关文件，并保留更改，方便你检查结果。

高级配置选项

poetry-dynamic-versioning提供了丰富的配置选项，让你可以根据项目需求定制版本管理策略。以下是一些常用的高级配置：

自定义版本格式

你可以使用format或format-jinja选项来自定义版本号的格式。例如：

[tool.poetry-dynamic-versioning] enable = true format = "v{base}+{distance}.{commit}"

或使用Jinja模板进行更复杂的格式化：

[tool.poetry-dynamic-versioning] enable = true format-jinja = "{% if distance == 0 %}{{ base }}{% else %}{{ base }}+{{ distance }}.{{ commit }}{% endif %}"

文件特定配置

通过[tool.poetry-dynamic-versioning.files]部分，你可以为特定文件设置个性化的处理方式。例如：

[tool.poetry-dynamic-versioning.files."package/_version.py"] persistent-substitution = true initial-content = """ # These version placeholders will be replaced later during substitution. __version__ = "0.0.0" __version_tuple__ = (0, 0, 0) """

环境变量覆盖

poetry-dynamic-versioning支持通过环境变量来临时覆盖版本设置，例如：

• POETRY_DYNAMIC_VERSIONING_BYPASS：直接指定静态版本号
• POETRY_DYNAMIC_VERSIONING_OVERRIDE：为特定包设置静态版本
• POETRY_DYNAMIC_VERSIONING_COMMANDS：指定在哪些Poetry命令中激活动态版本

常见问题解答

Q: 动态版本在poetry run或poetry shell中不可用怎么办？

A: 这是由于Poetry的设计限制，插件无法在这些命令后清理自身。你可以使用命令行模式手动生成版本文件，或在项目中添加一个简单的版本获取脚本。

Q: 如何处理Pip的隔离构建问题？

A: 较新版本的Pip默认支持树内构建，或可以使用--use-feature=in-tree-build选项。对于旧版本Pip，建议先导出依赖再构建：

poetry export -f requirements.txt -o requirements.txt --without-hashes pip wheel -r requirements.txt

Q: 如何在没有完整版本历史的情况下使用插件？

A: 插件支持从VCS归档中检测版本，具体请参考Dunamai文档。

总结

poetry-dynamic-versioning为Poetry用户提供了强大而灵活的动态版本管理能力，通过自动化版本号生成和文件替换，大大简化了版本管理流程。无论是小型个人项目还是大型团队协作，这款插件都能帮助你更专注于代码开发，而不是繁琐的版本管理。

现在就尝试在你的项目中集成poetry-dynamic-versioning，体验高效版本管理的乐趣吧！

【免费下载链接】poetry-dynamic-versioningPlugin for Poetry to enable dynamic versioning based on VCS tags项目地址: https://gitcode.com/gh_mirrors/po/poetry-dynamic-versioning