In this lecture, we will systematically go through the most important standard Cython language constructions.
We will not talk about using numpy from Cython, dynamic memory allocation, or subtleties of the C language in this lecture.
{{{id=4| /// }}}cdef type_name variable_name1, variable_name2, ...
The single most important statement that Cython adds to Python is
cdef type_name
. This allows you to declare a variable to have a type. The possibilities for the type include:
For the Cython source code of Sage integers, see /src/rings/integer.pxd and /src/rings/integer.pyx in the notebook. Also, browse /src/libs/gmp/ for the definition of functions such as mpz_set below.
{{{id=29| %cython from sage.rings.integer cimport Integer # note the cimport! def unsafe_mutate(Integer n, Integer m): mpz_set(n.value, m.value) /// }}} {{{id=28| n = 15 print n, id(n) unsafe_mutate(n, 2011) print n, id(n) /// 15 54852752 2011 54852752 }}} {{{id=3| /// }}}<data_type> foo
If you need to "brutally" force the compiler to treat a variable of one data type as another, you have to use an explicit cast. In Java and C/C++ you would use parenthesis around a type name, as follows:
int i = 1; long j = 3; i = (int)j;
But in Cython, you use angle brackets (note: in Cython this particular cast isn't strictly necessary, but in Java it is):
{{{id=37| %cython cdef int i = 1 cdef long j = 3 i =Here's an example where we convert a Python string to a char* (i.e., a pointer to an array of characters), then change one of the characters, thus mutating an immutable string.
{{{id=34| %cython def unsafe_mutate_str(bytes s, n, c): cdef char* t =In order for Cython to make use of a function or data type defined in external C/C++ library, Cython has to explicitly be told what the input and output types are for that function and what the function should be called. Cython will then generate appropriate C/C++ code and conversions based on these assumptions. There are a large number of files in Sage and Cython itself that declare all the functions provided by various standard libraries, but sometimes you want to make use of a function defined elsewhere, e.g., in your own C/C++ library, so you have to declare things yourself. The purpose of the following examples is to illustrate how to do this. It is also extremely useful to look at the Sage library source code for thousands of additional nontrivial working examples.
cdef extern from "filename.h":
declarations ...
The following examples illustrates several different possible declarations. We'll describe each line in detail.
This first example declares a single type of round function on doubles -- it's as straightforward as it gets.
{{{id=54| %cython cdef extern from "math.h": double round(double) def f(double n): return round(n) /// }}} {{{id=53| f(10.53595) /// 11.0 }}}Now suppose we want a version of round that returns a long. By consulting the man page for round, we find that there is a round function declared as follows:
long int lround(double x);
We can declare it exactly like the above, or we can use a C name specifier, which let's us tell Cython we want to call the function "round" in our Cython code, but when Cython generates code it should actually emit "lround". This is what we do below.
{{{id=56| %cython cdef extern from "math.h": long int round "lround"(double) def f(double n): return round(n) /// }}} {{{id=51| f(10.53595) /// 11 }}}Another case when using C name specifiers is useful if you want to be able to call both a C library version of a function and a builtin Python function with the same name.
{{{id=61| %cython cdef extern from "stdlib.h": int c_abs "abs"(int i) def myabs(n): print abs(n) print c_abs(n) /// }}} {{{id=62| myabs(-10) /// 10 10 }}}We can also declare data types and variables using extern. To write the code below, I used man several times on each referenced function. I knew the relevant functions because I read a book on the C programming language when I was a freshman; learning the basics of the C programming language and standard libraries is a very good idea if you want to be able to make effective use of Cython (or computers in general, since most systems programming is done in C).
Coming up with the declarations below is a little bit of an art form, in that they are not exactly what is given from the man pages, though they are close. Just realize that the declarations you give here do exactly one thing: they inform Cython about what C code it should generate, e.g., it will convert the "w" below to a char* before calling the fopen function. That's it -- that's all the declarations do. They do not have to be perfect. Click on the .html file below, and look at the corresponding C code, to see what I mean.
{{{id=63| %cython cdef extern from "stdio.h": ctypedef void FILE # use void if you don't care about internal structure FILE* fopen(char* filename, char* mode) int fclose(FILE *stream) int fprintf(FILE *stream, char *format, ...) def f(filename): cdef FILE* file file = fopen(filename, "w") fprintf(file, "Hi Mom!") fclose(file) /// }}} {{{id=60| f('foo.txt') print open('foo.txt').read() /// Hi Mom! }}} {{{id=58| /// }}} {{{id=8| /// }}}In addition to using the cdef keyword to define variables as above, we can also define functions. These are like Python functions, but you can declare the input types and the return type explicitly, and calling them is then blazingly fast, as compared to calling regular Python functions. (Remember, most of the point of Cython is speed.)
cdef return_type function_name(type1 input1, type2 input2...):{{{id=1| %cython cdef int add_cython(int a, int b): return a + b def add_python(int a, int b): return a + b def f(int n): cdef int i, s=0 for i in range(n): s += add_cython(s, i) return s def g(int n): cdef int i, s=0 for i in range(n): s += add_python(s, i) return s /// }}} {{{id=66| timeit('f(10^6)') /// 625 loops, best of 3: 595 µs per loop }}} {{{id=65| timeit('g(10^6)') /// 5 loops, best of 3: 94.6 ms per loop }}} {{{id=68| 94.6/.595 /// 158.991596638655 }}}
Notice that add_python is callable from the interpreter, but add_cython isn't:
{{{id=71| add_python(2,8) /// 10 }}} {{{id=69| add_cython(2,8) /// Traceback (most recent call last): File "If we use cpdef instead of cdef then everything is almost identical, except the cpdef'd method can also be called from Python. This is often extremely useful for testing and general usability. The cpdef method will be slightly slower though. In this example, it is about 4 times slower.
cpdef return_type function_name(type1 input1, type2 input2...):{{{id=73| %cython cpdef int add_cython2(int a, int b): return a + b def f2(int n): cdef int i, s=0 for i in range(n): s += add_cython2(s, i) return s /// }}} {{{id=74| timeit('f2(10^6)') /// 125 loops, best of 3: 2.63 ms per loop }}} {{{id=75| 2.63/.595 /// 4.42016806722689 }}} {{{id=76| add_cython2(2,8) /// 10 }}} {{{id=67| /// }}} {{{id=52| /// }}} {{{id=14| /// }}} {{{id=17| /// }}}
One of the most powerful features of Cython is that you can define new classes that have C-level attributes and cdef'd functions. The cdef'd attributed and function calls are very, very fast to use. Note that cdef'd classes in Cython can have at most one base class; there is no support for multiple inheritance.
cdef class ClassName(base_class):
cdef type_name variable
# ...
# Then functions mostly like a Python class, except
# you can include cdef'd methods with input and output
# types as in the previous section.
# ...
# There are some subtleties with special methods such
# as __add__ and __hash__; see the Cython documentation.
Here is an example in which we create a Cython class that wraps a Python string, and provides the ability of changing the entries of the string:
{{{id=20| %cython cdef class StringMutator: cdef bytes s # cdef's attribute def __init__(self, bytes s): self.s = s def __setitem__(self, int i, bytes a): if i < 0 or i >= len(self.s): raise IndexError if len(a) != 1: raise ValueError (