PyPi项目维护指南：解决库名与wheel文件命名规范冲突问题

背景概述

在Python生态系统中，PyPi作为核心的软件包仓库，其命名规范对项目发布具有强制约束力。近期部分项目（如msci.sdk）收到PyPi的弃用通知，主要问题在于wheel文件名与项目名称的合规性冲突。这反映了PyPi对PEP 427规范执行的严格化趋势。

问题本质

根本矛盾点在于：

1. 历史命名习惯：开发者习惯使用点分式命名（如msci.sdk）
2. PyPi新规要求：wheel文件名必须使用下划线格式（如msci_sdk）

这种冲突会导致两种后果：

• 旧版本工具生成的wheel文件被标记为"不合规"
• 直接修改项目名会导致用户安装命令变更（pip install msci_sdk替代原命令）

技术解决方案

通过实际案例验证，推荐采用以下技术路线：

方案一：构建工具升级（推荐）

1. 升级核心工具链：
   • wheel包升级至最新版（≥0.40.0）
   • setuptools同步更新
2. 保持项目元数据不变：
   • setup.py中仍可声明name="msci.sdk"
3. 构建命令不变：

   python setup.py bdist_wheel
   

该方案优势：

• 用户侧无感知（保持原安装命令）
• 自动生成合规的wheel文件名
• 符合PyPi长期规范要求

方案二：项目名改造（备选）

1. 修改项目元数据：

   name = "msci_sdk"
   

2. 添加兼容性声明：

   package_dir = {
       'msci.sdk': 'msci_sdk',
   }
   

注意事项：

• 需要大版本号升级（语义化版本控制）
• 需在文档中明确说明变更
• 可能影响依赖该包的其它项目

深度技术解析

wheel文件命名规范的核心约束来自PEP 427的"Canonical wheel names"定义：

• 项目名中的点(.)必须转换为下划线(_)
• 构建标签(build tag)需符合平台规范
• 文件扩展名必须为.whl

现代构建工具（setuptools≥60.0）已内置该转换逻辑，这正是升级工具链能解决问题的根本原因。

最佳实践建议

1. 定期更新构建工具链（至少每年升级一次）
2. 在CI流程中添加wheel合规性检查：

   check-wheel-contents dist/*.whl
   

3. 对于企业级项目，建议建立内部PyPi镜像进行预验证

总结

PyPi的规范演进是Python生态系统健康发展的重要保障。通过及时升级工具链，开发者既能满足平台要求，又能保持对终端用户的兼容性。建议所有维护者将构建工具更新纳入常规维护流程，避免类似合规性问题。