/
About.html
171 lines (163 loc) · 8.62 KB
/
About.html
1
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"><html><head> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta name="GENERATOR" content="Mozilla/4.51 (Macintosh; I; PPC) [Netscape]"> <title>About Cython</title></head><body><center><h1><hr width="100%">Cython</h1></center><center><i><font size=+1>A language for writing Python extension modules</font></i><hr width="100%"></center><h2>What is Cython all about?</h2>Cython is a language specially designed for writing Python extension modules.It's designed to bridge the gap between the nice, high-level, easy-to-useworld of Python and the messy, low-level world of C.<p>You may be wondering why anyone would want a special language for this.Python is really easy to extend using C or C++, isn't it? Why not justwrite your extension modules in one of those languages?<p>Well, if you've ever written an extension module for Python, you'llknow that things are not as easy as all that. First of all, there is afair bit of boilerplate code to write before you can even get off the ground.Then you're faced with the problem of converting between Python and C datatypes. For the basic types such as numbers and strings this is not toobad, but anything more elaborate and you're into picking Python objectsapart using the Python/C API calls, which requires you to be meticulousabout maintaining reference counts, checking for errors at every step andcleaning up properly if anything goes wrong. Any mistakes and you havea nasty crash that's very difficult to debug.<p>Various tools have been developed to ease some of the burdens of producingextension code, of which perhaps <a href="http://www.swig.org">SWIG</a>is the best known. SWIG takes a definition file consisting of a mixtureof C code and specialised declarations, and produces an extension module.It writes all the boilerplate for you, and in many cases you can use itwithout knowing about the Python/C API. But you need to use API calls ifany substantial restructuring of the data is required between Python andC.<p>What's more, SWIG gives you no help at all if you want to create a newbuilt-in Python <i>type. </i>It will generate pure-Python classes whichwrap (in a slightly unsafe manner) pointers to C data structures, but creationof true extension types is outside its scope.<p>Another notable attempt at making it easier to extend Python is <a href="http://pyinline.sourceforge.net/">PyInline</a>, inspired by a similar facility for Perl. PyInline lets you embed piecesof C code in the midst of a Python file, and automatically extracts themand compiles them into an extension. But it only converts the basic typesautomatically, and as with SWIG, it doesn't address the creationof new Python types.<p>Cython aims to go far beyond what any of these previous tools provides.Cython deals with the basic types just as easily as SWIG, but it also letsyou write code to convert between arbitrary Python data structures andarbitrary C data structures, in a simple and natural way, without knowing<i>anything</i> about the Python/C API. That's right -- <i>nothing at all</i>!Nor do you have to worry about reference counting or error checking --it's all taken care of automatically, behind the scenes, just as it isin interpreted Python code. And what's more, Cython lets you define new<i>built-in</i> Python types just as easily as you can define new classesin Python.<p>Sound too good to be true? Read on and find out how it's done.<h2>The Basics of Cython</h2>The fundamental nature of Cython can be summed up as follows: <b>Cython isPython with C data types</b>.<p><i>Cython is Python:</i> Almost any piece of Python code is also validCython code. (There are a few limitations, but this approximation will servefor now.) The Cython compiler will convert it into C code which makes equivalentcalls to the Python/C API. In this respect, Cython is similar to the formerPython2C project (to which I would supply a reference except that it nolonger seems to exist).<p><i>...with C data types.</i> But Cython is much more than that, becauseparameters and variables can be declared to have C data types. Code whichmanipulates Python values and C values can be freely intermixed, with conversionsoccurring automatically wherever possible. Reference count maintenanceand error checking of Python operations is also automatic, and the fullpower of Python's exception handling facilities, including the try-exceptand try-finally statements, is available to you -- even in the midst ofmanipulating C data.<p>Here's a small example showing some of what can be done. It's a routinefor finding prime numbers. You tell it how many primes you want, and itreturns them as a Python list.<blockquote><b><tt><font size=+1>primes.pyx</font></tt></b></blockquote><blockquote><pre> 1 def primes(int kmax): 2 cdef int n, k, i 3 cdef int p[1000] 4 result = [] 5 if kmax > 1000: 6 kmax = 1000 7 k = 0 8 n = 2 9 while k < kmax:10 i = 011 while i < k and n % p[i] <> 0:12 i = i + 113 if i == k:14 p[k] = n15 k = k + 116 result.append(n)17 n = n + 118 return result</pre></blockquote>You'll see that it starts out just like a normal Python function definition,except that the parameter <b>kmax</b> is declared to be of type <b>int</b>. This means that the object passed will be converted to a C integer (ora TypeError will be raised if it can't be).<p>Lines 2 and 3 use the <b>cdef</b> statement to define some local C variables.Line 4 creates a Python list which will be used to return the result. You'llnotice that this is done exactly the same way it would be in Python. Becausethe variable <b>result</b> hasn't been given a type, it is assumed to holda Python object.<p>Lines 7-9 set up for a loop which will test candidate numbers for primenessuntil the required number of primes has been found. Lines 11-12, whichtry dividing a candidate by all the primes found so far, are of particularinterest. Because no Python objects are referred to, the loop is translatedentirely into C code, and thus runs very fast.<p>When a prime is found, lines 14-15 add it to the p array for fast accessby the testing loop, and line 16 adds it to the result list. Again, you'llnotice that line 16 looks very much like a Python statement, and in factit is, with the twist that the C parameter <b>n</b> is automatically convertedto a Python object before being passed to the <b>append</b> method. Finally,at line 18, a normal Python <b>return</b> statement returns the resultlist.<p>Compiling primes.pyx with the Cython compiler produces an extension modulewhich we can try out in the interactive interpreter as follows:<blockquote><pre>>>> import primes>>> primes.primes(10)[2, 3, 5, 7, 11, 13, 17, 19, 23, 29]>>></pre></blockquote>See, it works! And if you're curious about how much work Cython has savedyou, take a look at the <a href="primes.c">C code generated for this module</a>.<h2>Language Details</h2>For more about the Cython language, see the <a href="overview.html">LanguageOverview</a> .<h2>Future Plans</h2>Cython is not finished. Substantial tasks remaining include:<ul><li>Support for certain Python language features which are planned but notyet implemented. See the <a href="overview.html#Limitations">Limitations</a>section of the <a href="overview.html">Language Overview</a> for a currentlist.</li></ul><ul><li>C++ support. This could be a very big can of worms - careful thought requiredbefore going there.</li></ul><ul><li>Reading C/C++ header files directly would be very nice, but there are somesevere problems that I will have to find solutions for first, such as whatto do about preprocessor macros. My current thinking is to use a separatetool to convert .h files into Cython declarations, possibly with some manualintervention.</li></ul></body></html>