不能手写绑定生成器，是因为Python C API对类型生命周期、引用计数、异常传播和对象模型映射有强约束；pybind11在class_、def()、return_value_policy等接口背后深度封装了元编程与RAII，生成器必须正确处理析构安全、智能指针语义、函数重载分发，并绕不开PyModule_Create2、PyType_Ready、PyCapsule_New/GetPointer、PyErr_SetString四大C API锚点，否则将导致segfault或内存泄漏。
为什么不能手写绑定生成器，而要理解 pybind11 的核心机制
直接写一个“自动导出 C++ 接口为 Python 模块”的绑定生成器，不是靠模板拼接或 AST 解析就能跑通的——Python C API 本身对类型生命周期、引用计数、异常传播、对象模型映射有强约束，pybind11 看似轻量，实则在 class_、def()、return_value_policy 这些接口背后做了大量元编程和 RAII 封装。你写的生成器若不处理：C++ 类析构时 Python 对象是否还活着、std::shared_ptr 和 std::unique_ptr 如何对应 Python 引用语义、重载函数如何按签名分发——生成的模块大概率会在调用时 segfault 或静默内存泄漏。
必须实现的最小运行时支撑层（绕不开的 4 个 C API 调用点）
任何绑定生成器最终都要落地到 Python C API，以下四个点是真正执行导出动作的“锚点”，生成器必须能插入或代理它们：
-
PyModule_Create2：创建模块对象，版本号必须匹配当前 Python 解释器（PY_MAJOR_VERSION和PY_MINOR_VERSION），否则ImportError: undefined symbol: PyModule_Create2 -
PyType_Ready：注册自定义类型前必须调用，否则TypeError: type 'X' is not ready and cannot be used -
PyCapsule_New+PyCapsule_GetPointer：用于在 Python 层安全传递原始 C++ 指针（比如this），避免裸指针被 GC 误回收 -
PyErr_SetString/PyErr_SetObject：C++ 异常（throw）必须转成 Python 异常，否则会直接 abort；且需调用PyErr_Fetch清理栈，否则后续调用全失败
如何让生成器识别并处理常见 C++ 类型（不是靠 string 替换）
简单正则替换 std::vector → list 是危险的：它无法区分 std::vector（应映射为只读视图）和 std::vector（可能需所有权转移）。真实方案依赖编译器前端或 Clang LibTooling 提取 AST：
- 用
clang++ -Xclang -ast-dump或libclang解析头文件，获取QualType和CanQualType，判断是否为模板特化、是否含 const/ref/&& 限定符 -
std::string默认映射为PyUnicodeObject*，但若函数返回const std::string&，生成器必须插入PyUnicode_FromStringAndSize(ptr, len)而非拷贝构造新字符串 - 对
std::shared_ptr，生成器需注入py::class_并设置> py::return_value_policy::reference_internal，否则每次调用都新建 Python 对象，破坏共享语义
生成器输出的 cpp 文件里，为什么必须带 PYBIND11_MODULE 宏展开逻辑
PYBIND11_MODULE(mymodule, m) 看似只是个宏，实际展开后包含三重关键行为：模块初始化函数注册、PyInit_mymodule 符号导出、以及模块对象作用域内 m 变量的生命周期绑定。如果你自己写生成器却只生成 PyInit_ 函数体而忽略宏中 static_assert 和 pybind11::module_ m(...) 初始化逻辑，会出现：
- Windows 下 DLL 导出失败：
undefined reference to `PyInit_mymodule'（符号名大小写/装饰问题） - Linux 下
import mymodule报SystemError: initialization of mymodule failed without raising an exception（因为缺少pybind11::detail::get_internals()初始化） - 即使加载成功，
m.def()调用也会 segfault——m是未初始化的空对象
真正可靠的生成器不会试图重写这个宏，而是复用 pybind11/detail/common.h 中已验证的展开逻辑，仅生成其内部 m.def(...) 和 m.class_<...>().def(...) 部分。
Python免费学习笔记（深入）：立即使用
在学习笔记中，你将探索 Python 的核心概念和高级技巧！
