• 15.6 从C语言中调用Python代码
    • 问题
    • 解决方案
    • 讨论

    15.6 从C语言中调用Python代码

    问题

    你想在C中安全的执行某个Python调用并返回结果给C。例如,你想在C语言中使用某个Python函数作为一个回调。

    解决方案

    在C语言中调用Python非常简单,不过设计到一些小窍门。下面的C代码告诉你怎样安全的调用:

    1. #include <Python.h>
    2.  
    3. /* Execute func(x,y) in the Python interpreter. The
    4. arguments and return result of the function must
    5. be Python floats */
    6.  
    7. double call_func(PyObject *func, double x, double y) {
    8. PyObject *args;
    9. PyObject *kwargs;
    10. PyObject *result = 0;
    11. double retval;
    12.  
    13. /* Make sure we own the GIL */
    14. PyGILState_STATE state = PyGILState_Ensure();
    15.  
    16. /* Verify that func is a proper callable */
    17. if (!PyCallable_Check(func)) {
    18. fprintf(stderr,"call_func: expected a callable\n");
    19. goto fail;
    20. }
    21. /* Build arguments */
    22. args = Py_BuildValue("(dd)", x, y);
    23. kwargs = NULL;
    24.  
    25. /* Call the function */
    26. result = PyObject_Call(func, args, kwargs);
    27. Py_DECREF(args);
    28. Py_XDECREF(kwargs);
    29.  
    30. /* Check for Python exceptions (if any) */
    31. if (PyErr_Occurred()) {
    32. PyErr_Print();
    33. goto fail;
    34. }
    35.  
    36. /* Verify the result is a float object */
    37. if (!PyFloat_Check(result)) {
    38. fprintf(stderr,"call_func: callable didn't return a float\n");
    39. goto fail;
    40. }
    41.  
    42. /* Create the return value */
    43. retval = PyFloat_AsDouble(result);
    44. Py_DECREF(result);
    45.  
    46. /* Restore previous GIL state and return */
    47. PyGILState_Release(state);
    48. return retval;
    49.  
    50. fail:
    51. Py_XDECREF(result);
    52. PyGILState_Release(state);
    53. abort(); // Change to something more appropriate
    54. }

    要使用这个函数,你需要获取传递过来的某个已存在Python调用的引用。有很多种方法可以让你这样做,比如将一个可调用对象传给一个扩展模块或直接写C代码从已存在模块中提取出来。

    下面是一个简单例子用来掩饰从一个嵌入的Python解释器中调用一个函数:

    1. #include <Python.h>
    2.  
    3. /* Definition of call_func() same as above */
    4. ...
    5.  
    6. /* Load a symbol from a module */
    7. PyObject *import_name(const char *modname, const char *symbol) {
    8. PyObject *u_name, *module;
    9. u_name = PyUnicode_FromString(modname);
    10. module = PyImport_Import(u_name);
    11. Py_DECREF(u_name);
    12. return PyObject_GetAttrString(module, symbol);
    13. }
    14.  
    15. /* Simple embedding example */
    16. int main() {
    17. PyObject *pow_func;
    18. double x;
    19.  
    20. Py_Initialize();
    21. /* Get a reference to the math.pow function */
    22. pow_func = import_name("math","pow");
    23.  
    24. /* Call it using our call_func() code */
    25. for (x = 0.0; x < 10.0; x += 0.1) {
    26. printf("%0.2f%0.2f\n", x, call_func(pow_func,x,2.0));
    27. }
    28. /* Done */
    29. Py_DECREF(pow_func);
    30. Py_Finalize();
    31. return 0;
    32. }

    要构建例子代码,你需要编译C并将它链接到Python解释器。下面的Makefile可以教你怎样做(不过在你机器上面需要一些配置)。

    1. all::
    2. cc -g embed.c -I/usr/local/include/python3.3m \
    3. -L/usr/local/lib/python3.3/config-3.3m -lpython3.3m

    编译并运行会产生类似下面的输出:

    1. 0.00 0.00
    2. 0.10 0.01
    3. 0.20 0.04
    4. 0.30 0.09
    5. 0.40 0.16
    6. ...

    下面是一个稍微不同的例子,展示了一个扩展函数,它接受一个可调用对象和其他参数,并将它们传递给 call_func() 来做测试:

    1. /* Extension function for testing the C-Python callback */
    2. PyObject *py_call_func(PyObject *self, PyObject *args) {
    3. PyObject *func;
    4.  
    5. double x, y, result;
    6. if (!PyArg_ParseTuple(args,"Odd", &func,&x,&y)) {
    7. return NULL;
    8. }
    9. result = call_func(func, x, y);
    10. return Py_BuildValue("d", result);
    11. }

    使用这个扩展函数,你要像下面这样测试它:

    1. >>> import sample
    2. >>> def add(x,y):
    3. ... return x+y
    4. ...
    5. >>> sample.call_func(add,3,4)
    6. 7.0
    7. >>>

    讨论

    如果你在C语言中调用Python,要记住最重要的是C语言会是主体。也就是说,C语言负责构造参数、调用Python函数、检查异常、检查类型、提取返回值等。

    作为第一步,你必须先有一个表示你将要调用的Python可调用对象。这可以是一个函数、类、方法、内置方法或其他任意实现了 call() 操作的东西。为了确保是可调用的,可以像下面的代码这样利用 PyCallable_Check() 做检查:

    1. double call_func(PyObject *func, double x, double y) {
    2. ...
    3. /* Verify that func is a proper callable */
    4. if (!PyCallable_Check(func)) {
    5. fprintf(stderr,"call_func: expected a callable\n");
    6. goto fail;
    7. }
    8. ...

    在C代码里处理错误你需要格外的小心。一般来讲,你不能仅仅抛出一个Python异常。错误应该使用C代码方式来被处理。在这里,我们打算将对错误的控制传给一个叫 abort() 的错误处理器。它会结束掉整个程序,在真实环境下面你应该要处理的更加优雅些(返回一个状态码)。你要记住的是在这里C是主角,因此并没有跟抛出异常相对应的操作。错误处理是你在编程时必须要考虑的事情。

    调用一个函数相对来讲很简单——只需要使用 PyObject_Call() ,传一个可调用对象给它、一个参数元组和一个可选的关键字字典。要构建参数元组或字典,你可以使用 Py_BuildValue() ,如下:

    1. double call_func(PyObject *func, double x, double y) {
    2. PyObject *args;
    3. PyObject *kwargs;
    4.  
    5. ...
    6. /* Build arguments */
    7. args = Py_BuildValue("(dd)", x, y);
    8. kwargs = NULL;
    9.  
    10. /* Call the function */
    11. result = PyObject_Call(func, args, kwargs);
    12. Py_DECREF(args);
    13. Py_XDECREF(kwargs);
    14. ...

    如果没有关键字参数,你可以传递NULL。当你要调用函数时,需要确保使用了 Py_DECREF() 或者 Py_XDECREF() 清理参数。第二个函数相对安全点,因为它允许传递NULL指针(直接忽略它),这也是为什么我们使用它来清理可选的关键字参数。

    调用万Python函数之后,你必须检查是否有异常发生。PyErr_Occurred() 函数可被用来做这件事。对对于异常的处理就有点麻烦了,由于是用C语言写的,你没有像Python那么的异常机制。因此,你必须要设置一个异常状态码,打印异常信息或其他相应处理。在这里,我们选择了简单的 abort() 来处理。另外,传统C程序员可能会直接让程序奔溃。

    1. ...
    2. /* Check for Python exceptions (if any) */
    3. if (PyErr_Occurred()) {
    4. PyErr_Print();
    5. goto fail;
    6. }
    7. ...
    8. fail:
    9. PyGILState_Release(state);
    10. abort();

    从调用Python函数的返回值中提取信息通常要进行类型检查和提取值。要这样做的话,你必须使用Python对象层中的函数。在这里我们使用了 PyFloat_Check()PyFloat_AsDouble() 来检查和提取Python浮点数。

    最后一个问题是对于Python全局锁的管理。在C语言中访问Python的时候,你需要确保GIL被正确的获取和释放了。不然的话,可能会导致解释器返回错误数据或者直接奔溃。调用 PyGILState_Ensure()PyGILState_Release() 可以确保一切都能正常。

    1. double call_func(PyObject *func, double x, double y) {
    2. ...
    3. double retval;
    4.  
    5. /* Make sure we own the GIL */
    6. PyGILState_STATE state = PyGILState_Ensure();
    7. ...
    8. /* Code that uses Python C API functions */
    9. ...
    10. /* Restore previous GIL state and return */
    11. PyGILState_Release(state);
    12. return retval;
    13.  
    14. fail:
    15. PyGILState_Release(state);
    16. abort();
    17. }

    一旦返回,PyGILState_Ensure() 可以确保调用线程独占Python解释器。就算C代码运行于另外一个解释器不知道的线程也没事。这时候,C代码可以自由的使用任何它想要的Python C-API 函数。调用成功后,PyGILState_Release()被用来讲解释器恢复到原始状态。

    要注意的是每一个 PyGILState_Ensure()调用必须跟着一个匹配的 PyGILState_Release() 调用——即便有错误发生。在这里,我们使用一个 goto 语句看上去是个可怕的设计,但是实际上我们使用它来讲控制权转移给一个普通的exit块来执行相应的操作。在 fail: 标签后面的代码和Python的 fianl: 块的用途是一样的。

    如果你使用所有这些约定来编写C代码,包括对GIL的管理、异常检查和错误检查,你会发现从C语言中调用Python解释器是可靠的——就算再复杂的程序,用到了高级编程技巧比如多线程都没问题。

    原文:

    http://python3-cookbook.readthedocs.io/zh_CN/latest/c15/p06_calling_python_from_c.html