<!doctype html public "-//w3c//dtd html 4.0 transitional//en"><html><head><metahttp-equiv="Content-Type"content="text/html; charset=iso-8859-1"><metaname="GENERATOR"content="Mozilla/4.51 (Macintosh; I; PPC) [Netscape]"><title>About Pyrex</title></head><body><center><h1><hrwidth="100%">Pyrex</h1></center><center><i><fontsize=+1>A language for writing Python extension modules</font></i><hrwidth="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 <ahref="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 <ahref="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, 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><fontsize=+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 = 0
11 while i < k and n % p[i] <> 0:
12 i = i + 1
13 if i == k:
14 p[k] = n
15 k = k + 1
16 result.append(n)
17 n = n + 1
18 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 <ahref="primes.c">C code generated for this module</a>
.<h2>
Language Details</h2>
For more about the Pyrex language, see the <ahref="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 <ahref="overview.html#Limitations">Limitations</a>
section of the <ahref="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>
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"><html><head><metahttp-equiv="Content-Type"content="text/html; charset=iso-8859-1"><metaname="GENERATOR"content="Mozilla/4.51 (Macintosh; I; PPC) [Netscape]"><title>About Cython</title></head><body><center><h1><hrwidth="100%">Cython</h1></center><center><i><fontsize=+1>A language for writing Python extension modules</font></i><hrwidth="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 <ahref="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 <ahref="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, 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><fontsize=+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 = 0
11 while i < k and n % p[i] <> 0:
12 i = i + 1
13 if i == k:
14 p[k] = n
15 k = k + 1
16 result.append(n)
17 n = n + 1
18 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 <ahref="primes.c">C code generated for this module</a>
.<h2>
Language Details</h2>
For more about the Cython language, see the <ahref="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 <ahref="overview.html#Limitations">Limitations</a>
section of the <ahref="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>
<li><b><ahref="#NumericAccess">How do I access the data inside a Numeric
<li><b><ahref="#NumericAccess">How do I access the data inside a Numeric
array object?</a></b></li>
array object?</a></b></li>
<li><b><ahref="#Rhubarb">Pyrex says my extension type object has no attribute
<li><b><ahref="#Rhubarb">Cython says my extension type object has no attribute
'rhubarb', but I know it does. What gives?</a></b></li><li><astyle="font-weight: bold;"href="#Quack">Python says my extension type has no method called 'quack', but I know it does. What gives?</a><br>
'rhubarb', but I know it does. What gives?</a></b></li><li><astyle="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>
</li>
...
@@ -55,10 +55,10 @@ bytes to a Python string?</h2>
...
@@ -55,10 +55,10 @@ bytes to a Python string?</h2>
section of the <ahref="extension_types.html">"Extension Types"</a> documentation
section of the <ahref="extension_types.html">"Extension Types"</a> documentation
page.<br>
page.<br>
<tt></tt></p>
<tt></tt></p>
<h2><aname="Rhubarb"></a>Pyrex says my extension type object has no attribute
<h2><aname="Rhubarb"></a>Cython says my extension type object has no attribute
'rhubarb', but I know it does. What gives?</h2>
'rhubarb', but I know it does. What gives?</h2>
You're probably trying to access it through a reference which Pyrex thinks
You're probably trying to access it through a reference which Cython thinks
is a generic Python object. You need to tell Pyrex that it's a reference
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>
to your extension type by means of a declaration,<br>
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
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:
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>
<blockquote><tt>def widen_shrubbery(Shrubbery sh not None, extra_width):</tt>
...
@@ -223,14 +223,14 @@ type:
...
@@ -223,14 +223,14 @@ type:
<tt> ...</tt></p>
<tt> ...</tt></p>
</blockquote>
</blockquote>
<p><br>
<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
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
module, it must either be declared as an extern extension type or imported
using the <b><ahref="sharing.html">cimport</a></b> statement. </p>
using the <b><ahref="sharing.html">cimport</a></b> statement. </p>
<p>An extension type can only have one base class (no multiple inheritance).
<p>An extension type can only have one base class (no multiple inheritance).
</p>
</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
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
rules for multiple inheritance are followed (i.e. the C layouts of all the
base classes must be compatible).<br>
base classes must be compatible).<br>
...
@@ -316,18 +316,18 @@ type <span style="font-family: monospace;">object</span> called <span style="fon
...
@@ -316,18 +316,18 @@ type <span style="font-family: monospace;">object</span> called <span style="fon
<h2><aname="PublicAndExtern"></a>Public and external extension types</h2>
<h2><aname="PublicAndExtern"></a>Public and external extension types</h2>
Extension types can be declared <b>extern</b> or <b>public</b>. An <ahref="#ExternalExtTypes"><b>extern</b> extension type declaration</a> makes
Extension types can be declared <b>extern</b> or <b>public</b>. An <ahref="#ExternalExtTypes"><b>extern</b> extension type declaration</a> makes
an extension type defined in external C code available to a Pyrex module.
an extension type defined in external C code available to a Cython module.
A <ahref="#PublicExtensionTypes"><b>public</b> extension type declaration</a> makes an extension type defined in a Pyrex module available to external C
A <ahref="#PublicExtensionTypes"><b>public</b> extension type declaration</a> makes an extension type defined in a Cython module available to external C
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"><html><head><metahttp-equiv="Content-Type"content="text/html; charset=iso-8859-1"><metaname="GENERATOR"content="Mozilla/4.51 (Macintosh; I; PPC) [Netscape]"><title>Pyrex - Front Page</title></head><body> <tableCELLSPACING=0CELLPADDING=10WIDTH="500"><tr><tdVALIGN=TOPBGCOLOR="#FF9218"><fontface="Arial,Helvetica"><fontsize=+4>Pyrex</font></font></td><tdALIGN=RIGHTVALIGN=TOPWIDTH="200"BGCOLOR="#5DBACA"><fontface="Arial,Helvetica"><fontsize=+1>A
smooth blend of the finest Python </font></font><br><fontface="Arial,Helvetica"><fontsize=+1>with the unsurpassed power </font></font><br><fontface="Arial,Helvetica"><fontsize=+1>of raw C.</font></font></td></tr></table><blockquote><fontsize=+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><fontface="Arial,Helvetica"><fontsize=+2>Documentation</font></font></h1><blockquote><h2><fontface="Arial,Helvetica"><fontsize=+1><ahref="About.html">About Pyrex</a></font></font></h2><blockquote><fontsize=+1>Read this to find out what Pyrex is all about
and what it can do for you.</font></blockquote><h2><fontface="Arial,Helvetica"><fontsize=+1><ahref="overview.html">Language
Overview</a></font></font></h2><blockquote><fontsize=+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><fontface="Arial,Helvetica"><fontsize=+1><ahref="FAQ.html">FAQ</a></font></font></h2><blockquote><fontsize=+1>Want to know how to do something in Pyrex? Check
here first<fontface="Arial,Helvetica">.</font></font></blockquote></blockquote><h1><fontface="Arial,Helvetica"><fontsize=+2>Other Resources</font></font></h1><blockquote><h2><fontface="Arial,Helvetica"><fontsize=+1><ahref="http://www.cosc.canterbury.ac.nz/~greg/python/Pyrex/mpj17-pyrex-guide/">Michael's
Quick Guide to Pyrex</a></font></font></h2><blockquote><fontsize=+1>This tutorial-style presentation will take you
through the steps of creating some Pyrex modules to wrap existing C libraries.
Contributed by <ahref="mailto:mpj17@cosc.canterbury.ac.nz">Michael JasonSmith</a>.</font></blockquote><h2><fontface="Arial,Helvetica"><fontsize=+1><ahref="mailto:greg@cosc.canterbury.ac.nz">Mail
to the Author</a></font></font></h2><blockquote><fontsize=+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:<fontface="Arial,Helvetica"></font><tt><ahref="mailto:greg@cosc.canterbury.ac.nz">greg@cosc.canterbury.ac.nz</a></tt></font></blockquote></blockquote></body></html>
<!doctype html public "-//w3c//dtd html 4.0 transitional//en"><html><head><metahttp-equiv="Content-Type"content="text/html; charset=iso-8859-1"><metaname="GENERATOR"content="Mozilla/4.51 (Macintosh; I; PPC) [Netscape]"><title>Cython - Front Page</title></head><body> <tableCELLSPACING=0CELLPADDING=10WIDTH="500"><tr><tdVALIGN=TOPBGCOLOR="#FF9218"><fontface="Arial,Helvetica"><fontsize=+4>Cython</font></font></td><tdALIGN=RIGHTVALIGN=TOPWIDTH="200"BGCOLOR="#5DBACA"><fontface="Arial,Helvetica"><fontsize=+1>A
smooth blend of the finest Python </font></font><br><fontface="Arial,Helvetica"><fontsize=+1>with the unsurpassed power </font></font><br><fontface="Arial,Helvetica"><fontsize=+1>of raw C.</font></font></td></tr></table><blockquote><fontsize=+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><fontface="Arial,Helvetica"><fontsize=+2>Documentation</font></font></h1><blockquote><h2><fontface="Arial,Helvetica"><fontsize=+1><ahref="About.html">About Cython</a></font></font></h2><blockquote><fontsize=+1>Read this to find out what Cython is all about
and what it can do for you.</font></blockquote><h2><fontface="Arial,Helvetica"><fontsize=+1><ahref="overview.html">Language
Overview</a></font></font></h2><blockquote><fontsize=+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><fontface="Arial,Helvetica"><fontsize=+1><ahref="FAQ.html">FAQ</a></font></font></h2><blockquote><fontsize=+1>Want to know how to do something in Cython? Check
here first<fontface="Arial,Helvetica">.</font></font></blockquote></blockquote><h1><fontface="Arial,Helvetica"><fontsize=+2>Other Resources</font></font></h1><blockquote><h2><fontface="Arial,Helvetica"><fontsize=+1><ahref="http://www.cosc.canterbury.ac.nz/~greg/python/Cython/mpj17-pyrex-guide/">Michael's
Quick Guide to Cython</a></font></font></h2><blockquote><fontsize=+1>This tutorial-style presentation will take you
through the steps of creating some Cython modules to wrap existing C libraries.
Contributed by <ahref="mailto:mpj17@cosc.canterbury.ac.nz">Michael JasonSmith</a>.</font></blockquote><h2><fontface="Arial,Helvetica"><fontsize=+1><ahref="mailto:greg@cosc.canterbury.ac.nz">Mail
to the Author</a></font></font></h2><blockquote><fontsize=+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:<fontface="Arial,Helvetica"></font><tt><ahref="mailto:greg@cosc.canterbury.ac.nz">greg@cosc.canterbury.ac.nz</a></tt></font></blockquote></blockquote></body></html>
<li><ahref="#SemanticDifferences">Semantic differences between Python
<li><ahref="#SemanticDifferences">Semantic differences between Python
and Pyrex</a></li>
and Cython</a></li>
</ul>
</ul>
</ul>
</ul>
...
@@ -72,13 +72,13 @@ expressions<br>
...
@@ -72,13 +72,13 @@ expressions<br>
<h2><hrwidth="100%"><aname="Basics"></a>Basics
<h2><hrwidth="100%"><aname="Basics"></a>Basics
<hrwidth="100%"></h2>
<hrwidth="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
covered in this section allow you to create Python-callable functions that
manipulate C data structures and convert between Python and C data types.
manipulate C data structures and convert between Python and C data types.
Later sections will cover facilities for <ahref="#InterfacingWithExternal">wrapping external C code</a>, <ahref="extension_types.html">creating new Python types</a> and <ahref="sharing.html">cooperation between Pyrex modules</a>.
Later sections will cover facilities for <ahref="#InterfacingWithExternal">wrapping external C code</a>, <ahref="extension_types.html">creating new Python types</a> and <ahref="sharing.html">cooperation between Cython modules</a>.
<h3><aname="PyFuncsVsCFuncs"></a>Python functions vs. C functions</h3>
<h3><aname="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
<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.
in Python. They take Python objects as parameters and return Python objects.
</p>
</p>
...
@@ -89,10 +89,10 @@ expressions<br>
...
@@ -89,10 +89,10 @@ expressions<br>
Python objects or C values. </p>
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
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
interpreted Python code. So, any functions that you want to "export" from
your Pyrex module must be declared as Python functions using <spanstyle="font-weight: bold;">def</span>. </p>
your Cython module must be declared as Python functions using <spanstyle="font-weight: bold;">def</span>. </p>
<p>Parameters of either type of function can be declared to have C data types,
<p>Parameters of either type of function can be declared to have C data types,
...
@@ -259,16 +259,16 @@ string.<br>
...
@@ -259,16 +259,16 @@ string.<br>
<br>
<br>
Pyrex detects and prevents <spanstyle="font-style: italic;">some</span> mistakes of this kind. For instance, if you attempt something like<br>
Cython detects and prevents <spanstyle="font-style: italic;">some</span> mistakes of this kind. For instance, if you attempt something like<br>
then Pyrex will produce the error message "<spanstyle="font-weight: bold;">Obtaining char * from temporary Python value</span>".
then Cython will produce the error message "<spanstyle="font-weight: bold;">Obtaining char * from temporary Python value</span>".
The reason is that concatenating the two Python strings produces a new
The reason is that concatenating the two Python strings produces a new
Python string object that is referenced only by a temporary internal
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
the temporary variable will be decrefed and the Python string
deallocated, leaving <spanstyle="font-family: monospace;">s</span> dangling. Since this code could not possibly work, Pyrex refuses to compile it.<br>
deallocated, leaving <spanstyle="font-family: monospace;">s</span> dangling. Since this code could not possibly work, Cython refuses to compile it.<br>
<br>
<br>
...
@@ -281,7 +281,7 @@ It is then your responsibility to hold the reference <span style="font-family: m
...
@@ -281,7 +281,7 @@ It is then your responsibility to hold the reference <span style="font-family: m
<br>
<br>
Keep in mind that the rules used to detect such errors are only
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
it will fail to detect a problem that exists. Ultimately, you need to
understand the issue and be careful what you do.<br>
understand the issue and be careful what you do.<br>
...
@@ -292,7 +292,7 @@ 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><aname="ScopeRules"></a>Scope rules</h3>
<h3><aname="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,
scope, or the built-in scope <i>completely statically.</i> As with Python,
assigning to a variable which is not otherwise declared implicitly declares
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
it to be a Python variable residing in the scope where it is assigned. Unlike
...
@@ -316,7 +316,7 @@ the builtins module.<br>
...
@@ -316,7 +316,7 @@ the builtins module.<br>
Note: A consequence of these rules is that the module-level scope behaves
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
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
to it. In particular, tricks such as the following will <i>not</i> work
in Pyrex:<br>
in Cython:<br>
<blockquote><pre>try:<br> x = True<br>except NameError:<br> True = 1<br></pre>
<blockquote><pre>try:<br> x = True<br>except NameError:<br> True = 1<br></pre>
...
@@ -347,21 +347,21 @@ all Python operations are automatically checked for errors, with appropriate
...
@@ -347,21 +347,21 @@ all Python operations are automatically checked for errors, with appropriate
action taken. </p>
action taken. </p>
<h4><aname="ExprSyntaxDifferences"></a>Differences between C and Pyrex
<h4><aname="ExprSyntaxDifferences"></a>Differences between C and Cython
expressions</h4>
expressions</h4>
There
There
are some differences in syntax and semantics between C expressions and
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>
no direct equivalent in Python.<br>
<ul>
<ul>
<li>An integer literal without an <spanstyle="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 <spanstyle="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>
<li>An integer literal without an <spanstyle="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 <spanstyle="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>
<br>
</li>
</li>
<li> There is no <b><tt>-></tt></b> operator in Pyrex. Instead of <tt>p->x</tt>,
<li> There is no <b><tt>-></tt></b> operator in Cython. Instead of <tt>p->x</tt>,
use <tt>p.x</tt></li>
use <tt>p.x</tt></li>
<li> There is no <b><tt>*</tt></b> operator in Pyrex. Instead of
<li> There is no <b><tt>*</tt></b> operator in Cython. Instead of
<tt>*p</tt>, use <tt>p[0]</tt></li>
<tt>*p</tt>, use <tt>p[0]</tt></li>
<li> There is an <b><tt>&</tt></b> operator, with the same semantics
<li> There is an <b><tt>&</tt></b> operator, with the same semantics
<i><b>Warning</b>: Don't attempt to use a typecast to convert between
<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>
the conversion automatically.</i>
</ul>
</ul>
...
@@ -393,12 +393,12 @@ the conversion automatically.</i>
...
@@ -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
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
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 <= i < n:</tt><br>
<blockquote><tt>for i from 0 <= i < n:</tt><br>
<tt> ...</tt></blockquote>
<tt> ...</tt></blockquote>
If the loop variable and the lower and upper bounds are all C integers,
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.
pure C code.
<p>Some things to note about the <tt>for-from</tt> loop: </p>
<p>Some things to note about the <tt>for-from</tt> loop: </p>
...
@@ -446,7 +446,7 @@ of exception value declaration: </p>
...
@@ -446,7 +446,7 @@ of exception value declaration: </p>
<blockquote><tt>cdef int spam() except? -1:</tt><br>
<blockquote><tt>cdef int spam() except? -1:</tt><br>
<tt> ...</tt></blockquote>
<tt> ...</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.
exception value is returned, to make sure it really is an error.
<p>There is also a third form of exception value declaration: </p>
<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.
...
@@ -454,7 +454,7 @@ exception value is returned, to make sure it really is an error.
<blockquote><tt>cdef int spam() except *:</tt><br>
<blockquote><tt>cdef int spam() except *:</tt><br>
<tt> ...</tt></blockquote>
<tt> ...</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
<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
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.
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>
...
@@ -484,7 +484,7 @@ is an example of a pointer-to-function declaration with an exception value:</li>
</ul>
</ul>
<h4><aname="CheckingReturnValues"></a>Checking return values of non-Pyrex
<h4><aname="CheckingReturnValues"></a>Checking return values of non-Cython
functions</h4>
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
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
...
@@ -495,7 +495,7 @@ example, you can't write something like
and expect an exception to be automatically raised if a call to fopen
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
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
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
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,
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> raise SpamError("Couldn't open the spam file")</pre>
<blockquote><pre>cdef FILE *p<br>p = fopen("spam.txt", "r")<br>if p == NULL:<br> 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,
...
@@ -507,20 +507,20 @@ have to check the return value and raise it yourself, for example,
You can make C variables and functions defined in a Pyrex module accessible
You can make C variables and functions defined in a Cython module accessible
to external C code (or another Pyrex module) using the <b><tt>public</tt></b> keyword, as follows:
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>
<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> ...</tt></p>
<tt> ...</tt></p>
</blockquote>
</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.
C code.
<p>Pyrex also generates a <b>.pxi</b> file containing Pyrex versions of the
<p>Cython also generates a <b>.pxi</b> file containing Cython versions of the
declarations for inclusion in another Pyrex module using the <b><ahref="#IncludeStatement">include</a></b> statement. If you use this, you
declarations for inclusion in another Cython module using the <b><ahref="#IncludeStatement">include</a></b> statement. If you use this, you
will need to arrange for the module using the declarations to be linked
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
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
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>
...
@@ -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
<blockquote>NOTE: If all you want to export is an extension type, there is
now a better way -- see <ahref="sharing.html">Sharing Declarations Between
now a better way -- see <ahref="sharing.html">Sharing Declarations Between
Pyrex Modules</a>.</blockquote>
Cython Modules</a>.</blockquote>
<h2><hrwidth="100%">Extension Types
<h2><hrwidth="100%">Extension Types
<hrwidth="100%"></h2>
<hrwidth="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
new built-in Python types, called <b>extension types</b>. This is a major
topic in itself, so there is a <ahref="extension_types.html">separate
topic in itself, so there is a <ahref="extension_types.html">separate
page</a> devoted to it.
page</a> devoted to it.
<h2><hrwidth="100%">Sharing Declarations Between Pyrex Modules
<h2><hrwidth="100%">Sharing Declarations Between Cython Modules
<hrwidth="100%"></h2>
<hrwidth="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
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
as easily as you can create a set of co-operating Python modules. There is
a <ahref="sharing.html">separate page</a> devoted to this topic.
a <ahref="sharing.html">separate page</a> devoted to this topic.
