Python 包结构设计的最佳实践

python包名须全小写、用短横线分隔（PyPI发布时），导入模块名则须为合法标识符（字母/数字/下划线）；__init__.py应精简，避免隐式依赖；推荐src布局确保开发与运行路径一致；弃用setup.py，统一用pyproject.toml管理。

包名必须全小写且不带下划线

Python 包名在 import 语句中是标识符，受 PEP 8 明确约束：应全部小写，多个单词用短横线（-）分隔——但注意，**这仅适用于 PyPI 发布时的包名**；实际导入时用的模块名仍须是合法 Python 标识符，即只能含字母、数字和下划线，且不能以数字开头。

常见错误是把包名设为 my_utils 或 MyPackage，导致下游用户写 import my_utils 看似可行，但一旦发布到 PyPI，pip install my_utils 会被 PyPI 视为独立包，与 import my_utils 的命名空间脱节，引发版本混乱或安装覆盖。

实操建议：

• 本地开发包名用纯小写+下划线（如 myproject），对应目录名 myproject/
• PyPI 上注册的发行包名用短横线（如 myproject-cli），但其内部 setup.py 或 pyproject.toml 中的 name 字段必须与安装命令一致，而 packages 列表仍指向实际 Python 包名（["myproject"]）
• 避免包名与标准库冲突（如 json、http），导入时会静默覆盖，调试极难定位

__init__.py 不该是功能堆积区

很多人习惯在 __init__.py 里集中导入所有子模块内容（from .core import func_a; from .utils import helper），再统一暴露给上层。这看似方便用户写 import myproject; myproject.func_a()，但会带来隐式依赖、启动变慢、循环导入风险。

立即学习“Python免费学习笔记（深入）”；

典型现象是：改动一个深层工具函数，触发整个包重加载；或测试时只导入 myproject.utils，却因 __init__.py 拉入了数据库模块而意外连接 mysql。

实操建议：

• __init__.py 只做三件事：声明包属性（如 __version__）、设置 __all__（若需显式控制 from myproject import *）、轻量级别名（如 from .core import CoreClass as Client）
• 子模块功能按需导入，用户应明确写 from myproject.core import process_data，而非依赖顶层通配
• 若真需简化常用路径，可用 __getattr__ 延迟加载（Python 3.7+），避免启动时硬导入

src 目录布局比扁平结构更可靠

直接把 myproject/ 放在项目根目录下（即 setup.py 同级），会导致测试时 python test/test_main.py 可能意外导入本地未安装的 myproject，也可能因当前路径优先被 sys.path 加载而跳过已安装版本，造成行为不一致。

根本问题是：开发态（源码）和运行态（安装后）的模块解析路径不统一。

实操建议：

• 强制采用 src/ 布局：项目结构为 src/myproject/__init__.py，pyproject.toml 中配置 packages = [{include = "myproject", from = "src"}]
• 这样 pip install -e . 安装的是可复现的包路径，单元测试也必须通过 python -m pytest tests/ 运行（而非 python test_*.py），确保走的是已安装包路径
• CI 中加一条检查：python -c "import myproject; print(myproject.__file__)"，确认输出路径含 site-packages 而非项目内 src/

避免 setup.py 与 pyproject.toml 功能重叠

很多项目同时存在 setup.py 和 pyproject.toml，且两者都定义依赖、入口点或元数据。这会造成构建行为分裂：用 pip wheel . 读 pyproject.toml，但 python setup.py bdist_wheel 读 setup.py，结果生成不同轮子。

更隐蔽的问题是：某些 CI 工具（如旧版 tox）默认调用 setup.py，而本地开发用 pip install -e . 实际走的是 pyproject.toml，导致环境不一致。

实操建议：

• 彻底弃用 setup.py，除非你必须支持 Python setuptools 插件（如 build_ext）
• pyproject.toml 中用 [build-system] 明确指定构建后端（推荐 setuptools>=61.0），用 [project] 定义元数据，用 [project.optional-dependencies] 管理 dev/test 分组
• 入口点（如 CLI 命令）统一写在 [project.entry-points."console_scripts"]，不要在 setup.py 里重复写 entry_points

包结构不是静态模板，而是随团队规模、部署方式、测试策略动态调整的契约。最常被忽略的其实是「导入路径」和「安装路径」的分离时机——等 CI 报出 ModuleNotFoundError 再改，往往已污染多个环境。