基础教程

原文： http://docs.cython.org/en/latest/src/tutorial/cython_tutorial.html

Cython 的基础知识

Cython 的基本特性可归纳如下：Cython 是具有 C 数据类型的 Python。

Cython 是 Python：几乎任何 Python 代码都是有效的 Cython 代码。 （有一些 限制 ，但这种近似现在将起作用。）Cython 编译器将其转换为 C 代码，它对 Python / C API 进行等效调用。

但 Cython 远不止于此，因为参数和变量可以声明为具有 C 数据类型。操作 Python 值和 C 值的代码可以自由混合，只要有可能就会自动进行转换。 Python 操作的引用计数维护和错误检查也是自动的，并且即使在操作 C 数据的过程中，您也可以使用 Python 的异常处理工具（包括 try-except 和 try-finally 语句）的全部功能。

Cython Hello World

由于 Cython 几乎可以接受任何有效的 python 源文件，因此入门中最困难的事情之一就是弄清楚如何编译扩展。

所以让我们从规范的 python hello 世界开始：

  1. print("Hello World")

将此代码保存在名为helloworld.pyx的文件中。现在我们需要创建setup.py，它就像一个 python Makefile（有关更多信息，请参阅 源文件和编译 ）。你的setup.py看起来像：

  1. from distutils.core import setup
  2. from Cython.Build import cythonize
  4. setup(
  5.     ext_modules = cythonize("helloworld.pyx")
  6. )

要使用它来构建您的 Cython 文件，请使用命令行选项：

  1. $ python setup.py build_ext --inplace

这将在您的本地目录中将文件保留在 unix 中的helloworld.so或 Windows 中的helloworld.pyd中。现在使用这个文件：启动 python 解释器并简单地导入它就好像它是一个普通的 python 模块：

  1. >>> import helloworld
  2. Hello World

恭喜！您现在知道如何构建 Cython 扩展。但到目前为止，这个例子并没有真正让人感觉为什么会想要使用 Cython，所以让我们创建一个更现实的例子。

pyximport：面向开发人员的 Cython 编译

如果您的模块不需要任何额外的 C 库或特殊的构建设置，那么您可以使用最初由 Paul Prescod 开发的 pyximport 模块在导入时直接加载.pyx 文件，而无需每个都运行setup.py文件你改变代码的时候了。它随 Cython 一起发货和安装，可以像这样使用：

  1. >>> import pyximport; pyximport.install()
  2. >>> import helloworld
  3. Hello World

Pyximport 模块还具有对普通 Python 模块的实验性编译支持。这允许您在 Py​​thon 导入的每个.pyx 和.py 模块上自动运行 Cython，包括标准库和已安装的软件包。 Cython 仍然无法编译很多 Python 模块，在这种情况下，导入机制将回退到加载 Python 源模块。 .py 导入机制安装如下：

  1. >>> pyximport.install(pyimport=True)

请注意，建议不要让 Pyximport在最终用户端构建代码，因为它会挂钩到他们的导入系统。满足最终用户的最佳方式是以轮包装格式提供预先构建的二进制包。

斐波那契乐趣

从官方 Python 教程中，一个简单的 fibonacci 函数定义为：

  1. from __future__ import print_function
  3. def fib(n):
  4.     """Print the Fibonacci series up to n."""
  5.     a, b = 0, 1
  6.     while b < n:
  7.         print(b, end=' ')
  8.         a, b = b, a + b
  10.     print()

现在按照 Hello World 示例的步骤，我们首先将文件重命名为 <cite>.pyx</cite> 扩展名，让我们说fib.pyx，然后我们创建setup.py文件。使用为 Hello World 示例创建的文件，您需要更改的是 Cython 文件名的名称，以及生成的模块名称，我们这样做：

  1. from distutils.core import setup
  2. from Cython.Build import cythonize
  4. setup(
  5.     ext_modules=cythonize("fib.pyx"),
  6. )

使用与 helloworld.pyx 相同的命令构建扩展：

  1. $ python setup.py build_ext --inplace

并使用新的扩展名：

  1. >>> import fib
  2. >>> fib.fib(2000)
  3. 1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597

Primes

这是一个小例子，展示了一些可以做的事情。这是查找素数的例程。你告诉它你想要多少素数，并将它们作为 Python 列表返回。

primes.pyx：

| 

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

| 

  1. def primes(int nb_primes):
  2.     cdef int n, i, len_p
  3.     cdef int p[1000]
  4.     if nb_primes &gt; 1000:
  5.         nb_primes = 1000
  7.     len_p = 0  # The current number of elements in p.
  8.     n = 2
  9.     while len_p &lt; nb_primes:
  10.         # Is n prime?
  11.         for i in p[:len_p]:
  12.             if n % i == 0:
  13.                 break
  15.         # If no break occurred in the loop, we have a prime.
  16.         else:
  17.             p[len_p] = n
  18.             len_p += 1
  19.         n += 1
  21.     # Let's return the result in a python list:
  22.     result_as_list  = [prime for prime in p[:len_p]]
  23.     return result_as_list

