</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> cdef int width, height</tt> </p>
<p><tt> def __init__(self, w, h):</tt> <br>
<tt>
"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.
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>
<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.
<blockquote><tt>cdef widen_shrubbery(Shrubbery sh, extra_width):</tt> <br>
<tt> 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>
<tt> if sh is None:</tt> <br>
<tt> raise TypeError</tt> <br>
<tt> 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>
<tt> ...</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>
<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> struct Py_complex:</tt> <br>
</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> ...</tt></blockquote>
<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
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>
<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 <hr width="100%"></h1>
+<h1> <hr width="100%">Overview of the Cython Language <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>
<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>
<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>
<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>
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,
<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>
<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>
<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
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> x = True<br>except NameError:<br> True = 1<br></pre>
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>-></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>
- <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>
<li> There is an <b><tt>&</tt></b> operator, with the same semantics
<pre>cdef char *p, float *q<br>p = <char*>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>
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 <= i < n:</tt> <br>
<tt> ...</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>
<blockquote><tt>cdef int spam() except? -1:</tt> <br>
<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.
<p>There is also a third form of exception value declaration: </p>
<blockquote><tt>cdef int spam() except *:</tt> <br>
<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
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.
</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
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> raise SpamError("Couldn't open the spam file")</pre>
<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>
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>
<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>
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>
- <li> It prevents Pyrex from generating any C code for the declarations
+ <li> It prevents Cython from generating any C code for the declarations
found in the associated block.<br>
</li>
<li> It treats all declarations within the block as though they
</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>
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>
<table cellpadding="5">
<td bgcolor="#8cbc1c"> </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">
<tt>};</tt></td>
<td bgcolor="#66cccc"><tt>cdef struct Foo:</tt> <br>
<tt> ...</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">
<tt>} Foo;</tt></td>
<td bgcolor="#66cccc" valign="top"><tt>ctypedef struct Foo:</tt> <br>
<tt> ...</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">
<tt> ...</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>
<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>
<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> c_eject_tomato(speed)</pre>
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>
<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> ...</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
<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 <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
<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>
<li> The<tt> import *</tt> form of import is not allowed anywhere
(other forms of the import statement are fine, though).<br>
</li>
- <li> Generators cannot be defined in Pyrex.<br>
+ <li> Generators cannot be defined in Cython.<br>
<br>
</li>
<li> The <tt>globals()</tt> and <tt>locals()</tt> functions cannot be
</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>
<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> def method(cls):<br> ...</pre>
<pre> 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> ...</pre>
<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>
<br>
projects / cython.git / commitdiff