Basic Tutorial

The Basics of Cython

The fundamental nature of Cython can be summed up as follows: Cython is Pythonwith C data types.

Cython is Python: Almost any piece of Python code is also valid Cython code.(There are a few Limitations, but this approximation willserve for now.) The Cython compiler will convert it into C code which makesequivalent calls to the Python/C API.

But Cython is much more than that, because parameters and variables can bedeclared to have C data types. Code which manipulates Python values and Cvalues can be freely intermixed, with conversions occurring automaticallywherever possible. Reference count maintenance and error checking of Pythonoperations is also automatic, and the full power of Python’s exceptionhandling facilities, including the try-except and try-finally statements, isavailable to you – even in the midst of manipulating C data.

Cython Hello World

As Cython can accept almost any valid python source file, one of the hardestthings in getting started is just figuring out how to compile your extension.

So lets start with the canonical python hello world:

  1. print("Hello World")

Save this code in a file named helloworld.pyx. Now we need to createthe setup.py, which is like a python Makefile (for more informationsee Source Files and Compilation). Your setup.py should look like:

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

To use this to build your Cython file use the commandline options:

  1. $ python setup.py build_ext --inplace

Which will leave a file in your local directory called helloworld.so in unixor helloworld.pyd in Windows. Now to use this file: start the pythoninterpreter and simply import it as if it was a regular python module:

  1. >>> import helloworld
  2. Hello World

Congratulations! You now know how to build a Cython extension. But so farthis example doesn’t really give a feeling why one would ever want to use Cython, solets create a more realistic example.

pyximport: Cython Compilation for Developers

If your module doesn’t require any extra C libraries or a specialbuild setup, then you can use the pyximport module, originally developedby Paul Prescod, to load .pyx files directly on import, without havingto run your setup.py file each time you change your code.It is shipped and installed with Cython and can be used like this:

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

The Pyximport module also has experimentalcompilation support for normal Python modules. This allows you toautomatically run Cython on every .pyx and .py module that Pythonimports, including the standard library and installed packages.Cython will still fail to compile a lot of Python modules, in whichcase the import mechanism will fall back to loading the Python sourcemodules instead. The .py import mechanism is installed like this:

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

Note that it is not recommended to let Pyximport build codeon end user side as it hooks into their import system. The best wayto cater for end users is to provide pre-built binary packages in thewheel packaging format.

Fibonacci Fun

From the official Python tutorial a simple fibonacci function is defined as:

  1. from __future__ import print_function
  2.  
  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
  9.  
  10.     print()

Now following the steps for the Hello World example we first rename the fileto have a .pyx extension, lets say fib.pyx, then we create thesetup.py file. Using the file created for the Hello World example, allthat you need to change is the name of the Cython filename, and the resultingmodule name, doing this we have:

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

Build the extension with the same command used for the helloworld.pyx:

  1. $ python setup.py build_ext --inplace

And use the new extension with:

  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

Here’s a small example showing some of what can be done. It’s a routine forfinding prime numbers. You tell it how many primes you want, and it returnsthem as a Python list.

primes.pyx:




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





  1. def primes(int nb_primes):
        cdef int n, i, len_p
        cdef int p[1000]
        if nb_primes > 1000:
            nb_primes = 1000

        len_p = 0  # The current number of elements in p.
        n = 2
        while len_p < nb_primes:
            # Is n prime?
            for i in p[:len_p]:
                if n % i == 0:
                    break

            # If no break occurred in the loop, we have a prime.
            else:
                p[len_p] = n
                len_p += 1
            n += 1

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


You’ll see that it starts out just like a normal Python function definition,except that the parameter nb_primes is declared to be of type int . Thismeans that the object passed will be converted to a C integer (or aTypeError. will be raised if it can’t be).

Now, let’s dig into the core of the function:

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

Lines 2 and 3 use the cdef statement to define some local C variables.The result is stored in the C array p during processing,and will be copied into a Python list at the end (line 22).

Note

You cannot create very large arrays in this manner, becausethey are allocated on the C function call stack, which is arather precious and scarce resource.To request larger arrays,or even arrays with a length only known at runtime,you can learn how to make efficient use ofC memory allocation,Python arraysor NumPy arrays with Cython.

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

As in C, declaring a static array requires knowing the size at compile time.We make sure the user doesn’t set a value above 1000 (or we would have asegmentation fault, just like in C).

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

Lines 7-9 set up for a loop which will test candidate numbers for primenessuntil the required number of primes has been found.

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

Lines 11-12, which try dividing a candidate by all the primes found so far,are of particular interest. Because no Python objects are referred to,the loop is translated entirely into C code, and thus runs very fast.You will notice the way we iterate over the p C array.

  1. for i in p[:len_p]:

The loop gets translated into a fast C loop and works just like iteratingover a Python list or NumPy array. If you don’t slice the C array with[:len_p], then Cython will loop over the 1000 elements of the array.

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

If no breaks occurred, it means that we found a prime, and the block of codeafter the else line 16 will be executed. We add the prime found to p.If you find having an else after a for-loop strange, just know that it’s alesser known features of the Python language, and that Cython executes it atC speed for you.If the for-else syntax confuses you, see this excellentblog post.

  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