|

您将看到它的开始就像普通的 Python 函数定义一样，除了参数nb_primes被声明为int类型。这意味着传递的对象将被转换为 C 整数（如果不能，则会引发TypeError.）。

现在，让我们深入研究该函数的核心：

  1. cdef int n, i, len_p
  2. cdef int p[1000]

第 2 行和第 3 行使用cdef语句定义一些本地 C 变量。结果在处理期间存储在 C 数组p中，并将在末尾复制到 Python 列表中（第 22 行）。

注意

您不能以这种方式创建非常大的数组，因为它们是在 C 函数调用堆栈上分配的，这是一个相当珍贵和稀缺的资源。要请求更大的数组，甚至是只在运行时知道长度的数组，您可以学习如何有效地使用 C 内存分配 ， Python 数组 或 NumPy 阵列 与 Cython。

  1. if nb_primes > 1000:
  2.     nb_primes = 1000

与在 C 中一样，声明静态数组需要在编译时知道大小。我们确保用户没有设置大于 1000 的值（或者我们会有一个分段错误，就像在 C 中一样）。

  1. len_p = 0  # The number of elements in p
  2. n = 2
  3. while len_p < nb_primes:

第 7-9 行设置了一个循环，它将测试候选数字的完整性，直到找到所需的素数。

  1. # Is n prime?
  2. for i in p[:len_p]:
  3.     if n % i == 0:
  4.         break

尝试将候选人除以迄今为止发现的所有素数的第 11-12 行特别令人感兴趣。因为没有引用 Python 对象，所以循环完全转换为 C 代码，因此运行速度非常快。你会注意到我们迭代p C 数组的方式。

  1. for i in p[:len_p]:

循环被转换为快速 C 循环，就像迭代 Python 列表或 NumPy 数组一样。如果不使用[:len_p]对 C 数组进行切片，则 Cython 将循环遍历数组的 1000 个元素。

  1. # If no break occurred in the loop
  2. else:
  3.     p[len_p] = n
  4.     len_p += 1
  5. n += 1

如果没有发生中断，则意味着我们找到了一个素数，并且将执行else行 16 之后的代码块。我们添加了p找到的素数。如果你发现在 for 循环奇怪之后有else，只要知道它是 Python 语言鲜为人知的特性，并且 Cython 会以 C 速度为你执行它。如果 for-else 语法让您感到困惑，请参阅这篇优秀的博客文章。

  1. # Let's put the result in a python list:
  2. result_as_list  = [prime for prime in p[:len_p]]
  3. return result_as_list

在第 22 行，在返回结果之前，我们需要将 C 数组复制到 Python 列表中，因为 Python 无法读取 C 数组。 Cython 可以自动将许多 C 类型转换为 Python 类型，如 类型转换 的文档中所述，因此我们可以使用简单的列表解析来复制 C int值为 Python int对象的 Python 列表，Cython 在此过程中自动创建。您也可以在 C 数组上手动迭代并使用result_as_list.append(prime)，结果将是相同的。

您会注意到我们声明的 Python 列表与 Python 中的完全相同。因为变量result_as_list尚未使用类型显式声明，所以假定它包含一个 Python 对象，并且从赋值中，Cython 也知道确切的类型是 Python 列表。

最后，在第 18 行，普通的 Python return 语句返回结果列表。

使用 Cython 编译器编译 primes.pyx 会生成一个扩展模块，我们可以在交互式解释器中尝试如下：

  1. >>> import primes
  2. >>> primes.primes(10)
  3. [2, 3, 5, 7, 11, 13, 17, 19, 23, 29]

看，它有效！如果您对 Cython 为您节省了多少工作感到好奇，请查看为此模块生成的 C 代码。

Cython 有一种方法可视化与 Python 对象和 Python 的 C-API 进行交互的位置。为此，将annotate=True参数传递给cythonize()。它生成一个 HTML 文件。让我们来看看：

../../_images/htmlreport1.png

如果一行为白色，则表示生成的代码不与 Python 交互，因此将以与普通 C 代码一样快的速度运行。黄色越深，该行中的 Python 交互越多。这些黄色线通常可以在 Python 对象上运行，引发异常，或执行其他类型的高级操作，而不是可以轻松转换为简单快速的 C 代码。函数声明和返回使用 Python 解释器，因此这些行是黄色的。列表推导也是如此，因为它涉及创建 Python 对象。但行if n % i == 0:，为什么？我们可以检查生成的 C 代码来理解：

