2022年 11月 6日

在python里调用C函数的三种方式

一个python项目快速开发完以后，常常针对瓶颈进行优化，其中一种方式就是对于性能至关重要的部分，使用C重写，这已经是一种最佳实践。如果整个项目完全使用C，开发效率就没有保障。python运行环境(CPython)是用C开发的，因此python与C结合起来很容易，而且方式多种多样。使用C重写了关键部分后，需要在python中调用，本文介绍三种最常用的调用C函数的方式，分别是c extension，Cython和ctypes。

举个例子，假设我们用C重写了add函数，它接受两个整数，计算他们的和并返回。

  1. #include <stdio.h>
  2.  
  3. int add(int a, int b)
  4. {
  5.     return a + b;
  6. }
  7.  
  8. int main()
  9. {
  10.     int a=1,b=1;
  11.     printf("%d\n", add(a,b));
  12. }

那么如何在python中调用add？

c extension

介绍

python标准库包含了很多使用C开发的扩展模块，比如对性能要求很高的json库。开发者同样可以使用C开发扩展，这是最原始也是最底层的扩展python的方式。

示例

demomodule.c

python的扩展模块由以下几部分组成：

  • Python.h
  • C函数
  • 接口函数（python代码调用的函数）到C函数的映射表
  • 初始化函数
  1. // pulls in the Python API 
  2. #include <Python.h>
  3.  
  4. // C function always has two arguments, conventionally named self and args
  5. // The args argument will be a pointer to a Python tuple object containing the arguments.
  6. // Each item of the tuple corresponds to an argument in the call’s argument list.
  7. static PyObject *
  8. demo_add(PyObject *self, PyObject *args)
  9. {
  10.     const int a, b;
  11.     // convert PyObject to C values
  12.     if (!PyArg_ParseTuple(args, "ii", &a, &b))
  13.         return NULL;
  14.     return Py_BuildValue("i", a+b);
  15. }
  16.  
  17. // module's method table
  18. static PyMethodDef DemoMethods[] = {
  19.     {"add", demo_add, METH_VARARGS, "Add two integers"},
  20.     {NULL, NULL, 0, NULL} 
  21. };
  22.  
  23. // module’s initialization function
  24. PyMODINIT_FUNC
  25. initdemo(void)
  26. {
  27.     (void)Py_InitModule("demo", DemoMethods);
  28. }

setup.py

编译扩展模块通常使用distutils或setuptools，它会自动调用gcc完成编译和链接。

  1. from distutils.core import setup, Extension
  2.  
  3. module1 = Extension('demo',
  4.                     sources = ['demomodule.c']
  5.                     )
  6.  
  7. setup (name = 'a demo extension module',
  8.        version = '1.0',
  9.        description = 'This is a demo package',
  10.        ext_modules = [module1])

执行

python setup.py build_ext --inplace

会在当前目录生成一个demo.so。一个python扩展模块其实就是一个共享库(.so)，它可以直接在python解释器中import。

--inplace表示将生成的扩展放到源码所在的目录，即当前目录，这样就可以直接import而不需要安装到site-packages目录。

测试

  1. >>> from demo import add
  2. >>> add(1,1)
  3. 2
  4. >>> add(1,2)
  5. 3
  6. >>> add(1)
  7. Traceback (most recent call last):
  8.   ...
  9. TypeError: function takes exactly 2 arguments (1 given)
  10. >>> add(1,'2')
  11. Traceback (most recent call last):
  12.   ...
  13. TypeError: an integer is required

Cython

介绍

Cython听起来像是一种语言，c与python的结合，这么说其实没有错。python是一种动态类型的解释型语言，执行效率低，Cython在python的基础上增加了可选的静态类型申明的语法，代码在使用前先被转换成优化过的C代码，然后编译成python扩展库，大大提升了执行效率。因此从语言的角度来讲，Cython是python的超集，即扩展了的python。

注意不要和CPython混淆，CPython是用c实现的python解释器，由官方提供，我们平时使用的python就是CPython。另外，pypy是python自己实现的python解释器。Cython是cpython标准库的一部分，不需要额外安装。

