本文介绍如何通过 setuptools 和命名空间包（namespace packages）机制，将项目中嵌套的子目录结构（如 types/type1 和 types/type2/categories）分别安装为可导入的 Python 包，实现跨目录、层级清晰的模块引用。
本文介绍如何通过 `setuptools` 和命名空间包（namespace packages）机制，将项目中嵌套的子目录结构（如 `types/type1` 和 `types/type2/categories`）分别安装为可导入的 Python 包，实现跨目录、层级清晰的模块引用。
要在 root_dir 根目录下将 python/libraries/types/ 下的子目录作为独立、可安装的命名空间包（如 types.type1 和 types.type2.categories），关键在于正确配置 setup.py 并利用 find_namespace_packages + package_dir 机制，而非依赖传统的 __init__.py 链式声明。Python 的命名空间包允许不同物理路径共同构成同一个逻辑包名（如 types），从而支持灵活的模块拆分与组合。
✅ 正确的项目结构与安装策略
首先，确保你的 types 目录下不包含 __init__.py 文件（这是命名空间包的必要条件）。即：
root_dir/
└── python/
└── libraries/
└── types/ # ← 无 __init__.py！
├── type1/ # ← 无 __init__.py！
│ └── math/
│ └── math.py
└── type2/ # ← 无 __init__.py！
└── categories/ # ← 无 __init__.py！
└── category1/
├── module1/
│ └── module1.py
└── ...⚠️ 注意：若任意一级（如 types/, type1/, categories/）存在 __init__.py，Python 会将其识别为常规包，破坏命名空间语义，导致 types.type1 导入失败。
? 安装配置：两个独立的 setup.py
1. 在 root_dir/python/libraries/ 下创建 setup.py（用于 types.type1）
# root_dir/python/libraries/setup.py
from setuptools import setup, find_namespace_packages
setup(
name="types.type1",
version="0.1.0",
packages=find_namespace_packages(
where=".",
include=["type1.*"] # 匹配 type1 及其所有子包（如 type1.math）
),
package_dir={"": "."}, # 表示源码根目录是当前目录（即 libraries/）
python_requires=">=3.8",
)2. 在 root_dir/python/libraries/types/ 下创建 setup.py（用于 types.type2.categories）
# root_dir/python/libraries/types/setup.py
from setuptools import setup, find_namespace_packages
setup(
name="types.type2.categories",
version="0.1.0",
packages=find_namespace_packages(
where=".",
include=["type2.categories.*"]
),
package_dir={"": "."}, # 源码根目录是当前目录（即 types/）
install_requires=["types.type1"], # 显式声明对 type1 的依赖
python_requires=">=3.8",
)? 提示：find_namespace_packages(where=".", include=[...]) 是核心——它自动发现符合命名空间规范的包，无需手动列出路径；package_dir={"": "."} 告诉 setuptools “代码从当前目录开始解析”。
▶️ 安装方式（推荐开发模式）
在对应 setup.py 所在目录执行：
# 安装 types.type1（在 root_dir/python/libraries/ 下运行） cd root_dir/python/libraries pip install -e . # 安装 types.type2.categories（在 root_dir/python/libraries/types/ 下运行） cd root_dir/python/libraries/types pip install -e .
-e（editable mode）确保修改代码后无需重新安装即可生效，非常适合开发 Notebook 场景。
✅ 验证导入（在 notebook.ipynb 中）
安装成功后，在 Jupyter Notebook 中可直接使用你期望的导入语法：
# ✅ 正确导入（完全匹配问题需求） from types.type1.math.math import Vector from types.type2.categories.category1.module1.module1 import Calculator from types.type2.categories.category1.module2.module2 import Processor # 使用示例 v = Vector(1, 2, 3) calc = Calculator() proc = Processor()
? 验证技巧：在 notebook 中运行 import types; print(types.__path__)，应看到多个路径（来自不同安装位置），证明命名空间已正确合并。
? 注意事项与最佳实践
- 避免 __init__.py：所有参与命名空间的中间目录（types/, type1/, type2/, categories/）必须不含 __init__.py，否则会中断命名空间链。
- 包名需严格匹配路径：name="types.type1" 要求模块实际位于 types/type1/；include=["type1.*"] 必须与目录名一致。
- 依赖显式声明：若 type2.categories 依赖 type1 的功能，务必在 install_requires 中写明，确保环境一致性。
- 隔离安装环境：强烈建议使用虚拟环境（venv 或 conda）避免全局污染。
- 替代方案（现代推荐）：可考虑迁移到 pyproject.toml（PEP 621），但 setup.py 在当前场景下更直观可控。
通过以上配置，你就能以模块化、可复用、符合 Python 生态规范的方式，将深层嵌套的代码组织为逻辑清晰的命名空间包，并无缝集成到 Jupyter 工作流中。
