pybind11：如何将pybind模块组织到命名空间包下

1. 调整目录结构 #

先搭建符合Python包规范的目录结构：

项目根目录/
├── setup.py
├── mypackage/
│   ├── __init__.py
│   └── src/
│       └── main.cpp

（cpp文件路径可按需调整，只要后续setup.py中指定正确路径即可）

2. 修改setup.py核心配置 #

关键是将扩展模块的名称改为完整的命名空间路径，同时配置包的相关参数：

from setuptools import setup, find_packages
from pybind11.setup_helpers import Pybind11Extension

ext_modules = [
    Pybind11Extension(
        # 改为带命名空间的模块名
        "mypackage.python_example",
        ["mypackage/src/main.cpp"],  # 对应你的cpp文件实际路径
        # 保留原有的编译参数
        extra_compile_args=["-O3"],
    ),
]

setup(
    name="mypackage",  # 包名设为你的命名空间名
    version="0.1.0",
    packages=find_packages(),  # 自动识别mypackage包
    ext_modules=ext_modules,
    # 其他元信息（作者、描述等）按需补充
)

3. 可选：配置__init__.py实现类似numpy的简化调用 #

如果想让用户像使用np.some_function那样直接调用模块内容，在mypackage/__init__.py中添加导入逻辑：

# 将子模块的内容导入到包的顶层命名空间
from .python_example import *

# 可选：明确列出对外暴露的函数/类，避免导入冗余内容
__all__ = ["your_function", "your_class"]

4. 安装与测试 #

执行安装命令：

pip install .

之后即可按预期方式导入使用：

# 方式1：直接导入子模块
import mypackage.python_example as pe
pe.your_function()

# 方式2：导入包并使用顶层暴露的内容（需配置__init__.py）
import mypackage as mp
mp.your_function()

核心注意点 #

• 扩展模块的名称必须遵循包名.子模块名格式，setuptools会自动将编译后的动态库安装到mypackage目录下，而非全局命名空间。
• 若不需要简化调用，__init__.py可以为空文件，此时必须通过mypackage.python_example的完整路径导入模块。
• 不要手动移动编译后的模块文件，完全依赖setup.py的配置控制安装路径。

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