用官网的一句话介绍Cython的作用：

extending the CPython interpreter with fast binary modules, and interfacing Python code with external C libraries.

简单的说，Cython的两个主要作用是：

  1. 将python代码编译成二进制的扩展模块，以获得加速；同时可以在python中使用类型声明，进一步提升性能；这就意味着可以使用python代替c编写python扩展
  2. 在python代码里调用外部的c库

示例

现在使用Cython重新实现上面的例子——编写C函数的包装器。

最终的目录结构如下

  1. .
  2. ├── add_wrapper.c
  3. ├── add_wrapper.pyx
  4. ├── add_wrapper.so
  5. ├── build
  6. │   └── temp.linux-x86_64-2.7
  7. │       └── add_wrapper.o
  8. ├── libadd.a
  9. ├── libadd.c
  10. ├── libadd.h
  11. ├── libadd.o
  12. └── setup.py

编译C程序

libadd.h

int add(int a, int b);

libadd.c

  1. int add(int a, int b)
  2. {
  3.     return a + b;
  4. }

一般都是通过python调用动态链接库，需要将生成的库文件(.so)安装到标准路径下（比如/usr/lib)下，链接和运行的时候才能找到该文件，为了方便这里以静态链接库为例。

首先将c文件编译成静态链接库：

  1. gcc -c libadd.c
  2. ar rcs libadd.a libadd.o

第一步会在当前目录下生成libadd.o，第二步创建静态链接库libadd.a。

使用Cython包装C函数

使用Cython调用c函数很简单，只需要在Cython中声明函数的签名，然后编译的时候正确地链接外部的动态或静态库。

下面就是一个add函数的python包装器： add_wrapper.pyx

  1. cdef extern from "libadd.h":
  2.     cpdef int add(int a, int b)

第一行表示引入头文件libadd.h。第二行声明该头文件中的add函数，直接从libadd.h拷贝过来即可，此时只有在Cython模块内部能调用该C函数，还需要在前面加cpdef声明，表示暴露出接口给python调用。

编译Cython代码

Cython是需要编译成二进制模块才能使用的，编译过程包含两步：

  1. Cython将Cython文件(.pyx)编译成c代码(.c)
  2. gcc将c代码编译成共享库(.so)

怎么编译呢？最常用的方式是编写一个setup.py文件：

  1. from distutils.core import setup, Extension
  2. from Cython.Build import Cythonize
  3.  
  4. ext_modules=[
  5.     Extension("add_wrapper",
  6.               sources=["add_wrapper.pyx"],
  7.               extra_objects=['libadd.a']
  8.     )
  9. ]
  10.  
  11. setup(
  12.   name = 'wrapper for libadd',
  13.   ext_modules = Cythonize(ext_modules),
  14. )

extra_objects表示需要链接的静态库文件，也可以替换成libraries=["add"],library_dirs=["."]，连接器会自动搜索libadd.so和libadd.a，动态链接库优先。

执行

python setup.py build_ext --inplace

在当前目录下会生成add_wrapper.c和add_wrapper.so，add_wrapper.c是第一步编译生成的中间文件，内容比较长。add_wrapper.so是最终的python二进制模块，将它放到PYTHONPATH的某个路径下，就可以直接import。

如果需要重新build，你可能需要加上--force选项，否则可能不会生效。

测试

  1. >>> from add_wrapper import add
  2. >>> add(1,1)
  3. 2
  4. >>> add(2,3)
  5. 5
  6. >>> add(-1,1)
  7. 0
  8. >>> add(1,False)                                                                                                  
  9. 1
  10. >>> add(1)
  11. Traceback (most recent call last):
  12.   ...
  13. TypeError: wrap() takes exactly 2 positional arguments (1 given)
  14. >>>
  15. >>> add(1,'1')
  16. Traceback (most recent call last):
  17.   ...
  18. TypeError: an integer is required

由此可见，Cython会自动检查参数类型并完成python对象到C类型的转换。

ctypes

