如何使用pybind11向已有Python子模块添加绑定方法？

这个需求完全可以实现，你之前的写法不生效是因为没有正确对接Python的模块导入系统，给临时导入的模块对象加属性不会同步到实际导入流程返回的模块实例上。

原有代码失效原因 #

你调用pybind11::module::import("my_module._internal")确实能拿到子模块的Python对象引用，但存在两个核心问题：

• 没有保证操作的是父模块my_module属性空间里实际挂载的_internal子模块对象，也没有同步更新sys.modules里的模块缓存，后续Python导入子模块时可能加载未修改的缓存版本、或是重新初始化模块覆盖你的修改。
• 没有控制加载顺序，如果C++绑定代码执行时，my_module._internal还没完成初始化挂载，你修改的只是一个临时的模块引用，后续正式导入子模块时不会保留你添加的绑定。

正确实现方式 #

第一步：编写pybind11绑定代码 #

不要直接导入子模块后修改，要在C++扩展的模块入口内，先获取顶层父模块，再判断子模块是否存在，追加绑定后同步到模块缓存：

#include <pybind11/pybind11.h>

namespace py = pybind11;

void test_func() {
    // 你的C++函数逻辑
}

PYBIND11_MODULE(_my_cpp_ext, m) {
    // _my_cpp_ext是你编译出的C++扩展模块名，可自定义
    // 先获取顶层my_module模块
    py::module_ top_mod = py::module_::import("my_module");
    py::module_ internal_mod;

    if (py::hasattr(top_mod, "_internal")) {
        // 子模块已存在（比如已经被纯Python代码导入），直接获取已有实例
        internal_mod = top_mod.attr("_internal");
    } else {
        // 子模块不存在则创建新的子模块
        internal_mod = top_mod.def_submodule("_internal");
        // 显式注册到sys.modules，让Python导入系统能识别到
        py::module_::import("sys").attr("modules")["my_module._internal"] = internal_mod;
    }

    // 给子模块添加C++绑定，这一步的修改会正常生效
    internal_mod.def("_test_func", &test_func, "Test function.");
}

第二步：控制模块加载顺序 #

在my_module的__init__.py最顶部先导入编译好的C++扩展，确保绑定注入逻辑在所有纯Python子模块导入前执行：

# my_module/__init__.py 最顶部
from . import _my_cpp_ext  # 先执行C++绑定注入

# 之后再导入其他模块，包括纯Python实现的_internal
from . import _internal

补充说明 #

• 这种实现方式支持C++绑定和_internal.py里的纯Python逻辑共存，两边定义的方法、属性只要不同名就不会互相覆盖。
• 如果你后续要给子模块加更多C++绑定，直接在internal_mod对象上调用def、def_class等接口即可，和普通pybind11绑定写法没有区别。

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