C++通过 Py_Initialize实现对Python的嵌入调用

利华汽修 · 發表於 2025-12-30 08:28:19

在现代软件开发中，性能（C++）与灵活性（Python）的结合是许多大型项目的首选方案。无论是游戏引擎（如 Unreal Engine）还是高性能计算工具，通过在 C++ 中嵌入 Python 脚本，可以让用户在不重新编译程序的情况下编写插件或逻辑。

本文将带你走进 Python C API 的世界，重点介绍如何通过 Py_Initialize 实现 C++ 对 Python 的嵌入调用。

为什么要嵌入 Python

脚本化：允许用户自定义逻辑。
快速原型：利用 Python 丰富的库（如 NumPy, SciPy）处理数据，而核心逻辑保持在 C++ 中。
逻辑分离：将频繁变动的业务逻辑放在脚本层，核心底层放在 C++ 层。

核心流程图

在深入代码之前，我们先看下 C++ 调用 Python 的标准生命周期：

第一步：环境配置

要在 C++ 中使用 Python API，你需要：

头文件：Python.h（位于 Python 安装目录的 include 文件夹）。

库文件：python3x.lib（Windows）或 libpython3x.so（Linux）。

注意：确保你的 C++ 编译位数（x64/x86）与 Python 安装版本一致，否则会报链接错误。

第二步：最简实现：Hello World

我们先从最简单的初始化和运行一段 Python 代码开始。

#include <Python.h>
#include <iostream>

int main() {
    // 1. 初始化 Python 解释器
    Py_Initialize();

    if (!Py_IsInitialized()) {
        std::cerr << "Python 初始化失败！" << std::endl;
        return -1;
    }

    // 2. 执行简单的 Python 语句
    PyRun_SimpleString("print('Hello from Python! I am embedded in C++.')");
    PyRun_SimpleString("import platform; print('Python Version:', platform.python_version())");

    // 3. 释放资源
    Py_Finalize();
    return 0;
}

第三步：进阶——调用 Python 函数并传递参数

在实际项目中，我们通常需要加载一个 .py 文件，并调用其中的特定函数。

1. 准备 Python 脚本 (script.py)

# script.py
def add(a, b):
    print(f"Python 收到参数: {a} 和 {b}")
    return a + b

2. C++ 调用代码

调用过程涉及 Python 对象的引用计数管理，这是最容易出错的地方。

#include <Python.h>
#include <iostream>

int main() {
    Py_Initialize();

    // 将当前路径加入 Python 的搜索路径，否则找不到 script.py
    PyRun_SimpleString("import sys; sys.path.append('.')");

    // 加载模块
    PyObject* pModule = PyImport_ImportModule("script");
    if (pModule) {
        // 获取函数对象
        PyObject* pFunc = PyObject_GetAttrString(pModule, "add");

        if (pFunc && PyCallable_Check(pFunc)) {
            // 创建参数元组 (3, 5)
            PyObject* pArgs = PyTuple_Pack(2, PyLong_FromLong(3), PyLong_FromLong(5));

            // 调用函数
            PyObject* pValue = PyObject_CallObject(pFunc, pArgs);

            if (pValue) {
                std::cout << "C++ 收到结果: " << PyLong_AsLong(pValue) << std::endl;
                Py_DECREF(pValue);
            }
            Py_DECREF(pArgs);
        }
        Py_XDECREF(pFunc);
        Py_DECREF(pModule);
    } else {
        PyErr_Print(); // 打印 Python 错误堆栈
    }

    Py_Finalize();
    return 0;
}

核心 API 详解

函数	功能
Py_Initialize()	启动 Python 解释器并加载基本模块。
PyRun_SimpleString()	执行单行 Python 代码，简单快捷，但无法获取返回值。
PyImport_ImportModule()	动态加载一个 .py 模块。
PyObject_GetAttrString()	从模块中获取属性（如函数、类）。
PyTuple_Pack()	将 C++ 数据打包成 Python 的元组，用于函数传参。
Py_DECREF()	减少引用计数。极其重要，否则会导致严重的内存泄漏。

避坑指南（经验总结）

路径问题：Python 解释器默认不搜索 C++ 可执行文件目录。务必使用 sys.path.append('.') 或设置 PYTHONPATH 环境变量。
Debug/Release 陷阱：在 Windows 上，如果你编译 C++ 为 Debug 模式，它会尝试寻找 python3x_d.lib。如果你的 Python 环境没有安装调试库，请确保 C++ 使用 Release 模式，或者手动修改宏定义。
引用计数：遵循“谁创建，谁负责”的原则。如果你通过 PyImport 或 PyObject_Get 获得了对象，不用时必须 Py_DECREF。
多线程 (GIL)：如果你的 C++ 程序是多线程的，且多个线程都要调用 Python，你需要处理 GIL (Global Interpreter Lock)。

总结

通过 Py_Initialize 嵌入 Python，为 C++ 程序打开了一扇通往无限库资源的大门。虽然 Python C API 的语法略显繁琐（尤其是内存管理），但它带来的灵活性是无与伦比的。

到此这篇关于C++通过 Py_Initialize实现对Python的嵌入调用的文章就介绍到这了,更多相关C++嵌入调用Python内容请搜索琼殿技术社区以前的文章或继续浏览下面的相关文章希望大家以后多多支持琼殿技术社区！

您可能感兴趣的文章:

Python使用grpc服务并与C++互相调用
使用Doxygen生成Python与C++ 的项目文档
Python中调用C++代码的方法总结
Python调用C++ DLL失败的根本原因和解决方案
python调用C/C++动态库的实践案例
Python调用C/C++函数库的多种方法与实践指南
Python获取C++中返回的char*字段的两种思路

[教程] C++通过 Py_Initialize实现对Python的嵌入调用

目录