Commit 90b64b51 authored by William Stein's avatar William Stein

More Pyrex/SageX --> Cython changes

parent c4fa206b
......@@ -8,4 +8,6 @@ Cython, which derives from Pyrex, is licensed under the Python
Software Foundation License. More precisely, all modifications
made to go from Pyrex to Cython are so licensed.
See LICENSE.txt for more details.
from distutils.core import setup
from distutils.extension import Extension
from Pyrex.Distutils import build_ext
from Cython.Distutils import build_ext
setup(
name = 'Demos',
......
......@@ -4,7 +4,7 @@ PYINCLUDE = \
-I$(PYHOME)/$(ARCH)/include/python2.2
%.c: %.pyx
../../bin/pyrexc $<
../../bin/cython $<
%.o: %.c
gcc -c -fPIC $(PYINCLUDE) $<
......
from distutils.core import setup
from distutils.extension import Extension
from Pyrex.Distutils import build_ext
from Cython.Distutils import build_ext
setup(
name = 'callback',
......
<!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 Pyrex</title></head><body> <center><h1> <hr width="100%">Pyrex</h1></center> <center><i><font size=+1>A language for writing Python extension modules</font></i><hr width="100%"></center> <h2> What is Pyrex all about?</h2> Pyrex is a language specially designed for writing Python extension modules. It's designed to bridge the gap between the nice, high-level, easy-to-use world 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 just write your extension modules in one of those languages?<p>Well, if you've ever written an extension module for Python, you'll know that things are not as easy as all that. First of all, there is a fair 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 data types. For the basic types such as numbers and strings this is not too bad, but anything more elaborate and you're into picking Python objects apart using the Python/C API calls, which requires you to be meticulous about maintaining reference counts, checking for errors at every step and cleaning up properly if anything goes wrong. Any mistakes and you have a nasty crash that's very difficult to debug.<p>Various tools have been developed to ease some of the burdens of producing extension code, of which perhaps <a href="http://www.swig.org">SWIG</a> is the best known. SWIG takes a definition file consisting of a mixture of C code and specialised declarations, and produces an extension module. It writes all the boilerplate for you, and in many cases you can use it without knowing about the Python/C API. But you need to use API calls if any substantial restructuring of the data is required between Python and C.<p>What's more, SWIG gives you no help at all if you want to create a new built-in Python <i>type. </i>It will generate pure-Python classes which wrap (in a slightly unsafe manner) pointers to C data structures, but creation of 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 pieces of C code in the midst of a Python file, and automatically extracts them and compiles them into an extension. But it only converts the basic types automatically, and as with SWIG,&nbsp; it doesn't address the creation of new Python types.<p>Pyrex aims to go far beyond what any of these previous tools provides. Pyrex deals with the basic types just as easily as SWIG, but it also lets you write code to convert between arbitrary Python data structures and arbitrary 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 is in interpreted Python code. And what's more, Pyrex lets you define new<i>built-in</i> Python types just as easily as you can define new classes in Python.<p>Sound too good to be true? Read on and find out how it's done.<h2> The Basics of Pyrex</h2> The fundamental nature of Pyrex can be summed up as follows: <b>Pyrex is Python with C data types</b>.<p><i>Pyrex is Python:</i> Almost any piece of Python code is also valid Pyrex code. (There are a few limitations, but this approximation will serve for now.) The Pyrex compiler will convert it into C code which makes equivalent calls to the Python/C API. In this respect, Pyrex is similar to the former Python2C project (to which I would supply a reference except that it no longer seems to exist).<p><i>...with C data types.</i> But Pyrex is much more than that, because parameters and variables can be declared to have C data types. Code which manipulates Python values and C values can be freely intermixed, with conversions occurring automatically wherever possible. Reference count maintenance and error checking of Python operations is also automatic, and the full power of Python's exception handling facilities, including the try-except and try-finally statements, is available to you -- even in the midst of manipulating C data.<p>Here's a small example showing some of what can be done. It's a routine for finding prime numbers. You tell it how many primes you want, and it returns them as a Python list.<blockquote><b><tt><font size=+1>primes.pyx</font></tt></b></blockquote> <blockquote><pre>&nbsp;1&nbsp; def primes(int kmax):&nbsp;2&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; cdef int n, k, i&nbsp;3&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; cdef int p[1000]&nbsp;4&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; result = []&nbsp;5&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; if kmax > 1000:&nbsp;6&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; kmax = 1000&nbsp;7&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; k = 0&nbsp;8&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; n = 2&nbsp;9&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; while k &lt; kmax: 10&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; i = 0 11&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; while i &lt; k and n % p[i] &lt;> 0: 12&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; i = i + 1 13&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; if i == k: 14&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; p[k] = n 15&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; k = k + 1 16&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; result.append(n) 17&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; n = n + 1 18&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 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 (or a 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'll notice that this is done exactly the same way it would be in Python. Because the variable <b>result</b> hasn't been given a type, it is assumed to hold a Python object.<p>Lines 7-9 set up for a loop which will test candidate numbers for primeness until the required number of primes has been found. Lines 11-12, which try dividing a candidate by all the primes found so far, are of particular interest. Because no Python objects are referred to, the loop is translated entirely 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 access by the testing loop, and line 16 adds it to the result list. Again, you'll notice that line 16 looks very much like a Python statement, and in fact it is, with the twist that the C parameter <b>n</b> is automatically converted to 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 result list.<p>Compiling primes.pyx with the Pyrex compiler produces an extension module which 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 Pyrex has saved you, take a look at the <a href="primes.c">C code generated for this module</a> .<h2> Language Details</h2> For more about the Pyrex language, see the <a href="overview.html">Language Overview</a> .<h2> Future Plans</h2> Pyrex is not finished. Substantial tasks remaining include:<ul><li> Support for certain Python language features which are planned but not yet implemented. See the <a href="overview.html#Limitations">Limitations</a> section of the <a href="overview.html">Language Overview</a> for a current list.</li></ul> <ul><li> C++ support. This could be a very big can of worms - careful thought required before going there.</li></ul> <ul><li> Reading C/C++ header files directly would be very nice, but there are some severe problems that I will have to find solutions for first, such as what to do about preprocessor macros. My current thinking is to use a separate tool to convert .h files into Pyrex declarations, possibly with some manual intervention.</li></ul> </body></html>
\ No newline at end of file
<!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-use world 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 just write your extension modules in one of those languages?<p>Well, if you've ever written an extension module for Python, you'll know that things are not as easy as all that. First of all, there is a fair 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 data types. For the basic types such as numbers and strings this is not too bad, but anything more elaborate and you're into picking Python objects apart using the Python/C API calls, which requires you to be meticulous about maintaining reference counts, checking for errors at every step and cleaning up properly if anything goes wrong. Any mistakes and you have a nasty crash that's very difficult to debug.<p>Various tools have been developed to ease some of the burdens of producing extension code, of which perhaps <a href="http://www.swig.org">SWIG</a> is the best known. SWIG takes a definition file consisting of a mixture of C code and specialised declarations, and produces an extension module. It writes all the boilerplate for you, and in many cases you can use it without knowing about the Python/C API. But you need to use API calls if any substantial restructuring of the data is required between Python and C.<p>What's more, SWIG gives you no help at all if you want to create a new built-in Python <i>type. </i>It will generate pure-Python classes which wrap (in a slightly unsafe manner) pointers to C data structures, but creation of 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 pieces of C code in the midst of a Python file, and automatically extracts them and compiles them into an extension. But it only converts the basic types automatically, and as with SWIG,&nbsp; it doesn't address the creation of 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 lets you write code to convert between arbitrary Python data structures and arbitrary 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 is in 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 classes in 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 is Python with C data types</b>.<p><i>Cython is Python:</i> Almost any piece of Python code is also valid Cython code. (There are a few limitations, but this approximation will serve for now.) The Cython compiler will convert it into C code which makes equivalent calls to the Python/C API. In this respect, Cython is similar to the former Python2C project (to which I would supply a reference except that it no longer seems to exist).<p><i>...with C data types.</i> But Cython is much more than that, because parameters and variables can be declared to have C data types. Code which manipulates Python values and C values can be freely intermixed, with conversions occurring automatically wherever possible. Reference count maintenance and error checking of Python operations is also automatic, and the full power of Python's exception handling facilities, including the try-except and try-finally statements, is available to you -- even in the midst of manipulating C data.<p>Here's a small example showing some of what can be done. It's a routine for finding prime numbers. You tell it how many primes you want, and it returns them as a Python list.<blockquote><b><tt><font size=+1>primes.pyx</font></tt></b></blockquote> <blockquote><pre>&nbsp;1&nbsp; def primes(int kmax):&nbsp;2&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; cdef int n, k, i&nbsp;3&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; cdef int p[1000]&nbsp;4&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; result = []&nbsp;5&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; if kmax > 1000:&nbsp;6&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; kmax = 1000&nbsp;7&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; k = 0&nbsp;8&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; n = 2&nbsp;9&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; while k &lt; kmax: 10&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; i = 0 11&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; while i &lt; k and n % p[i] &lt;> 0: 12&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; i = i + 1 13&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; if i == k: 14&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; p[k] = n 15&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; k = k + 1 16&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; result.append(n) 17&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; n = n + 1 18&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 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 (or a 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'll notice that this is done exactly the same way it would be in Python. Because the variable <b>result</b> hasn't been given a type, it is assumed to hold a Python object.<p>Lines 7-9 set up for a loop which will test candidate numbers for primeness until the required number of primes has been found. Lines 11-12, which try dividing a candidate by all the primes found so far, are of particular interest. Because no Python objects are referred to, the loop is translated entirely 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 access by the testing loop, and line 16 adds it to the result list. Again, you'll notice that line 16 looks very much like a Python statement, and in fact it is, with the twist that the C parameter <b>n</b> is automatically converted to 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 result list.<p>Compiling primes.pyx with the Cython compiler produces an extension module which 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 saved you, 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">Language Overview</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 not yet implemented. See the <a href="overview.html#Limitations">Limitations</a> section of the <a href="overview.html">Language Overview</a> for a current list.</li></ul> <ul><li> C++ support. This could be a very big can of worms - careful thought required before going there.</li></ul> <ul><li> Reading C/C++ header files directly would be very nice, but there are some severe problems that I will have to find solutions for first, such as what to do about preprocessor macros. My current thinking is to use a separate tool to convert .h files into Cython declarations, possibly with some manual intervention.</li></ul> </body></html>
\ No newline at end of file
......
......@@ -4,7 +4,7 @@
<meta name="GENERATOR" content="Mozilla/4.51 (Macintosh; I; PPC) [Netscape]"><title>FAQ.html</title></head>
<body>
<center> <h1> <hr width="100%">Pyrex FAQ
<center> <h1> <hr width="100%">Cython FAQ
<hr width="100%"></h1>
</center>
<h2> Contents</h2>
......@@ -14,7 +14,7 @@
bytes to a Python string?</a></b></li>
<li> <b><a href="#NumericAccess">How do I access the data inside a Numeric
array object?</a></b></li>
<li><b><a href="#Rhubarb">Pyrex says my extension type object has no attribute
<li><b><a href="#Rhubarb">Cython says my extension type object has no attribute
'rhubarb', but I know it does. What gives?</a></b></li><li><a style="font-weight: bold;" href="#Quack">Python says my extension type has no method called 'quack', but I know it does. What gives?</a><br>
</li>
......@@ -55,10 +55,10 @@ bytes to a Python string?</h2>
section of the <a href="extension_types.html">"Extension Types"</a> documentation
page.<br>
<tt> </tt> </p>
<h2><a name="Rhubarb"></a>Pyrex says my extension type object has no attribute
<h2><a name="Rhubarb"></a>Cython says my extension type object has no attribute
'rhubarb', but I know it does. What gives?</h2>
You're probably trying to access it through a reference which Pyrex thinks
is a generic Python object. You need to tell Pyrex that it's a reference
You're probably trying to access it through a reference which Cython thinks
is a generic Python object. You need to tell Cython that it's a reference
to your extension type by means of a declaration,<br>
for example,<br>
<blockquote><tt>cdef class Vegetables:</tt><br>
......
......@@ -31,7 +31,7 @@
</ul>
<h2> <a name="Introduction"></a>Introduction</h2>
As well as creating normal user-defined classes with the Python <b>class</b>
statement, Pyrex also lets you create new built-in Python types, known as
statement, Cython also lets you create new built-in Python types, known as
<i>extension types</i>. You define an extension type using the <b>cdef class</b> statement. Here's an example:
<blockquote><tt>cdef class Shrubbery:</tt> <p><tt>&nbsp;&nbsp;&nbsp; cdef int width, height</tt> </p>
<p><tt>&nbsp;&nbsp;&nbsp; def __init__(self, w, h):</tt> <br>
......@@ -43,7 +43,7 @@ self.width, \</tt> <br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
"by", self.height, "cubits."</tt></p>
</blockquote>
As you can see, a Pyrex extension type definition looks a lot like a Python
As you can see, a Cython extension type definition looks a lot like a Python
class definition. Within it, you use the <b>def</b> statement to define
methods that can be called from Python code. You can even define many of
the special methods such as <tt>__init__</tt> as you would in Python.
......@@ -59,9 +59,9 @@ to an extension type instance at run time simply by assigning to them, as
you could with a Python class instance. (You can subclass the extension type
in Python and add attributes to instances of the subclass, however.)
<p>There are two ways that attributes of an extension type can be accessed:
by Python attribute lookup, or by direct access to the C struct from Pyrex
by Python attribute lookup, or by direct access to the C struct from Cython
code. Python code is only able to access attributes of an extension type
by the first method, but Pyrex code can use either method. </p>
by the first method, but Cython code can use either method. </p>
<p>By default, extension type attributes are only accessible by direct access,
not Python access, which means that they are not accessible from Python code.
To make them accessible from Python code, you need to declare them as <tt>public</tt> or <tt>readonly</tt>. For example, </p>
......@@ -79,7 +79,7 @@ To make them accessible from Python code, you need to declare them as <tt>public
<p>Note also that the <tt>public</tt> and <tt>readonly</tt> options apply
only to <i>Python</i> access, not direct access. All the attributes of an
extension type are always readable and writable by direct access. </p>
<p>Howerver, for direct access to be possible, the Pyrex compiler must know
<p>Howerver, for direct access to be possible, the Cython compiler must know
that you have an instance of that type, and not just a generic Python object.
It knows this already in the case of the "self" parameter of the methods of
that type, but in other cases you will have to tell it by means of a declaration.
......@@ -87,19 +87,19 @@ For example, </p>
<blockquote><tt>cdef widen_shrubbery(Shrubbery sh, extra_width):</tt> <br>
<tt>&nbsp;&nbsp;&nbsp; sh.width = sh.width + extra_width</tt></blockquote>
If you attempt to access an extension type attribute through a generic
object reference, Pyrex will use a Python attribute lookup. If the attribute
object reference, Cython will use a Python attribute lookup. If the attribute
is exposed for Python access (using <tt>public</tt> or <tt>readonly</tt>)
then this will work, but it will be much slower than direct access.
<h2> <a name="NotNone"></a>Extension types and None</h2>
When you declare a parameter or C variable as being of an extension type,
Pyrex will allow it to take on the value None as well as values of its declared
Cython will allow it to take on the value None as well as values of its declared
type. This is analogous to the way a C pointer can take on the value NULL,
and you need to exercise the same caution because of it. There is no problem
as long as you are performing Python operations on it, because full dynamic
type checking will be applied. However, when you access C attributes of an
extension type (as in the <tt>widen_shrubbery</tt> function above), it's up
to you to make sure the reference you're using is not None -- in the interests
of efficiency, Pyrex does <i>not</i> check this.
of efficiency, Cython does <i>not</i> check this.
<p>You need to be particularly careful when exposing Python functions which
take extension types as arguments. If we wanted to make <tt>widen_shrubbery</tt>
a Python function, for example, if we simply wrote </p>
......@@ -113,7 +113,7 @@ parameter.
<tt>&nbsp;&nbsp;&nbsp; if sh is None:</tt> <br>
<tt>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; raise TypeError</tt> <br>
<tt>&nbsp;&nbsp;&nbsp; sh.width = sh.width + extra_width</tt></blockquote>
but since this is anticipated to be such a frequent requirement, Pyrex
but since this is anticipated to be such a frequent requirement, Cython
provides a more convenient way. Parameters of a Python function declared
as an extension type can have a <b><tt>not None</tt></b> clause:
<blockquote><tt>def widen_shrubbery(Shrubbery sh not None, extra_width):</tt>
......@@ -223,14 +223,14 @@ type:
<tt>&nbsp;&nbsp;&nbsp; ...</tt></p>
</blockquote>
<p><br>
A complete definition of the base type must be available to Pyrex, so if
A complete definition of the base type must be available to Cython, so if
the base type is a built-in type, it must have been previously declared as
an <b>extern</b> extension type. If the base type is defined in another Pyrex
an <b>extern</b> extension type. If the base type is defined in another Cython
module, it must either be declared as an extern extension type or imported
using the <b><a href="sharing.html">cimport</a></b> statement. </p>
<p>An extension type can only have one base class (no multiple inheritance).
</p>
<p>Pyrex extension types can also be subclassed in Python. A Python class
<p>Cython extension types can also be subclassed in Python. A Python class
can inherit from multiple extension types provided that the usual Python
rules for multiple inheritance are followed (i.e. the C layouts of all the
base classes must be compatible).<br>
......@@ -316,18 +316,18 @@ type <span style="font-family: monospace;">object</span> called <span style="fon
<h2><a name="PublicAndExtern"></a>Public and external extension types</h2>
Extension types can be declared <b>extern</b> or <b>public</b>. An <a href="#ExternalExtTypes"><b>extern</b> extension type declaration</a> makes
an extension type defined in external C code available to a Pyrex module.
A <a href="#PublicExtensionTypes"><b>public</b> extension type declaration</a> makes an extension type defined in a Pyrex module available to external C
an extension type defined in external C code available to a Cython module.
A <a href="#PublicExtensionTypes"><b>public</b> extension type declaration</a> makes an extension type defined in a Cython module available to external C
code.
<h3> <a name="ExternalExtTypes"></a>External extension types</h3>
An <b>extern</b> extension type allows you to gain access to the internals
of Python objects defined in the Python core or in a non-Pyrex extension
of Python objects defined in the Python core or in a non-Cython extension
module.
<blockquote><b>NOTE:</b> In Pyrex versions before 0.8, <b>extern</b> extension
types were also used to reference extension types defined in another Pyrex
module. While you can still do that, Pyrex 0.8 and later provides a better
<blockquote><b>NOTE:</b> In Cython versions before 0.8, <b>extern</b> extension
types were also used to reference extension types defined in another Cython
module. While you can still do that, Cython 0.8 and later provides a better
mechanism for this. See <a href="sharing.html">Sharing C Declarations Between
Pyrex Modules</a>.</blockquote>
Cython Modules</a>.</blockquote>
Here is an example which will let you get at the C-level members of the
built-in <i>complex</i> object.
<blockquote><tt>cdef extern from "complexobject.h":</tt> <p><tt>&nbsp;&nbsp;&nbsp; struct Py_complex:</tt> <br>
......@@ -365,11 +365,11 @@ if your extension class declaration is inside a <i>cdef extern from</i> block,
</ol>
<h3> <a name="ImplicitImport"></a>Implicit importing</h3>
<blockquote><font color="#ef1f1d">Backwards Incompatibility Note</font>:
You will have to update any pre-0.8 Pyrex modules you have which use <b>extern</b>
You will have to update any pre-0.8 Cython modules you have which use <b>extern</b>
extension types. I apologise for this, but for complicated reasons it proved
to be too difficult to continue supporting the old way of doing these while
introducing the new features that I wanted.</blockquote>
Pyrex 0.8 and later requires you to include a module name in an extern
Cython 0.8 and later requires you to include a module name in an extern
extension class declaration, for example,
<blockquote><tt>cdef extern class MyModule.Spam:</tt> <br>
<tt>&nbsp;&nbsp;&nbsp; ...</tt></blockquote>
......@@ -394,7 +394,7 @@ using an <b>as</b> clause, for example,
<pre>from <tt>My.Nested.Package</tt> import <tt>Spam</tt> as <tt>Yummy</tt></pre>
</ol>
<h3> <a name="TypeVsConstructor"></a>Type names vs. constructor names</h3>
Inside a Pyrex module, the name of an extension type serves two distinct
Inside a Cython module, the name of an extension type serves two distinct
purposes. When used in an expression, it refers to a module-level global
variable holding the type's constructor (i.e. its type-object). However,
it can also be used as a C type name to declare variables, arguments and
......@@ -429,12 +429,12 @@ struct, and <i>type_object_name</i> is the name to assume for the type's
statically declared type object. (The object and type clauses can be written
in either order.)
<p>If the extension type declaration is inside a <b>cdef extern from</b>
block, the <b>object</b> clause is required, because Pyrex must be able to
block, the <b>object</b> clause is required, because Cython must be able to
generate code that is compatible with the declarations in the header file.
Otherwise, for <b>extern</b> extension types, the <b>object</b> clause is
optional. </p>
<p>For <b>public</b> extension types, the <b>object</b> and <b>type</b> clauses
are both required, because Pyrex must be able to generate code that is compatible
are both required, because Cython must be able to generate code that is compatible
with external C code. </p>
<p> </p>
<hr width="100%"> <br>
......
<!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>Pyrex - Front Page</title></head><body>&nbsp;<table CELLSPACING=0 CELLPADDING=10 WIDTH="500" ><tr><td VALIGN=TOP BGCOLOR="#FF9218"><font face="Arial,Helvetica"><font size=+4>Pyrex</font></font></td> <td ALIGN=RIGHT VALIGN=TOP WIDTH="200" BGCOLOR="#5DBACA"><font face="Arial,Helvetica"><font size=+1>A smooth blend of the finest Python&nbsp;</font></font><br><font face="Arial,Helvetica"><font size=+1>with the unsurpassed power&nbsp;</font></font><br><font face="Arial,Helvetica"><font size=+1>of raw C.</font></font></td></tr></table> <blockquote><font size=+1>Welcome to Pyrex, a language for writing Python extension modules. Pyrex makes creating an extension module is almost as easy as creating a Python module! To find out more, consult one of the edifying documents below.</font></blockquote> <h1><font face="Arial,Helvetica"><font size=+2>Documentation</font></font></h1> <blockquote><h2><font face="Arial,Helvetica"><font size=+1><a href="About.html">About Pyrex</a></font></font></h2> <blockquote><font size=+1>Read this to find out what Pyrex is all about and what it can do for you.</font></blockquote> <h2><font face="Arial,Helvetica"><font size=+1><a href="overview.html">Language Overview</a></font></font></h2> <blockquote><font size=+1>A description of all the features of the Pyrex language. This is the closest thing to a reference manual in existence yet.</font></blockquote> <h2><font face="Arial,Helvetica"><font size=+1><a href="FAQ.html">FAQ</a></font></font></h2> <blockquote><font size=+1>Want to know how to do something in Pyrex? Check here first<font face="Arial,Helvetica">.</font></font></blockquote></blockquote> <h1><font face="Arial,Helvetica"><font size=+2>Other Resources</font></font></h1> <blockquote><h2><font face="Arial,Helvetica"><font size=+1><a href="http://www.cosc.canterbury.ac.nz/~greg/python/Pyrex/mpj17-pyrex-guide/">Michael's Quick Guide to Pyrex</a></font></font></h2> <blockquote><font size=+1>This tutorial-style presentation will take you through the steps of creating some Pyrex modules to wrap existing C libraries. Contributed by <a href="mailto:mpj17@cosc.canterbury.ac.nz">Michael JasonSmith</a>.</font></blockquote> <h2><font face="Arial,Helvetica"><font size=+1><a href="mailto:greg@cosc.canterbury.ac.nz">Mail to the Author</a></font></font></h2> <blockquote><font size=+1>If you have a question that's not answered by anything here, you're not sure about something, or you have a bug to report or a suggestion to make, or anything at all to say about Pyrex, feel free to email me:<font face="Arial,Helvetica"> </font><tt><a href="mailto:greg@cosc.canterbury.ac.nz">greg@cosc.canterbury.ac.nz</a></tt></font></blockquote></blockquote> </body></html>
\ No newline at end of file
<!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>Cython - Front Page</title></head><body>&nbsp;<table CELLSPACING=0 CELLPADDING=10 WIDTH="500" ><tr><td VALIGN=TOP BGCOLOR="#FF9218"><font face="Arial,Helvetica"><font size=+4>Cython</font></font></td> <td ALIGN=RIGHT VALIGN=TOP WIDTH="200" BGCOLOR="#5DBACA"><font face="Arial,Helvetica"><font size=+1>A smooth blend of the finest Python&nbsp;</font></font><br><font face="Arial,Helvetica"><font size=+1>with the unsurpassed power&nbsp;</font></font><br><font face="Arial,Helvetica"><font size=+1>of raw C.</font></font></td></tr></table> <blockquote><font size=+1>Welcome to Cython, a language for writing Python extension modules. Cython makes creating an extension module is almost as easy as creating a Python module! To find out more, consult one of the edifying documents below.</font></blockquote> <h1><font face="Arial,Helvetica"><font size=+2>Documentation</font></font></h1> <blockquote><h2><font face="Arial,Helvetica"><font size=+1><a href="About.html">About Cython</a></font></font></h2> <blockquote><font size=+1>Read this to find out what Cython is all about and what it can do for you.</font></blockquote> <h2><font face="Arial,Helvetica"><font size=+1><a href="overview.html">Language Overview</a></font></font></h2> <blockquote><font size=+1>A description of all the features of the Cython language. This is the closest thing to a reference manual in existence yet.</font></blockquote> <h2><font face="Arial,Helvetica"><font size=+1><a href="FAQ.html">FAQ</a></font></font></h2> <blockquote><font size=+1>Want to know how to do something in Cython? Check here first<font face="Arial,Helvetica">.</font></font></blockquote></blockquote> <h1><font face="Arial,Helvetica"><font size=+2>Other Resources</font></font></h1> <blockquote><h2><font face="Arial,Helvetica"><font size=+1><a href="http://www.cosc.canterbury.ac.nz/~greg/python/Cython/mpj17-pyrex-guide/">Michael's Quick Guide to Cython</a></font></font></h2> <blockquote><font size=+1>This tutorial-style presentation will take you through the steps of creating some Cython modules to wrap existing C libraries. Contributed by <a href="mailto:mpj17@cosc.canterbury.ac.nz">Michael JasonSmith</a>.</font></blockquote> <h2><font face="Arial,Helvetica"><font size=+1><a href="mailto:greg@cosc.canterbury.ac.nz">Mail to the Author</a></font></font></h2> <blockquote><font size=+1>If you have a question that's not answered by anything here, you're not sure about something, or you have a bug to report or a suggestion to make, or anything at all to say about Cython, feel free to email me:<font face="Arial,Helvetica"> </font><tt><a href="mailto:greg@cosc.canterbury.ac.nz">greg@cosc.canterbury.ac.nz</a></tt></font></blockquote></blockquote> </body></html>
\ No newline at end of file
......
......@@ -5,14 +5,14 @@
<meta name="GENERATOR" content="Mozilla/4.61 (Macintosh; I; PPC) [Netscape]">
<title>Pyrex Language Overview</title>
<title>Cython Language Overview</title>
</head>
<body>
<h1> <hr width="100%">Overview of the Pyrex Language&nbsp; <hr width="100%"></h1>
<h1> <hr width="100%">Overview of the Cython Language&nbsp; <hr width="100%"></h1>
This document informally describes the extensions to the Python language
made by Pyrex. Some day there will be a reference manual covering everything
made by Cython. Some day there will be a reference manual covering everything
in more detail. <br>
&nbsp;
......@@ -33,14 +33,14 @@
<li> <a href="#ScopeRules">Scope rules</a></li>
<li> <a href="#StatsAndExprs">Statements and expressions</a></li>
<ul>
<li> <a href="#ExprSyntaxDifferences">Differences between C and Pyrex
<li> <a href="#ExprSyntaxDifferences">Differences between C and Cython
expressions<br>
</a></li>
<li> <a href="#ForFromLoop">Integer for-loops</a></li>
</ul>
<li> <a href="#ExceptionValues">Error return values</a></li>
<ul>
<li> <a href="#CheckingReturnValues">Checking return values of non-Pyrex
<li> <a href="#CheckingReturnValues">Checking return values of non-Cython
functions</a></li>
</ul>
<li> <a href="#IncludeStatement">The <tt>include</tt> statement</a></li>
......@@ -57,13 +57,13 @@ expressions<br>
<li> <a href="#PublicDecls">Public declarations</a></li>
</ul>
<li> <a href="extension_types.html">Extension Types</a> <font color="#006600">(Section revised in 0.9)</font></li>
<li> <a href="sharing.html">Sharing Declarations Between Pyrex Modules</a>
<li> <a href="sharing.html">Sharing Declarations Between Cython Modules</a>
<font color="#006600">(NEW in 0.8)</font></li>
<li> <a href="#Limitations">Limitations</a></li>
<ul>
<li> <a href="#Unsupported">Unsupported Python features</a></li>
<li> <a href="#SemanticDifferences">Semantic differences between Python
and Pyrex</a></li>
and Cython</a></li>
</ul>
</ul>
......@@ -72,13 +72,13 @@ expressions<br>
<h2> <hr width="100%"><a name="Basics"></a>Basics
<hr width="100%"></h2>
This section describes the basic features of the Pyrex language. The facilities
This section describes the basic features of the Cython language. The facilities
covered in this section allow you to create Python-callable functions that
manipulate C data structures and convert between Python and C data types.
Later sections will cover facilities for <a href="#InterfacingWithExternal">wrapping external C code</a>, <a href="extension_types.html">creating new Python types</a> and <a href="sharing.html">cooperation between Pyrex modules</a>.
Later sections will cover facilities for <a href="#InterfacingWithExternal">wrapping external C code</a>, <a href="extension_types.html">creating new Python types</a> and <a href="sharing.html">cooperation between Cython modules</a>.
<h3> <a name="PyFuncsVsCFuncs"></a>Python functions vs. C functions</h3>
There are two kinds of function definition in Pyrex:
There are two kinds of function definition in Cython:
<p><b>Python functions</b> are defined using the <b>def</b> statement, as
in Python. They take Python objects as parameters and return Python objects.
</p>
......@@ -89,10 +89,10 @@ expressions<br>
Python objects or C values. </p>
<p>Within a Pyrex module, Python functions and C functions can call each other
<p>Within a Cython module, Python functions and C functions can call each other
freely, but only Python functions can be called from outside the module by
interpreted Python code. So, any functions that you want to "export" from
your Pyrex module must be declared as Python functions using <span style="font-weight: bold;">def</span>. </p>
your Cython module must be declared as Python functions using <span style="font-weight: bold;">def</span>. </p>
<p>Parameters of either type of function can be declared to have C data types,
......@@ -259,16 +259,16 @@ string.<br>
<br>
Pyrex detects and prevents <span style="font-style: italic;">some</span> mistakes of this kind. For instance, if you attempt something like<br>
Cython detects and prevents <span style="font-style: italic;">some</span> mistakes of this kind. For instance, if you attempt something like<br>
<pre style="margin-left: 40px;">cdef char *s<br>s = pystring1 + pystring2</pre>
then Pyrex will produce the error message "<span style="font-weight: bold;">Obtaining char * from temporary Python value</span>".
then Cython will produce the error message "<span style="font-weight: bold;">Obtaining char * from temporary Python value</span>".
The reason is that concatenating the two Python strings produces a new
Python string object that is referenced only by a temporary internal
variable that Pyrex generates. As soon as the statement has finished,
variable that Cython generates. As soon as the statement has finished,
the temporary variable will be decrefed and the Python string
deallocated, leaving <span style="font-family: monospace;">s</span> dangling. Since this code could not possibly work, Pyrex refuses to compile it.<br>
deallocated, leaving <span style="font-family: monospace;">s</span> dangling. Since this code could not possibly work, Cython refuses to compile it.<br>
<br>
......@@ -281,7 +281,7 @@ It is then your responsibility to hold the reference <span style="font-family: m
<br>
Keep in mind that the rules used to detect such errors are only
heuristics. Sometimes Pyrex will complain unnecessarily, and sometimes
heuristics. Sometimes Cython will complain unnecessarily, and sometimes
it will fail to detect a problem that exists. Ultimately, you need to
understand the issue and be careful what you do.<br>
......@@ -292,7 +292,7 @@ understand the issue and be careful what you do.<br>
<h3> <a name="ScopeRules"></a>Scope rules</h3>
Pyrex determines whether a variable belongs to a local scope, the module
Cython determines whether a variable belongs to a local scope, the module
scope, or the built-in scope <i>completely statically.</i> As with Python,
assigning to a variable which is not otherwise declared implicitly declares
it to be a Python variable residing in the scope where it is assigned. Unlike
......@@ -316,7 +316,7 @@ the builtins module.<br>
Note: A consequence of these rules is that the module-level scope behaves
the same way as a Python local scope if you refer to a variable before assigning
to it. In particular, tricks such as the following will <i>not</i> work
in Pyrex:<br>
in Cython:<br>
<blockquote> <pre>try:<br>&nbsp; x = True<br>except NameError:<br>&nbsp; True = 1<br></pre>
......@@ -347,21 +347,21 @@ all Python operations are automatically checked for errors, with appropriate
action taken. </p>
<h4> <a name="ExprSyntaxDifferences"></a>Differences between C and Pyrex
<h4> <a name="ExprSyntaxDifferences"></a>Differences between C and Cython
expressions</h4>
There
are some differences in syntax and semantics between C expressions and
Pyrex expressions, particularly in the area of C constructs which have
Cython expressions, particularly in the area of C constructs which have
no direct equivalent in Python.<br>
<ul>
<li>An integer literal without an <span style="font-family: monospace; font-weight: bold;">L</span> suffix is treated as a C constant, and will be truncated to whatever size your C compiler thinks appropriate. With an <span style="font-family: monospace; font-weight: bold;">L</span> suffix, it will be converted to Python long integer (even if it would be small enough to fit into a C int).<br>
<br>
</li>
<li> There is no <b><tt>-&gt;</tt></b> operator in Pyrex. Instead of <tt>p-&gt;x</tt>,
<li> There is no <b><tt>-&gt;</tt></b> operator in Cython. Instead of <tt>p-&gt;x</tt>,
use <tt>p.x</tt></li>
&nbsp; <li> There is no <b><tt>*</tt></b> operator in Pyrex. Instead of
&nbsp; <li> There is no <b><tt>*</tt></b> operator in Cython. Instead of
<tt>*p</tt>, use <tt>p[0]</tt></li>
&nbsp; <li> There is an <b><tt>&amp;</tt></b> operator, with the same semantics
......@@ -380,7 +380,7 @@ example:</li>
<pre>cdef char *p, float *q<br>p = &lt;char*&gt;q</pre>
</ul>
<i><b>Warning</b>: Don't attempt to use a typecast to convert between
Python and C data types -- it won't do the right thing. Leave Pyrex to perform
Python and C data types -- it won't do the right thing. Leave Cython to perform
the conversion automatically.</i>
</ul>
......@@ -393,12 +393,12 @@ the conversion automatically.</i>
won't be very fast, even if <tt>i</tt> and <tt>n</tt> are declared as
C integers, because <tt>range</tt> is a Python function. For iterating over
ranges of integers, Pyrex has another form of for-loop:
ranges of integers, Cython has another form of for-loop:
<blockquote><tt>for i from 0 &lt;= i &lt; n:</tt> <br>
<tt>&nbsp;&nbsp;&nbsp; ...</tt></blockquote>
If the loop variable and the lower and upper bounds are all C integers,
this form of loop will be much faster, because Pyrex will translate it into
this form of loop will be much faster, because Cython will translate it into
pure C code.
<p>Some things to note about the <tt>for-from</tt> loop: </p>
......@@ -446,7 +446,7 @@ of exception value declaration: </p>
<blockquote><tt>cdef int spam() except? -1:</tt> <br>
<tt>&nbsp;&nbsp;&nbsp; ...</tt></blockquote>
The "?" indicates that the value <tt>-1</tt> only indicates a <i>possible</i> error. In this case, Pyrex generates a call to <tt>PyErr_Occurred</tt>if the
The "?" indicates that the value <tt>-1</tt> only indicates a <i>possible</i> error. In this case, Cython generates a call to <tt>PyErr_Occurred</tt>if the
exception value is returned, to make sure it really is an error.
<p>There is also a third form of exception value declaration: </p>
......@@ -454,7 +454,7 @@ exception value is returned, to make sure it really is an error.
<blockquote><tt>cdef int spam() except *:</tt> <br>
<tt>&nbsp;&nbsp;&nbsp; ...</tt></blockquote>
This form causes Pyrex to generate a call to <tt>PyErr_Occurred</tt> after
This form causes Cython to generate a call to <tt>PyErr_Occurred</tt> after
<i>every</i> call to spam, regardless of what value it returns. If you have
a function returning <tt>void</tt> that needs to propagate errors, you will
have to use this form, since there isn't any return value to test.
......@@ -484,7 +484,7 @@ is an example of a pointer-to-function declaration with an exception value:</li>
</ul>
<h4> <a name="CheckingReturnValues"></a>Checking return values of non-Pyrex
<h4> <a name="CheckingReturnValues"></a>Checking return values of non-Cython
functions</h4>
It's important to understand that the <tt>except</tt> clause does <i>not</i> cause an error to be <i>raised</i> when the specified value is returned. For
......@@ -495,7 +495,7 @@ example, you can't write something like
and expect an exception to be automatically raised if a call to fopen
returns NULL. The except clause doesn't work that way; its only purpose
is for <i>propagating</i> exceptions that have already been raised, either
by a Pyrex function or a C function that calls Python/C API routines. To
by a Cython function or a C function that calls Python/C API routines. To
get an exception from a non-Python-aware function such as fopen, you will
have to check the return value and raise it yourself, for example,
<blockquote> <pre>cdef FILE *p<br>p = fopen("spam.txt", "r")<br>if p == NULL:<br>&nbsp;&nbsp;&nbsp; raise SpamError("Couldn't open the spam file")</pre>
......@@ -507,20 +507,20 @@ have to check the return value and raise it yourself, for example,
<h4> <a name="IncludeStatement"></a>The <tt>include</tt> statement</h4>
For convenience, a large Pyrex module can be split up into a number of
For convenience, a large Cython module can be split up into a number of
files which are put together using the <b>include</b> statement, for example
<blockquote> <pre>include "spamstuff.pxi"</pre>
</blockquote>
The contents of the named file are textually included at that point. The
included file can contain any complete top-level Pyrex statements, including
included file can contain any complete top-level Cython statements, including
other <b>include</b> statements. The <b>include</b> statement itself can
only appear at the top level of a file.
<p>The <b>include</b> statement can also be used in conjunction with <a href="#PublicDecls"><b>public</b> declarations</a> to make C functions and
variables defined in one Pyrex module accessible to another. However, note
variables defined in one Cython module accessible to another. However, note
that some of these uses have been superseded by the facilities described
in <a href="sharing.html">Sharing Declarations Between Pyrex Modules</a>,
in <a href="sharing.html">Sharing Declarations Between Cython Modules</a>,
and it is expected that use of the <b>include</b> statement for this purpose
will be phased out altogether in future versions. </p>
......@@ -529,14 +529,14 @@ will be phased out altogether in future versions. </p>
C Code
<hr width="100%"></h2>
One of the main uses of Pyrex is wrapping existing libraries of C code.
One of the main uses of Cython is wrapping existing libraries of C code.
This is achieved by using <a href="#ExternDecls">external declarations</a> to declare the C functions and variables from the library that you want to
use.
<p>You can also use <a href="#PublicDecls">public declarations</a> to make
C functions and variables defined in a Pyrex module available to external
C functions and variables defined in a Cython module available to external
C code. The need for this is expected to be less frequent, but you might
want to do it, for example, if you are embedding Python in another application
as a scripting language. Just as a Pyrex module can be used as a bridge to
as a scripting language. Just as a Cython module can be used as a bridge to
allow Python code to call C code, it can also be used to allow C code to
call Python code. </p>
......@@ -558,12 +558,12 @@ can also be declared <b>extern</b> to specify that they are defined elsewhere,
<h4> <a name="ReferencingHeaders"></a>Referencing C header files</h4>
When you use an extern definition on its own as in the examples above,
Pyrex includes a declaration for it in the generated C file. This can cause
Cython includes a declaration for it in the generated C file. This can cause
problems if the declaration doesn't exactly match the declaration that will
be seen by other C code. If you're wrapping an existing C library, for example,
it's important that the generated C code is compiled with exactly the same
declarations as the rest of the library.
<p>To achieve this, you can tell Pyrex that the declarations are to be found
<p>To achieve this, you can tell Cython that the declarations are to be found
in a C header file, like this: </p>
......@@ -575,10 +575,10 @@ declarations as the rest of the library.
The <b>cdef extern from</b> clause does three things:
<ol>
<li> It directs Pyrex to place a <b>#include</b> statement for the named
<li> It directs Cython to place a <b>#include</b> statement for the named
header file in the generated C code.<br>
</li>
&nbsp; <li> It prevents Pyrex from generating any C code for the declarations
&nbsp; <li> It prevents Cython from generating any C code for the declarations
found in the associated block.<br>
</li>
&nbsp; <li> It treats all declarations within the block as though they
......@@ -586,14 +586,14 @@ started with <b>cdef extern</b>.</li>
</ol>
It's important to understand that Pyrex does <i>not</i> itself read the
C header file, so you still need to provide Pyrex versions of any declarations
from it that you use. However, the Pyrex declarations don't always have to
It's important to understand that Cython does <i>not</i> itself read the
C header file, so you still need to provide Cython versions of any declarations
from it that you use. However, the Cython declarations don't always have to
exactly match the C ones, and in some cases they shouldn't or can't. In particular:
<ol>
<li> Don't use <b>const</b>. Pyrex doesn't know anything about const,
<li> Don't use <b>const</b>. Cython doesn't know anything about const,
so just leave it out. Most of the time this shouldn't cause any problem,
although on rare occasions you might have to use a cast.<sup><a href="#Footnote1"> 1</a></sup><br>
</li>
......@@ -673,21 +673,21 @@ name:</li>
There are two main ways that structs, unions and enums can be declared
in C header files: using a tag name, or using a typedef. There are also some
variations based on various combinations of these.
<p>It's important to make the Pyrex declarations match the style used in the
header file, so that Pyrex can emit the right sort of references to the type
in the code it generates. To make this possible, Pyrex provides two different
<p>It's important to make the Cython declarations match the style used in the
header file, so that Cython can emit the right sort of references to the type
in the code it generates. To make this possible, Cython provides two different
syntaxes for declaring a struct, union or enum type. The style introduced
above corresponds to the use of a tag name. To get the other style, you prefix
the declaration with <b>ctypedef</b>, as illustrated below. </p>
<p>The following table shows the various possible styles that can be found
in a header file, and the corresponding Pyrex declaration that you should
in a header file, and the corresponding Cython declaration that you should
put in the <b>cdef exern from </b>block. Struct declarations are used as
an example; the same applies equally to union and enum declarations. </p>
<p>Note that in all the cases below, you refer to the type in Pyrex code simply
<p>Note that in all the cases below, you refer to the type in Cython code simply
as <tt><font size="+1">Foo</font></tt>, not <tt><font size="+1">struct Foo</font></tt>.
<br>
&nbsp; <table cellpadding="5">
......@@ -696,7 +696,7 @@ as <tt><font size="+1">Foo</font></tt>, not <tt><font size="+1">struct Foo</font
<td bgcolor="#8cbc1c">&nbsp;</td>
<td bgcolor="#ff9933" nowrap="nowrap"><b>C code</b></td>
<td bgcolor="#66cccc" valign="top"><b>Possibilities for corresponding
Pyrex code</b></td>
Cython code</b></td>
<td bgcolor="#99cc33" valign="top"><b>Comments</b></td>
</tr>
<tr bgcolor="#8cbc1c" valign="top">
......@@ -706,7 +706,7 @@ Pyrex code</b></td>
<tt>};</tt></td>
<td bgcolor="#66cccc"><tt>cdef struct Foo:</tt> <br>
<tt>&nbsp; ...</tt></td>
<td>Pyrex will refer to the type as <tt>struct Foo </tt>in the generated
<td>Cython will refer to the type as <tt>struct Foo </tt>in the generated
C code<tt>.</tt></td>
</tr>
<tr bgcolor="#8cbc1c" valign="top">
......@@ -716,7 +716,7 @@ Pyrex code</b></td>
<tt>} Foo;</tt></td>
<td bgcolor="#66cccc" valign="top"><tt>ctypedef struct Foo:</tt> <br>
<tt>&nbsp; ...</tt></td>
<td valign="top">Pyrex will refer to the type simply as <tt>Foo</tt>
<td valign="top">Cython will refer to the type simply as <tt>Foo</tt>
in the generated C code.</td>
</tr>
<tr bgcolor="#8cbc1c" valign="top">
......@@ -729,7 +729,7 @@ foo {</tt> <br>
<tt>&nbsp; ...</tt> <br>
<tt>ctypedef foo Foo #optional</tt></td>
<td rowspan="2" valign="top">If the C header uses both a tag and a typedef
with <i>different</i> names, you can use either form of declaration in Pyrex
with <i>different</i> names, you can use either form of declaration in Cython
(although if you need to forward reference the type, you'll have to use
the first form).</td>
</tr>
......@@ -767,19 +767,19 @@ necessary.</td>
<hr width="100%">
<h3> <a name="CNameSpecs"></a>Resolving naming conflicts - C name specifications</h3>
Each Pyrex module has a single module-level namespace for both Python
Each Cython module has a single module-level namespace for both Python
and C names. This can be inconvenient if you want to wrap some external
C functions and provide the Python user with Python functions of the same
names.
<p>Pyrex 0.8 provides a couple of different ways of solving this problem.
<p>Cython 0.8 provides a couple of different ways of solving this problem.
The best way, especially if you have many C functions to wrap, is probably
to put the extern C function declarations into a different namespace using
the facilities described in the section on <a href="sharing.html">sharing
declarations between Pyrex modules</a>. </p>
declarations between Cython modules</a>. </p>
<p>The other way is to use a <b>c name specification</b> to give different
Pyrex and C names to the C function. Suppose, for example, that you want
Cython and C names to the C function. Suppose, for example, that you want
to wrap an external function called <tt>eject_tomato</tt>. If you declare
it as </p>
......@@ -787,7 +787,7 @@ it as </p>
<blockquote> <pre>cdef extern void c_eject_tomato "eject_tomato" (float speed)</pre>
</blockquote>
then its name inside the Pyrex module will be <tt>c_eject_tomato</tt>,
then its name inside the Cython module will be <tt>c_eject_tomato</tt>,
whereas its name in C will be <tt>eject_tomato</tt>. You can then wrap it
with
<blockquote> <pre>def eject_tomato(speed):<br>&nbsp; c_eject_tomato(speed)</pre>
......@@ -796,8 +796,8 @@ with
so that users of your module can refer to it as <tt>eject_tomato</tt>.
<p>Another use for this feature is referring to external names that happen
to be Pyrex keywords. For example, if you want to call an external function
called <tt>print</tt>, you can rename it to something else in your Pyrex
to be Cython keywords. For example, if you want to call an external function
called <tt>print</tt>, you can rename it to something else in your Cython
module. </p>
......@@ -814,16 +814,16 @@ module. </p>
<hr width="100%">
<h3> <a name="PublicDecls"></a>Public Declarations</h3>
You can make C variables and functions defined in a Pyrex module accessible
to external C code (or another Pyrex module) using the <b><tt>public</tt></b> keyword, as follows:
You can make C variables and functions defined in a Cython module accessible
to external C code (or another Cython module) using the <b><tt>public</tt></b> keyword, as follows:
<blockquote><tt>cdef public int spam # public variable declaration</tt> <p><tt>cdef public void grail(int num_nuns): # public function declaration</tt> <br>
<tt>&nbsp;&nbsp;&nbsp; ...</tt></p>
</blockquote>
If there are any <tt>public</tt> declarations in a Pyrex module, a <b>.h</b> file is generated containing equivalent C declarations for inclusion in other
If there are any <tt>public</tt> declarations in a Cython module, a <b>.h</b> file is generated containing equivalent C declarations for inclusion in other
C code.
<p>Pyrex also generates a <b>.pxi</b> file containing Pyrex versions of the
declarations for inclusion in another Pyrex module using the <b><a href="#IncludeStatement">include</a></b> statement. If you use this, you
<p>Cython also generates a <b>.pxi</b> file containing Cython versions of the
declarations for inclusion in another Cython module using the <b><a href="#IncludeStatement">include</a></b> statement. If you use this, you
will need to arrange for the module using the declarations to be linked
against the module defining them, and for both modules to be available to
the dynamic linker at run time. I haven't tested this, so I can't say how
......@@ -832,22 +832,22 @@ well it will work on the various platforms. </p>
<blockquote>NOTE: If all you want to export is an extension type, there is
now a better way -- see <a href="sharing.html">Sharing Declarations Between
Pyrex Modules</a>.</blockquote>
Cython Modules</a>.</blockquote>
<h2> <hr width="100%">Extension Types
<hr width="100%"></h2>
One of the most powerful features of Pyrex is the ability to easily create
One of the most powerful features of Cython is the ability to easily create
new built-in Python types, called <b>extension types</b>. This is a major
topic in itself, so there is a&nbsp; <a href="extension_types.html">separate
page</a> devoted to it.
<h2> <hr width="100%">Sharing Declarations Between Pyrex Modules
<h2> <hr width="100%">Sharing Declarations Between Cython Modules
<hr width="100%"></h2>
Pyrex 0.8 introduces a substantial new set of facilities allowing a Pyrex
Cython 0.8 introduces a substantial new set of facilities allowing a Cython
module to easily import and use C declarations and extension types from another
Pyrex module. You can now create a set of co-operating Pyrex modules just
Cython module. You can now create a set of co-operating Cython modules just
as easily as you can create a set of co-operating Python modules. There is
a <a href="sharing.html">separate page</a> devoted to this topic.
<h2> <hr width="100%"><a name="Limitations"></a>Limitations
......@@ -856,7 +856,7 @@ a <a href="sharing.html">separate page</a> devoted to this topic.
<h3> <a name="Unsupported"></a>Unsupported Python features</h3>
Pyrex is not quite a full superset of Python. The following restrictions
Cython is not quite a full superset of Python. The following restrictions
apply:
<blockquote> <li> Function definitions (whether using <b>def</b> or <b>cdef</b>)
cannot be nested within other function definitions.<br>
......@@ -867,7 +867,7 @@ a <a href="sharing.html">separate page</a> devoted to this topic.
&nbsp; <li> The<tt> import *</tt> form of import is not allowed anywhere
(other forms of the import statement are fine, though).<br>
</li>
&nbsp; <li> Generators cannot be defined in Pyrex.<br>
&nbsp; <li> Generators cannot be defined in Cython.<br>
<br>
</li>
<li> The <tt>globals()</tt> and <tt>locals()</tt> functions cannot be
......@@ -875,7 +875,7 @@ used.</li>
</blockquote>
The above restrictions will most likely remain, since removing them would
be difficult and they're not really needed for Pyrex's intended applications.
be difficult and they're not really needed for Cython's intended applications.
<p>There are also some temporary limitations, which may eventually be lifted, including:
</p>
......@@ -895,26 +895,26 @@ docstrings.<br>
<br>
</li>
<li> The use of string literals as comments is not recommended at present,
because Pyrex doesn't optimize them away, and won't even accept them in
because Cython doesn't optimize them away, and won't even accept them in
places where executable statements are not allowed.</li>
</blockquote>
<h3> <a name="SemanticDifferences"></a>Semantic differences between Python
and Pyrex</h3>
and Cython</h3>
<h4> Behaviour of class scopes</h4>
In Python, referring to a method of a class inside the class definition,
i.e. while the class is being defined, yields a plain function object, but
in Pyrex it yields an unbound method<sup><font size="-2"><a href="#Footnote2">2</a></font></sup>. A consequence of this is that the
in Cython it yields an unbound method<sup><font size="-2"><a href="#Footnote2">2</a></font></sup>. A consequence of this is that the
usual idiom for using the classmethod and staticmethod functions, e.g.
<blockquote> <pre>class Spam:</pre>
<pre>&nbsp; def method(cls):<br>&nbsp;&nbsp;&nbsp; ...</pre>
<pre>&nbsp; method = classmethod(method)</pre>
</blockquote>
will not work in Pyrex. This can be worked around by defining the function
will not work in Cython. This can be worked around by defining the function
<i>outside</i> the class, and then assigning the result of classmethod or
staticmethod inside the class, i.e.
<blockquote> <pre>def Spam_method(cls):<br>&nbsp; ...</pre>
......@@ -947,10 +947,10 @@ casting away the constness:
<hr width="100%"><a name="Footnote2"></a>2. The reason for the different behaviour
of class scopes is that Pyrex-defined Python functions are PyCFunction objects,
of class scopes is that Cython-defined Python functions are PyCFunction objects,
not PyFunction objects, and are not recognised by the machinery that creates
a bound or unbound method when a function is extracted from a class. To get
around this, Pyrex wraps each method in an unbound method object itself before
around this, Cython wraps each method in an unbound method object itself before
storing it in the class's dictionary. <br>
&nbsp; <br>
......
<!DOCTYPE doctype 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.61 (Macintosh; I; PPC) [Netscape]"><title>Sharing Declarations Between Pyrex Modules</title></head>
<meta name="GENERATOR" content="Mozilla/4.61 (Macintosh; I; PPC) [Netscape]"><title>Sharing Declarations Between Cython Modules</title></head>
<body>
<h1> <hr width="100%">Sharing Declarations Between Pyrex Modules
<h1> <hr width="100%">Sharing Declarations Between Cython Modules
<hr width="100%"></h1>
This section describes a new set of facilities introduced in Pyrex 0.8
for making C declarations and extension types in one Pyrex module available
for use in another Pyrex module. These facilities are closely modelled on
This section describes a new set of facilities introduced in Cython 0.8
for making C declarations and extension types in one Cython module available
for use in another Cython module. These facilities are closely modelled on
the Python import mechanism, and can be thought of as a compile-time version
of it.
<h2> Contents</h2>
......@@ -27,9 +27,9 @@ naming conflicts</a></li>
<li> <a href="#SharingExtensionTypes">Sharing extension types</a></li>
</ul>
<h2> <a name="DefAndImpFiles"></a>Definition and Implementation files</h2>
A Pyrex module can be split into two parts: a <i>definition file</i> with
A Cython module can be split into two parts: a <i>definition file</i> with
a <tt>.pxd</tt> suffix, containing C declarations that are to be available
to other Pyrex modules, and an <i>implementation file</i> with a <tt>.pyx</tt>
to other Cython modules, and an <i>implementation file</i> with a <tt>.pyx</tt>
suffix, containing everything else. When a module wants to use something
declared in another module's definition file, it imports it using the <a href="#CImportStatement"><b>cimport</b> statement</a>.
<h3> <a name="WhatDefFileContains"></a>What a Definition File contains</h3>
......@@ -44,11 +44,11 @@ declared in another module's definition file, it imports it using the <a href="#
<p>It cannot contain the implementations of any C or Python functions, or
any Python class definitions, or any executable statements. </p>
<blockquote>NOTE: You don't need to (and shouldn't) declare anything in a
declaration file <b>public</b> in order to make it available to other Pyrex
declaration file <b>public</b> in order to make it available to other Cython
modules; its mere presence in a definition file does that. You only need a
public declaration if you want to make something available to external C code.</blockquote>
<h3> <a name="WhatImpFileContains"></a>What an Implementation File contains</h3>
An implementation file can contain any kind of Pyrex statement, although
An implementation file can contain any kind of Cython statement, although
there are some restrictions on the implementation part of an extension type
if the corresponding definition file also defines that type (see below).
......@@ -101,7 +101,7 @@ name under which you imported it. Using <b>cimport</b> to import extension
types is covered in more detail <a href="#SharingExtensionTypes">below</a>.
</p>
<h3> <a name="SearchPaths"></a>Search paths for definition files</h3>
When you <b>cimport</b> a module called <tt>modulename</tt>, the Pyrex
When you <b>cimport</b> a module called <tt>modulename</tt>, the Cython
compiler searches for a file called <tt>modulename.pxd</tt> along the search
path for include files, as specified by <b>-I</b> command line options.
<p>Also, whenever you compile a file <tt>modulename.pyx</tt>, the corresponding
......
......@@ -5,7 +5,7 @@
<body>
<h1> <hr width="100%">Special Methods of Extension Types
<hr width="100%"></h1>
This page describes the special methods currently supported by Pyrex extension
This page describes the special methods currently supported by Cython extension
types. A complete list of all the special methods appears in the table at
the bottom. Some of these methods behave differently from their Python counterparts
or have no direct Python counterparts, and require special mention.
......@@ -73,11 +73,11 @@ touch the object. In particular, don't call any other methods of the object
or do anything which might cause the object to be resurrected. It's best if
you stick to just deallocating C data. </p>
<p>You don't need to worry about deallocating Python attributes of your object,
because that will be done for you by Pyrex after your <tt>__dealloc__</tt>
because that will be done for you by Cython after your <tt>__dealloc__</tt>
method returns.<br>
<br>
<b>Note:</b> There is no <tt>__del__</tt> method for extension types. (Earlier
versions of the Pyrex documentation stated that there was, but this turned
versions of the Cython documentation stated that there was, but this turned
out to be incorrect.)<br>
</p>
<h2><font size="+1">Arithmetic methods</font></h2>
......
include MANIFEST.in README.txt INSTALL.txt CHANGES.txt ToDo.txt USAGE.txt
include setup.py
include bin/pyrexc
include pyrexc.py
include Pyrex/Compiler/Lexicon.pickle
include bin/cython
include cython.py
include Cython/Compiler/Lexicon.pickle
include Doc/*
include Demos/*
VERSION = 0.9.4.1
VERSION = 0.9.6
version:
@echo "Setting version to $(VERSION)"
@echo "version = '$(VERSION)'" > Pyrex/Compiler/Version.py
#check_contents:
# @if [ ! -d Pyrex/Distutils ]; then \
# echo Pyrex/Distutils missing; \
# exit 1; \
# fi
@echo "version = '$(VERSION)'" > Cython/Compiler/Version.py
clean:
@echo Cleaning Source
......
Welcome to Cython!
=================
Cython (http://www.cython.org) is based on Pyrex, but
supports more cutting edge functionality and optimizations.
Cython (http://www.cython.org) is based on Pyrex, but supports more
cutting edge functionality and optimizations.
LICENSE:
......@@ -14,17 +14,24 @@ below). Cython itself is licensed under the
--------------------------
There are TWO mercurial (hg) repositories included with Cython:
--------------------------
* Various project files, documentation, etc. (in the top level directory)
* The main codebase itself (in Cython/)
To see the change history, go to the Pyrex directory and type
We keep these separate for easier merging with the Pyrex project.
To see the change history for Cython code itself, go to the Cython
directory and type
$ hg log
This requires that you have installed Mercurial.
-- William Stein (wstein@gmail.com)
-- William Stein (wstein@gmail.com)
xxxx
......
-- The Original Pyrex Todo List --
DONE - Pointer-to-function types.
DONE - Nested declarators.
......
Pyrex - Usage Instructions
Cython - Usage Instructions
==========================
Building Pyrex extensions using distutils
Building Cython extensions using distutils
-----------------------------------------
Pyrex comes with an experimental distutils extension for compiling
Pyrex modules, contributed by Graham Fawcett of the University of
Cython comes with an experimental distutils extension for compiling
Cython modules, contributed by Graham Fawcett of the University of
Windsor (fawcett@uwindsor.ca).
The Demos directory contains a setup.py file demonstrating its use. To
......@@ -30,17 +30,17 @@ Try out the extensions with:
python run_numeric_demo.py
Building Pyrex extensions by hand
Building Cython extensions by hand
---------------------------------
You can also invoke the Pyrex compiler on its own to translate a .pyx
You can also invoke the Cython compiler on its own to translate a .pyx
file to a .c file. On Unix,
pyrexc filename.pyx
cython filename.pyx
On other platforms,
python pyrexc.py filename.pyx
python cython.py filename.pyx
It's then up to you to compile and link the .c file using whatever
procedure is appropriate for your platform. The file
......@@ -51,19 +51,25 @@ one particular Unix system.
Command line options
--------------------
The pyrexc command supports the following options:
The cython command supports the following options:
Short Long Argument Description
-----------------------------------------------------------------------------
-v --version Display version number of pyrex compiler
-v --version Display version number of cython compiler
-l --create-listing Write error messages to a .lis file
-I --include-dir <directory> Search for include files in named
directory (may be repeated)
-o --output-file <filename> Specify name of generated C file (only
one source file allowed if this is used)
-p, --embed-positions If specified, the positions in Cython files of each
function definition is embedded in its docstring.
-z, --pre-import <module> If specified, assume undeclared names in this
module. Emulates the behavior of putting
"from <module> import *" at the top of the file.
Anything else is taken as the name of a Pyrex source file and compiled
to a C source file. Multiple Pyrex source files can be specified
Anything else is taken as the name of a Cython source file and compiled
to a C source file. Multiple Cython source files can be specified
(unless -o is used), in which case each source file is treated as the
source of a distinct extension module and compiled separately to
produce its own C file.
#
# Pyrex -- Main Program, generic
# Cython -- Main Program, generic
#
from Pyrex.Compiler.Main import main
from Cython.Compiler.Main import main
main(command_line = 1)
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment