Python项目命名应使用短横线还是下划线？

Question

在Python项目开发中，关于项目目录和包命名应使用短横线（kebab-case）还是下划线（snake_case）常引发争议。根据PEP 517和PyPA官方建议，项目名称（如用于`setup.py`或`pyproject.toml`中的`name`字段）推荐使用小写字母并以短横线分隔（如 `my-awesome-project`），因为这符合PyPI包名规范，便于发布和安装。然而，Python模块和包的导入名称应使用下划线（如 `my_module`），以避免语法错误——文件名含短横线会导致无法通过 `import` 正确导入。因此，常见做法是：项目文件夹用短横线命名，而可导入的Python包使用下划线。这种不一致易造成混淆，如何统一管理项目结构与导入规范成为开发者常遇问题。

Answer 1

1. 命名规范的背景与核心冲突

在Python项目开发中，命名规范看似微小，实则深刻影响项目的可维护性、发布流程和团队协作。根据PyPA（Python Packaging Authority）和PEP 517等官方建议，项目名称（即pyproject.toml或setup.py中的name字段）应使用短横线命名法（kebab-case），例如：my-awesome-library。这种命名方式是PyPI包注册系统的标准，确保包名在命令行中可通过pip install my-awesome-library正确解析。

然而，Python语言本身对模块导入有语法限制：文件名若包含短横线（如my-module.py），将导致import my-module语法错误，因为Python解释器会将其解析为减法操作。因此，模块和包的命名必须使用下划线（snake_case），如my_module.py，才能通过import my_module正常导入。

命名类型	推荐格式	示例	用途	依据
项目名称（Project Name）	kebab-case	data-processing-tool	用于pyproject.toml中的name	PyPA, PEP 517
Python 包/模块名	snake_case	data_processing_tool	用于import语句	Python 语法规范

2. 典型问题场景与开发者困惑

• 新手开发者常误将项目目录名直接作为导入包名，导致ModuleNotFoundError。
• 团队协作中，成员对目录结构命名不统一，造成代码库混乱。
• 自动化构建脚本（如CI/CD）因路径与包名不一致而失败。
• 使用poetry或setuptools时，配置项packages与实际目录结构不匹配。

例如，一个项目命名为ml-pipeline，其内部若直接创建ml-pipeline/作为源码目录，则无法执行from ml-pipeline import core。必须将源码包命名为ml_pipeline，形成如下结构：

ml-pipeline/
├── pyproject.toml
├── README.md
└── src/
    └── ml_pipeline/
        ├── __init__.py
        └── core.py

3. 解决方案：分层命名策略与最佳实践

为解决项目名与包名的命名冲突，业界逐渐形成以下共识：

1. 项目根目录使用 kebab-case：便于发布到PyPI，符合工具链预期。
2. 源码包（source package）使用 snake_case：确保可导入性。
3. 采用src布局：将源码置于src/子目录下，隔离项目元数据与可导入模块。
4. 通过find_namespace_packages或packages显式声明包路径。

以pyproject.toml为例：

[build-system]
requires = ["setuptools>=45", "wheel"]
build-backend = "setuptools.build_meta"

[project]
name = "my-awesome-app"
version = "0.1.0"
description = "A sample Python project"

[tool.setuptools.packages.find]
where = ["src"]

配合目录结构：

my-awesome-app/
├── pyproject.toml
├── src/
│   └── my_awesome_app/
│       ├── __init__.py
│       └── main.py
└── tests/
    └── test_main.py

4. 工程化视角下的自动化与工具支持

现代Python项目管理工具已能有效缓解命名不一致问题。例如：

• Poetry：自动识别src目录并映射包名。
• Hatch：支持灵活的包发现机制。
• Cookiecutter：可通过模板预设标准结构。

graph TD A[项目初始化] --> B{选择工具} B --> C[Poetry] B --> D[Hatch] B --> E[Setuptools + src layout] C --> F[自动生成 kebab-case 项目名] D --> G[强制 snake_case 包名] E --> H[手动配置 packages 发现] F --> I[发布至 PyPI] G --> I H --> I

5. 高级考量：命名一致性与组织治理

对于大型组织或跨项目团队，需建立统一的命名规范文档，明确以下内容：

层级	命名规则	工具支持	检查方式
GitHub仓库名	kebab-case	CI 脚本校验	正则匹配 ^[a-z]+(-[a-z]+)*$
PyPI 包名	kebab-case	poetry build 验证	打包时自动检测
Python 包导入名	snake_case	mypy 或 flake8 插件	静态分析检查
模块文件名	snake_case	pre-commit hook	文件名正则校验

此外，可通过pre-commit钩子自动验证命名合规性：

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v4.4.0
    hooks:
      - id: check-yaml
      - id: debug-statements
      - id: name-tests-test
        args: [--filename-regex=^test_.*\.py$]