纯 Python 模式 ¶

在某些情况下，期望在不丢失采用 Python 解释器运行它的能力的情况下加速 Python 代码。当采用 Cython 编译纯 Python 脚本时，通常只会产生大约 20%-50% 的速度提升。

To go beyond that, Cython provides language constructs to add static typing and cythonic functionalities to a Python module to make it run much faster when compiled, while still allowing it to be interpreted. This is accomplished via an augmenting .pxd file, via Python type annotations (following PEP 484 and PEP 526 ), and/or via special functions and decorators available after importing the magic cython module. All three ways can be combined at need, although projects would commonly decide on a specific way to keep the static type information easy to manage.

Although it is not typically recommended over writing straight Cython code in a .pyx file, there are legitimate reasons to do this - easier testing and debugging, collaboration with pure Python developers, etc. In pure mode, you are more or less restricted to code that can be expressed (or at least emulated) in Python, plus static type declarations. Anything beyond that can only be done in .pyx files with extended language syntax, because it depends on features of the Cython compiler.

Augmenting .pxd ¶

使用增广 .pxd 允许让原始 .py 文件完全不受影响。另一方面，需要同时维护 .pxd 和 .py 使它们保持同步。

While declarations in a .pyx file must correspond exactly with those of a .pxd file with the same name (and any contradiction results in a compile time error, see pxd 文件 ), the untyped definitions in a .py file can be overridden and augmented with static types by the more specific ones present in a .pxd .

若 .pxd file is found with the same name as the .py file being compiled, it will be searched for cdef classes and cdef / cpdef functions and methods. The compiler will then convert the corresponding classes/functions/methods in the .py file to be of the declared type. Thus if one has a file A.py :

def myfunction(x, y=2):
    a = x - y
    return a + x * y
def _helper(a):
    return a + 1
class A:
    def __init__(self, b=0):
        self.a = 3
        self.b = b
    def foo(self, x):
        print(x + _helper(1.0))

和添加 A.pxd :

cpdef int myfunction(int x, int y=*)
cdef double _helper(double a)
cdef class A:
    cdef public int a, b
    cpdef foo(self, double x)

then Cython will compile the A.py as if it had been written as follows:

cpdef int myfunction(int x, int y=2):
    a = x - y
    return a + x * y
cdef double _helper(double a):
    return a + 1
cdef class A:
    cdef public int a, b
    def __init__(self, b=0):
        self.a = 3
        self.b = b
    cpdef foo(self, double x):
        print(x + _helper(1.0))

Notice how in order to provide the Python wrappers to the definitions in the .pxd , that is, to be accessible from Python,

Python visible function signatures must be declared as cpdef (with default arguments replaced by a * to avoid repetition):
```
cpdef int myfunction(int x, int y=*)
							
```
C function signatures of internal functions can be declared as cdef :
```
cdef double _helper(double a)
							
```
cdef classes (extension types) are declared as cdef class ;
cdef class attributes must be declared as cdef public if read/write Python access is needed, cdef readonly for read-only Python access, or plain cdef for internal C level attributes;
cdef class methods must be declared as cpdef for Python visible methods or cdef for internal C methods.

In the example above, the type of the local variable a in myfunction() is not fixed and will thus be a Python object. To statically type it, one can use Cython’s @cython.locals decorator (see 魔法属性，和 .pxd 中的魔法属性 ).

Normal Python ( def ) functions cannot be declared in .pxd files. It is therefore currently impossible to override the types of plain Python functions in .pxd files, e.g. to override types of their local variables. In most cases, declaring them as cpdef will work as expected.

魔法属性 ¶

Special decorators are available from the magic cython module that can be used to add static typing within the Python file, while being ignored by the interpreter.

This option adds the cython module dependency to the original code, but does not require to maintain a supplementary .pxd file. Cython provides a fake version of this module as Cython.Shadow , which is available as cython.py when Cython is installed, but can be copied to be used by other modules when Cython is not installed.

compiled 切换 ¶

