命名空间包是Python 3.3+引入的机制，允许多个无__init__.py的同名目录通过sys.path合并为一个逻辑包；它绕过__init__.py是因为PEP 420规定只要目录无该文件，Python就将其视为命名空间路径而非普通包。
什么是命名空间包，为什么它能绕过 __init__.py
命名空间包（namespace package）是 Python 3.3+ 引入的机制，允许将同一个包名分散在多个物理目录中，且这些目录**不需要**包含 __init__.py 文件。它不是“普通包”，而是一个逻辑容器，只负责聚合子模块路径。
关键判断：如果你看到 ImportError: attempted relative import with no known parent package 或者想把 mylib.utils 和 mylib.storage 分开维护在不同 Git 仓库或目录下，命名空间包就是正解——前提是所有相关目录都满足 PEP 420 规则。
确保 Python 版本和目录结构合规
命名空间包仅在 Python 3.3+ 默认启用（无需额外配置），但必须满足：所有同名父目录都不能有 __init__.py。哪怕其中任意一个目录里存在空的 __init__.py，Python 就会把它识别为普通包，整个命名空间链就断了。
- ✅ 正确结构（无任何
__init__.py）：project-a/mylib/utils.py<br>project-b/mylib/storage.py
，然后把project-a和project-b都加进sys.path或安装为可编辑包 - ❌ 错误结构：
project-a/mylib/__init__.py存在 → Python 认为mylib是普通包，project-b/mylib/...永远不会被扫描 - ⚠️ 注意：
mylib目录本身不能是 zip 或 egg —— 命名空间包只支持文件系统路径
让 Python 发现并合并多个命名空间路径
Python 通过 sys.path 顺序扫描每个路径下的同名目录。只要多个路径中都有 mylib/xxx.py，它们就会被自动合并到同一个 mylib 命名空间下。
立即学习“Python免费学习笔记（深入）”；
- 最常用方式：用
pip install -e /path/to/project-a和pip install -e /path/to/project-b（两个都带setup.py或pyproject.toml，且packages不显式声明mylib） - 手动调试时可临时加路径：
import sys<br>sys.path.insert(0, "/path/to/project-a")<br>sys.path.insert(0, "/path/to/project-b")
- 验证是否生效：
import mylib.utils<br>import mylib.storage<br>print(mylib.__path__) # 应输出类似 _NamespacePath(['.../project-a/mylib', '.../project-b/mylib'])
setup.py / pyproject.toml 怎么写才不破坏命名空间
如果用 setuptools 安装，绝不能在 setup(...) 中写 packages=['mylib'] 或 find_packages()（默认会找到 mylib 并当作普通包处理）。必须显式排除或使用命名空间专用声明。
- ✅ 推荐（pyproject.toml）：
[build-system]<br>requires = ["setuptools>=45", "wheel"]<br>build-backend = "setuptools.build_meta"<br><br>[project]<br>name = "mylib-utils"<br>...<br>[project.optional-dependencies]<br>full = ["mylib-storage"]
—— 每个子项目独立命名，不声明packages - ✅ 兼容写法（setup.py）：
from setuptools import setup<br>setup(<br> name="mylib-utils",<br> # 不写 packages=...<br> namespace_packages=['mylib'], # 已废弃但兼容；新项目建议不用<br>)
- ❌ 危险操作：
find_packages(include=['mylib*'])→ 会把mylib当作普通包注册，覆盖命名空间逻辑
真正的难点不在语法，而在于团队协作时没人敢删掉那个“看起来无害”的 __init__.py——它一旦出现，整个分布式包结构就静默失效，且错误往往延迟到某个子模块首次导入时才暴露。
