Cython入门教程

Cython入门教程_第1张图片
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入门教程_第2张图片
Cython和Python/C API

第1章 Cython的安装和使用

1.1 安装

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

1.2 快速入门

本节完整代码见这里

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

# file: hello.pyx
def say_hello_to(name):
    print("Hello %s!" % name)
# file: setup.py
from distutils.core import setup
from Cython.Build import cythonize

setup(name='Hello world app',
      ext_modules=cythonize("hello.pyx"))

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

# coding: utf-8
# 这个import会先找hello.py,找不到就会找hello.so
import hello  # 导入了hello.so

hello.say_hello_to('张三')

1.3 Cython实现Python调用C库

完整代码见这里

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

现有C库如下,是一个叫做cmath的库:

// file: cmath.c
#include "cmath.h"
int add(int a, int b)
{
    return a + b;
}
// file: cmath.h
int add(int a, int b);

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

# file: pymath.pyx
cdef extern from "cmath.h":
    int add(int a, int b)

def pyadd(int a, int b):
    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入门教程_第3张图片
图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库函数:

# file: demo.pyx
from libc.math cimport sin
from libc.stdlib cimport atof

def foo(char *s):
    x = atof(s)
    return sin(x)

测试一下可不可以用:

# file: test.py
import demo
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入门教程_第4张图片
图2-1 wrapper

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

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

// file: queue.h
typedef struct _Queue Queue;
typedef void *QueueValue;
struct _Queue {
    QueueEntry *head;
    QueueEntry *tail;
};
Queue *queue_new(void);
void queue_free(Queue *queue);

希望在Cython中调用:

# file: queue.pyx
cdef extern from "queue.h":  # 包含头文件
    ctypedef struct Queue:
        pass
    ctypedef void *QueueValue

    Queue *queue_new()
    void queue_free(Queue *queue)

def foo():
    # 虽然没有实际意义,但这段代码很自嗨,可以看到Cython中完全可以调用C函数
    cdef Queue *q
    q = queue_new()
    queue_free(q)

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

cdef class PyQueue:
    cdef Queue *_c_queue

    def __cinit__(self):
        self._c_queue = queue_new()

    def __dealloc__(self):
        if self._c_queue is not NULL:
            queue_free(self._c_queue)

编译:

# file: setup.py
from distutils.core import setup, Extension
from Cython.Build import cythonize

extension = Extension(
    "queue",
    ["queue.pyx"],
    libraries=["cqueue"]  # 在这边声明需要链接的C库(libcqueue.so)
)

setup(
    ext_modules=cythonize([extension])
)

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

2.3 回调函数

本节完整代码见这里。

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

void traverse(int *arr, int len, void (*cb)(int)) {
    for (int i = 0; i < len; i++) {
        cb(arr[i]);
    }
}

为了实现回调的封装:

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

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

Cython入门教程_第5张图片
图2-2 回调函数的封装

2.4 异步回调

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

2.5 结构体的封装

本节完整代码见这里。

第3章 pxd文件

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

3.1 名称冲突问题

本节完整代码见这里

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

cdef extern from "queue.h":
    # 这是声明C语言中有一个名为Queue的结构体
    ctypedef struct Queue:
        pass

# 这是提供给Python用的类,我们其实也想起名叫做Queue,但C语言结构体也叫这个名字
# 所以我们不得不把提供给Python的类名改为PyQueue
cdef class PyQueue:
    cdef Queue *_c_queue

    def __cinit__(self):
        self._c_queue = ...

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

# cqueue.pxd
cdef extern from "queue.h":
    ctypedef struct Queue:
        pass

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

# queue.pyx
cimport cqueue
cdef class Queue:
    cdef cqueue.Queue *_c_queue

    def __cinit__(self):
        self._c_queue = ...

3.2 Cython代码复用

第4章 异步和内存管理

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

附录:Cython语法参考

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

# Python语法
import math  # 导入math.py或math.so或math目录
from math import add as myadd  # Python:导入math.py中的add符号,为避免名字冲突,重命名为myadd
math.add(1, 2)  # 访问math中的add符号
myadd(1, 2)

# 对应的Cython语法
cimport math  # 导入math.pxd
from math cimport add as myadd  # 导入math.pxd中的add符号,为避免名字冲突,重命名为myadd
math.add(1, 2)  # 访问math中的add符号
myadd(1, 2)
# Python语法
def foo(a, b):  # 定义foo函数
    c = 0  # 创建Python的int对象
    c = a + b
    return c

# Cython语法
cdef int foo(int a, int b):  # cdef是定义C语言函数,注意该函数不能被Python调用
    cdef int c = 0  # 这是C语言的int变量
    c = a + b
    return c  # 返回C语言的int

# Cython语法
cpdef int foo(int a, int b):  # cpdef定义的函数可以被Python调用
    cdef int c = 0  # C语言的int变量
    c = a + b

    # 返回的是Python的int对象
    # Cython在这里隐式将C语言int变量转为了Python的int对象
    # 因为变量c是基本类型,Cython帮忙转了,如果c是复杂的是不能直接return的
    return c
# Python语法
class Person():
    def __init__(self):  # 这是构造函数
        pass

# Cython语法
class Person():
    def __init__(self):  # 和C语言相关的内存分配(如malloc)不能放在这里实现
        pass

    def __cinit__(self):  # 和C语言相关的内存分配(如malloc)要放在这里实现 
        ... = malloc();

    def __dealloc__(self):  # 和C语言相关的内存释放(如free)要放在这里实现 
        free(...);

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

你可能感兴趣的:(Cython入门教程)