Getting started – Hello World
As you will see when running the Hello World program, Cython generates native Python modules. Therefore, running any Cython code, you will reference it via a module import in Python. Let's build the module:
You should now have created helloworld.so! This is a Cython module of the same name as the Cython source code file. While in the same directory of the shared object module, you can invoke this code by running a respective Python import:
As you can see by opening helloworld.pyx, it looks just like a normal Python Hello World application, but as previously stated, Cython generates modules. These modules need a name so that they can be correctly imported by the Python runtime. The Cython compiler simply uses the name of the source code file. It then requires us to compile this to the same shared object name.
Overall, Cython source code files have the .pyx,.pxd, and .pxi extensions. For now, all we care about are the .pyx files; the others are for cimports and includes respectively within a .pyx module file.
The following screenshot depicts the compilation flow required to have a callable native Python module:
I wrote a basic makefile so that you can simply run make to compile these examples. Here's the code to do this manually:
Using distutils with Cython
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:
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.
Calling C functions from Python
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:
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:
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:
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:
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:
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:
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.
Type conversion in Cython
Notice that we had to declare a prototype inside the Cython source code PyAddFunction.pyx:
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:
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.
Tip
Downloading the example code
You can download the example code files for all Packt books you have purchased from your account at http://www.PacktPub.com. If you purchased this book elsewhere, you can visit http://www.PacktPub.com/support and register to have the files e-mailed directly to you.
United States
Great Britain
India
Germany
France
Canada
Russia
Spain
Brazil
Australia
Singapore
Hungary
Ukraine
Luxembourg
Estonia
Lithuania
South Korea
Turkey
Switzerland
Colombia
Taiwan
Chile
Norway
Ecuador
Indonesia
New Zealand
Cyprus
Denmark
Finland
Poland
Malta
Czechia
Austria
Sweden
Italy
Egypt
Belgium
Portugal
Slovenia
Ireland
Romania
Greece
Argentina
Netherlands
Bulgaria
Latvia
South Africa
Malaysia
Japan
Slovakia
Philippines
Mexico
Thailand