compiled is a special variable which is set to True when the compiler runs, and False in the interpreter. Thus, the code
```
import cython
if cython.compiled:
    print("Yep, I'm compiled.")
else:
    print("Just a lowly interpreted script.")
							
```
will behave differently depending on whether or not the code is executed as a compiled extension ( .so / .pyd ) module or a plain .py 文件。

静态类型化 ¶

cython.declare declares a typed variable in the current scope, which can be used in place of the cdef type var [= value] construct. This has two forms, the first as an assignment (useful as it creates a declaration in interpreted mode as well):

import cython
x = cython.declare(cython.int)              # cdef int x
y = cython.declare(cython.double, 0.57721)  # cdef double y = 0.57721

and the second mode as a simple function call:

import cython
cython.declare(x=cython.int, y=cython.double)  # cdef int x; cdef double y

It can also be used to define extension type private, readonly and public attributes:

import cython
@cython.cclass
class A:
    cython.declare(a=cython.int, b=cython.int)
    c = cython.declare(cython.int, visibility='public')
    d = cython.declare(cython.int)  # private by default.
    e = cython.declare(cython.int, visibility='readonly')
    def __init__(self, a, b, c, d=5, e=3):
        self.a = a
        self.b = b
        self.c = c
        self.d = d
        self.e = e

@cython.locals is a decorator that is used to specify the types of local variables in the function body (including the arguments):

import cython
@cython.locals(a=cython.long, b=cython.long, n=cython.longlong)
def foo(a, b, x, y):
    n = a * b
    # ...

@cython.returns(<type>) specifies the function’s return type.

@cython.exceptval(value=None, *, check=False) specifies the function’s exception return value and exception check semantics as follows:

@exceptval(-1)               # cdef int func() except -1:
@exceptval(-1, check=False)  # cdef int func() except -1:
@exceptval(check=True)       # cdef int func() except *:
@exceptval(-1, check=True)   # cdef int func() except? -1:

Python annotations can be used to declare argument types, as shown in the following example. To avoid conflicts with other kinds of annotation usages, this can be disabled with the directive annotation_typing=False .

import cython
def func(foo: dict, bar: cython.int) -> tuple:
    foo["hello world"] = 3 + bar
    return foo, 5

This can be combined with the @cython.exceptval() decorator for non-Python return types:

import cython
@cython.exceptval(-1)
def func(x: cython.int) -> cython.int:
    if x < 0:
        raise ValueError("need integer >= 0")
    return x + 1

Since version 0.27, Cython also supports the variable annotations defined in PEP 526 . This allows to declare types of variables in a Python 3.6 compatible way as follows:

import cython
def func():
    # Cython types are evaluated as for cdef declarations
    x: cython.int               # cdef int x
    y: cython.double = 0.57721  # cdef double y = 0.57721
    z: cython.float = 0.57721   # cdef float z  = 0.57721
    # Python types shadow Cython types for compatibility reasons
    a: float = 0.54321          # cdef double a = 0.54321
    b: int = 5                  # cdef object b = 5
    c: long = 6                 # cdef object c = 6
    pass
@cython.cclass
class A:
    a: cython.int
    b: cython.int
    def __init__(self, b=0):
        self.a = 3
        self.b = b

There is currently no way to express the visibility of object attributes.

C 类型 ¶

There are numerous types built into the Cython module. It provides all the standard C types, namely char , short , int , long , longlong as well as their unsigned versions uchar , ushort , uint , ulong , ulonglong . The special bint type is used for C boolean values and Py_ssize_t for (signed) sizes of Python containers.

For each type, there are pointer types p_int , pp_int , etc., up to three levels deep in interpreted mode, and infinitely deep in compiled mode. Further pointer types can be constructed with cython.pointer(cython.int) , and arrays as cython.int[10] . A limited attempt is made to emulate these more complex types, but only so much can be done from the Python language.

The Python types int, long and bool are interpreted as C int , long and bint respectively. Also, the Python builtin types list , dict , tuple , etc. may be used, as well as any user defined types.

Typed C-tuples can be declared as a tuple of C types.

