Setuptools项目中关于模块命名规范的兼容性问题解析

在Python包管理工具Setuptools的最新开发中，发现了一个关于模块命名规范的兼容性问题。这个问题涉及到Python模块名称中是否允许使用连字符（-）的特殊情况，值得广大Python开发者关注。

问题背景

在Python生态中，模块名称通常使用下划线（_）作为单词分隔符。然而，某些项目出于用户体验考虑，会刻意使用连字符（-）命名模块。例如pip-run项目就采用了"pip-run"这样的模块名，目的是为了让用户能够更方便地通过python -m pip-run命令调用，避免输入更复杂的下划线字符。

技术冲突

当这些项目从传统的setup.cfg迁移到新的pyproject.toml配置格式时，遇到了验证错误。Setuptools的后端验证机制将模块名称中的连字符视为非法字符，这与Python解释器实际能够处理的情况产生了矛盾。

事实上，Python解释器本身完全支持执行带有连字符的模块。通过简单的测试就可以验证这一点：

mkdir foo-bar
touch foo-bar/__main__.py
python -m foo-bar

这个命令能够正常执行，证明Python运行时环境确实支持这种命名方式。

技术考量

从技术实现角度来看，这个限制主要来源于validate-pyproject项目中的格式验证规则。当前验证逻辑过于严格，将模块名称限制为传统的Python标识符格式（仅允许字母、数字和下划线）。

实际上，Python的runpy模块能够处理更广泛的模块名称，包括：

• 包含连字符的名称
• 包含Unicode字符的名称
• 包含空格的名称（虽然不推荐）

唯一的限制应该是避免使用路径分隔符（/或\）和点号（.），因为这些字符在模块导入系统中有特殊含义。

解决方案建议

对于Setuptools项目来说，可以考虑以下几种改进方向：

1. 放宽验证规则：至少允许连字符作为下划线的替代
2. 完全兼容Python实际行为：只禁止真正的非法字符（路径分隔符和点号）
3. 保持严格验证但提供明确文档：如果坚持严格验证，应该明确说明这种限制及其原因

从向后兼容性和用户体验角度考虑，第一种方案（允许连字符）可能是最合理的折中方案。这样既保持了基本的命名规范，又支持了现有的特殊用例。

对开发者的影响

这个问题的解决将直接影响以下几类开发者：

1. 已经使用连字符模块名的项目（需要确保迁移到pyproject.toml时的兼容性）
2. 工具链开发者（需要确保工具能够正确处理这种特殊情况）
3. 新项目设计者（在选择模块命名策略时有更多灵活性）

最佳实践建议

虽然技术上支持使用连字符命名模块，但从代码可维护性角度，我们仍然建议：

1. 优先使用传统的下划线命名法
2. 仅在确实需要优化命令行体验时使用连字符
3. 在项目文档中明确说明这种特殊命名的原因

随着Python打包生态的不断发展，这类边界情况的处理将变得越来越重要。开发者应当关注相关规范的更新，以确保项目的长期可维护性。