../../_images/python_division.png

我们可以看到一些检查发生。因为 Cython 默认使用 Python 行为，所以语言将在运行时执行除法检查，就像 Python 一样。您可以使用 编译器指令 取消激活这些检查。

现在让我们看看，即使我们有分区检查，我们也获得了提升速度。让我们编写相同的程序，但是 Python 风格：

  1. def primes_python(nb_primes):
  2.     p = []
  3.     n = 2
  4.     while len(p) < nb_primes:
  5.         # Is n prime?
  6.         for i in p:
  7.             if n % i == 0:
  8.                 break
  10.         # If no break occurred in the loop
  11.         else:
  12.             p.append(n)
  13.         n += 1
  14.     return p

也可以采用普通的.py文件并使用 Cython 进行编译。让我们拿primes_python，将函数名改为primes_python_compiled并用 Cython 编译（不改变代码）。我们还将文件名更改为example_py_cy.py，以区别于其他文件。现在setup.py看起来像这样：

  1. from distutils.core import setup
  2. from Cython.Build import cythonize
  4. setup(
  5.     ext_modules=cythonize(['example.pyx',        # Cython code file with primes() function
  6.                            'example_py_cy.py'],  # Python code file with primes_python_compiled() function
  7.                           annotate=True),        # enables generation of the html annotation file
  8. )

现在我们可以确保这两个程序输出相同的值：

  1. >>> primes_python(1000) == primes(1000)
  2. True
  3. >>> primes_python_compiled(1000) == primes(1000)
  4. True

现在可以比较速度：

  1. python -m timeit -s 'from example_py import primes_python' 'primes_python(1000)'
  2. 10 loops, best of 3: 23 msec per loop
  4. python -m timeit -s 'from example_py_cy import primes_python_compiled' 'primes_python_compiled(1000)'
  5. 100 loops, best of 3: 11.9 msec per loop
  7. python -m timeit -s 'from example import primes' 'primes(1000)'
  8. 1000 loops, best of 3: 1.65 msec per loop

primes_python的 cythonize 版本比 Python 版本快 2 倍，而不需要更改单行代码。 Cython 版本比 Python 版本快 13 倍！有什么可以解释这个？

Multiple things:

  • 在这个程序中，每行都进行很少的计算。因此 python 解释器的开销非常重要。如果你要在每一行做很多计算，那将会非常不同。以 NumPy 为例。
  • 数据位置。使用 C 时，使用 Python 时可能会有更多的内容适合 CPU 缓存。因为 python 中的所有内容都是一个对象，并且每个对象都是作为字典实现的，所以这不是很容易缓存的。

通常加速比在 2x 到 1000x 之间。这取决于你调用 Python 解释器的程度。与往常一样，请记住在各地添加类型之前进行配置添加类型会降低代码的可读性，因此请谨慎使用它们。

使用 C ++ 的 Primes

使用 Cython，也可以利用 C ++语言，特别是 C ++标准库的一部分可以直接从 Cython 代码导入。

让我们看看当使用 C ++标准库中的向量时我们的primes.pyx变成了什么。

Note

C ++中的 Vector 是一种数据结构，它基于可调整大小的 C 数组实现列表或堆栈。它类似于array标准库模块中的 Python array类型。有一种方法<cite>保留</cite>可用，如果你事先知道你要在矢量中放入多少元素，它将避免复制。有关详细信息，请参阅 cppreference 中的此页面。

| 

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

| 

  1. # distutils: language=c++
  3. from libcpp.vector cimport vector
  5. def primes(unsigned int nb_primes):
  6.     cdef int n, i
  7.     cdef vector[int] p
  8.     p.reserve(nb_primes)  # allocate memory for 'nb_primes' elements.
  10.     n = 2
  11.     while p.size() &lt; nb_primes:  # size() for vectors is similar to len()
  12.         for i in p:
  13.             if n % i == 0:
  14.                 break
  15.         else:
  16.             p.push_back(n)  # push_back is similar to append()
  17.         n += 1
  19.     # Vectors are automatically converted to Python
  20.     # lists when converted to Python objects.
  21.     return p

|

第一行是编译器指令。它告诉 Cython 将您的代码编译为 C ++。这将允许使用 C ++语言功能和 C ++标准库。请注意，使用 <cite>pyximport</cite> 无法将 Cython 代码编译为 C ++。您应该使用setup.py或笔记本来运行此示例。

您可以看到向量的 API 类似于 Python 列表的 API，有时可以用作 Cython 中的替代品。

有关在 Cython 中使用 C ++的更多详细信息，请参阅 在 Cython中使用 C ++。

语言详细信息

有关 Cython 语言的更多信息，请参阅 语言基础知识 。要在数值计算环境中直接使用 Cython，请参阅 类型记忆视图 。