PocketPy快速入门指南：轻量级Python嵌入方案-优快云博客

本文链接：https://blog.youkuaiyun.com/gitblog_00192/article/details/148943774

PocketPy快速入门指南：轻量级Python嵌入方案

pocketpy Open Source Python Interpreter in 1 File for Game Scripting 项目地址: https://gitcode.com/gh_mirrors/po/pocketpy

项目概述

PocketPy是一个轻量级的Python实现，专为嵌入到C/C++应用程序而设计。它提供了完整的Python语法支持，同时保持了极小的代码体积和高效的执行性能。本文将详细介绍如何快速将PocketPy集成到您的项目中。

集成方式

单文件头方案

对于小型项目或快速原型开发，推荐使用单文件头方案：

获取pocketpy.h和pocketpy.c两个核心文件
在项目中包含头文件：#include "pocketpy.h"
将pocketpy.c加入编译列表

这种方案简单直接，适合快速集成测试。

CMake集成方案

对于大型项目或需要版本管理的场景，推荐使用CMake集成：

将PocketPy作为子模块添加到项目中
在CMakeLists.txt中添加以下配置：

add_subdirectory(pocketpy)
target_link_libraries(<your_target> pocketpy)

编译配置

为确保正确编译，必须设置以下编译选项：

C标准：必须启用C11标准(--std=c11)
MSVC特殊配置：
- 设置/utf-8编码选项
- 启用/experimental:c11atomics实验性特性
性能优化：发布版本应定义NDEBUG宏以获得最佳性能

预编译二进制文件

PocketPy提供了跨平台的预编译二进制文件，包含以下平台支持：

Android：arm64-v8a、armeabi-v7a、x86_64架构
iOS：静态库格式
Linux：x86_64架构动态库
Windows：x86_64架构DLL

示例代码解析

以下是一个完整的PocketPy使用示例，展示了核心功能：

#include "pocketpy.h"
#include <stdio.h>

// 自定义原生函数：整数加法
static bool int_add(int argc, py_Ref argv) {
    // 参数检查
    PY_CHECK_ARGC(2);
    PY_CHECK_ARG_TYPE(0, tp_int);
    PY_CHECK_ARG_TYPE(1, tp_int);
    
    // 获取参数值
    py_i64 a = py_toint(py_arg(0));
    py_i64 b = py_toint(py_arg(1));
    
    // 返回结果
    py_newint(py_retval(), a + b);
    return true;
}

int main() {
    // 初始化PocketPy运行时
    py_initialize();

    // 执行Python代码
    bool ok = py_exec("print('Hello world!')", "<string>", EXEC_MODE, NULL);
    if(!ok) goto __ERROR;

    // 创建Python列表[1, 2, 3]
    py_Ref r0 = py_getreg(0);
    py_newlistn(r0, 3);
    py_newint(py_list_getitem(r0, 0), 1);
    py_newint(py_list_getitem(r0, 1), 2);
    py_newint(py_list_getitem(r0, 2), 3);

    // 调用内置sum函数计算列表总和
    py_Ref f_sum = py_getbuiltin(py_name("sum"));
    py_push(f_sum);
    py_pushnil();
    py_push(r0);
    ok = py_vectorcall(1, 0);
    if(!ok) goto __ERROR;

    printf("列表总和: %d\n", (int)py_toint(py_retval()));  // 输出6

    // 将原生函数注册为Python全局变量
    py_newnativefunc(r0, int_add);
    py_setglobal(py_name("add"), r0);

    // 在Python中调用原生函数
    ok = py_exec("add(3, 7)", "<string>", EVAL_MODE, NULL);
    if(!ok) goto __ERROR;

    py_i64 res = py_toint(py_retval());
    printf("两数之和: %d\n", (int)res);  // 输出10

    // 清理资源
    py_finalize();
    return 0;

__ERROR:
    // 错误处理
    py_printexc();
    py_finalize();
    return 1;
}

关键API说明

初始化/销毁：
- py_initialize()：初始化运行时环境
- py_finalize()：释放资源
执行Python代码：
- py_exec()：执行Python代码字符串
- py_vectorcall()：调用Python函数
类型操作：
- py_newint()/py_toint()：整数创建与转换
- py_newlistn()：创建列表
- py_list_getitem()：获取列表元素
错误处理：
- py_printexc()：打印异常信息
- PY_CHECK_*宏：参数检查