如何将Git分支名关联到Python Wheel？解决命名合规问题

一、利用Wheel内部元数据（推荐方案） #

Wheel作为标准归档格式，内部的METADATA文件支持自定义字段，完全可以用来存储Git分支信息，不会破坏文件名的合规性，也能完美解决分支名不符合命名规范的问题。

具体实现步骤： #

1. 在构建配置中注入自定义元数据

   • 若使用pyproject.toml（现代Python项目推荐配置），可以通过动态元数据字段添加分支信息：

     [project]
     name = "project_name"
     version = "0.1283453523+myusername"  # 保留你的时间戳版本格式
     dynamic = ["custom_metadata"]
     
     [tool.setuptools.dynamic]
     custom_metadata = ["Git-Branch"]
     
     [tool.setuptools.metadata.custom]
     Git-Branch = "your_branch_name"
     

   • 若使用传统setup.py，则通过metadata参数传递：

     from setuptools import setup
     
     setup(
         name="project_name",
         version="0.1283453523+myusername",
         metadata={
             "custom_metadata": {
                 "Git-Branch": "your_branch_name"
             }
         }
     )
     

   实际构建时，可通过Git命令动态获取当前分支名：git rev-parse --abbrev-ref HEAD，将结果注入到配置中（比如用脚本生成临时配置文件，或直接在构建脚本中传递参数）。

2. 验证元数据
   构建完成后，解压Wheel文件，查看project_name-0.xxxx+myusername.dist-info/METADATA，会看到新增的自定义字段：

   Git-Branch: feature/add-user-auth
   

3. 安装后快速查询分支信息
   包安装完成后，用pip命令即可查看元数据：

   pip show -f project_name | grep -A 10 "Metadata"
   # 或直接查看安装目录下的METADATA文件
   cat $(pip show project_name | grep Location | cut -d' ' -f2)/project_name-*.dist-info/METADATA
   

二、合规化分支名后嵌入版本后缀（可选） #

如果坚持要把分支名放到Wheel文件名中，需要先对分支名做合规化处理，符合PEP 440的版本规范：

1. 分支名转换规则

   • 将斜杠、连续连字符、空格等替换为单个下划线/点
   • 移除@、#、$等特殊字符
     示例：分支名feature/add-user--auth转换为feature.add_user.auth

2. 动态生成合规版本号
   在构建脚本中完成分支名处理和版本拼接：

   # 获取当前分支名
   BRANCH_NAME=$(git rev-parse --abbrev-ref HEAD)
   # 合规化处理
   SANITIZED_BRANCH=$(echo "$BRANCH_NAME" | sed -e 's/[^a-zA-Z0-9._-]/_/g' -e 's/--*/_/g')
   # 生成最终版本号
   VERSION="0.$(date +%s)+myusername.$SANITIZED_BRANCH"
   # 构建Wheel
   python -m build --wheel --no-isolation --version "$VERSION"
   

   生成的Wheel文件名类似project_name-0.1699999999+myusername.feature_add_user_auth-py3-none-any.whl，符合PEP 440规范，可被pip正常识别。

三、额外优化：关联Git提交哈希 #

为进一步提升可追溯性，除分支名外，还可将Git提交短哈希也加入元数据或版本后缀：

• 元数据方式：添加自定义字段Git-Commit-Hash: $(git rev-parse --short HEAD)
• 版本后缀方式：在合规分支名后拼接哈希，比如0.1699999999+myusername.feature_add_user_auth.abc123

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