13. 内嵌解释器

13. 内嵌解释器

虽然pybind11主要聚焦于使用C++扩展Python，反过来也是可以的，可以内嵌Python解释器到C++程序中。前面章节讲解的pybind11内容仍然适用。本节将介绍嵌入所需的一些额外内容。

13.1 准备开始

创建一个内嵌解释器的程序，可以在Cmake中添加pybind11::embed来支持。

cmake_minimum_required(VERSION 3.4)
project(example)
find_package(pybind11 REQUIRED)  # or `add_subdirectory(pybind11)`
add_executable(example main.cpp)
target_link_libraries(example PRIVATE pybind11::embed)

main.cpp的基本结构如下：

#include <pybind11/embed.h> // everything needed for embedding
namespace py = pybind11;
int main() {
    py::scoped_interpreter guard{}; // start the interpreter and keep it alive
    py::print("Hello, World!"); // use the Python API
}

需要在使用任意Python API前初始化解释器，包括pybind11 Python函数和类。RAII guard类scoped_interpreter可用来管理解释器的生命周期。在guard类销毁时，解释器将会关闭并占用的内存。必须在所有Python函数前调用它。

13.2 执行Python代码

在12.3.3节中，我们介绍了可以使用eval、exec和eval_file函数来执行Python表达式或语句。下面的例子展示了附带解释器来执行Python代码的流程：

#include <pybind11/embed.h>
namespace py = pybind11;
int main() {
    py::scoped_interpreter guard{};
    py::exec(R"(
        kwargs = dict(name="World", number=42)
        message = "Hello, {name}! The answer is {number}".format(**kwargs)
        print(message)
    )");
}

也可以使用pybind11 API来实现相同的功能（参考12章）。

#include <pybind11/embed.h>
namespace py = pybind11;
using namespace py::literals;
int main() {
    py::scoped_interpreter guard{};
    auto kwargs = py::dict("name"_a="World", "number"_a=42);
    auto message = "Hello, {name}! The answer is {number}"_s.format(**kwargs);
    py::print(message);
}

两种方法也可以混合使用：

#include <pybind11/embed.h>
#include <iostream>
namespace py = pybind11;
using namespace py::literals;
int main() {
    py::scoped_interpreter guard{};
    auto locals = py::dict("name"_a="World", "number"_a=42);
    py::exec(R"(
        message = "Hello, {name}! The answer is {number}".format(**locals())
    )", py::globals(), locals);
    auto message = locals["message"].cast<std::string>();
    std::cout << message;
}

12.3 导入模块

使用module_::import()可以导入Python模块。

py::module_ sys = py::module_::import("sys");
py::print(sys.attr("path"));

为方便起见，内嵌解释器时，会将当前工作路径包含到sys.path中。这样我们可以方便地导入本地Python文件。

"""calc.py located in the working directory"""
def add(i, j):
    return i + j

py::module_ calc = py::module_::import("calc");
py::object result = calc.attr("add")(1, 2);
int n = result.cast<int>();
assert(n == 3);

如果运行时源文件被修改（如被外部进程修改），可以使用module_::reload()重新导入模块。这在下面的场景中十分有用：有个应用程序要导入用户定义数据处理脚本，该脚本需要在用户修改后更新时。注意，这个函数不会递归地重新加载模块。

12.4 添加内嵌模块

使用宏PYBIND11_EMBEDDED_MODULE可以添加内嵌的二进制模块。这个定义需要放在全局作用域中。定义后，他们可以向其他模块一样导入。

#include <pybind11/embed.h>
namespace py = pybind11;
PYBIND11_EMBEDDED_MODULE(fast_calc, m) {
    // `m` is a `py::module_` which is used to bind functions and classes
    m.def("add", [](int i, int j) {
        return i + j;
    });
}
int main() {
    py::scoped_interpreter guard{};
    auto fast_calc = py::module_::import("fast_calc");
    auto result = fast_calc.attr("add")(1, 2).cast<int>();
    assert(result == 3);
}

Unlike extension modules where only a single binary module can be created, on the embedded side an unlimited number of modules can be added using multiple PYBIND11_EMBEDDED_MODULE definitions (as long as they have unique names).

These modules are added to Python’s list of builtins, so they can also be imported in pure Python files loaded by the interpreter. Everything interacts naturally:

"""py_module.py located in the working directory"""
import cpp_module
a = cpp_module.a
b = a + 1
#include <pybind11/embed.h>
namespace py = pybind11;
PYBIND11_EMBEDDED_MODULE(cpp_module, m) {
    m.attr("a") = 1;
}
int main() {
    py::scoped_interpreter guard{};
    auto py_module = py::module_::import("py_module");
    auto locals = py::dict("fmt"_a="{} + {} = {}", **py_module.attr("__dict__"));
    assert(locals["a"].cast<int>() == 1);
    assert(locals["b"].cast<int>() == 2);
    py::exec(R"(
        c = a + b
        message = fmt.format(a, b, c)
    )", py::globals(), locals);
    assert(locals["c"].cast<int>() == 3);
    assert(locals["message"].cast<std::string>() == "1 + 2 = 3");
}

12.5 解释器的生命周期

当 scoped_interpreter 销毁时，程序会自动关闭Python解释器。后面再创建一个新的示例会重启解释器。或者，我们也可以使用 initialize_interpreter / finalize_interpreter 这组函数在任意时刻直接设置解释器状态。

解释器重启后，pybind11创建的模块可以安全地重新初始化，但第三方扩展模块可能会有些问题。问题在于Python本身不能完全卸载扩展模块，并且会有一些解释器重启的警告。简而言之，由于Python引用循环或用户创建的全局数据，并非所有内存都可能被释放。具体细节可以查看CPython文档。

Warning

Creating two concurrent scoped_interpreter guards is a fatal error. So is calling initialize_interpreter for a second time after the interpreter has already been initialized.

Do not use the raw CPython API functions Py_Initialize and Py_Finalize as these do not properly handle the lifetime of pybind11’s internal data.