扩展类型和 cdef 函数 ¶

The class decorator @cython.cclass 创建 cdef class .
The function/method decorator @cython.cfunc 创建 cdef 函数。
@cython.ccall 创建 cpdef function, i.e. one that Cython code can call at the C level.
@cython.locals declares local variables (see above). It can also be used to declare types for arguments, i.e. the local variables that are used in the signature.
@cython.inline is the equivalent of the C inline modifier.
@cython.final terminates the inheritance chain by preventing a type from being used as a base class, or a method from being overridden in subtypes. This enables certain optimisations such as inlined method calls.

Here is an example of a cdef 函数：

@cython.cfunc
@cython.returns(cython.bint)
@cython.locals(a=cython.int, b=cython.int)
def c_compare(a,b):
    return a == b

进一步 Cython 函数和声明 ¶

address is used in place of the & 运算符：

cython.declare(x=cython.int, x_ptr=cython.p_int)
x_ptr = cython.address(x)

sizeof emulates the sizeof operator. It can take both types and expressions.

cython.declare(n=cython.longlong)
print(cython.sizeof(cython.longlong))
print(cython.sizeof(n))

struct can be used to create struct types.:

MyStruct = cython.struct(x=cython.int, y=cython.int, data=cython.double)
a = cython.declare(MyStruct)

is equivalent to the code:

cdef struct MyStruct:
    int x
    int y
    double data
cdef MyStruct a

union creates union types with exactly the same syntax as struct .

typedef defines a type under a given name:

T = cython.typedef(cython.p_int)   # ctypedef int* T

cast will (unsafely) reinterpret an expression type. cython.cast(T, t) 相当于 <T>t . The first attribute must be a type, the second is the expression to cast. Specifying the optional keyword argument typecheck=True has the semantics of <T?>t .
```
t1 = cython.cast(T, t)
t2 = cython.cast(T, t, typecheck=True)
							
```

.pxd 中的魔法属性 ¶

特殊 cython module can also be imported and used within the augmenting .pxd file. For example, the following Python file dostuff.py :

def dostuff(n):
    t = 0
    for i in range(n):
        t += i
    return t

can be augmented with the following .pxd file dostuff.pxd :

import cython
@cython.locals(t=cython.int, i=cython.int)
cpdef int dostuff(int n)

cython.declare() function can be used to specify types for global variables in the augmenting .pxd 文件。

提示和技巧 ¶

调用 C 函数 ¶

Normally, it isn’t possible to call C functions in pure Python mode as there is no general way to support it in normal (uncompiled) Python. However, in cases where an equivalent Python function exists, this can be achieved by combining C function coercion with a conditional import as follows:

# mymodule.pxd
# declare a C function as "cpdef" to export it to the module
cdef extern from "math.h":
    cpdef double sin(double x)

# mymodule.py
import cython
# override with Python import if not in compiled code
if not cython.compiled:
    from math import sin
# calls sin() from math.h when compiled with Cython and math.sin() in Python
print(sin(0))

Note that the “sin” function will show up in the module namespace of “mymodule” here (i.e. there will be a mymodule.sin() function). You can mark it as an internal name according to Python conventions by renaming it to “_sin” in the .pxd file as follows:

cdef extern from "math.h":
    cpdef double _sin "sin" (double x)

You would then also change the Python import to from math import sin as _sin to make the names match again.

将 C 数组用于固定大小列表 ¶

C arrays can automatically coerce to Python lists or tuples. This can be exploited to replace fixed size Python lists in Python code by C arrays when compiled. An example:

import cython
@cython.locals(counts=cython.int[10], digit=cython.int)
def count_digits(digits):
    """
    >>> digits = '01112222333334445667788899'
    >>> count_digits(map(int, digits))
    [1, 3, 4, 5, 3, 1, 2, 2, 3, 2]
    """
    counts = [0] * 10
    for digit in digits:
        assert 0 <= digit <= 9
        counts[digit] += 1
    return counts

In normal Python, this will use a Python list to collect the counts, whereas Cython will generate C code that uses a C array of C ints.