为什么选择poetry-dynamic-versioning？5大优势助你提升开发效率

【免费下载链接】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设计的动态版本管理插件，能够基于Git、Mercurial等版本控制系统（VCS）的标签自动生成版本号，让开发者告别手动修改版本的繁琐流程。作为Poetry生态中不可或缺的工具，它通过自动化版本管理、灵活配置和无缝集成，帮助团队提升开发效率，确保版本信息的准确性和一致性。

1. 基于VCS标签的全自动版本生成 ✨

传统版本管理需要手动修改pyproject.toml或__version__变量，容易出现疏漏或冲突。而poetry-dynamic-versioning通过分析VCS标签（如git tag v1.2.3）自动生成版本号，彻底解放人工操作。

当你执行poetry build等命令时，插件会：

• 从Git/Mercurial等VCS中读取最新标签
• 自动计算距离上次标签的提交次数（如1.2.3.post5）
• 检测未提交修改并添加dirty标记（如1.2.3+dirty）
• 生成符合PEP 440规范的版本字符串

配置示例（pyproject.toml）：

[tool.poetry-dynamic-versioning] enable = true vcs = "git" # 支持git/mercurial/subversion等 style = "pep440" # 自动生成符合PEP 440规范的版本

2. 多文件版本同步，保持一致性 📝

项目中通常需要在多处维护版本信息（如__init__.py、_version.py或文档文件），手动同步容易出错。poetry-dynamic-versioning提供强大的版本替换功能，自动更新所有指定文件的版本占位符。

核心特性：

• 默认替换*.py文件中的__version__ = "0.0.0"和__version_tuple__ = (0, 0, 0)
• 支持自定义正则表达式匹配任意版本格式（如VERSION = "dev"）
• 可配置文件路径和替换规则，覆盖源码、文档等多种场景

配置示例：

[tool.poetry-dynamic-versioning.substitution] files = ["*.py", "docs/version.txt"] # 需要替换的文件 patterns = [ '''(^__version__\s*=\s*['"])[^'"]*(['"])''', # 匹配字符串格式版本 '''(^VERSION\s*=\s*['"])[^'"]*(['"])''', # 自定义格式 ]

3. 灵活的版本格式定制，满足多样化需求 🛠️

不同项目可能需要遵循不同的版本规范（如SemVer、PEP 440或自定义格式）。poetry-dynamic-versioning提供丰富的配置选项，支持从简单到复杂的版本格式定义。

主要定制方式：

• 预设风格：直接选择pep440、semver或pvp
• 自定义格式：通过format参数组合版本组件（如v{base}+{distance}.{commit}）
• Jinja模板：使用format-jinja实现复杂逻辑（如条件判断、版本递增）

Jinja模板示例：

[tool.poetry-dynamic-versioning] format-jinja = """ {% if distance == 0 %} {{ base }} # 无新提交时使用纯标签版本 {% else %} {{ base }}.dev{{ distance }}+{{ commit }} # 有新提交时添加开发标记 {% endif %} """

4. 与Poetry生态无缝集成，零侵入工作流 🔄

作为官方认证的Poetry插件，poetry-dynamic-versioning与Poetry命令体系深度融合，无需改变现有开发习惯。插件在执行poetry build、poetry publish等命令时自动激活，完成版本注入后自动还原文件修改，保持工作区清洁。

关键集成点：

• 支持Poetry 1.2.0+的插件系统，通过poetry self add poetry-dynamic-versioning[plugin]安装
• 兼容PEP 517构建后端，确保pip install .等命令正常工作
• 提供poetry dynamic-versioning命令，支持手动触发版本生成和文件更新

安装命令：

# 全局安装插件 poetry self add "poetry-dynamic-versioning[plugin]" # 项目初始化配置 poetry dynamic-versioning enable

5. 严格遵循规范，兼容主流工具链 📦

poetry-dynamic-versioning生成的版本号严格遵循PEP 440规范，确保与PyPI、setuptools等工具兼容。同时支持多种高级场景，满足复杂项目需求：

• 版本递增（bump）：自动递增补丁号（如从1.2.3变为1.2.4.dev5）
• 分支特定版本：通过tag-branch参数为不同分支生成独立版本
• 环境变量覆盖：使用POETRY_DYNAMIC_VERSIONING_BYPASS强制指定版本（适合CI/CD）
• 持久化替换：通过persistent-substitution保留部分文件的版本修改（适合可编辑安装）

快速开始使用指南 🚀

1. 安装插件：

poetry self add "poetry-dynamic-versioning[plugin]"

2. 初始化项目配置：

poetry dynamic-versioning enable

3. 创建VCS标签：

git tag v1.0.0 -m "Initial stable release"

4. 构建项目：

poetry build # 自动生成版本并注入到构建产物中

通过以上步骤，你的项目即可实现基于VCS标签的全自动版本管理，告别手动操作，专注核心开发！

总结

poetry-dynamic-versioning通过自动化版本生成、多文件同步、灵活定制、无缝集成和规范兼容五大优势，为Poetry项目提供了完整的动态版本解决方案。无论是小型库还是大型应用，都能显著减少版本管理的工作量，降低人为错误风险，让开发流程更高效、更可靠。

立即尝试将其集成到你的Poetry项目中，体验现代化版本管理的便捷与强大！

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