@@ -73,5 +73,5 @@ section of the <a href="extension_types.html">"Extension
Types"</a> documentation page.<br>
<h2><aname="Quack"></a>Python says my extension type has no method called 'quack', but I know it does. What gives?</h2>
You may have declared the method using <spanstyle="font-family: monospace;">cdef</span> instead of <spanstyle="font-family: monospace;">def</span>. Only functions and methods declared with <spanstyle="font-family: monospace;">def</span> are callable from Python code.<br>
Although the principles are similar, there are substantial differences
between many of the <spanstyle="font-family: monospace;">__xxx__</span> special methods of extension types and their
Python counterparts. There is a <ahref="special_methods.html">separate page</a> devoted to this subject, and you should read it carefully before attempting
to use any special methods in your extension types.
Python counterparts. There is a <ahref="special_methods.html">separate page</a> devoted to this subject, and you should read it carefully before attempting
to use any special methods in your extension types.
<h2><aname="Properties"></a>Properties</h2>
There is a special syntax for defining <b>properties</b> in an extension
class:
class:
<blockquote><tt>cdef class Spam:</tt><p><tt> property cheese:</tt></p>
<p><tt> "A doc string can go
here."</tt></p>
...
...
@@ -166,8 +166,8 @@ here."</tt> </p>
</p>
</blockquote>
The <tt>__get__</tt>, <tt>__set__</tt> and <tt>__del__</tt> methods are
all optional; if they are omitted, an exception will be raised when the corresponding
operation is attempted.
all optional; if they are omitted, an exception will be raised when the corresponding
operation is attempted.
<p>Here's a complete example. It defines a property which adds to a list
each time it is written to, returns the list when it is read, and empties
the list when it is deleted. <br>
...
...
@@ -217,16 +217,16 @@ the list when it is deleted. <br>
@@ -315,21 +315,21 @@ type <span style="font-family: monospace;">object</span> called <span style="fon
<br>
<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
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 Cython module available to external C
code.
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 Cython module.
A <ahref="#PublicExtensionTypes"><b>public</b> extension type declaration</a> makes an extension type defined in a Cython module available to external C
<h1><hrwidth="100%">Overview of the Cython Language <hrwidth="100%"></h1>
This document informally describes the extensions to the Python language
made by Cython. Some day there will be a reference manual covering everything
This document informally describes the extensions to the Python language
made by Cython. Some day there will be a reference manual covering everything
in more detail. <br>
<h2> Contents</h2>
<ul>
<li><ahref="#Basics">Basics</a></li>
...
...
@@ -65,90 +65,90 @@ expressions<br>
<li><ahref="#SemanticDifferences">Semantic differences between Python
and Cython</a></li>
</ul>
</ul>
<h2><hrwidth="100%"><aname="Basics"></a>Basics
<h2><hrwidth="100%"><aname="Basics"></a>Basics
<hrwidth="100%"></h2>
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 <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>.
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 <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>
There are two kinds of function definition in Cython:
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.
in Python. They take Python objects as parameters and return Python objects.
</p>
<p><b>C functions</b> are defined using the new <b>cdef</b> statement. They
take either Python objects or C values as parameters, and can return either
Python objects or C values. </p>
<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 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,
using normal C declaration syntax. For example, </p>
<blockquote><pre>def spam(int i, char *s):<br> ...</pre>
<pre>cdef int eggs(unsigned long l, float f):<br> ...</pre>
</blockquote>
When a parameter of a Python function is declared to have a C data type,
it is passed in as a Python object and automatically converted to a C value,
if possible. Automatic conversion is currently only possible for numeric
types and string types; attempting to use any other type for the parameter
of a Python function will result in a compile-time error.
<p>C functions, on the other hand, can have parameters of any type, since
When a parameter of a Python function is declared to have a C data type,
it is passed in as a Python object and automatically converted to a C value,
if possible. Automatic conversion is currently only possible for numeric
types and string types; attempting to use any other type for the parameter
of a Python function will result in a compile-time error.
<p>C functions, on the other hand, can have parameters of any type, since
they're passed in directly using a normal C function call. </p>
<h3><aname="PyObjParams"></a>Python objects as parameters and return values</h3>
If no type is specified for a parameter or return value, <i>it is assumed
to be a Python object.</i> (Note that this is different from the C convention,
where it would default to <tt>int</tt>.) For example, the following defines
If no type is specified for a parameter or return value, <i>it is assumed
to be a Python object.</i> (Note that this is different from the C convention,
where it would default to <tt>int</tt>.) For example, the following defines
a C function that takes two Python objects as parameters and returns a Python
Note that the words <spanstyle="font-family: monospace;">struct</span>, <spanstyle="font-family: monospace;">union</span> and <spanstyle="font-family: monospace;">enum</span> are used only when <i>defining</i> a type, not when referring to it. For example, to declare a variable pointing
to a Grail you would write
Note that the words <spanstyle="font-family: monospace;">struct</span>, <spanstyle="font-family: monospace;">union</span> and <spanstyle="font-family: monospace;">enum</span> are used only when <i>defining</i> a type, not when referring to it. For example, to declare a variable pointing
<h3><aname="StatsAndExprs"></a>Statements and expressions</h3>
Control structures and expressions follow Python syntax for the most part.
When applied to Python objects, they have the same semantics as in Python
(unless otherwise noted). Most of the Python operators can also be applied
to C values, with the obvious semantics.
<p>If Python objects and C values are mixed in an expression, conversions
are performed automatically between Python objects and C numeric or string
Control structures and expressions follow Python syntax for the most part.
When applied to Python objects, they have the same semantics as in Python
(unless otherwise noted). Most of the Python operators can also be applied
to C values, with the obvious semantics.
<p>If Python objects and C values are mixed in an expression, conversions
are performed automatically between Python objects and C numeric or string
types. </p>
<p>Reference counts are maintained automatically for all Python objects, and
all Python operations are automatically checked for errors, with appropriate
all Python operations are automatically checked for errors, with appropriate
action taken. </p>
<h4><aname="ExprSyntaxDifferences"></a>Differences between C and Cython
expressions</h4>
There
...
...
@@ -358,18 +358,18 @@ no direct equivalent in Python.<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>
</li>
<li> There is no <b><tt>-></tt></b> operator in Cython. 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 Cython. 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
as in C.</li>
<li> The null C pointer is called <b><tt>NULL</tt></b>, not 0 (and
<tt>NULL</tt> is a reserved word).</li>
<li> Character literals are written with a <b>c</b> prefix, for
If you don't do anything special, a function declared with <b>cdef</b> that does not return a Python object has no way of reporting Python exceptions
to its caller. If an exception is detected in such a function, a warning
message is printed and the exception is ignored.
If you don't do anything special, a function declared with <b>cdef</b> that does not return a Python object has no way of reporting Python exceptions
to its caller. If an exception is detected in such a function, a warning
message is printed and the exception is ignored.
<p>If you want a C function that does not return a Python object to be able
to propagate exceptions to its caller, you need to declare an <b>exception
to propagate exceptions to its caller, you need to declare an <b>exception
value</b> for it. Here is an example: </p>
<blockquote><tt>cdef int spam() except -1:</tt><br>
<tt> ...</tt></blockquote>
With this declaration, whenever an exception occurs inside <tt>spam</tt>,
it will immediately return with the value <tt>-1</tt>. Furthermore, whenever
a call to <tt>spam</tt> returns <tt>-1</tt>, an exception will be assumed
to have occurred and will be propagated.
With this declaration, whenever an exception occurs inside <tt>spam</tt>,
it will immediately return with the value <tt>-1</tt>. Furthermore, whenever
a call to <tt>spam</tt> returns <tt>-1</tt>, an exception will be assumed
to have occurred and will be propagated.
<p>When you declare an exception value for a function, you should never explicitly
return that value. If all possible return values are legal and you can't
reserve one entirely for signalling errors, you can use an alternative form
of exception value declaration: </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, 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>
<blockquote><tt>cdef int spam() except *:</tt><br>
<tt> ...</tt></blockquote>
This form causes Cython 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.
have to use this form, since there isn't any return value to test.
<p>Some things to note: </p>
<ul>
<li> Currently, exception values can only declared for functions returning
an integer, float or pointer type, and the value must be a <i>literal</i>,
not an expression (although it can be negative). The only possible pointer
exception value is <tt>NULL</tt>. Void functions can only use the <tt>except
an integer, float or pointer type, and the value must be a <i>literal</i>,
not an expression (although it can be negative). The only possible pointer
exception value is <tt>NULL</tt>. Void functions can only use the <tt>except
*</tt> form.</li>
<br>
<li> The exception value specification is part of the signature
...
...
@@ -477,18 +477,18 @@ is an example of a pointer-to-function declaration with an exception value:</li>
<li> You don't need to (and shouldn't) declare exception values for functions
<li> You don't need to (and shouldn't) declare exception values for functions
which return Python objects. Remember that a function with no declared return
type implicitly returns a Python object.</li>
</ul>
<h4><aname="CheckingReturnValues"></a>Checking return values of non-Cython
<h4><aname="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
@@ -497,26 +497,26 @@ 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 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,
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>
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:
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 Cython module, a <b>.h</b> file is generated containing equivalent C declarations for inclusion in other
C code.
C code.
<p>Cython also generates a <b>.pxi</b> file containing Cython versions of the
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
...
...
@@ -829,35 +829,35 @@ 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
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 <ahref="sharing.html">Sharing Declarations Between
Cython Modules</a>.</blockquote>
<h2><hrwidth="100%">Extension Types
<h2><hrwidth="100%">Extension Types
<hrwidth="100%"></h2>
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 <ahref="extension_types.html">separate
page</a> devoted to it.
<h2><hrwidth="100%">Sharing Declarations Between Cython Modules
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 <ahref="extension_types.html">separate
page</a> devoted to it.
<h2><hrwidth="100%">Sharing Declarations Between Cython Modules
<hrwidth="100%"></h2>
Cython 0.8 introduces a substantial new set of facilities allowing a Cython
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
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 <ahref="sharing.html">separate page</a> devoted to this topic.
<metaname="GENERATOR"content="Mozilla/4.61 (Macintosh; I; PPC) [Netscape]"><title>Special Methods of Extenstion Types</title></head>
<body>
<h1><hrwidth="100%">Special Methods of Extension Types
<h1><hrwidth="100%">Special Methods of Extension Types
<hrwidth="100%"></h1>
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.
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.
<p><spanstyle="font-weight: bold;">Note:</span><i> Everything said on this page applies only to </i><spanstyle="font-weight: bold;">extension</span><istyle="font-weight: bold;">
</i><spanstyle="font-weight: bold;">types</span><i>, defined with the </i><spanstyle="font-weight: bold; font-family: monospace;">cdef class</span><i> statement. It doesn't apply
to classes defined with the Python </i><spanstyle="font-family: monospace;">class</span><i><spanstyle="font-family: monospace;"></span>statement, where the normal
...
...
@@ -20,19 +20,19 @@ to classes defined with the Python </i><span style="font-family: monospace;">cla
types. You can place a docstring in the source to serve as a comment, but
it won't show up in the corresponding <spanstyle="font-family: monospace;">__doc__</span> attribute at run time. (This
is a Python limitation -- there's nowhere in the PyTypeObject data structure
to put such docstrings.)
to put such docstrings.)
<h2><fontsize="+1">Initialisation methods: <tt>__new__</tt> and <tt>__init__</tt></font></h2>
There are two methods concerned with initialising the object<tt>.</tt>
<p>The <b><tt>__new__</tt></b> method is where you should perform basic C-level
initialisation of the object, including allocation of any C data structures
that your object will own. You need to be careful what you do in the __new__
method, because the object may not yet be a valid Python object when it is
<p>The <b><tt>__new__</tt></b> method is where you should perform basic C-level
initialisation of the object, including allocation of any C data structures
that your object will own. You need to be careful what you do in the __new__
method, because the object may not yet be a valid Python object when it is
called. Therefore, you must not invoke any Python operations which might touch
the object; in particular, do not try to call any of its methods. </p>
<p>Unlike the corresponding method in Python, your <tt>__new__</tt> method
is <i>not</i> responsible for <i>creating</i> the object. By the time your
<tt>__new__</tt> method is called, memory has been allocated for the object
and any C attributes it has have been initialised to 0 or null. (Any Python
<tt>__new__</tt> method is called, memory has been allocated for the object
and any C attributes it has have been initialised to 0 or null. (Any Python
attributes have also been initialised to <tt>None</tt>, but you probably shouldn't
rely on that.) Your <tt>__new__</tt> method is guaranteed to be called exactly
once.<br>
...
...
@@ -44,11 +44,11 @@ If you need to pass a modified argument list to the base type, you will have
to do the relevant part of the initialisation in the <tt>__init__</tt> method
instead (where the normal rules for calling inherited methods apply).<br>
</p>
<p>Note that the first parameter of the <tt>__new__</tt> method is the object
<p>Note that the first parameter of the <tt>__new__</tt> method is the object
to be initialised, not the class of the object as it is in Python. </p>
<p>Any initialisation which cannot safely be done in the <tt>__new__</tt>
method should be done in the <b><tt>__init__</tt></b> method. By the time
<tt>__init__</tt> is called, the object is a fully valid Python object and
<tt>__init__</tt> is called, the object is a fully valid Python object and
all operations are safe. Under some circumstances it is possible for <tt>__init__</tt>
to be called more than once or not to be called at all, so your other methods
should be designed to be robust in such situations. </p>
...
...
@@ -57,27 +57,27 @@ to be called more than once or not to be called at all, so your other methods
If you anticipate subclassing your extension type in Python, you may find
it useful to give the <tt>__new__</tt> method * and ** arguments so that
it can accept and ignore extra arguments. Otherwise, any Python subclass
which has an <tt>__init__</tt> with a different signature will have to override
<tt>__new__</tt> as well as <tt>__init__</tt>, which the writer of a Python
which has an <tt>__init__</tt> with a different signature will have to override
<tt>__new__</tt> as well as <tt>__init__</tt>, which the writer of a Python
@@ -35,7 +35,7 @@ The main difference is that you can use the :keyword:`cdef` statement to define
attributes. The attributes may be Python objects (either generic or of a
particular extension type), or they may be of any C data type. So you can use
extension types to wrap arbitrary C data structures and provide a Python-like
interface to them.
interface to them.
.. _readonly:
...
...
@@ -117,35 +117,35 @@ The same consideration applies to local variables, for example,::
Type Testing and Casting
------------------------
Suppose I have a method :meth:`quest` which returns an object of type :class:`Shrubbery`.
Suppose I have a method :meth:`quest` which returns an object of type :class:`Shrubbery`.
To access it's width I could write::
cdef Shrubbery sh = quest()
print sh.width
which requires the use of a local variable and performs a type test on assignment.
which requires the use of a local variable and performs a type test on assignment.
If you *know* the return value of :meth:`quest` will be of type :class:`Shrubbery`
you can use a cast to write::
print (<Shrubbery>quest()).width
This may be dangerous if :meth:`quest()` is not actually a :class:`Shrubbery`, as it
will try to access width as a C struct member which may not exist. At the C level,
rather than raising an :class:`AttributeError`, either an nonsensical result will be
This may be dangerous if :meth:`quest()` is not actually a :class:`Shrubbery`, as it
will try to access width as a C struct member which may not exist. At the C level,
rather than raising an :class:`AttributeError`, either an nonsensical result will be
returned (interpreting whatever data is at that address as an int) or a segfault
may result from trying to access invalid memory. Instead, one can write::
print (<Shrubbery?>quest()).width
which performs a type check (possibly raising a :class:`TypeError`) before making the
cast and allowing the code to proceed.
which performs a type check (possibly raising a :class:`TypeError`) before making the
cast and allowing the code to proceed.
To explicitly test the type of an object, use the :meth:`isinstance` method. By default,
in Python, the :meth:`isinstance` method checks the :class:`__class__` attribute of the
first argument to determine if it is of the required type. However, this is potentially
unsafe as the :class:`__class__` attribute can be spoofed or changed, but the C structure
of an extension type must be correct to access its :keyword:`cdef` attributes and call its :keyword:`cdef` methods. Cython detects if the second argument is a known extension
type and does a type check instead, analogous to Pyrex's :meth:`typecheck`.
To explicitly test the type of an object, use the :meth:`isinstance` method. By default,
in Python, the :meth:`isinstance` method checks the :class:`__class__` attribute of the
first argument to determine if it is of the required type. However, this is potentially
unsafe as the :class:`__class__` attribute can be spoofed or changed, but the C structure
of an extension type must be correct to access its :keyword:`cdef` attributes and call its :keyword:`cdef` methods. Cython detects if the second argument is a known extension
type and does a type check instead, analogous to Pyrex's :meth:`typecheck`.
The old behavior is always available by passing a tuple as the second parameter::
print isinstance(sh, Shrubbery) # Check the type of sh
...
...
@@ -207,7 +207,7 @@ with checking that it has the right type.
be ``None``.
* When comparing a value with ``None``, keep in mind that, if ``x`` is a Python
object, ``x is None`` and ``x is not None`` are very efficient because they
translate directly to C pointer comparisons, whereas ``x == None`` and
translate directly to C pointer comparisons, whereas ``x == None`` and
``x != None``, or simply using ``x`` as a boolean value (as in ``if x: ...``)
will invoke Python operations and therefore be much slower.
...
...
@@ -260,7 +260,7 @@ There is also a special (deprecated) legacy syntax for defining properties in an
def __del__(self):
# This is called when the property is deleted.
The :meth:`__get__`, :meth:`__set__` and :meth:`__del__` methods are all
optional; if they are omitted, an exception will be raised when the
...
...
@@ -269,7 +269,7 @@ corresponding operation is attempted.
Here's a complete example. It defines a property which adds to a list each
time it is written to, returns the list when it is read, and empties the list
when it is deleted.::
# cheesy.pyx
cdef class CheeseShop:
...
...
@@ -494,7 +494,7 @@ object called :attr:`__weakref__`. For example,::
cdef class ExplodingAnimal:
"""This animal will self-destruct when it is
no longer strongly referenced."""
cdef object __weakref__
...
...
@@ -546,7 +546,7 @@ can participate in cycles could cause memory leaks ::
cdef str name
cdef tuple addresses
If you can be sure addresses will contain only references to strings,
If you can be sure addresses will contain only references to strings,
the above would be safe, and it may yield a significant speedup, depending on
your usage pattern.
...
...
@@ -604,7 +604,7 @@ built-in complex object.::
2. As well as the name of the extension type, the module in which its type
object can be found is also specified. See the implicit importing section
below.
below.
3. When declaring an external extension type, you don't declare any
methods. Declaration of methods is not required in order to call them,
...
...
@@ -662,7 +662,7 @@ You can also specify an alternative name under which to import the type using
an as clause, for example,::
cdef extern class My.Nested.Package.Spam as Yummy:
...
...
which corresponds to the implicit import statement::