介绍

ctypes的主要作用就是在python中调用C动态链接库（shared library）中的函数。

示例

编译成动态链接库

libadd.c

  1. int add(int a, int b)
  2. {
  3.     return a + b;
  4. }

gcc -shared -o libadd.so libadd.c

加载共享库

使用CDLL动态加载共享库，一个共享库对应一个cdll对象。调用cdll的LoadLibrary()方法或直接调用CDLL的构造函数创建一个CDLL对象。

  1. >>> from ctypes import *
  2. >>> mylib = CDLL('/home/yanxurui/test/keepcoding/python/extension/ctypes/libadd.so')

第二行的CDLL等价于cdll.LoadLibrary。

如果共享库不在标准路径/usr/lib下则需要使用完整的路径。 ctypes提供了find_library用来找到共享库的位置，但是find_library会查找/usr/local/lib，因此搜索成功不代表也能加载成功。有人也反映了这个bug：

CDLL does not use the same paths as find_library and thus you can find a library, but you can’t necessarily use it.

调用共享库里的函数

通过访问dll对象的属性来调用相应的函数，就像调用python的函数对象一样：

  1. >>> mylib.add
  2. <_FuncPtr object at 0x7ff6864b7bb0>
  3. >>> add = mylib.add
  4. >>> add(1,2)
  5. 3
  6. >>> add()
  7. 1
  8. >>> add(1)
  9. -2044290911
  10. >>> add(1,'a')                                                                                                    
  11. -2042137139

指定函数类型

ctypes并不会校验参数的数量和类型，通过设置函数的argtypes的属性可以指定函数参数的类型：

  1. >>> add.argtypes = [c_int, c_int]
  2. >>> add(1, 2)
  3. 3
  4. >>> add(1)
  5. Traceback (most recent call last):
  6.   ...
  7. TypeError: this function takes at least 2 arguments (1 given)
  8. >>> add(1, '2')
  9. Traceback (most recent call last):
  10.   ...
  11. ctypes.ArgumentError: argument 2: <type 'exceptions.TypeError'>: wrong type

另外，原生的python类型中只允许传入None, 整数, 字符串作为函数的参数。如果需要传递其他的类型，则需要使用ctypes定义的类型，比如c_double表示double。

benchmark

从上面看出，c扩展虽然复杂，但更接地气，性能必然也是最好的，而Cython和ctypes开发效率奇高。

调用C库的一个主要目的是优化性能，因此我们更关心三种方式对性能的影响。 下面通过一个简单的benchmark来比较，即使10000000次加法操作也很快，很难看出调用C函数对性能带来的提升，但这无所谓，因为我们的主要目的是对比不同调用方式在调用共享库时的性能开销。

测试的代码如下，由于模块名以及import的方式不同，所以每次测试需要稍微修改一下注释的地方。

  1. from time import time
  2. # c ext
  3. # from demo import add
  4.  
  5. # Cython
  6. # from add_wrapper import add
  7.  
  8. # ctypes
  9. # mylib = CDLL('/home/yanxurui/test/keepcoding/python/extension/ctypes/libadd.so')
  10. # add = mylib.add
  11. # add.argtypes = [c_int, c_int]
  12.  
  13. # python
  14. # def add(a,b):
  15. #    return a+b
  16.  
  17. s=time()
  18. for i in range(10000000):
  19.     r = add(i, i)
  20. print(time()-s)

10000000 loops, best of 3:

method cost(s)
c ext 2.522
Cython 1.723
ctypes 8.896
python 1.879

测试的结果让人惊讶：

  1. 纯python比c扩展快？
  2. Cython的调用开销居然比C模块还低，这个是为何？？？
  3. 使用ctypes调用C库居然比纯python慢这么多

对于这个测试的结果，我无法盲目的相信，还需要进一步的探究。

总结

如果已经有一个现成的库，我会选择使用Cython或ctypes作为包装器，如果还需要考虑性能的话，当然就是Cython了。 如果需要从零开始开发一个功能模块，并且对性能要求极严，我会编写C扩展。