Cython入门教程 – 简书

Igor
Python评论19,325字数 5424阅读18分4秒阅读模式
Cython Logo

好好的为何要混合Python代码和C代码呢？原因主要有2个：

  • Python性能差，将一部分核心逻辑用C语言实现以提升整体性能
  • 希望Python能够调用一个C语言实现的系统，典型例子：OpenCV计算机视觉库

Python、C混合编程并不奇怪，Python官方就提供了Python/C API可以实现「用C语言编写Python库」，见官方文档，如果你点开看了你可能就会发现，这好难啊！Python/C API入门门槛太高，于是有了Cython的诞生。

Cython是基于Python/C API的，但学习Cython的时候完全不用了解Python/C API。

Cython入门教程 – 简书-图片1
Cython和Python/C API

第1章 Cython的安装和使用

1.1 安装

在Linux下通过pip install Cython安装。安装完毕后执行cython --version，如果输出了版本号即安装成功。

1.2 快速入门

本节完整代码见这里

安装完成后，我们创建一个Hello World项目，需要创建hello.pyx和setup.py两个文件。

  1. # file: hello.pyx
  2. def say_hello_to(name):
  3.     print("Hello %s!" % name)
  1. # file: setup.py
  2. from distutils.core import setup
  3. from Cython.Build import cythonize
  4.  
  5. setup(name='Hello world app',
  6.       ext_modules=cythonize("hello.pyx"))

这样编译项目：python setup.py build_ext --inplace，会生成hello.so以及一些没用的中间文件。
下面测试我们生成的hello.so能不能用：

  1. # coding: utf-8
  2. # 这个import会先找hello.py，找不到就会找hello.so
  3. import hello  # 导入了hello.so
  4.  
  5. hello.say_hello_to('张三')

1.3 Cython实现Python调用C库

完整代码见这里

如果我们已经有一个C语言的动态库、静态库，如何在Python中调用外部C库呢（本节以动态库为例）？

现有C库如下，是一个叫做cmath的库：

  1. // file: cmath.c
  2. #include "cmath.h"
  3. int add(int a, int b)
  4. {
  5.     return a + b;
  6. }
  1. // file: cmath.h
  2. int add(int a, int b);

下面将该cmath封装为Python库，为了防止名称冲突，命名为pymath：

  1. # file: pymath.pyx
  2. cdef extern from "cmath.h":
  3.     int add(int a, int b)
  4.  
  5. def pyadd(int a, int b):
  6.     return add(a, b)

然后还需要写setup.py，这里已经不想继续写了，本文主要用的是gcc手工编译方式，

1.4 手工gcc编译

本节完整代码见这里

本节介绍gcc这种比较原始的编译方式，是希望你能搞懂Cython如何运作。如果能掌握那么相信在日后的开发工作中各种编译、部署的问题都不太可能难倒你。

我们知道Ubuntu下Python是这样安装的：apt-get install python3，但你可能不知道有这个东西：apt-get install python3-dev。
python3-dev这个包安装的是Python的头文件，以Ubuntu 18.04为例，安装完成后你应该可以在/usr/include/python3.6/找到一些头文件。

看图1-1可以看到3种方式的对比：

  • 第一条线是用Python/C API，有2个哭脸，不但代码写起来烦人，编译构建也烦人，所以我们才用Cython取代Python/C API；
  • 第二条线是我们最常用的setup.py，有2个笑脸，Cython项目最常用的方式；
  • 第三条线有1个哭脸，也是本节要讲的，如何使用gcc这种传统的方式来编译Cython项目；
Cython入门教程 – 简书-图片2
图1-1 3种方式对比

主要步骤是：

  • 使用cython xxx.pyx生成xxx.c
  • 然后使用gcc -fPIC -shared -I/usr/include/python2.7/ xxx.c -o xxx.so来生成so文件
  • 要注意头文件版本，自己用的是python2的头文件还是python3的头文件

第2章 Cython封装C库基础

2.1 在Cython中调用C库函数

本节完整代码见这里

C语言有很多库函数，例如：

  • libc的atoi函数
  • math库的sin函数

这些库函数非常常用，所以Cython已经帮我们封装了，所以我们直接调用即可。
那么Cython到底帮我们封装了多少C库函数呢？你可以在这里找找。
如果你需要调用的函数Cython没有封装，那么你需要自己封装，会在2.2节介绍。

