2023年Setuptools包命名：用连字符还是下划线？

首先得搞清楚两个核心概念，别搞混：

• 模块/包名：就是你代码里import的那个名字，比如import abc_def里的abc_def。
• 分发版名称：就是PyPI上显示的名字、生成的whl包名，比如abc-def-0.1.0-py310.whl里的abc-def。

2023年的明确规范和实践 #

1. 模块名必须用下划线
   Python的标识符规则不允许用连字符，连字符会被当成减号，所以你的代码目录、包文件夹名必须用下划线（比如abc_def），不然根本没法正常导入。Setuptools警告的就是这个——别把连字符用在模块/包的实际目录和导入名里。

2. 分发版名称推荐用连字符
   PyPI的命名规范里，连字符是标准的分隔符，用户搜索和安装时更习惯这种写法。而且pip和setuptools会自动处理下划线和连字符的等价转换：你用pip install abc-def和pip install abc_def效果完全一样，工具会自动把这俩当成同一个包。

你遇到的情况是正常的 #

你把模块名改成下划线后，执行pip install -e .时工具自动把下划线转成连字符生成whl包，这是工具的正常兼容行为，完全符合规范，不用慌。

总结实践方案 #

• 代码里的模块/包目录、导入名：统一用下划线（比如abc_def），保证语法合法。
• pyproject.toml里的name字段：写连字符（比如abc-def）就行，要是你写了下划线，工具也会自动转成连字符生成包，两种写法都没问题。
• 不用纠结转换的问题，这是工具为了兼顾Python语法和PyPI命名习惯做的兼容，属于正常操作。

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