Learning Cython Programming (Second Edition) - Second Edition

There is an emacs mode available for Cython. Although the syntax is nearly the same as Python, there are differences that conflict in simply using Python-mode. You can grab cython-mode.el from the Cython source code (inside the Tools directory.) The preferred way of installing packages to emacs would be to use a package repository like MELPA:

To add the package repository to emacs, open your ~/.emacs configuration file and add:

(when (>= emacs-major-version 24)
  (require 'package)
  (add-to-list
   'package-archives
   '("melpa" . "http://melpa.org/packages/")
   t)
  (package-initialize))

Once you add this and reload your configuration to install the Cython mode, you can simply run:

'M-x package-install RET cython-mode'

Once this is installed, you can activate the mode by adding this into your emacs config file:

(require 'cython-mode)

You can activate the mode manually at any time with:

'M-x cython-mode RET'

Throughout this book, I intend to show real examples that are easy to digest in order to help you get a feel of the different things you can achieve with Cython. To access and download the code used, please clone this repository:

$ git clone git://github.com/redbrain/cython-book.git

You can also compile this HelloWorld example module using Python distutils and cythonize. Open the setup.py along side the Makefile and you can see the alternate way to compile Cython modules:

from distutils.core import setup
from Cython.Build import cythonize

setup(
    ext_modules = cythonize("helloworld.pyx")
)

Using the cythonize function as part of the ext_modules section will build any specified Cython source into an installable Python module. This will compile helloworld.pyx into the same shared library. This provides the Python practice to distribute native modules as part of distutils.

We should be careful for clarity when talking about Python and Cython since the syntax is so similar. Let's wrap a simple AddFunction in C and make it callable from Python.

First, open a file called AddFunction.c, and write a simple function in it:

#include <stdio.h>

int AddFunction(int a, int b) {
    printf("look we are within your c code!\n");
    return a + b;
}

This is the C code that we will call—just a simple function to add two integers. Now, let's get Python to call it. Open a file called AddFunction.h, wherein we will declare our prototype:

#ifndef __ADDFUNCTION_H__
#define __ADDFUNCTION_H__

extern int AddFunction (int, int);

#endif //__ADDFUNCTION_H__

We need this so that Cython can see the prototype for the function we want to call. In practice, you will already have your headers in your own project with your prototypes and declarations already available.

Open a file called AddFunction.pyx, and insert the following code in it:

cdef extern from "AddFunction.h":
    cdef int AddFunction(int, int)

Here, we have to declare which code we want to call. The cdef is a keyword signifying that this is from the C code that will be linked in. Now, we need a Python entry point:

def Add(a, b):
     return AddFunction(a, b)

This Add function is a Python callable inside a PyAddFunction module this acts as a wrapper for Python code to be able to call directly into the C code. Again, I have provided a handy makefile to produce the module:

$ cd cython-book/chapter1/ownmodule
$ make
cython -2 PyAddFunction.pyx
gcc -g -O2 -fpic -c PyAddFunction.c -o PyAddFunction.o `python-config --includes`
gcc -g -O2 -fpic -c AddFunction.c -o AddFunction.o
gcc -g -O2 -shared -o PyAddFunction.so AddFunction.o PyAddFunction.o `python-config --libs`

Notice that AddFunction.c is compiled into the same PyAddFunction.so shared object. Now, let's call this AddFunction and check to see if C can add numbers correctly:

$ python
>>> from PyAddFunction import Add
>>> Add(1,2)
look we are within your c code!!
3

Notice that the print statement inside the AddFunction and the final result are printed correctly. Therefore, we know that the control hit the C code and did the calculation in C, and not inside the Python runtime. This is a revelation of what is possible. Python can be cited to be slow in some circumstances. Using this technique makes it possible for Python code to bypass its own runtime and to run in an unsafe context, which is unrestricted by the Python runtime which is much faster.

Notice that we had to declare a prototype inside the Cython source code PyAddFunction.pyx:

cdef extern from "AddFunction.h":
    cdef int AddFunction(int, int)

It lets the compiler know that there is a function called AddFunction and it takes two ints and returns an int. This is all the information the compiler needs to know beside the host and target operating system's calling convention to call this function safely. Then, we created the Python entry point, which is a Python callable that takes two parameters:

def Add(a, b):
     return AddFunction(a, b)

Inside this entry point, it simply returned the native AddFunction and passed the two Python objects as parameters. This is what makes Cython so powerful. Here, the Cython compiler must inspect the function call and generate code to safely try and convert these Python objects to native C integers. This becomes difficult when precision is taken into account as well as potential overflow, which just so happens to be a major use case since it handles everything so well. Also, remember that this function returns an integer, and Cython also generates code to convert the integer return into a valid Python object.