1 <!doctype html public "-//w3c//dtd html 4.0 transitional//en">
\r<html>
\r<head>
\r <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
\r <meta name="GENERATOR" content="Mozilla/4.51 (Macintosh; I; PPC) [Netscape]">
\r <title>About Cython</title>
\r</head>
\r<body>
\r\r<center>
\r<h1>
\r\r<hr width="100%">Cython</h1></center>
\r\r<center><i><font size=+1>A language for writing Python extension modules</font></i>
\r<hr width="100%"></center>
\r\r<h2>
\rWhat is Cython all about?</h2>
\rCython is a language specially designed for writing Python extension modules.
\rIt's designed to bridge the gap between the nice, high-level, easy-to-use
\rworld of Python and the messy, low-level world of C.
\r<p>You may be wondering why anyone would want a special language for this.
\rPython is really easy to extend using C or C++, isn't it? Why not just
\rwrite your extension modules in one of those languages?
\r<p>Well, if you've ever written an extension module for Python, you'll
\rknow that things are not as easy as all that. First of all, there is a
\rfair bit of boilerplate code to write before you can even get off the ground.
\rThen you're faced with the problem of converting between Python and C data
\rtypes. For the basic types such as numbers and strings this is not too
\rbad, but anything more elaborate and you're into picking Python objects
\rapart using the Python/C API calls, which requires you to be meticulous
\rabout maintaining reference counts, checking for errors at every step and
\rcleaning up properly if anything goes wrong. Any mistakes and you have
\ra nasty crash that's very difficult to debug.
\r<p>Various tools have been developed to ease some of the burdens of producing
\rextension code, of which perhaps <a href="http://www.swig.org">SWIG</a>
\ris the best known. SWIG takes a definition file consisting of a mixture
\rof C code and specialised declarations, and produces an extension module.
\rIt writes all the boilerplate for you, and in many cases you can use it
\rwithout knowing about the Python/C API. But you need to use API calls if
\rany substantial restructuring of the data is required between Python and
\rC.
\r<p>What's more, SWIG gives you no help at all if you want to create a new
\rbuilt-in Python <i>type. </i>It will generate pure-Python classes which
\rwrap (in a slightly unsafe manner) pointers to C data structures, but creation
\rof true extension types is outside its scope.
\r<p>Another notable attempt at making it easier to extend Python is <a href="http://pyinline.sourceforge.net/">PyInline</a>
\r, inspired by a similar facility for Perl. PyInline lets you embed pieces
\rof C code in the midst of a Python file, and automatically extracts them
\rand compiles them into an extension. But it only converts the basic types
\rautomatically, and as with SWIG, it doesn't address the creation
\rof new Python types.
\r<p>Cython aims to go far beyond what any of these previous tools provides.
\rCython deals with the basic types just as easily as SWIG, but it also lets
\ryou write code to convert between arbitrary Python data structures and
\rarbitrary C data structures, in a simple and natural way, without knowing
\r<i>anything</i> about the Python/C API. That's right -- <i>nothing at all</i>!
\rNor do you have to worry about reference counting or error checking --
\rit's all taken care of automatically, behind the scenes, just as it is
\rin interpreted Python code. And what's more, Cython lets you define new
\r<i>built-in</i> Python types just as easily as you can define new classes
\rin Python.
\r<p>Sound too good to be true? Read on and find out how it's done.
\r<h2>
\rThe Basics of Cython</h2>
\rThe fundamental nature of Cython can be summed up as follows: <b>Cython is
\rPython with C data types</b>.
\r<p><i>Cython is Python:</i> Almost any piece of Python code is also valid
\rCython code. (There are a few limitations, but this approximation will serve
\rfor now.) The Cython compiler will convert it into C code which makes equivalent
\rcalls to the Python/C API. In this respect, Cython is similar to the former
\rPython2C project (to which I would supply a reference except that it no
\rlonger seems to exist).
\r<p><i>...with C data types.</i> But Cython is much more than that, because
\rparameters and variables can be declared to have C data types. Code which
\rmanipulates Python values and C values can be freely intermixed, with conversions
\roccurring automatically wherever possible. Reference count maintenance
\rand error checking of Python operations is also automatic, and the full
\rpower of Python's exception handling facilities, including the try-except
\rand try-finally statements, is available to you -- even in the midst of
\rmanipulating C data.
\r<p>Here's a small example showing some of what can be done. It's a routine
\rfor finding prime numbers. You tell it how many primes you want, and it
\rreturns them as a Python list.
\r<blockquote><b><tt><font size=+1>primes.pyx</font></tt></b></blockquote>
\r\r<blockquote>
\r<pre> 1 def primes(int kmax):
\r 2 cdef int n, k, i
\r 3 cdef int p[1000]
\r 4 result = []
\r 5 if kmax > 1000:
\r 6 kmax = 1000
\r 7 k = 0
\r 8 n = 2
\r 9 while k < kmax:
\r10 i = 0
\r11 while i < k and n % p[i] <> 0:
\r12 i = i + 1
\r13 if i == k:
\r14 p[k] = n
\r15 k = k + 1
\r16 result.append(n)
\r17 n = n + 1
\r18 return result</pre>
\r</blockquote>
\rYou'll see that it starts out just like a normal Python function definition,
\rexcept that the parameter <b>kmax</b> is declared to be of type <b>int</b>
\r. This means that the object passed will be converted to a C integer (or
\ra TypeError will be raised if it can't be).
\r<p>Lines 2 and 3 use the <b>cdef</b> statement to define some local C variables.
\rLine 4 creates a Python list which will be used to return the result. You'll
\rnotice that this is done exactly the same way it would be in Python. Because
\rthe variable <b>result</b> hasn't been given a type, it is assumed to hold
\ra Python object.
\r<p>Lines 7-9 set up for a loop which will test candidate numbers for primeness
\runtil the required number of primes has been found. Lines 11-12, which
\rtry dividing a candidate by all the primes found so far, are of particular
\rinterest. Because no Python objects are referred to, the loop is translated
\rentirely into C code, and thus runs very fast.
\r<p>When a prime is found, lines 14-15 add it to the p array for fast access
\rby the testing loop, and line 16 adds it to the result list. Again, you'll
\rnotice that line 16 looks very much like a Python statement, and in fact
\rit is, with the twist that the C parameter <b>n</b> is automatically converted
\rto a Python object before being passed to the <b>append</b> method. Finally,
\rat line 18, a normal Python <b>return</b> statement returns the result
\rlist.
\r<p>Compiling primes.pyx with the Cython compiler produces an extension module
\rwhich we can try out in the interactive interpreter as follows:
\r<blockquote>
\r<pre>>>> import primes
\r>>> primes.primes(10)
\r[2, 3, 5, 7, 11, 13, 17, 19, 23, 29]
\r>>></pre>
\r</blockquote>
\rSee, it works! And if you're curious about how much work Cython has saved
\ryou, take a look at the <a href="primes.c">C code generated for this module</a>
\r.
\r<h2>
\rLanguage Details</h2>
\rFor more about the Cython language, see the <a href="overview.html">Language
\rOverview</a> .
\r<h2>
\rFuture Plans</h2>
\rCython is not finished. Substantial tasks remaining include:
\r<ul>
\r<li>
\rSupport for certain Python language features which are planned but not
\ryet implemented. See the <a href="overview.html#Limitations">Limitations</a>
\rsection of the <a href="overview.html">Language Overview</a> for a current
\rlist.</li>
\r</ul>
\r\r<ul>
\r<li>
\rC++ support. This could be a very big can of worms - careful thought required
\rbefore going there.</li>
\r</ul>
\r\r<ul>
\r<li>
\rReading C/C++ header files directly would be very nice, but there are some
\rsevere problems that I will have to find solutions for first, such as what
\rto do about preprocessor macros. My current thinking is to use a separate
\rtool to convert .h files into Cython declarations, possibly with some manual
\rintervention.</li>
\r</ul>
\r\r</body>
\r</html>
\r
projects / cython.git / blob