In line 22, before returning the result, we need to copy our C array into aPython list, because Python can’t read C arrays. Cython can automaticallyconvert many C types from and to Python types, as described in thedocumentation on type conversion, so we can usea simple list comprehension here to copy the C int values into a Pythonlist of Python int objects, which Cython creates automatically along the way.You could also have iterated manually over the C array and usedresult_as_list.append(prime), the result would have been the same.

You’ll notice we declare a Python list exactly the same way it would be in Python.Because the variable result_as_list hasn’t been explicitly declared with a type,it is assumed to hold a Python object, and from the assignment, Cython also knowsthat the exact type is a Python list.

Finally, at line 18, a normalPython return statement returns the result list.

Compiling primes.pyx with the Cython compiler produces an extension modulewhich we can try out in the interactive interpreter as follows:

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

See, it works! And if you’re curious about how much work Cython has saved you,take a look at the C code generated for this module.

Cython has a way to visualise where interaction with Python objects andPython’s C-API is taking place. For this, pass theannotate=True parameter to cythonize(). It produces a HTML file. Let’s see:

../../_images/htmlreport1.png

If a line is white, it means that the code generated doesn’t interactwith Python, so will run as fast as normal C code. The darker the yellow, the morePython interaction there is in that line. Those yellow lines will usually operateon Python objects, raise exceptions, or do other kinds of higher-level operationsthan what can easily be translated into simple and fast C code.The function declaration and return use the Python interpreter so it makessense for those lines to be yellow. Same for the list comprehension becauseit involves the creation of a Python object. But the line if n % i == 0:, why?We can examine the generated C code to understand:

../../_images/python_division.png

We can see that some checks happen. Because Cython defaults to thePython behavior, the language will perform division checks at runtime,just like Python does. You can deactivate those checks by using thecompiler directives.

Now let’s see if, even if we have division checks, we obtained a boost in speed.Let’s write the same program, but Python-style:

  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
  9.  
  10.         # If no break occurred in the loop
  11.         else:
  12.             p.append(n)
  13.         n += 1
  14.     return p

It is also possible to take a plain .py file and to compile it with Cython.Let’s take primes_python, change the function name to primes_python_compiled andcompile it with Cython (without changing the code). We will also change the name of thefile to example_py_cy.py to differentiate it from the others.Now the setup.py looks like this:

  1. from setuptools import setup
  2. from Cython.Build import cythonize
  3.  
  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. )

Now we can ensure that those two programs output the same values:

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

It’s possible to compare the speed now:

  1. python -m timeit -s 'from example_py import primes_python' 'primes_python(1000)'
  2. 10 loops, best of 3: 23 msec per loop
  3.  
  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
  6.  
  7. python -m timeit -s 'from example import primes' 'primes(1000)'
  8. 1000 loops, best of 3: 1.65 msec per loop

The cythonize version of primes_python is 2 times faster than the Python one,without changing a single line of code.The Cython version is 13 times faster than the Python version! What could explain this?

  • Multiple things:
    • In this program, very little computation happen at each line.So the overhead of the python interpreter is very important. It would bevery different if you were to do a lot computation at each line. Using NumPy forexample.
    • Data locality. It’s likely that a lot more can fit in CPU cache when using C thanwhen using Python. Because everything in python is an object, and every object isimplemented as a dictionary, this is not very cache friendly.

Usually the speedups are between 2x to 1000x. It depends on how much you callthe Python interpreter. As always, remember to profile before adding typeseverywhere. Adding types makes your code less readable, so use them withmoderation.

Primes with C++

With Cython, it is also possible to take advantage of the C++ language, notably,part of the C++ standard library is directly importable from Cython code.

Let’s see what our primes.pyx becomes whenusing vector from the C++standard library.

Note

Vector in C++ is a data structure which implements a list or stack basedon a resizeable C array. It is similar to the Python arraytype in the array standard library module.There is a method reserve available which will avoid copies if you know in advancehow many elements you are going to put in the vector. For more detailssee this page from cppreference.




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





  1. # distutils: language=c++

    from libcpp.vector cimport vector

    def primes(unsigned int nb_primes):
        cdef int n, i
        cdef vector[int] p
        p.reserve(nb_primes)  # allocate memory for 'nb_primes' elements.

        n = 2
        while p.size() < nb_primes:  # size() for vectors is similar to len()
            for i in p:
                if n % i == 0:
                    break
            else:
                p.push_back(n)  # push_back is similar to append()
            n += 1

        # Vectors are automatically converted to Python
        # lists when converted to Python objects.
        return p


The first line is a compiler directive. It tells Cython to compile your code to C++.This will enable the use of C++ language features and the C++ standard library.Note that it isn’t possible to compile Cython code to C++ with pyximport. Youshould use a setup.py or a notebook to run this example.

You can see that the API of a vector is similar to the API of a Python list,and can sometimes be used as a drop-in replacement in Cython.

For more details about using C++ with Cython, see Using C++ in Cython.

Language Details

For more about the Cython language, see Language Basics.To dive right in to using Cython in a numerical computation context,see Typed Memoryviews.