同名模块与命名空间包：Python库扩展及可编辑安装兼容方案咨询

问题根源 #

你当前的核心包foobar-core把foobar作为常规包（带__init__.py），而组件包的foobar是命名空间包的一部分，两者在虚拟环境中（尤其是可编辑安装组件时）会因为sys.path路径优先级导致模块冲突，无法正常合并命名空间。

可行方案 #

方案1：统一使用PEP 420命名空间包（推荐） #

这是Python 3.3+的标准命名空间实现，无需额外依赖：

• 核心包foobar-core调整结构：删除foobar/__init__.py，将原有核心代码迁移到foobar/core/__init__.py及子模块中
• 若需兼容原有import foobar的使用习惯，可在核心包的setup.py中配置安装时生成foobar/__init__.py，内容如下做导入转发：

  from .core import *
  __all__ = [...]  # 列出核心功能的导出对象
  

• 组件包foobar-component-fizz保持foobar/components/fizz.py结构，foobar和foobar/components目录均不添加__init__.py（若需统一导出组件，可给components目录加__init__.py，比如from .fizz import FizzComponent）
• 可编辑安装组件包时，Python会自动合并sys.path中多个位置的foobar命名空间，核心包与组件包的子模块可正常导入（如import foobar.core、import foobar.components.fizz）

方案2：调整核心包结构，隔离核心功能 #

• 核心包foobar-core改为以foobar/core作为核心模块，其中foobar是无__init__.py的命名空间目录，core子目录带__init__.py存放核心代码
• 组件包维持foobar/components/fizz.py结构，components目录可按需添加__init__.py
• 此方案下，核心包与组件包的foobar均为命名空间包，无论常规安装还是可编辑安装，都不会出现路径冲突

方案3：兼容旧版本的pkg_resources命名空间包 #

若需支持Python 3.3之前的版本，可采用setuptools的命名空间机制：

• 核心包foobar/__init__.py添加命名空间声明：

  __import__('pkg_resources').declare_namespace(__name__)
  

• 组件包的foobar/__init__.py和foobar/components/__init__.py也添加相同声明
• 在所有包的setup.py中配置namespace_packages=['foobar', 'foobar.components']
• 注意：此方式依赖setuptools，且PEP 420已替代该方案，仅作兼容备选

关键注意事项 #

• 所有涉及foobar命名空间的包，必须统一命名空间实现方式，不能混合常规包与命名空间包
• 可编辑安装组件包时，使用pip install -e .即可，无需额外配置

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