现在我们看下Cython如何调用这些封装好的C库函数：

  1. # file: demo.pyx
  2. from libc.math cimport sin
  3. from libc.stdlib cimport atof
  4.  
  5. def foo(char *s):
  6.     x = atof(s)
  7.     return sin(x)

测试一下可不可以用：

  1. # file: test.py
  2. import demo
  3. print(demo.foo("3.1415"))  # 答案约等于0

2.2 实现Python环境调用C库函数

本节完整代码见这里。

在2.1节我们已经看到Cython能够调用C函数，Cython中定义的函数能被Python调用，因此Cython就成为了Python调用C的“桥梁”，我们把这一过程叫做wrap，实现这一功能的Cython代码叫做wrapper，见图2-1。通常wrapper可以指一段代码、一个类，甚至也能泛指一类技术。

Cython入门教程 – 简书-图片3
图2-1 wrapper

就和C语言开发一样，Cython代码也需要：包含头文件、链接静态库/动态库。

对于这几个C结构体、函数：

  1. // file: queue.h
  2. typedef struct _Queue Queue;
  3. typedef void *QueueValue;
  4. struct _Queue {
  5.     QueueEntry *head;
  6.     QueueEntry *tail;
  7. };
  8. Queue *queue_new(void);
  9. void queue_free(Queue *queue);

希望在Cython中调用：

  1. # file: queue.pyx
  2. cdef extern from "queue.h":  # 包含头文件
  3.     ctypedef struct Queue:
  4.         pass
  5.     ctypedef void *QueueValue
  6.  
  7.     Queue *queue_new()
  8.     void queue_free(Queue *queue)
  9.  
  10. def foo():
  11.     # 虽然没有实际意义，但这段代码很自嗨，可以看到Cython中完全可以调用C函数
  12.     cdef Queue *q
  13.     q = queue_new()
  14.     queue_free(q)

上面代码看出来虽然Cython可以调用C，但作为wrapper还有一个功能是将其自然的封装给Python，所以还需要下面这段代码：

  1. cdef class PyQueue:
  2.     cdef Queue *_c_queue
  3.  
  4.     def __cinit__(self):
  5.         self._c_queue = queue_new()
  6.  
  7.     def __dealloc__(self):
  8.         if self._c_queue is not NULL:
  9.             queue_free(self._c_queue)

编译：

  1. # file: setup.py
  2. from distutils.core import setup, Extension
  3. from Cython.Build import cythonize
  4.  
  5. extension = Extension(
  6.     "queue",
  7.     ["queue.pyx"],
  8.     libraries=["cqueue"]  # 在这边声明需要链接的C库（libcqueue.so）
  9. )
  10.  
  11. setup(
  12.     ext_modules=cythonize([extension])
  13. )

这里只贴了创建、释放的封装。其它功能（如pop、push）见完整代码。

2.3 回调函数

本节完整代码见这里。

对于一些需要传入回调函数的接口，会造成调用、被调用关系的反转。在之前我们讨论的都是在Cython中调用C函数，然而回调函数使得问题变为如何让C调用Cython函数。例如现在希望封装一个这样的C函数：

  1. void traverse(int *arr, int len, void (*cb)(int)) {
  2.     for (int i = 0; i < len; i++) {
  3.         cb(arr[i]);
  4.     }
  5. }

为了实现回调的封装：

  • 首先需要在Cython中定义一个能被C语言调用的wrap_cb，这是容易的
  • 然后需要在Cython的wrap_cb中调用Python的回调函数（我们把它叫做app_cb），这步会比较难实现，因为C环境调用wrap_cb时无法将app_cb的信息传入

在图2-2展示的方案中，将app_cb存至全局变量，这样wrap_cb可以从全局变量取到app_cb。

Cython入门教程 – 简书-图片4
图2-2 回调函数的封装

2.4 异步回调

2.3节中提到的方案不适用于异步场景，见下文专门章节分析异步场景。

2.5 结构体的封装

本节完整代码见这里。

第3章 pxd文件

就像C语言有.c和.h文件，Cython有.pyx和.pxd文件，可以帮助更好的组织、管理代码，pxd也可以实现wrapper的复用。

3.1 名称冲突问题

本节完整代码见这里

