Python Poetry如何在版本号中添加自定义标签？

核心思路：直接指定完整版本号 #

Poetry其实支持直接传入完整的自定义版本号，不用局限于prepatch/major这类预设命令。你可以直接执行：

poetry version 0.1.1a0+20240520

这条命令会直接修改pyproject.toml里的版本值，同时自动生成对应的Git标签（如果开启了标签功能）。

自动化实现方案 #

1. 脚本动态生成版本号

写个简单的shell脚本，就能根据需求自动拼接不同后缀的版本号，以下是几种常用场景：

生成带日期的版本

# 读取当前基础版本（从pyproject.toml获取）
BASE_VERSION=$(poetry version --short)
# 生成YYYYMMDD格式的日期后缀
DATE_SUFFIX=$(date +%Y%m%d)
# 拼接新版本
NEW_VERSION="${BASE_VERSION}a0+${DATE_SUFFIX}"
# 设置版本
poetry version "$NEW_VERSION"

生成带Git分支名的版本

BASE_VERSION=$(poetry version --short)
# 获取当前分支名，替换特殊字符（避免PEP 440不允许的字符）
BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD | tr '/' '-')
NEW_VERSION="${BASE_VERSION}a0+${BRANCH_NAME}"
poetry version "$NEW_VERSION"

生成带Jira任务号的版本

如果你的分支名包含Jira任务号（比如feature/PROJ-1234），可以直接提取：

BASE_VERSION=$(poetry version --short)
# 从分支名中匹配Jira任务号格式（如PROJ-XXXX）
JIRA_TASK=$(git rev-parse --abbrev-ref HEAD | grep -oE '[A-Z]+-[0-9]+')
NEW_VERSION="${BASE_VERSION}a0+${JIRA_TASK}"
poetry version "$NEW_VERSION"

2. 集成到工作流实现自动触发

把上面的脚本保存成update-version.sh，可以集成到以下场景自动执行：

• Git钩子：在pre-push钩子中加入脚本执行命令，每次推送分支前自动更新版本并打标签。
• CI/CD流程：在GitHub Actions、GitLab CI等构建流程中，触发分支构建时执行脚本，自动生成对应版本。

3. 可选：用插件简化（非必需）

如果不想写脚本，可以尝试poetry-dynamic-versioning插件，它支持根据Git信息自动生成版本号，但需要额外安装和配置。不过原生脚本方案更轻量，无需依赖第三方插件。

注意事项 #

• 确保生成的版本号符合PEP 440规范，你使用的0.1.1a0+xxx格式是合规的，+后面的本地标识符可以自由定义。
• 若需要自动生成Git标签，确认pyproject.toml中[tool.poetry]下的version已配置，执行poetry version时会自动创建标签（可通过poetry version --help查看参数细节）。

内容的提问来源于stack exchange，提问作者Selva