Cython Note

基础

Cython 的本质可以总结如下：Cython 是包含 C 数据类型的 Python。

Cython 是 Python：几乎所有 Python 代码都是合法的 Cython 代码。 （存在一些限制，但是差不多也可以。） Cython 的编译器会转化 Python 代码为 C 代码，这些 C 代码均可以调用 Python/C 的 API。

Cython 可不仅仅包含这些，Cython 中的参数和变量还可以以 C 数据类型来声明。代码中的 Python 值和 C 的值可以自由地交叉混合（intermixed）使用, 所有的转化都是自动进行。Python 中的引用计数维护（Reference count maintenance）和错误检查（error checking）操作同样是自动进行的，并且全面支持 Python 的异常处理工具（facilities），包括 try-except 和 try-finally，即便在其中操作 C 数据都是可以的。

There are three file types in Cython:

The implementation files, carrying a .py or .pyx suffix.

The definition files, carrying a .pxd suffix.

The include files, carrying a .pxi suffix.

Declaring Data Types

C variables can be declared by

• using the Cython specific cdef statement,

• using PEP-484/526 type annotations with C data types or

• using the function cython.declare().

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22

cdef int a_global_variable

def func():
    cdef int i, j, k
    cdef float f, g[42], *h

cdef struct Grail:
    int age
    float volume

cdef union Food:
    char *spam
    float *eggs

cdef enum CheeseType:
    cheddar, edam,
    camembert

cdef enum CheeseState:
    hard = 1
    soft = 2
    runny = 3

1
2
3

ctypedef unsigned long ULong

ctypedef int* IntPtr

You can create a C function by declaring it with cdef or by decorating a Python function with @cfunc:

1
2

cdef int eggs(unsigned long l, float f):
    ...

Classes can be declared as Extension Types.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

from __future__ import print_function


cdef class Shrubbery:
    cdef int width
    cdef int height

    def __init__(self, w, h):
        self.width = w
        self.height = h

    def describe(self):
        print("This shrubbery is", self.width,
              "by", self.height, "cubits.")

If you have a series of declarations that all begin with cdef, you can group them into a cdef block like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

from __future__ import print_function

cdef:
    struct Spam:
        int tons

    int i
    float a
    Spam *p

    void f(Spam *s) except *:
        print(s.tons, "Tons of spam")

If no type is specified for a parameter or return value, it is assumed to be a Python object. (Note that this is different from the C convention, where it would default to int.) For example, the following defines a C function that takes two Python objects as parameters and returns a Python object

1
2

cdef spamobjs(x, y):
    ...

The type name object can also be used to explicitly declare something as a Python object. This can be useful if the name being declared would otherwise be taken as the name of a type, for example,

1
2

cdef object ftang(object int):
    ...

Differences between C and Cython expressions

There are some differences in syntax and semantics between C expressions and Cython expressions, particularly in the area of C constructs which have no direct equivalent in Python.

An integer literal is treated as a C constant, and will be truncated to whatever size your C compiler thinks appropriate. To get a Python integer (of arbitrary precision), cast immediately to an object (e.g.