在之前的例子中，我们把C函数的导入、Python wrapper的封装都放在了pyx文件中，这会导致一些符号名冲突。例如：

  1. cdef extern from "queue.h":
  2.     # 这是声明C语言中有一个名为Queue的结构体
  3.     ctypedef struct Queue:
  4.         pass
  5.  
  6. # 这是提供给Python用的类，我们其实也想起名叫做Queue，但C语言结构体也叫这个名字
  7. # 所以我们不得不把提供给Python的类名改为PyQueue
  8. cdef class PyQueue:
  9.     cdef Queue *_c_queue
  10.  
  11.     def __cinit__(self):
  12.         self._c_queue = ...

为了解决开发中遇到的这些问题，我们可以把声明放在pxd中，这样就多了一层命名空间，如下：

  1. # cqueue.pxd
  2. cdef extern from "queue.h":
  3.     ctypedef struct Queue:
  4.         pass

有了命名空间，在pyx中就不会产生符号名冲突了：

  1. # queue.pyx
  2. cimport cqueue
  3. cdef class Queue:
  4.     cdef cqueue.Queue *_c_queue
  5.  
  6.     def __cinit__(self):
  7.         self._c_queue = ...

3.2 Cython代码复用

第4章 异步和内存管理

C程序员手动管理内存，而Python得益于垃圾回收机制，程序员无需感知内存管理。

附录：Cython语法参考

Cython易用的原因是它的代码跟Python几乎一样，Cython的语法是Python的「超集」，即Python代码一定是Cython代码，而Cython代码不一定是Python代码。比起Python来说，Cython多了一些跟C语言相关的语法。

  1. # Python语法
  2. import math  # 导入math.py或math.so或math目录
  3. from math import add as myadd  # Python：导入math.py中的add符号，为避免名字冲突，重命名为myadd
  4. math.add(1, 2)  # 访问math中的add符号
  5. myadd(1, 2)
  6.  
  7. # 对应的Cython语法
  8. cimport math  # 导入math.pxd
  9. from math cimport add as myadd  # 导入math.pxd中的add符号，为避免名字冲突，重命名为myadd
  10. math.add(1, 2)  # 访问math中的add符号
  11. myadd(1, 2)
  1. # Python语法
  2. def foo(a, b):  # 定义foo函数
  3.     c = 0  # 创建Python的int对象
  4.     c = a + b
  5.     return c
  6.  
  7. # Cython语法
  8. cdef int foo(int a, int b):  # cdef是定义C语言函数，注意该函数不能被Python调用
  9.     cdef int c = 0  # 这是C语言的int变量
  10.     c = a + b
  11.     return c  # 返回C语言的int
  12.  
  13. # Cython语法
  14. cpdef int foo(int a, int b):  # cpdef定义的函数可以被Python调用
  15.     cdef int c = 0  # C语言的int变量
  16.     c = a + b
  17.  
  18.     # 返回的是Python的int对象
  19.     # Cython在这里隐式将C语言int变量转为了Python的int对象
  20.     # 因为变量c是基本类型，Cython帮忙转了，如果c是复杂的是不能直接return的
  21.     return c
  1. # Python语法
  2. class Person():
  3.     def __init__(self):  # 这是构造函数
  4.         pass
  5.  
  6. # Cython语法
  7. class Person():
  8.     def __init__(self):  # 和C语言相关的内存分配（如malloc）不能放在这里实现
  9.         pass
  10.  
  11.     def __cinit__(self):  # 和C语言相关的内存分配（如malloc）要放在这里实现 
  12.         ... = malloc();
  13.  
  14.     def __dealloc__(self):  # 和C语言相关的内存释放（如free）要放在这里实现 
  15.         free(...);

写在最后：完整介绍Cython是一个庞大的工程，本文只是介绍了Cython的皮毛，若有疑问欢迎交流。

 

来源： Cython入门教程 - 简书

文章末尾固定信息

历史上的今天
1 月
16
weinxin
我的微信
我的微信
一个码农、工程狮、集能量和智慧于一身的、DIY高手、小伙伴er很多的、80后奶爸。
 
Igor
  • 本文由 Igor 发表于 2020-01-1614:45:30
  • Cython
  • Python
vscode配置pyqt5全过程(最新最全)

加载中...

匿名

发表评论

匿名网友
:?: :razz: :sad: :evil: :!: :smile: :oops: :grin: :eek: :shock: :???: :cool: :lol: :mad: :twisted: :roll: :wink: :idea: :arrow: :neutral: :cry: :mrgreen:
确定

拖动滑块以完成验证
加载中...