命名空间包的本质是无__init__.py的同名目录聚合：Python 3.3+自动将多个不含__init__.py的同名目录合并为一个逻辑包，仅作路径聚合，不支持包级代码；需确保所有参与目录同名且无__init__.py，避免覆盖或误加__init__.py导致合并失败。
命名空间包的本质：没有 __init__.py 的包目录
命名空间包不是普通包，它不依赖 __init__.py 文件来声明自身为包。Python 在导入时，只要多个路径下存在同名目录（且都不含 __init__.py），就会把它们“拼接”成一个逻辑上的包。比如 mylib.utils 可能来自 /path/a/mylib/utils/ 和 /path/b/mylib/utils/ 两个物理位置——只要两者都**没有 __init__.py**，Python 就会合并它们的模块内容。
关键点在于：命名空间包本身不能定义任何代码（没有 __init__.py 就无法执行初始化逻辑），它的作用纯粹是“路径聚合”。所以你不能在命名空间包里写 __all__、设置包级变量或运行启动逻辑。
如何让多个目录参与同一个命名空间包
核心是确保所有参与目录满足两个条件：同名 + 无 __init__.py。实际分发时，常见做法是用 setuptools 声明为 namespace_packages（旧方式）或更推荐的 PEP 420 自动发现（默认启用，无需配置）。
- 如果你用的是 Python 3.3+（几乎所有人），只要目录结构对、没
__init__.py，就自动生效，不需要在setup.py里写namespace_packages=['mylib'] - 如果某个子目录（如
mylib/utils）需要被当作常规包（含初始化逻辑），它必须有__init__.py——但此时它不再是命名空间的一部分，而是“嵌套在命名空间下的普通包” - 安装多个分发包时，确保它们的
package_dir或源码布局最终映射到同一命名空间路径，例如两个 wheel 分别安装了mylib/feature_a/和mylib/feature_b/（均无__init__.py）
常见错误：导入失败或模块被覆盖
最常遇到的现象是 ImportError: cannot import name 'X' 或看似成功导入却用不到另一个目录里的模块。根本原因通常是：
立即学习“Python免费学习笔记（深入）”；
快速生成专业的 Python 脚本和应用代码。一键创建完整项目结构，支持CLI、API、爬虫、Bot、Django等多种项目类型，包含完整的项目结构、配置文件、依赖管理、测试、README和文档。
- 某个路径下误放了
__init__.py，导致该路径被识别为普通包，阻断了命名空间合并 - 两个分发包安装后，site-packages 中同名目录发生覆盖（比如都用了
mylib/作为顶层目录但未声明为命名空间），后安装的直接替换了前一个 - 使用
pip install -e .开发模式时，不同项目同时pip install -e到同一虚拟环境，但路径顺序导致只有第一个被扫描到（sys.path顺序决定优先级） - IDE（如 PyCharm）缓存了包结构，删掉
__init__.py后未刷新解释器路径，仍按旧逻辑解析
验证命名空间是否生效的实操方法
不要只靠 import 是否报错，要检查 Python 实际看到的路径：
import mylib print(mylib.__path__)
如果输出类似 _NamespacePath(['/path/to/a/mylib', '/path/to/b/mylib'])，说明命名空间已正确聚合；如果只显示单个路径或报 AttributeError: 'module' object has no attribute '__path__'，说明它被当成了普通模块或未识别为命名空间。
另外，运行 python -v -c "import mylib.utils" 可看到详细导入过程，确认哪些路径被尝试加载、是否跳过了无 __init__.py 的目录。
跨目录分发的关键不在“怎么写”，而在“怎么不写”：刻意省略 __init__.py、避免路径冲突、理解 sys.path 顺序的影响——这些细节比语法本身更容易决定成败。
