Python包目录结构命名遇困：同名引发冗余导入，求改进方案及PEP规范

这确实是Python包结构设计里很容易踩的坑！我之前帮朋友排查过类似的问题，给你梳理几个实用的改进思路，还有对应的PEP规范依据：

一、具体改进方案 #

1. 采用src布局（推荐的现代做法） #

把源码放在src目录下，彻底区分项目根目录和包目录，结构大概是这样：

bucha-project/
├── src/
│   └── bucha/
│       ├── __init__.py
│       └── core.py  # 把Bucha类放在这里
├── pyproject.toml  # 或者setup.py/setup.cfg
└── README.md

然后在src/bucha/__init__.py里添加导出语句：

from .core import Bucha

这样用户安装后，就可以直接用简洁的导入方式：

from bucha import Bucha
# 或者
import bucha
my_instance = bucha.Bucha()

这种布局还能避免本地开发时不小心导入项目根目录的bucha文件夹，而是确保导入的是安装后的包。

2. 调整内部模块名，通过__init__.py导出 #

如果不想用src布局，也可以把内部的同名模块改成更具体的名字，比如core.py或main.py，结构如下：

bucha/
├── bucha/
│   ├── __init__.py
│   └── core.py  # 原bucha.py改名为core.py
├── pyproject.toml
└── README.md

同样在__init__.py里导入Bucha类，把它提升到包的级别，用户就能直接从bucha包导入。

3. 直接把主类放在__init__.py中 #

如果你的包核心就是这个Bucha类，没有太多其他子模块，完全可以把类的定义直接写在bucha/__init__.py里，结构简化成：

bucha/
├── bucha/
│   └── __init__.py  # 这里直接定义Bucha类
├── pyproject.toml
└── README.md

这种方式最简洁，用户导入时完全不需要关心内部结构。

二、相关PEP规范参考 #

• PEP 8：Python的基础命名规范，明确要求包名和模块名使用小写字母，尽量简短，避免不必要的下划线（除非能提升可读性），你的bucha包名是符合这个规范的。
• PEP 420：允许无__init__.py的命名空间包，但对于可安装的常规包，推荐保留__init__.py来控制对外导出的内容——这正是我们前面用__init__.py提升类的原因，让用户不用深入到子模块层级。
• PEP 621：现代Python包的配置规范，推荐配合src布局使用，能更清晰地分离项目配置和源码，减少命名冲突的概率。

为什么之前的结构会有冗余导入？ #

因为你把包名、内部模块名、类名都设成了近似的名称（包名小写bucha，模块名也是bucha），所以导入时必须穿过两层同名结构。通过上面的调整，我们把核心类提升到包的顶层，就消除了这种冗余。

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