diff options
| author | Slávek Banko <[email protected]> | 2021-03-26 13:52:33 +0100 |
|---|---|---|
| committer | Slávek Banko <[email protected]> | 2021-03-26 13:52:33 +0100 |
| commit | 0f27805eedcc40ae34009aa31a4dc08cb949f867 (patch) | |
| tree | 8b1c8995d7fdab97acde4bd7c63f96d378c34d02 /debian/pyrex/pyrex-0.9.9/Doc | |
| parent | bad411472a12b93f8bfca6b7ca52d89488a8d8ce (diff) | |
| download | extra-dependencies-0f27805eedcc40ae34009aa31a4dc08cb949f867.tar.gz extra-dependencies-0f27805eedcc40ae34009aa31a4dc08cb949f867.zip | |
DEB pyrex: Added to repository.
Signed-off-by: Slávek Banko <[email protected]>
Diffstat (limited to 'debian/pyrex/pyrex-0.9.9/Doc')
| -rw-r--r-- | debian/pyrex/pyrex-0.9.9/Doc/About.html | 149 | ||||
| -rw-r--r-- | debian/pyrex/pyrex-0.9.9/Doc/FAQ.html | 75 | ||||
| -rw-r--r-- | debian/pyrex/pyrex-0.9.9/Doc/LanguageOverview.html | 17 | ||||
| -rw-r--r-- | debian/pyrex/pyrex-0.9.9/Doc/Manual/Limitations.html | 53 | ||||
| -rw-r--r-- | debian/pyrex/pyrex-0.9.9/Doc/Manual/basics.html | 1118 | ||||
| -rw-r--r-- | debian/pyrex/pyrex-0.9.9/Doc/Manual/extension_types.html | 1079 | ||||
| -rw-r--r-- | debian/pyrex/pyrex-0.9.9/Doc/Manual/external.html | 294 | ||||
| -rw-r--r-- | debian/pyrex/pyrex-0.9.9/Doc/Manual/sharing.html | 342 | ||||
| -rw-r--r-- | debian/pyrex/pyrex-0.9.9/Doc/Manual/source_files.html | 78 | ||||
| -rw-r--r-- | debian/pyrex/pyrex-0.9.9/Doc/Manual/special_methods.html | 1124 | ||||
| -rw-r--r-- | debian/pyrex/pyrex-0.9.9/Doc/Manual/using_with_c++.html | 7 | ||||
| -rw-r--r-- | debian/pyrex/pyrex-0.9.9/Doc/Release_Notes_0.9.9.html | 43 | ||||
| -rw-r--r-- | debian/pyrex/pyrex-0.9.9/Doc/index.html | 70 | ||||
| -rw-r--r-- | debian/pyrex/pyrex-0.9.9/Doc/primes.c | 1 |
14 files changed, 4450 insertions, 0 deletions
diff --git a/debian/pyrex/pyrex-0.9.9/Doc/About.html b/debian/pyrex/pyrex-0.9.9/Doc/About.html new file mode 100644 index 00000000..373625aa --- /dev/null +++ b/debian/pyrex/pyrex-0.9.9/Doc/About.html @@ -0,0 +1,149 @@ +<!DOCTYPE html PUBLIC "-//w3c//dtd html 4.0 transitional//en"> +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.51 (Macintosh; I; PPC) [Netscape]"> + <title>About Pyrex</title></head> + +<body> + +<center> +<h1> + +<hr width="100%">Pyrex</h1></center> + +<center><i><font size="+1">A language for writing Python extension modules</font></i> +<hr width="100%"></center> + +<h2> +What is Pyrex all about?</h2> +Pyrex is a language specially designed for writing Python extension modules. +It's designed to bridge the gap between the nice, high-level, easy-to-use +world of Python and the messy, low-level world of C. +<p>You may be wondering why anyone would want a special language for this. +Python is really easy to extend using C or C++, isn't it? Why not just +write your extension modules in one of those languages? +</p><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><p>Various tools have been developed to ease some of the burdens of producing +extension code, of which perhaps <a href="http://www.swig.org">SWIG</a> +is the best known. SWIG takes a definition file consisting of a mixture +of C code and specialised declarations, and produces an extension module. +It writes all the boilerplate for you, and in many cases you can use it +without knowing about the Python/C API. But you need to use API calls if +any substantial restructuring of the data is required between Python and +C. +</p><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><p>Another notable attempt at making it easier to extend Python is <a href="http://pyinline.sourceforge.net/">PyInline</a> +, inspired by a similar facility for Perl. PyInline lets you embed pieces +of C code in the midst of a Python file, and automatically extracts them +and compiles them into an extension. But it only converts the basic types +automatically, and as with SWIG, it doesn't address the creation +of new Python types. +</p><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><p>Sound too good to be true? Read on and find out how it's done. +</p><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><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><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. +</p><blockquote><b><tt><font size="+1">primes.pyx</font></tt></b></blockquote> + +<blockquote> +<pre> 1 def primes(int kmax):<br> 2 cdef int n, k, i<br> 3 cdef int p[1000]<br> 4 result = []<br> 5 if kmax > 1000:<br> 6 kmax = 1000<br> 7 k = 0<br> 8 n = 2<br> 9 while k < kmax:<br>10 i = 0<br>11 while i < k and n % p[i] <> 0:<br>12 i = i + 1<br>13 if i == k:<br>14 p[k] = n<br>15 k = k + 1<br>16 result.append(n)<br>17 n = n + 1<br>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><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><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><p>Compiling primes.pyx with the Pyrex compiler produces an extension module +which we can try out in the interactive interpreter as follows: +</p><blockquote> +<pre>>>> import primes<br>>>> primes.primes(10)<br>[2, 3, 5, 7, 11, 13, 17, 19, 23, 29]<br>>>></pre> +</blockquote> +See, it works! And if you're curious about how much work Pyrex has saved +you, take a look at the <a href="primes.c">C code generated for this module</a> +. +<h2> +Language Details</h2> +For more about the Pyrex language, see the <a href="LanguageOverview.html">Language +Overview</a> . +<h2> +Future Plans</h2> +Pyrex is not finished. Substantial tasks remaining include: +<ul> +<li> +Support for certain Python language features which are planned but not +yet implemented. See the <a href="Manual/Limitations.html">Limitations</a> +section of the <a href="LanguageOverview.html">Language Overview</a> for a current +list.</li> +</ul> + +<ul> +<li> +C++ support. This could be a very big can of worms - careful thought required +before going there.</li> +</ul> + +<ul> +<li> +Reading C/C++ header files directly would be very nice, but there are some +severe problems that I will have to find solutions for first, such as what +to do about preprocessor macros. My current thinking is to use a separate +tool to convert .h files into Pyrex declarations, possibly with some manual +intervention.</li> +</ul> + +</body></html>
\ No newline at end of file diff --git a/debian/pyrex/pyrex-0.9.9/Doc/FAQ.html b/debian/pyrex/pyrex-0.9.9/Doc/FAQ.html new file mode 100644 index 00000000..d55f3a6a --- /dev/null +++ b/debian/pyrex/pyrex-0.9.9/Doc/FAQ.html @@ -0,0 +1,75 @@ +<!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en"> +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.51 (Macintosh; I; PPC) [Netscape]"><title>FAQ.html</title></head> +<body> + <center> <h1> <hr width="100%">Pyrex FAQ +<hr width="100%"></h1> + </center> + <h2> Contents</h2> + <ul> + <li> <b><a href="#CallCAPI">How do I call Python/C API routines?</a></b></li> + <li> <b><a href="#NullBytes">How do I convert a C string containing null + bytes to a Python string?</a></b></li> + <li> <b><a href="#NumericAccess">How do I access the data inside a Numeric + array object?</a></b></li> + <li><b><a href="#Rhubarb">Pyrex says my extension type object has no attribute +'rhubarb', but I know it does. What gives?</a></b></li><li><a style="font-weight: bold;" href="#Quack">Python says my extension type has no method called 'quack', but I know it does. What gives?</a><br> + </li> + + </ul> + <hr width="100%"> <h2> <a name="CallCAPI"></a>How do I call Python/C API routines?</h2> + Declare them as C functions inside a <tt>cdef extern from</tt> block. +Use the type name <tt>object</tt> for any parameters and return types which +are Python object references. Don't use the word <tt>const</tt> anywhere. +Here is an example which defines and uses the <tt>PyString_FromStringAndSize</tt> routine: +<blockquote><tt>cdef extern from "Python.h":</tt> <br> + <tt> object PyString_FromStringAndSize(char *, int)</tt> <p><tt>cdef char buf[42]</tt> <br> + <tt>my_string = PyString_FromStringAndSize(buf, 42)</tt></p> + </blockquote> + <h2> <a name="NullBytes"></a>How do I convert a C string containing null +bytes to a Python string?</h2> + Put in a declaration for the <tt>PyString_FromStringAndSize</tt> API routine + and use that<tt>.</tt> See <a href="#CallCAPI">How do I call Python/C API + routines?</a> <h2> <a name="NumericAccess"></a>How do I access the data inside a Numeric + array object?</h2> + Use a <tt>cdef extern from</tt> block to include the Numeric header file + and declare the array object as an external extension type. The following + code illustrates how to do this: +<blockquote><tt>cdef extern from "Numeric/arrayobject.h":</tt> <p><tt> struct PyArray_Descr:</tt> <br> + <tt> int type_num, elsize</tt> <br> + <tt> char type</tt> </p> + <p><tt> ctypedef class Numeric.ArrayType [object PyArrayObject]</tt><tt>:</tt> <br> + <tt> cdef char *data</tt> <br> + <tt> cdef int nd</tt> <br> + <tt> cdef int *dimensions, +*strides</tt> <br> + <tt> cdef object base</tt> + <br> + <tt> cdef PyArray_Descr *descr</tt> <br> + <tt> cdef int flags<br> + </tt></p> +</blockquote> +<p>For more information about external extension types, see the <a href="extension_types.html#ExternalExtTypes">"External Extension Types"</a> +section of the <a href="extension_types.html">"Extension Types"</a> documentation +page.<br> +<tt> </tt> </p> + <h2><a name="Rhubarb"></a>Pyrex says my extension type object has no attribute +'rhubarb', but I know it does. What gives?</h2> +You're probably trying to access it through a reference which Pyrex thinks +is a generic Python object. You need to tell Pyrex that it's a reference +to your extension type by means of a declaration. For example,<br> +<blockquote><tt>cdef class Vegetables:</tt><br> + <tt> cdef int rhubarb</tt><br> + <br> + <tt>...</tt><br> + <tt>cdef Vegetables veg</tt><br> + <tt>veg.rhubarb = 42</tt><br> +</blockquote> +Also see the <a href="Manual/extension_types.html#ExtTypeAttrs">"Attributes"</a> +section of the <a href="Manual/extension_types.html">"Extension +Types"</a> documentation page.<br> +<h2><a name="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 <span style="font-family: monospace;">cdef</span> instead of <span style="font-family: monospace;">def</span>. Only functions and methods declared with <span style="font-family: monospace;">def</span> are callable from Python code.<br><br> +--- +</body></html>
\ No newline at end of file diff --git a/debian/pyrex/pyrex-0.9.9/Doc/LanguageOverview.html b/debian/pyrex/pyrex-0.9.9/Doc/LanguageOverview.html new file mode 100644 index 00000000..17722e55 --- /dev/null +++ b/debian/pyrex/pyrex-0.9.9/Doc/LanguageOverview.html @@ -0,0 +1,17 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> +<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="content-type"><title>Pyrex Language Overview</title></head> +<body> + + +<h1> +<hr width="100%">Overview of the Pyrex Language +<hr width="100%"></h1> + + + This is a combined tutorial and reference manual that describes the extensions to the Python language + made by Pyrex.<h2> Contents</h2> + + + +<ul><li><a href="Manual/source_files.html">Source Files and Compilation</a> <span style="color: rgb(0, 153, 0);">(Section added in 0.9.5)</span><br> + </li><li><a href="Manual/basics.html">Language Basics</a></li><li> <a href="Manual/external.html">Interfacing with External C Code</a></li><li> <a href="Manual/extension_types.html">Extension Types</a></li><li><a href="Manual/special_methods.html">Special Methods of Extension Types</a></li><li> <a href="Manual/sharing.html">Sharing Declarations Between Pyrex Modules</a></li><li><a href="Manual/using_with_c++.html">Using Pyrex with C++</a></li><li> <a href="Manual/Limitations.html">Limitations</a></li></ul>---</body></html>
\ No newline at end of file diff --git a/debian/pyrex/pyrex-0.9.9/Doc/Manual/Limitations.html b/debian/pyrex/pyrex-0.9.9/Doc/Manual/Limitations.html new file mode 100644 index 00000000..74131730 --- /dev/null +++ b/debian/pyrex/pyrex-0.9.9/Doc/Manual/Limitations.html @@ -0,0 +1,53 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> +<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="content-type"><title>Limitations</title></head> +<body><h1><hr width="100%"> +<a name="Limitations"></a>Limitations <hr width="100%"></h1><h2> <a name="Unsupported"></a>Unsupported +Python features</h2> +Pyrex 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> + <li> Class definitions can only appear at the top +level of a module, not inside a function.<br> </li> + <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> <br> </li> <li> +The <tt>globals()</tt> and <tt>locals()</tt> +functions cannot be used.</li> </blockquote> The above +restrictions will most likely remain, since removing them would be +difficult and they're not really needed for Pyrex's intended +applications. <p>There are also some temporary limitations, +which may eventually be lifted, including: </p> <blockquote> +<li> Class and function definitions cannot be placed inside +control structures.<br> </li> <li> List comprehensions are not yet +supported.<br> </li> <li> There is no +support for Unicode.<br> </li> <li> +Special methods of extension types cannot have functioning +docstrings.<br> <br> </li> <li> The use of +string literals as comments is not recommended at present, because they are not accepted in +places where executable statements are not allowed.</li></blockquote><hr style="width: 100%; height: 2px;"><h2><a name="SemanticDifferences"></a>Semantic +differences between Python and Pyrex</h2> <h3> Behaviour +of class scopes</h3> 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="#Footnote1">1</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 <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> <pre>class Spam:</pre><pre> method = classmethod(Spam_method)</pre> +</blockquote> <hr width="100%"><span style="font-weight: bold;">Footnotes</span><br><hr style="width: 100%; height: 2px;"><a name="Footnote1"></a>1. +The reason for the different +behaviour +of class scopes is that Pyrex-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 +storing it in the class's dictionary.<br><br>--- </body></html>
\ No newline at end of file diff --git a/debian/pyrex/pyrex-0.9.9/Doc/Manual/basics.html b/debian/pyrex/pyrex-0.9.9/Doc/Manual/basics.html new file mode 100644 index 00000000..132c2899 --- /dev/null +++ b/debian/pyrex/pyrex-0.9.9/Doc/Manual/basics.html @@ -0,0 +1,1118 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> +<html><head> +<meta content="text/html; charset=ISO-8859-1" http-equiv="content-type"><title>Language Basics</title> + +</head> +<body> +<h1> +<hr style="width: 100%; height: 2px;">Language +Basics +<hr width="100%"></h1> +<ul id="mozToc"> +<!--mozToc h2 1 h3 2--><li><a href="#mozTocId641350">Python +functions vs. C functions</a></li> +<li><a href="#mozTocId972536">Python objects as +parameters +and return values</a></li> +<li><a href="#mozTocId155104">C +variable and type definitions</a> +<ul> +<li><a href="#mozTocId890190">Forward +Declarations</a></li> +<li><a href="#mozTocId522210">Grouping +multiple C declarations</a></li> +</ul> +</li> +<li><a href="#mozTocId763321">Automatic +type conversions</a> +<ul> +<li><a href="#mozTocId440941">Caveats +when using a Python string in a C context</a></li> +</ul> +</li> +<li><a href="#mozTocId834148">Scope rules</a></li> +<li><a href="#mozTocId954330">Statements and +expressions</a> +<ul> +<li><a href="#mozTocId401576">Differences +between C +and Pyrex +expressions</a></li> +<li><a href="#mozTocId899067">Integer for-loops</a></li> +<li><a href="#mozTocId457396">Catching +exceptions and tracebacks</a></li> +</ul> +</li> +<li><a href="#mozTocId482761">Error return values</a> +<ul> +<li><a href="#mozTocId622828">Checking +return values of non-Pyrex functions</a></li> +</ul> +</li> +<li><a href="#mozTocId494354">The include +statement</a></li> +<li><a href="#mozTocId849661">Keyword-only +arguments</a></li> +<li><a href="#mozTocId829237">Built-in Names</a> +<ul> +<li><a href="#mozTocId813519">Built-in +Constants</a></li> +<li><a href="#mozTocId593628">Built-in +Functions</a></li> +<li><a href="#mozTocId452377">Built-in Types</a></li> +</ul> +</li> +<li><a href="#mozTocId42018">Conditional +Compilation</a> +<ul> +<li><a href="#mozTocId379306">Compile-Time +Definitions</a></li> +<li><a href="#mozTocId997015">Conditional +Statements</a></li> +</ul> +</li> +</ul> +This +section describes the basic features of the Pyrex 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="external.html">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>.<br> +<h2><a class="mozTocH2" name="mozTocId641350"></a> +<a name="PyFuncsVsCFuncs"></a>Python +functions vs. C functions</h2> +There are two kinds of function +definition in Pyrex: +<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> +<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 Pyrex 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> +<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 they're passed in +directly using a normal C function call. </p> +<h2><a class="mozTocH2" name="mozTocId972536"></a> +<a name="PyObjParams"></a>Python objects as +parameters +and return values</h2> +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 object: +<blockquote> +<pre>cdef spamobjs(x, y):<br> ...</pre> +</blockquote> +Reference counting for these objects is performed +automatically according to the standard Python/C API rules (i.e. +borrowed references are taken as parameters and a new reference is +returned). +<p>The name <b>object</b> can also be +used to explicitly declare something as a Python object. This can be +useful if the name being declared would otherwise +be taken as the name of a type, for example, </p> +<blockquote> +<pre>cdef ftang(object int):<br> ...</pre> +</blockquote> +declares +a parameter called <tt>int</tt> +which is a Python object. You can also use <b>object </b>as +the explicit return type of a function, e.g. +<blockquote> +<pre>cdef object ftang(object int):<br> ...</pre> +</blockquote> +In the interests of clarity, it is probably a good +idea to always be explicit about <b>object </b>parameters +in C functions. +<h2><a class="mozTocH2" name="mozTocId155104"></a><a name="CVarAndTypeDecls"></a>C +variable and type definitions</h2> +The <b>cdef</b> +statement is also used to declare C variables, either +local or module-level: +<blockquote> +<pre>cdef int i, j, k<br>cdef float f, g[42], *h</pre> +</blockquote> +and C struct, union or enum types: +<blockquote> +<pre>cdef struct Grail:<br> int age<br> float volume</pre> +<pre>cdef union Food:<br> char *spam<br> float *eggs</pre> +<pre>cdef enum CheeseType:<br> cheddar, edam, <br> camembert</pre> +<pre>cdef enum CheeseState:<br> hard = 1<br> soft = 2<br> runny = 3</pre> +</blockquote> +There is currently no special syntax for defining a +constant, but you +can use an anonymous enum declaration for this purpose, for example, +<blockquote><tt>cdef +enum:</tt> <br> +<tt> +tons_of_spam = 3</tt></blockquote> +Note that the words <span style="font-family: monospace;">struct</span>, +<span style="font-family: monospace;">union</span> +and <span style="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 +<blockquote> +<pre>cdef Grail *gp</pre> +</blockquote> +and <i>not</i> +<blockquote> +<pre>cdef struct Grail *gp <font color="#ed181e"># WRONG</font></pre> +</blockquote> +There is also a <b>ctypedef</b> statement for giving names +to types, e.g. +<blockquote> +<pre>ctypedef unsigned long ULong</pre> +<pre>ctypedef int *IntPtr<br></pre> +</blockquote> +<h3><a class="mozTocH2" name="mozTocId890190"></a>Forward +Declarations</h3> +If +you have two struct or union types containing pointers that refer to +each other, you will need to use a forward declaration for at least one +of them. This is simply the header of a struct or union without the +colon or body, for example,<br> +<br> +<div style="margin-left: 40px;"><span style="font-family: monospace;">cdef struct Sandwich</span><br style="font-family: monospace;"> +<br style="font-family: monospace;"> +<span style="font-family: monospace;">cdef struct Lunchbox:</span><br style="font-family: monospace;"> +<div style="margin-left: 40px;"><span style="font-family: monospace;">Sandwich *lunch</span><br style="font-family: monospace;"> +</div> +<br style="font-family: monospace;"> +<span style="font-family: monospace;">cdef struct Sandwich:</span><br style="font-family: monospace;"> +<div style="margin-left: 40px;"><span style="font-family: monospace;">Lunchbox *container</span><br> +</div> +</div> +<br> +You +can also forward-declare C functions, but there should be little need +to do this. Pyrex processes all declarations in a module before +analysing any executable statements, so calling a function defined +further down in the source file is usually not a problem. +<h3><a class="mozTocH2" name="mozTocId522210"></a><a name="Grouping_multiple_C_declarations"></a>Grouping +multiple C declarations</h3> +If you have a series of declarations that all begin with <span style="font-family: monospace;">cdef</span>, you can +group them into a cdef block like this:<br> +<pre style="margin-left: 40px;">cdef:<br><br> struct Spam:<br> int tons<br><br> int i<br> float f<br> Spam *p<br><br> void f(Spam *s):<br> print s.tons, "Tons of spam"<br> </pre> +<h2><a class="mozTocH2" name="mozTocId763321"></a><a name="AutomaticTypeConversions"></a>Automatic +type conversions</h2> +In most situations, automatic conversions will be performed for the +basic numeric and string types when a Python object is used in a +context requiring a C value, or vice versa. The following table +summarises the conversion possibilities.<br> +<br> +<table style="text-align: left; background-color: rgb(204, 255, 255); width: 10%; margin-left: 40px;" border="1" cellpadding="4" cellspacing="0"> +<tbody> +<tr> +<th style="vertical-align: top; width: 40%; white-space: nowrap; background-color: rgb(255, 204, 51);">C +types<br> +</th> +<th style="vertical-align: top; width: 150px; white-space: nowrap; background-color: rgb(255, 204, 51);">From +Python types<br> +</th> +<th style="vertical-align: top; width: 150px; white-space: nowrap; background-color: rgb(255, 204, 51);">To +Python types<br> +</th> +</tr> +<tr> +<td colspan="1" rowspan="1" style="vertical-align: top; width: 40%; white-space: nowrap;">[unsigned] +char<br> +[unsigned] short<br> +int, long</td> +<td colspan="1" rowspan="1" style="vertical-align: top; width: 150px; white-space: nowrap;">int, +long<br> +</td> +<td colspan="1" rowspan="1" style="vertical-align: top; width: 150px; white-space: nowrap;">int<br> +</td> +</tr> +<tr> +</tr> +<tr> +<td colspan="1" rowspan="1" style="vertical-align: top; width: 40%; white-space: nowrap;">unsigned +int<br> +unsigned long<br> +[unsigned] long long<br> +</td> +<td colspan="1" rowspan="1" style="vertical-align: top; white-space: nowrap;">int, long<br> +<br> +</td> +<td colspan="1" rowspan="1" style="vertical-align: top; white-space: nowrap;">long<br> +<br> +</td> +</tr> +<tr> +</tr> +<tr> +<td style="vertical-align: top; width: 40%; white-space: nowrap;">float, +double, long double<br> +</td> +<td style="vertical-align: top; width: 150px; white-space: nowrap;">int, +long, float<br> +</td> +<td style="vertical-align: top; width: 150px; white-space: nowrap;">float<br> +</td> +</tr> +<tr> +<td style="vertical-align: top; width: 40%; white-space: nowrap;">char +*<br> +</td> +<td style="vertical-align: top; width: 150px; white-space: nowrap;">str<span style="font-style: italic;"></span><br> +</td> +<td style="vertical-align: top; width: 150px; white-space: nowrap;">str<br> +</td> +</tr> +</tbody> +</table> +<br> +<h3><a class="mozTocH3" name="mozTocId440941"></a><a name="PyToCStringCaveats"></a>Caveats +when using a Python string in a C context</h3> +You need to be careful when using a Python string in a context +expecting a <span style="font-family: monospace;">char *</span>. +In this situation, a pointer to the contents of the Python string is +used, which is only valid as long as the Python string exists. So you +need to make sure that a reference to the original Python string is +held for as long as the C string is needed. If you can't guarantee that +the Python string will live long enough, you will need to copy the C +string.<br> +<br> +Pyrex detects and prevents <span style="font-style: italic;">some</span> +mistakes of +this kind. For instance, if you attempt something like<br> +<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>". +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, +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> +<br> +The solution is to assign the result of the concatenation to +a Python variable, and then obtain the char * from that, i.e.<br> +<pre style="margin-left: 40px;">cdef char *s<br>p = pystring1 + pystring2<br>s = p<br></pre> +It +is then your responsibility to hold the reference <span style="font-family: monospace;">p</span> for as long +as necessary.<br> +<br> +Keep in mind that the rules used to detect such errors are +only +heuristics. Sometimes Pyrex 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. +<h2><a class="mozTocH2" name="mozTocId834148"></a><a name="ScopeRules"></a>Scope rules</h2> +Pyrex +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 Python, however, a name which is referred +to but not declared or assigned is assumed to reside in the <i>builtin +scope, </i>not the module scope. +Names added to the module dictionary at run time will not shadow such +names.<br> +<br> +This can result in some odd things happening under rare circumstances, +for example<br> +<br> +<div style="margin-left: 40px;"><tt>print __name__</tt></div> +<p>In +Pyrex, instead of printing the name of the current module, this prints +the name of the builtins module. The reason is that because Pyrex +hasn't seen a declaration of anything called <span style="font-family: monospace;">__name__</span> in the +module, it's assumed to reside in the builtins. The solution is to use +a <span style="font-weight: bold;">global</span> +statement to declare <span style="font-family: monospace;">__name__</span> +as a module-level name:</p> +<p style="margin-left: 40px;"><tt>global +__name__</tt><tt><br> +print __name__</tt></p> +Another +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> +<blockquote> +<pre>try:<br> x = True<br>except NameError:<br> True = 1<br></pre> +</blockquote> +because, due to the assignment in the last line, <span style="font-family: monospace;">True</span> will +always be looked up in the module-level scope. You would have to do +something like this instead:<br> +<blockquote> +<pre>import __builtin__<br>try:<br> True = __builtin__.True<br>except AttributeError:<br> True = 1<br></pre> +</blockquote> +<hr width="100%"> +<h2><a class="mozTocH2" name="mozTocId954330"></a><a name="StatsAndExprs"></a>Statements and +expressions</h2> +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 action taken. </p> +<h3><a class="mozTocH3" name="mozTocId401576"></a> +<a name="ExprSyntaxDifferences"></a>Differences +between C +and Pyrex +expressions</h3> +There +are some differences in syntax and semantics between C expressions and +Pyrex 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>, use <tt>p.x</tt></li> + <li> There is no <b><tt>*</tt></b> +operator in Pyrex. 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 +example:</li> +<ul> +<pre>c'X'</pre> +</ul> +<li>Type casts are written <b><tt><type>value</tt></b> +, for example:</li> +<ul> +<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 the conversion automatically.</i> +</ul> +<h4>Operator Precedence</h4> +Keep in mind that there are +some differences +in operator precedence between Python and C, and that Pyrex uses the +Python precedences, not the C ones. +<h3><a class="mozTocH3" name="mozTocId899067"></a>Integer +for-loops</h3> +You should be aware that a for-loop such as +<blockquote><tt>for +i in range(n):</tt> <br> +<tt> +...</tt></blockquote> +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: +<blockquote><tt>for 0 <= i +< n:</tt> <br> +<tt> +...</tt></blockquote> +Provided 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 pure C code. +<p>Some +things to note about the integer for-loop: </p> +<ul> +<li> The target expression (the middle one) must be a variable +name.</li> +<li>The direction of iteration is +determined by the relations. If they are both from the set {<tt><</tt>, +<tt><=</tt>} then it is upwards; if they are +both +from the set {<tt>></tt>, <tt>>=</tt>} +then it is +downwards. (Any other combination is disallowed.)</li> +</ul> +Like other Python looping statements, <tt>break</tt> and <tt>continue</tt> +may be used in the body, and the loop may have an <tt>else</tt> +clause. +<h3><a class="mozTocH3" name="mozTocId457396"></a>Catching +exceptions and tracebacks</h3> +For +reasons of efficiency, there are some differences between Pyrex and +Python concerning the way exceptions caught by a try-except statement +are handled.<br> +<ul> +<li>Exceptions caught by an <span style="font-family: monospace;">except</span> clause <span style="font-style: italic;">cannot</span> be retrieved +using <span style="font-family: monospace;">sys.exc_info()</span>. +To access the caught exception, you must bind it to a name in the +except clause.<br><br>Pyrex also allows an additional name to be provided for +catching the traceback. For example,</li> +</ul> +<pre style="margin-left: 80px;">try:<br> start_engine()<br>except HovercraftError, e, tb:<br> print "Got an error:", e<br> traceback.print_tb(tb)</pre> +<ul> +<li>A <span style="font-family: monospace;">raise</span> +statement with no arguments (to re-raise the last exception caught) +must be lexically enclosed in the <span style="font-family: monospace;">except</span> clause +which caught the exception. A raise statement in a Python function +called from the except clause will <span style="font-style: italic;">not</span> +work.</li> +</ul> +<pre style="margin-left: 80px;">try:<br> start_engine()<br>except HovercraftError, e:<br> print "Unable to start:", e<br> raise # the exception caught by the enclosing except clause</pre> +<h2><a class="mozTocH2" name="mozTocId329136"></a> +<hr width="100%"></h2> +<h2><a class="mozTocH2" name="mozTocId482761"></a><a name="ExceptionValues"></a>Error return values</h2> +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 +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. +<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, +Pyrex 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 <i>every</i> +call to <code>spam</code>, 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. +<p>Some things to note: </p> +<ul> +<li>Exception values can only declared for functions +returning an integer, enum, float or pointer type, and the value must +be a constant expression. The only possible pointer exception value is <tt>NULL</tt>. +Void functions can only use the <tt>except *</tt> form.</li> + <li> The exception value specification is part of the +signature +of the function. If you're passing a pointer to a function as a +parameter +or assigning it to a variable, the declared type of the parameter or +variable must have the same exception value specification (or lack +thereof). Here +is an example of a pointer-to-function declaration with an exception +value:</li> +<ul> +<pre><tt>int (*grail)(int, char *) except -1</tt></pre> +</ul> +<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> +<h3><a class="mozTocH3" name="mozTocId622828"></a> +<a name="CheckingReturnValues"></a>Checking +return values of non-Pyrex functions</h3> +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 +example, you can't write something like +<blockquote> +<pre>cdef extern FILE *fopen(char *filename, char *mode) except NULL <font color="#ed181e"># WRONG!</font></pre> +</blockquote> +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 +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> +</blockquote> +<h4> +<hr width="100%"></h4> +<h2><a class="mozTocH2" name="mozTocId494354"></a> +<a name="IncludeStatement"></a>The <tt>include</tt> +statement</h2> +A Pyrex source file can include material from other files +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 +statements or declarations that are valid in the context where the +include statement appears, including other <b>include</b> +statements. The contents of the included file should begin at an +indentation level of zero, and will be treated as though they were +indented to the level of the include statement that is including the +file.<br> +<br> +Note +that there are other mechanisms available for splitting Pyrex code into +separate parts that may be more appropriate in many cases. See<a href="sharing.html"> Sharing Declarations Between +Pyrex Modules</a>.<br> +<hr style="width: 100%; height: 2px;"> +<h2><a class="mozTocH2" name="mozTocId849661"></a><a name="KeywordOnlyArguments"></a>Keyword-only arguments</h2> +<p>Python +functions can have keyword-only arguments listed after the * parameter +and before the ** paramter if any, e.g.</p> +<pre style="margin-left: 40px;">def f(a, b, *args, c, d = 42, e, **kwds):<br> ...<br></pre> +Here +c, d and e cannot be passed as position arguments and must be passed as +keyword arguments. Furthermore, c and e are required keyword arguments, +since they do not have a default value.<br> +<br> +If the +parameter name after the * is omitted, the function will not accept any +extra positional arguments, e.g.<br> +<br> +<pre style="margin-left: 40px;">def g(a, b, *, c, d):<br> ...<br></pre> +takes +exactly two positional parameters and has two required keyword +parameters.<br> +<br> +<hr style="width: 100%; height: 2px;"> +<h2><a class="mozTocH2" name="mozTocId829237"></a><a name="Built-in_Names"></a>Built-in Names</h2> +Pyrex +knows about many of the names in the builtin namespace, and treats them +specially in the interests of generating efficient code.<br> +<h3><a class="mozTocH3" name="mozTocId813519"></a><a name="Built-in_Constants"></a>Built-in Constants</h3> +Pyrex +knows the following built-in constant and type names, and references +their values directly instead of using a dictionary lookup.<br> +<br> +<table style="background-color: rgb(204, 255, 255); width: 10px; margin-left: 40px;" border="1" cellpadding="5" cellspacing="0"> +<tbody> +<tr> +<td style="vertical-align: top; white-space: nowrap; text-align: left; background-color: rgb(255, 204, 0);">Type +objects (type <span style="font-family: monospace;">type</span>)</td> +<td colspan="2" rowspan="1" style="vertical-align: top; white-space: nowrap; text-align: left; background-color: rgb(255, 204, 0);">Exceptions +(type <span style="font-family: monospace;">type</span>)</td> +</tr> +<tr> +<td style="vertical-align: top; white-space: nowrap; text-align: left; height: 10px;">buffer<br> +enumerate<br> +file<br> +float<br> +int<br> +long<br> +open<br> +property<br> +str<br> +tuple<br> +xrange</td> +<td colspan="1" rowspan="3" align="left" nowrap="nowrap" valign="top">Exception<br> +StopIteration<br> +StandardError<br> +ArithmeticError<br> +LookupError<br> +AsssertionError<br> +EOFError<br> +FloatingPointError<br> +EnvironmentError<br> +IOError<br> +OSError<br> +ImportError<br> +IndexError<br> +KeyError<br> +KeyboardInterrupt<br> +MemoryError<br> +NameError<br> +OverflowError<br> +RuntimeError<br> +NotImplementedError<br> +SyntaxError</td> +<td colspan="1" rowspan="3" style="vertical-align: top; white-space: nowrap; text-align: left;">IndentationError<br> +TabError<br> +ReferenceError<br> +SystemError<br> +SystemExit<br> +TypeError<br> +UnboundLocalError<br> +UnicodeError<br> +UnicodeEncodeError<br> +UnicodeDecodeError<br> +UnicodeTranslateError<br> +ValueError<br> +ZeroDivisionError<br> +Warning<br> +UserWarning<br> +DeprecationWarning<br> +PendingDeprecationWarning<br> +SyntaxWarning<br> +OverflowWarning<br> +RuntimeWarning<br> +FutureWarning</td> +</tr> +<tr> +<td style="vertical-align: top; white-space: nowrap; text-align: left; height: 10px; background-color: rgb(255, 204, 0);">Constants +(type <span style="font-family: monospace;">object</span>)</td> +</tr> +<tr> +<td align="left" nowrap="nowrap" valign="top">True<br> +False<br> +Ellipsis</td> +</tr> +<tr> +</tr> +<tr> +</tr> +<tr> +</tr> +<tr> +</tr> +<tr> +</tr> +<tr> +</tr> +<tr> +</tr> +<tr> +</tr> +<tr> +</tr> +<tr> +</tr> +<tr> +</tr> +<tr> +</tr> +</tbody> +</table> +<br> +Note that although some of the above names refer to type objects, they +are not Pyrex type names and therefore can't be used to declare the +type of a variable. Only the names listed under Built-in Types below +can be used as type names in declarations.<br> +<h3><a class="mozTocH3" name="mozTocId593628"></a><a name="Built-in_Functions"></a>Built-in Functions</h3> +Pyrex +compiles calls to the following built-in functions into direct calls to +the corresponding Python/C API routines, making them particularly fast.<br> +<br> +<table style="text-align: left; background-color: rgb(204, 255, 255); margin-left: 40px;" border="1" cellpadding="4" cellspacing="0"> +<tbody> +<tr> +<td style="font-weight: bold; background-color: rgb(255, 204, 51);">Function +and arguments</td> +<td style="font-weight: bold; background-color: rgb(255, 204, 51);">Return +type</td> +<td style="font-weight: bold; white-space: nowrap; background-color: rgb(255, 204, 51);">Python/C +API Equivalent</td> +</tr> +<tr> +<td>abs(obj)</td> +<td>object</td> +<td>PyNumber_Absolute</td> +</tr> +<tr> +<td align="left" nowrap="nowrap" valign="top">bool(obj) + <span style="font-style: italic;">(Note 3)</span></td> +<td align="left" nowrap="nowrap" valign="top">int</td> +<td align="left" nowrap="nowrap" valign="top">PyObject_IsTrue</td> +</tr> +<tr> +<td>delattr(obj, name)</td> +<td>int</td> +<td>PyObject_DelAttr</td> +</tr> +<tr> +<td>dir(obj)</td> +<td>object</td> +<td>PyObject_Dir</td> +</tr> +<tr> +<td>divmod(x, y)</td> +<td>object</td> +<td>PyNumber_Divmod</td> +</tr> +<tr> +<td style="white-space: nowrap;">getattr(obj, name) +<span style="font-style: italic;"> (Note 1</span>)<br> +getattr3(obj, name, default)</td> +<td>object</td> +<td>PyObject_GetAttr</td> +</tr> +<tr> +<td>hasattr(obj, name)</td> +<td>int</td> +<td>PyObject_HasAttr</td> +</tr> +<tr> +<td>hash(obj)</td> +<td>int</td> +<td>PyObject_Hash</td> +</tr> +<tr> +<td>cintern(char *)<span style="font-style: italic;"> + (Note 5)</span></td> +<td>object</td> +<td>PyString_InternFromString</td> +</tr> +<tr> +<td>isinstance(obj, type)</td> +<td>int</td> +<td>PyObject_IsInstance</td> +</tr> +<tr> +<td>issubclass(obj, type)</td> +<td>int</td> +<td>PyObject_IsSubclass</td> +</tr> +<tr> +<td align="left" nowrap="nowrap" valign="top">issubtype(type, +type) <span style="font-style: italic;">(Note 4</span>)</td> +<td align="left" nowrap="nowrap" valign="top">int</td> +<td align="left" nowrap="nowrap" valign="top">PyType_IsSubType</td> +</tr> +<tr> +<td>iter(obj)</td> +<td>object</td> +<td>PyObject_GetIter</td> +</tr> +<tr> +<td align="left" nowrap="nowrap" valign="top">iter2(obj, +obj)</td> +<td align="left" nowrap="nowrap" valign="top">object</td> +<td align="left" nowrap="nowrap" valign="top">PyCallIter_New</td> +</tr> +<tr> +<td>len(obj)</td> +<td>Py_ssize_t</td> +<td>PyObject_Length</td> +</tr> +<tr> +<td style="width: 1px;">pow(x, y, z) <span style="font-style: italic;"> (Note 2)</span></td> +<td style="width: 1px;">object</td> +<td style="width: 1px;">PyNumber_Power</td> +</tr> +<tr> +<td>reload(obj)</td> +<td>object</td> +<td>PyImport_ReloadModule</td> +</tr> +<tr> +<td>repr(obj)</td> +<td>object</td> +<td>PyObject_Repr</td> +</tr> +<tr> +<td style="width: 200px;">setattr(obj, name)</td> +<td style="width: 100px;">void</td> +<td style="width: 150px;">PyObject_SetAttr</td> +</tr> +<tr> +<td align="left" nowrap="nowrap" valign="top">typecheck(obj, +type) <span style="font-style: italic;">(Note +4)</span></td> +<td align="left" nowrap="nowrap" valign="top">int</td> +<td align="left" nowrap="nowrap" valign="top">PyObject_TypeCheck</td> +</tr> +</tbody> +</table> +<br> +<div style="margin-left: 40px;"><span style="font-style: italic;">Note 1:</span> There are +two different functions corresponding to the Python <span style="font-family: monospace;">getattr</span> +depending on whether a third argument is used. In a non-call context, +they both evaluate to the Python <span style="font-family: monospace;">getattr</span> +function.<br> +<br> +<span style="font-style: italic;">Note 2:</span> +Only the three-argument form of <span style="font-family: monospace;">pow()</span> is +supported. Use the <span style="font-family: monospace;">**</span> +operator otherwise.<br> +<br> +<span style="font-style: italic;">Note 3:</span> In +a non-call context, the name <span style="font-family: monospace;">bool</span> +refers to the Python built-in bool type.<br> +<br> +<span style="font-style: italic;">Note 4:</span> The +functions <span style="font-family: monospace;">typecheck</span> +and <span style="font-family: monospace;">issubtype</span> +have no exact Python equivalent. They are included for fast, safe type +checking of extension types. They are safer than using <span style="font-family: monospace;">isinstance</span> and <span style="font-family: monospace;">issubclass</span> +for this purpose, because the behaviour of the latter functions can be +overridden, so they don't necessarily reflect the true C types of the +objects involved.<br> +<br> +<span style="font-style: italic;">Note 5:</span> +This function is named <span style="font-family: monospace;">cintern</span> +instead of <span style="font-family: monospace;">intern</span> +because it takes a null-terminated C string rather than a Python +string, and therefore cannot handle strings containing null bytes.<br> +</div> +<br> +Only +direct function calls using these names are optimised. If you do +something else with one of these names that assumes it's a Python +object, such as assign it to a Python variable, and later call it, the +call will be made as a Python function call. +<h3><a class="mozTocH3" name="mozTocId452377"></a><a name="BuiltinTypes"></a>Built-in Types</h3> +Pyrex +knows about the following builtin +types:<br> +<br> +<div style="margin-left: 40px;"><span style="font-family: monospace;">dict</span><br style="font-family: monospace;"> +<span style="font-family: monospace;">list</span><br> +<span style="font-family: monospace;">object</span><br style="font-family: monospace;"> +<span style="font-family: monospace;">slice</span><br style="font-family: monospace;"> +<span style="font-family: monospace;">type</span><br> +</div> +<br> +If you declare a variable as being of one of these types, then +calls to the methods in the table below will be compiled to direct +Python/C API calls, +avoiding the overhead of a Python attribute lookup and function call. +In the case of attributes, they will be accessed directly from the +object's C struct.<br> +<br> +Referring to the types themselves is also +slightly more efficient, because the relevant type object is accessed +directly rather than via a global variable lookup.<br> +<br> +<table style="text-align: left; background-color: rgb(204, 255, 255); width: 665px; height: 330px;" border="1" cellpadding="4" cellspacing="0"> +<tbody> +<tr> +<td style="font-weight: bold; background-color: rgb(255, 204, 51);">Method +or Attribute</td> +<td style="font-weight: bold; background-color: rgb(255, 204, 51);">Return +type</td> +<td colspan="1" rowspan="1" style="font-weight: bold; white-space: nowrap; background-color: rgb(255, 204, 51);">Python/C +API Equivalent</td> +<td style="background-color: rgb(255, 204, 51); font-weight: bold;" align="left" nowrap="nowrap">Notes</td> +</tr> +<tr> +<td colspan="4" rowspan="1" style="vertical-align: top; white-space: nowrap; text-align: left; background-color: rgb(51, 153, 153);"><span style="font-weight: bold;">Type </span><span style="font-family: monospace; font-weight: bold;">dict</span></td> +</tr> +<tr> +<td align="left" nowrap="nowrap" valign="top">clear()</td> +<td align="left" nowrap="nowrap" valign="top"></td> +<td align="left" nowrap="nowrap" valign="top">PyDict_Clear</td> +<td align="left" nowrap="nowrap" valign="top"></td> +</tr> +<tr> +<td align="left" nowrap="nowrap" valign="top">copy()</td> +<td align="left" nowrap="nowrap" valign="top"></td> +<td align="left" nowrap="nowrap" valign="top">PyDict_Copy</td> +<td align="left" nowrap="nowrap" valign="top"></td> +</tr> +<tr> +<td align="left" nowrap="nowrap" valign="top">items()</td> +<td align="left" nowrap="nowrap" valign="top">object</td> +<td align="left" nowrap="nowrap" valign="top">PyDict_Items</td> +<td align="left" nowrap="nowrap" valign="top"></td> +</tr> +<tr> +<td align="left" nowrap="nowrap" valign="top">keys()</td> +<td align="left" nowrap="nowrap" valign="top">object</td> +<td align="left" nowrap="nowrap" valign="top">PyDict_Keys</td> +<td align="left" nowrap="nowrap" valign="top"></td> +</tr> +<tr> +<td align="left" nowrap="nowrap" valign="top">values()</td> +<td align="left" nowrap="nowrap" valign="top">object</td> +<td align="left" nowrap="nowrap" valign="top">PyDict_Values</td> +<td align="left" nowrap="nowrap" valign="top"></td> +</tr> +<tr> +<td align="left" nowrap="nowrap" valign="top">merge(obj, +override)</td> +<td align="left" nowrap="nowrap" valign="top"></td> +<td align="left" nowrap="nowrap" valign="top">PyDict_Merge</td> +<td align="left" nowrap="nowrap" valign="top">Merge +items from a mapping</td> +</tr> +<tr> +<td align="left" nowrap="nowrap" valign="top">update(obj)</td> +<td align="left" nowrap="nowrap" valign="top"></td> +<td align="left" nowrap="nowrap" valign="top">PyDict_Update</td> +<td align="left" nowrap="nowrap" valign="top"></td> +</tr> +<tr> +<td align="left" nowrap="nowrap" valign="top">merge_pairs(obj, override)</td> +<td align="left" nowrap="nowrap" valign="top"></td> +<td align="left" nowrap="nowrap" valign="top">PyDict_MergeFromSeq2</td> +<td align="left" nowrap="nowrap" valign="top">Merge +(key, value) pairs from a sequence</td> +</tr> +<tr> +<td colspan="4" rowspan="1" style="vertical-align: top; white-space: nowrap; text-align: left; background-color: rgb(51, 153, 153);"><span style="font-weight: bold;">Type </span><span style="font-family: monospace; font-weight: bold;">list</span></td> +</tr> +<tr> +<td align="left" nowrap="nowrap" valign="top">insert(int, +obj)</td> +<td align="left" nowrap="nowrap" valign="top"></td> +<td align="left" nowrap="nowrap" valign="top">PyList_Insert</td> +<td align="left" nowrap="nowrap" valign="top"></td> +</tr> +<tr> +<td align="left" nowrap="nowrap" valign="top">append(obj)</td> +<td align="left" nowrap="nowrap" valign="top"></td> +<td align="left" nowrap="nowrap" valign="top">PyList_Append</td> +<td align="left" nowrap="nowrap" valign="top"></td> +</tr> +<tr> +<td align="left" nowrap="nowrap" valign="top">sort()</td> +<td align="left" nowrap="nowrap" valign="top"></td> +<td align="left" nowrap="nowrap" valign="top">PyList_Sort</td> +<td align="left" nowrap="nowrap" valign="top"></td> +</tr> +<tr> +<td align="left" nowrap="nowrap" valign="top">reverse()</td> +<td align="left" nowrap="nowrap" valign="top"></td> +<td align="left" nowrap="nowrap" valign="top">PyList_Reverse</td> +<td align="left" nowrap="nowrap" valign="top"></td> +</tr> +<tr> +<td align="left" nowrap="nowrap" valign="top">as_tuple()</td> +<td align="left" nowrap="nowrap" valign="top">object</td> +<td align="left" nowrap="nowrap" valign="top">PyList_AsTuple</td> +<td align="left" nowrap="nowrap" valign="top"></td> +</tr> +<tr> +<td colspan="4" rowspan="1" style="vertical-align: top; white-space: nowrap; text-align: left; background-color: rgb(51, 153, 153);"><span style="font-weight: bold;">Type <span style="font-family: monospace;">slice</span></span></td> +</tr> +<tr> +<td align="left" nowrap="nowrap" valign="top">indices()</td> +<td align="left" nowrap="nowrap" valign="top">object</td> +<td align="left" nowrap="nowrap" valign="top">PySlice_Indices</td> +<td align="left" nowrap="nowrap" valign="top"></td> +</tr> +<tr> +<td align="left" nowrap="nowrap" valign="top">start</td> +<td align="left" nowrap="nowrap" valign="top">object</td> +<td align="left" nowrap="nowrap" valign="top"></td> +<td align="left" nowrap="nowrap" valign="top"></td> +</tr> +<tr> +<td align="left" nowrap="nowrap" valign="top">stop</td> +<td align="left" nowrap="nowrap" valign="top">object</td> +<td align="left" nowrap="nowrap" valign="top"></td> +<td align="left" nowrap="nowrap" valign="top"></td> +</tr> +<tr> +<td align="left" nowrap="nowrap" valign="top">step</td> +<td align="left" nowrap="nowrap" valign="top">object</td> +<td align="left" nowrap="nowrap" valign="top"></td> +<td align="left" nowrap="nowrap" valign="top"></td> +</tr> +</tbody> +</table> +<br> +Some +of the above methods have no direct Python equivalent, but are there to +provide access to routines that exist in the Python/C API.<br> +<br> +As an example, the following compiles into code containing no Python +attribute lookups or function calls.<br> +<br> +<div style="margin-left: 40px;"><span style="font-family: monospace;">cdef list cheeses</span><br style="font-family: monospace;"> +<span style="font-family: monospace;">cheeses = []</span><br style="font-family: monospace;"> +<span style="font-family: monospace;">cheeses.append("camembert")</span><br style="font-family: monospace;"> +<span style="font-family: monospace;">cheeses.append("cheddar")</span><br style="font-family: monospace;"> +<span style="font-family: monospace;">cheeses.insert(1, +"something runny")</span><br style="font-family: monospace;"> +</div> +<br> +<hr style="width: 100%; height: 2px;"> +<h2><a class="mozTocH2" name="mozTocId42018"></a><a name="Conditional_Compilation"></a>Conditional +Compilation</h2> +Some features are available for conditional compilation and +compile-time constants within a Pyrex source file.<br> +<h3><a class="mozTocH3" name="mozTocId379306"></a><a name="Compile-Time_Definitions"></a>Compile-Time +Definitions</h3> +A compile-time constant can be defined using the <span style="font-family: monospace; font-weight: bold;">DEF</span> +statement:<br> +<pre style="margin-left: 40px;">DEF FavouriteFood = "spam"<br>DEF ArraySize = 42<br>DEF OtherArraySize = 2 * ArraySize + 17</pre> +The +right-hand side of the DEF must be a valid compile-time expression. +Such expressions are made up of literal values and names defined using +DEF statements, combined using any of the Python expression syntax.<br> +<br> +The following compile-time names are predefined, corresponding to the +values returned by <span style="font-weight: bold;">os.uname()</span>.<br> +<pre style="margin-left: 40px;">UNAME_SYSNAME, UNAME_NODENAME, UNAME_RELEASE,<br>UNAME_VERSION, UNAME_MACHINE</pre> +The following selection of builtin constants and functions are also +available:<br> +<pre style="margin-left: 40px;">None, True, False,<br>abs, bool, chr, cmp, complex, dict, divmod, enumerate,<br>float, hash, hex, int, len, list, long, map, max, min,<br>oct, ord, pow, range, reduce, repr, round, slice, str,<br>sum, tuple, xrange, zip</pre> +A +name defined using DEF can be used anywhere an identifier can appear, +and it is replaced with its compile-time value as though it were +written into the source at that point as a literal. For this to work, +the compile-time expression must evaluate to a Python value of type <span style="font-weight: bold;">int</span>, <span style="font-weight: bold;">long</span>, <span style="font-weight: bold;">float </span>or <span style="font-weight: bold;">str</span>.<br> +<pre style="margin-left: 40px;">cdef int a1[ArraySize]<br>cdef int a2[OtherArraySize]<br>print "I like", FavouriteFood</pre> +<h3><a class="mozTocH3" name="mozTocId997015"></a><a name="Conditional_Statements"></a>Conditional +Statements</h3> +The <span style="font-family: monospace; font-weight: bold;">IF</span> +statement can be used to conditionally include or exclude sections of +code at compile time. It works in a similar way to the <span style="font-weight: bold;">#if</span> preprocessor +directive in C.<br> +<pre style="margin-left: 40px;">IF UNAME_SYSNAME == "Windows":<br> include "icky_definitions.pxi"<br>ELIF UNAME_SYSNAME == "Darwin":<br> include "nice_definitions.pxi"<br>ELIF UNAME_SYSNAME == "Linux":<br> include "penguin_definitions.pxi"<br>ELSE:<br> include "other_definitions.pxi"</pre> +The +ELIF and ELSE clauses are optional. An IF statement can appear anywhere +that a normal statement or declaration can appear, and it can contain +any statements or declarations that would be valid in that context, +including DEF statements and other IF statements.<br> +<br> +The +expressions in the IF and ELIF clauses must be valid compile-time +expressions as for the DEF statement, although they can evaluate to any +Python value, and the truth of the result is determined in the usual +Python way.<br> +<br> +--- +</body></html>
\ No newline at end of file diff --git a/debian/pyrex/pyrex-0.9.9/Doc/Manual/extension_types.html b/debian/pyrex/pyrex-0.9.9/Doc/Manual/extension_types.html new file mode 100644 index 00000000..3cd3dc42 --- /dev/null +++ b/debian/pyrex/pyrex-0.9.9/Doc/Manual/extension_types.html @@ -0,0 +1,1079 @@ +<!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en"> +<html><head> + + + + + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + + + + + <meta name="GENERATOR" content="Mozilla/4.61 (Macintosh; I; PPC) [Netscape]"> + + + <title>Extension Types</title></head> +<body> + + + +<h1> +<hr width="100%">Extension Types +<hr width="100%"></h1> + + + +<h2> Contents</h2> + + + +<ul> + + + <li> <a href="#Introduction">Introduction</a></li> + + + <li> <a href="#ExtTypeAttrs">Attributes</a></li> + <li><a href="#TypeDeclarations">Type declarations</a></li> + + + <li> <a href="#NotNone">Extension types and None</a></li> + + + <li> <a href="special_methods.html">Special methods</a></li> + + + <li> <a href="#Properties">Properties</a></li> + + + <li><a href="#SubclassingExtTypes">Subclassing</a></li> + + + <li> <a href="#CMethods">C Methods</a></li><li><a href="#ForwardDeclaringExtTypes">Forward-declaring extension types</a></li> + + <li><a href="#WeakRefs">Making extension types weak-referenceable</a><span style="color: rgb(255, 0, 0);"></span><br> + + + </li> + + + + <li> <a href="#PublicAndExtern">Public and external extension types</a><font color="#2f8b20"><br> + + + </font></li> + + + + + <ul> + + + <li> <a href="#ExternalExtTypes">External extension types</a></li> + + + <li> <a href="#ImplicitImport">Implicit importing</a><font color="#2f8b20"><br> + + + </font></li> + + + <li> <a href="#TypeVsConstructor">Type names vs. constructor names</a></li> + + + <li> <a href="#PublicExtensionTypes">Public extension types</a></li> + + + <li> <a href="#NameSpecClause">Name specification clause</a></li> + + + + + </ul> + + + +</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 +<i>extension types</i>. <br><br><table style="text-align: left; background-color: rgb(255, 255, 0); width: 554px; margin-left: 40px;" border="0" cellpadding="5" cellspacing="0"><tbody><tr><td style="vertical-align: top; text-align: left;">WARNING: There are substantial differences in the way many of the +special methods work in extension types compared to Python classes. +Before attempting to define any __xxx__ methods, read the section on <a href="special_methods.html">Special Methods of Extension Types.</a></td></tr></tbody></table><br>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> self.width = w</tt> <br> + + + <tt> self.height = h</tt> </p> + + + + + <p><tt> def describe(self):</tt> <br> + + + <tt> print "This shrubbery is", +self.width, \</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 + 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. +<p>The main difference is that you can use the <b>cdef</b> 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. </p> + + + +<h2> <a name="ExtTypeAttrs"></a>Attributes</h2> + + + Attributes of an extension type are stored directly in the object's C struct. + The set of attributes is fixed at compile time; you can't add attributes +to an extension type instance at run time simply by assigning to them, as +you could with a Python class instance. (You can subclass the extension type +in Python and add attributes to instances of the subclass, however.) +<p>There are two ways that attributes of an extension type can be accessed: + by Python attribute lookup, or by direct access to the C struct from Pyrex + 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> + + + +<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> + + + +<blockquote><tt>cdef class Shrubbery:</tt> <br> + + + <tt> cdef public int width, height</tt> <br> + + + <tt> cdef readonly float depth</tt></blockquote> + + + makes the <tt>width</tt> and <tt>height</tt> attributes readable and writable + from Python code, and the <tt>depth</tt> attribute readable but not writable. + +<p>Note that you can only expose simple C types, such as ints, floats and + strings, for Python access. You can also expose Python-valued attributes, + although read-write exposure is only possible for generic Python attributes + (of type <tt>object</tt>). If the attribute is declared to be of an extension + type, it must be exposed <tt>readonly</tt>. </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> + +<h2><a name="TypeDeclarations"></a>Type declarations </h2> + + + +<p>Before you can directly access the attributes of an extension type, the Pyrex 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 use a type declaration.</p> + +<p>For example, in the following function,</p> + +<blockquote><tt>cdef widen_shrubbery(sh, extra_width): # </tt><span style="font-family: monospace;"><span style="color: rgb(255, 0, 0);">BAD</span></span><br> + + + <tt> sh.width = sh.width + extra_width</tt></blockquote> + +<p> because the <span style="font-family: monospace;">sh</span> parameter hasn't been given a type, the <span style="font-family: monospace;">width</span> +attribute will be accessed by a Python attribute lookup. If the +attribute has been declared <span style="font-style: italic;">public</span> or <span style="font-style: italic;">readonly</span> then this will work, but +it will be very inefficient. If the attribute is private, it will not work at all -- the +code will compile, but an attribute error will be raised at run time.</p> + +<p>The solution is to declare sh as being of type <span style="font-family: monospace;">Shrubbery</span>, as follows:</p> + + + +<blockquote><tt>cdef widen_shrubbery(Shrubbery sh, extra_width):</tt> <br> + + + <tt> sh.width = sh.width + extra_width</tt></blockquote> + +Now the Pyrex compiler knows that <span style="font-family: monospace;">sh</span> has a C attribute called <span style="font-family: monospace;">width</span> and will generate code to access it directly and efficiently. The same consideration applies to local variables, for example,<br> + +<br> + +<div style="margin-left: 40px;"><code>cdef Shrubbery another_shrubbery(Shrubbery sh1):<br> + + cdef Shrubbery sh2<br> + + sh2 = Shrubbery()<br> + + sh2.width = sh1.width<br> + + sh2.height = sh1.height<br> + + return sh2</code></div> + + +<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 +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. +<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> + + + +<blockquote><tt>def widen_shrubbery(Shrubbery sh, extra_width): # <font color="#ed181e">This is</font></tt> <br> + + + <tt> sh.width = sh.width + extra_width +# <font color="#ed181e">dangerous!</font></tt></blockquote> + + + then users of our module could crash it by passing None for the <tt>sh</tt> +parameter. +<p>One way to fix this would be </p> + + + +<blockquote><tt>def widen_shrubbery(Shrubbery sh, extra_width):</tt> <br> + + + <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 +provides a more convenient way. Parameters of a Python function declared +as an extension type can have a <b><tt>not</tt></b> <b><tt>None</tt></b> clause: +<blockquote><tt>def widen_shrubbery(Shrubbery sh not None, extra_width):</tt> + <br> + + + <tt> sh.width = sh.width + extra_width</tt></blockquote> + + + Now the function will automatically check that <tt>sh</tt> is not None +along with checking that it has the right type. +<p>Note, however that the <tt>not</tt> <tt>None</tt> clause can <i>only</i> be used + in Python functions (defined with <tt>def</tt>) and not C functions (defined + with <tt>cdef</tt>). If you need to check whether a parameter to a C function + is None, you will need to do it yourself. </p> + + + +<p>Some more things to note: </p> + + + +<ul> + + + <li> The <b>self</b> parameter of a method of an extension type is guaranteed + never to be None.</li> + + + +</ul> + + + +<ul> + + + <li> When comparing a value with None, keep in mind that, if <tt>x</tt> is a Python object, <tt>x</tt> <tt>is</tt> <tt>None</tt> and <tt>x is</tt> <tt>not</tt> <tt>None</tt> are very +efficient because they translate directly to C pointer comparisons, whereas + <tt>x == None</tt> and <tt>x != None</tt>, or simply using <tt>x</tt> as a boolean value (as in <tt>if x: ...</tt>) will invoke Python operations +and therefore be much slower.</li> + + + +</ul> + + + +<h2> <a name="ExtTypeSpecialMethods"></a>Special methods</h2> + + + Although the principles are similar, there are substantial differences +between many of the <span style="font-family: monospace;">__xxx__</span> special methods of extension types and their +Python counterparts. There is a <a href="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> <a name="Properties"></a>Properties</h2> + + + There is a special syntax for defining <b>properties</b> in an extension + class: +<blockquote><tt>cdef class Spam:</tt> + + <p><tt> property cheese:</tt> </p> + + + + + <p><tt> "A doc string can go +here."</tt> </p> + + + + + <p><tt> def __get__(self):</tt> + <br> + + + <tt> +# This is called when the property is read.</tt> <br> + + + <tt> +...</tt> </p> + + + + + <p><tt> def __set__(self, value):</tt> + <br> + + + <tt> +# This is called when the property is written.</tt> <br> + + + <tt> +...</tt> </p> + + + + + <p><tt> def __del__(self):</tt> + <br> + + + <tt> +# This is called when the property is deleted.</tt> <br> + + + </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. +<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> + + + </p> + + + +<center> +<table align="center" cellpadding="5"> + + + <tbody> + + + <tr> + + + <td bgcolor="#ffaf18"><b><tt>cheesy.pyx</tt></b></td> + + + <td bgcolor="#5dbaca"><b>Test input</b></td> + + + </tr> + + + <tr> + + + <td rowspan="3" bgcolor="#ffaf18" valign="top"><tt>cdef class CheeseShop:</tt> + + + <p><tt> cdef object cheeses</tt> </p> + + + + + <p><tt> def __cinit__(self):</tt> <br> + + + <tt> self.cheeses = []</tt> </p> + + + + + <p><tt> property cheese:</tt> </p> + + + + + <p><tt> def __get__(self):</tt> <br> + + + <tt> return "We don't have: %s" % self.cheeses</tt> + </p> + + + + + <p><tt> def __set__(self, value):</tt> <br> + + + <tt> self.cheeses.append(value)</tt> + </p> + + + + + <p><tt> def __del__(self):</tt> <br> + + + <tt> del self.cheeses[:]</tt></p> + + + </td> + + + <td bgcolor="#5dbaca" valign="top"><tt>from cheesy import CheeseShop</tt> + + + <p><tt>shop = CheeseShop()</tt> <br> + + + <tt>print shop.cheese</tt> </p> + + + + + <p><tt>shop.cheese = "camembert"</tt> <br> + + + <tt>print shop.cheese</tt> </p> + + + + + <p><tt>shop.cheese = "cheddar"</tt> <br> + + + <tt>print shop.cheese</tt> </p> + + + + + <p><tt>del shop.cheese</tt> <br> + + + <tt>print shop.cheese</tt></p> + + + </td> + + + </tr> + + + <tr> + + + <td bgcolor="#8cbc1c"><b>Test output</b></td> + + + </tr> + + + <tr> + + + <td bgcolor="#8cbc1c"><tt>We don't have: []</tt> <br> + + + <tt>We don't have: ['camembert']</tt> <br> + + + <tt>We don't have: ['camembert', 'cheddar']</tt> <br> + + + <tt>We don't have: []</tt></td> + + + </tr> + + + + + </tbody> +</table> + + + </center> + + + +<h2> <a name="SubclassingExtTypes"></a>Subclassing</h2> + + + An extension type may inherit from a built-in type or another extension +type: +<blockquote><tt>cdef class Parrot:</tt> <br> + + + <tt> ...</tt><tt></tt> + + <p><tt>cdef class Norwegian(Parrot):</tt> <br> + + + <tt> ...</tt></p> + + + </blockquote> + + + +<p><br> + + + A complete definition of the base type must be available to Pyrex, 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 +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 + 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> + + + </p> + + + +<h2><a name="CMethods"></a>C methods</h2> + + + Extension types can have C methods as well as Python methods. Like C functions, +C methods are declared using <tt>cdef</tt> instead of <tt>def</tt>. C methods +are "virtual", and may be overridden in derived extension types.<br> + + + <br> + + + +<table align="center" cellpadding="5"> + + + <tbody> + + + <tr> + + + <td bgcolor="#ffaf18" valign="top" width="50%"><b><tt>pets.pyx</tt></b><br> + + + </td> + + + <td bgcolor="#8cbc1c" valign="top" width="30%"><b>Output</b><br> + + + </td> + + + </tr> + + + <tr> + + + <td bgcolor="#ffaf18" valign="top" width="50%"><tt>cdef class Parrot:<br> + + + <br> + + + cdef void describe(self):<br> + + + print "This parrot is resting."<br> + + + <br> + + + cdef class Norwegian(Parrot):<br> + + + <br> + + + cdef void describe(self):<br> + + + Parrot.describe(self)<br> + + + print "Lovely plumage!"<br> + + + <br> + + + <br> + + + cdef Parrot p1, p2<br> + + + p1 = Parrot()<br> + + + p2 = Norwegian()<br> + + +print "p1:"<br> + + + p1.describe()<br> + + +print "p2:"<br> + + + p2.describe()</tt> <br> + + + </td> + + + <td bgcolor="#8cbc1c" valign="top" width="30%"><tt>p1:<br> + + +This parrot is resting.<br> + + +p2:<br> + + + </tt><tt>This parrot is resting.<br> + + + </tt><tt> Lovely plumage!</tt><br> + + + </td> + + + </tr> + + + + + </tbody> +</table> + + + <br> + + + The above example also illustrates that a C method can call an inherited +C method using the usual Python technique, i.e.<br> + + +<blockquote><tt>Parrot.describe(self)</tt><br> + + +</blockquote> + + + +<h2><a name="ForwardDeclaringExtTypes"></a>Forward-declaring extension types</h2> + + + Extension types can be forward-declared, like struct and union types. This + will be necessary if you have two extension types that need to refer to +each other, e.g. +<blockquote><tt>cdef class Shrubbery # forward declaration</tt> + + <p><tt>cdef class Shrubber:</tt> <br> + + + <tt> cdef Shrubbery work_in_progress</tt> </p> + + + + + <p><tt>cdef class Shrubbery:</tt> <br> + + + <tt> cdef Shrubber creator</tt></p> + + + </blockquote><h2><a name="WeakRefs"></a>Making extension types weak-referenceable</h2> + +By +default, extension types do not support having weak references made to +them. You can enable weak referencing by declaring a C attribute of +type <span style="font-family: monospace;">object</span> called <span style="font-family: monospace; font-weight: bold;">__weakref__</span>. For example,<br> + + +<br> + + +<div style="margin-left: 40px;"><span style="font-family: monospace;">cdef class ExplodingAnimal:<br><br style="font-family: monospace;"></span> + + +<span style="font-family: monospace;"> """This animal will self-destruct when it is</span><br> + + +<span style="font-family: monospace;"> no longer strongly referenced."""</span><br> + + +<span style="font-family: monospace;"> </span><br style="font-family: monospace;"> + + +<span style="font-family: monospace;"></span><span style="font-family: monospace;"> cdef object __weakref__</span><br> + + +</div> + + +<h2>Garbage Collection</h2>Normally, any extension type which has +Python-valued attributes automatically participates in cyclic garbage +collection. You can prevent this as follows:<br><pre style="margin-left: 40px;">cdef class Hovercraft [nogc]:<br><br> """This object will not participate in cyclic gc<br> even though it has a Python attribute."""<br><br> cdef object eels<br></pre>However, +if there is a base type with Python attributes that participates in GC, +any subclasses of it will also participate in GC regardless of their <span style="font-family: monospace;">nogc</span> options. + + +<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 +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 +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 + mechanism for this. See <a href="sharing.html">Sharing C Declarations Between + Pyrex 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> + + + <tt> double real</tt> <br> + + + <tt> double imag</tt> </p> + + + + + <p><tt> ctypedef class __builtin__.complex [object PyComplexObject]:</tt> + <br> + + + <tt> cdef Py_complex cval</tt> + </p> + + + + + <p><tt># A function which uses the above type</tt> <br> + + + <tt>def spam(complex c):</tt> <br> + + + <tt> print "Real:", c.cval.real</tt> <br> + + + <tt> print "Imag:", c.cval.imag</tt></p> + + + </blockquote> + + + Some important things to note are: +<ol> + + + <li> In this example, <b>ctypedef class</b> has been used. This is because, + in the Python header files, the <tt>PyComplexObject</tt> struct is declared + with<br> + + + <br> + + + + + <div style="margin-left: 40px;"><tt>ctypedef struct {</tt> <br> + + + <tt> ...</tt> <br> + + + <tt>} PyComplexObject;<br> + + + <br> + + + </tt></div> + + + </li> + + <li>As well as the name of the extension type, the <i>module</i> in which +its type object can be found is also specified. See the <a href="#ImplicitImport">implicit importing</a> section below. <br> + + + <br> + + + </li> + + + <li> When declaring an external extension type, you don't declare +any methods. Declaration of methods is not required in order to call them, +because the calls are Python method calls. Also, as with structs and unions, +if your extension class declaration is inside a <i>cdef extern from</i> block, + you only need to declare those C members which you wish to access.</li> + + + +</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> +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 +extension class declaration, for example, +<blockquote><tt>cdef extern class MyModule.Spam:</tt> <br> + + + <tt> ...</tt></blockquote> + + + The type object will be implicitly imported from the specified module and + bound to the corresponding name in this module. In other words, in this +example an implicit +<ol> + + + + + <pre>from <tt>MyModule</tt> import Spam</pre> + + + +</ol> + + + statement will be executed at module load time. +<p>The module name can be a dotted name to refer to a module inside a package + hierarchy, for example, </p> + + + +<blockquote><tt>cdef extern class My.Nested.Package.Spam:</tt> <br> + + + <tt> ...</tt></blockquote> + + + You can also specify an alternative name under which to import the type +using an <b>as</b> clause, for example, +<ol> + + + <tt>cdef extern class My.Nested.Package.Spam as Yummy:</tt> <br> + + + <tt> ...</tt> +</ol> + + + which corresponds to the implicit import statement +<ol> + + + + + <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 + 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 +return values of that type. +<p>When you declare </p> + + + +<blockquote><tt>cdef extern class MyModule.Spam:</tt> <br> + + + <tt> ...</tt></blockquote> + + + the name <tt>Spam</tt> serves both these roles. There may be other names + by which you can refer to the constructor, but only <tt>Spam</tt> can be +used as a type name. For example, if you were to explicity <tt>import MyModule</tt>, + you could use<tt> MyModule.Spam()</tt> to create a Spam instance, but you + wouldn't be able to use <tt>MyModule.Spam</tt> as a type name. +<p>When an <b>as</b> clause is used, the name specified in the <b>as</b> +clause also takes over both roles. So if you declare </p> + + + +<blockquote><tt>cdef extern class MyModule.Spam as Yummy:</tt> <br> + + + <tt> ...</tt></blockquote> + + + then <tt>Yummy</tt> becomes both the type name and a name for the constructor. + Again, there are other ways that you could get hold of the constructor, +but only <tt>Yummy</tt> is usable as a type name. +<h3> <a name="PublicExtensionTypes"></a>Public extension types</h3> + + + An extension type can be declared <b>public</b>, in which case a <b>.h</b> +file is generated containing declarations for its object struct and type +object. By including the <b>.h</b> file in external C code that you write, +that code can access the attributes of the extension type. +<h3> <a name="NameSpecClause"></a>Name specification clause</h3> + + + The part of the class declaration in square brackets is a special feature + only available for <b>extern</b> or <b>public</b> extension types. The full +form of this clause is +<blockquote><tt>[object </tt><i>object_struct_name</i><tt>, type </tt><i>type_object_name</i><span style="font-family: monospace;"> ]</span></blockquote> + + + where <i>object_struct_name</i> is the name to assume for the type's C +struct, and <i>type_object_name</i> is the name to assume for the type's +statically declared type object. (The object and type clauses can be written +in either order.) +<p>If the extension type declaration is inside a <b>cdef extern from</b> +block, the <b>object</b> clause is required, because Pyrex must be able to +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 +with external C code. </p> + + + +<p> </p> + + + +<hr width="100%"> <br> + + + Back to the <a href="overview.html">Language Overview</a> <br> + + + <br> + + + <br> + + +</body></html>
\ No newline at end of file diff --git a/debian/pyrex/pyrex-0.9.9/Doc/Manual/external.html b/debian/pyrex/pyrex-0.9.9/Doc/Manual/external.html new file mode 100644 index 00000000..38f19270 --- /dev/null +++ b/debian/pyrex/pyrex-0.9.9/Doc/Manual/external.html @@ -0,0 +1,294 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> +<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="content-type"><title>Interfacing with External C Code</title></head> +<body><h1><hr style="width: 100%; height: 2px;"><a name="InterfacingWithExternal"></a>Interfacing with +External C Code <hr width="100%"></h1><ul><li> +<a href="#ExternDecls">External declarations</a></li><ul><li> +<a href="#ReferencingHeaders">Referencing C header files</a></li><li> +<a href="#StructDeclStyles">Styles of struct/union/enum +declaration</a></li><li> <a href="#AccessingAPI">Accessing +Python/C API routines</a></li><li><a href="#SpecialTypes">Special Types</a><span style="color: rgb(255, 0, 0);"> <span style="color: rgb(255, 102, 0);">(New in 0.9.6)</span></span></li><li><a href="#CallingConventions">Windows Calling Conventions</a><span style="color: rgb(255, 0, 0);"> <span style="color: rgb(255, 102, 0);">(New in 0.9.6)</span></span></li><li> +<a href="#CNameSpecs">Resolving naming conflicts - C name +specifications</a></li></ul><li><a href="#Using_Pyrex_Declarations_from_C">Using Pyrex +declarations from C</a></li><ul><li> <a href="#PublicDecls">Public declarations</a></li></ul><ul><li><a href="#C_API_Declarations">C API declarations</a><span style="color: rgb(255, 0, 0);"> <span style="color: rgb(255, 102, 0);">(New in 0.9.6)</span></span></li><li><a href="#Multiple_public_and_api_declarations">Multiple public and API declarations</a><span style="color: rgb(255, 0, 0);"> (New in 0.9.6.3)</span></li><li><a href="#Acquiring_and_Releasing_the_GIL">Acquiring and Releasing the GIL</a><span style="color: rgb(255, 0, 0);"> <span style="color: rgb(255, 102, 0);">(New in 0.9.6)</span></span></li></ul></ul> +One of the main uses of Pyrex 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 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 +allow Python code to call C code, it can also be used to allow C code +to +call Python code.</p><hr style="width: 100%; height: 2px;"> <h2> <a name="ExternDecls"></a>External +declarations</h2> By default, C functions and variables declared +at the module level are local to the module (i.e. they have the C <b>static</b> +storage class). They can also be declared <b>extern</b> to +specify that they are defined elsewhere, for example: <blockquote> +<pre>cdef extern int spam_counter</pre> <pre>cdef extern void order_spam(int tons)</pre></blockquote> + <h3> +<a name="ReferencingHeaders"></a>Referencing C +header files</h3> 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 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 in a C header file, like this: </p> +<blockquote> <pre>cdef extern from "spam.h":</pre> <pre> int spam_counter</pre><pre> void order_spam(int tons)</pre> +</blockquote> 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 header file in the generated C code.<br> </li> + <li> It prevents Pyrex 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 +started with <b>cdef extern</b>.</li></ol> +It's important to understand that Pyrex does <i>not</i> +itself read the C header file, so you still need to provide Pyrex +versions of any declarations from it that you use. However, the Pyrex +declarations don't always have to +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, +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> + <li> Leave out any platform-specific extensions to C +declarations such as <b>__declspec()</b>.<br> </li> + <li> If the header file declares a big struct and you +only want +to use a few members, you only need to declare the members you're +interested in. Leaving the rest out doesn't do any harm, because the C +compiler will use the full definition from the header file.<br> <br> +In some cases, you might not need <i>any</i> of the +struct's members, in +which case you can just put <tt>pass</tt> in the body of +the struct declaration, +e.g.<br> <br> <tt> cdef extern +from "foo.h":<br> +struct spam:<br> + pass</tt><br> <br> +Note that you can only do this inside a <b>cdef extern from</b> +block; struct +declarations anywhere else must be non-empty.<br> <br> </li><li> +If the header file uses typedef names such as <b>size_t </b>to +refer to platform-dependent flavours of numeric types, you will need a +corresponding <b>ctypedef</b> statement, but you don't +need to match the type exactly, just use something of the right general +kind (int, float, etc). For example,</li><ol><pre>ctypedef int size_t</pre></ol> +will work okay whatever the actual size of a size_t is (provided the +header file defines it correctly). <br> <li> +If the header file uses macros to define constants, translate them into +a dummy <b>enum</b> declaration.<br> </li> + <li> If the header file defines a function using a +macro, declare it as though it were an ordinary function, with +appropriate argument and +result types.</li></ol> A few more tricks and tips: <ul><li> +If you want to include a C header because it's needed by another +header, but don't want to use any declarations from it, put <tt><font size="+1">pass</font></tt> in the extern-from +block:</li></ul> <ul><ul><tt>cdef extern +from "spam.h":</tt><br><tt> +pass</tt></ul></ul> <ul><li> If you want +to include some external declarations, but don't want to specify a +header file (because it's included by some other header that you've +already included) you can put <tt>*</tt> in place of the +header file name:</li></ul> <blockquote> <blockquote><tt>cdef +extern from *:</tt> <br> <tt> +...</tt></blockquote> </blockquote> <h3> <a name="StructDeclStyles"></a>Styles of struct, union +and enum declaration</h3> 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 +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 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 +as <tt><font size="+1">Foo</font></tt>, +not <tt><font size="+1">struct Foo</font></tt>. + </p><table cellpadding="5"> <tbody> +<tr bgcolor="#8cbc1c" valign="top"> <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> <td bgcolor="#99cc33" valign="top"><b>Comments</b></td> +</tr> <tr bgcolor="#8cbc1c" valign="top"> <td>1</td> +<td bgcolor="#ff9900"><tt>struct Foo {</tt> <br> +<tt> ...</tt> <br> <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 C code<tt>.</tt></td> </tr> <tr bgcolor="#8cbc1c" valign="top"> <td valign="top">2</td> +<td bgcolor="#ff9900" nowrap="nowrap"><tt>typedef +struct {</tt> <br> <tt> ...</tt> <br> +<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> +in the generated C code.</td> </tr> <tr bgcolor="#8cbc1c" valign="top"> <td rowspan="2">3</td> +<td rowspan="2" bgcolor="#ff9900" nowrap="nowrap"><tt>typedef +struct +foo {</tt> <br> <tt> ...</tt> <br> +<tt>} Foo;</tt></td> <td bgcolor="#66cccc" nowrap="nowrap" valign="top"><tt>cdef struct +foo:</tt> <br> <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 (although if you need to forward +reference the type, you'll have to use +the first form).</td> </tr> <tr> <td bgcolor="#66cccc"><tt>ctypedef struct Foo:</tt> <br> +<tt> ...</tt></td> </tr> <tr bgcolor="#8cbc1c" valign="top"> <td>4</td> +<td bgcolor="#ff9900" nowrap="nowrap"><tt>typedef +struct Foo {</tt> <br> <tt> ...</tt> +<br> <tt>} Foo;</tt></td> <td bgcolor="#66cccc" valign="top"><tt>cdef struct +Foo:</tt> <br> <tt> ...</tt></td> +<td>If the header uses the <i>same</i> name for the +tag and the typedef, you won't be able to include a <b>ctypedef</b> +for it -- but then, it's not +necessary.</td> </tr> </tbody> </table> <h3> +<a name="AccessingAPI"></a>Accessing +Python/C API routines</h3> One particular use of the <b>cdef +extern from</b> statement is for gaining access to routines in +the Python/C API. For example, <blockquote> <pre>cdef extern from "Python.h":</pre> +<pre> object PyString_FromStringAndSize(char *s, Py_ssize_t len)</pre></blockquote> +will allow you to create Python strings containing +null bytes. <h3> <a name="SpecialTypes"></a>Special +Types</h3><p>Pyrex predefines the name <span style="font-family: monospace;">Py_ssize_t</span> +for use with Python/C API routines. To make your extensions compatible +with 64-bit systems, you should always use this type where it is +specified in the documentation of Python/C API routines.</p><h3><a name="CallingConventions"></a>Windows Calling +Conventions</h3><p>The <span style="font-family: monospace;">__stdcall</span>, <span style="font-family: monospace;">__fastcall</span> and <span style="font-family: monospace;">__cdecl</span> calling +convention specifiers can be used in Pyrex, with the same syntax as +used by C compilers on Windows, for example,</p><pre style="margin-left: 40px;">cdef extern int __stdcall FrobnicateWindow(long handle)<br><br>cdef void (__stdcall *callback)(void *)<br></pre>If +__stdcall is used, the function is only considered compatible with +other __stdcall functions of the same signature.<br><br> <hr width="100%"> <h2> <a name="CNameSpecs"></a>Resolving +naming conflicts - C name specifications</h2> Each Pyrex 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. 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> <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 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>, +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> +</blockquote> 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 module. </p> <p>As well +as functions, C names can be specified for variables, structs, unions, +enums, struct and union members, and enum values. For example, </p> +<blockquote> <pre>cdef extern int one "ein", two "zwei"<br>cdef extern float three "drei"<br><br>cdef struct spam "SPAM":<br> int i "eye"</pre><tt>cdef +enum surprise "inquisition":</tt> <br> <tt> +first "alpha"</tt> <br> <tt> second +"beta" = 3</tt></blockquote> <hr width="100%"> +<h2><a name="Using_Pyrex_Declarations_from_C"></a>Using +Pyrex Declarations from C</h2>Pyrex +provides two methods for making C declarations from a Pyrex module +available for use by external C code – public declarations and C API +declarations.<br><br><div style="margin-left: 40px;"><span style="font-weight: bold;">NOTE:</span> You do <span style="font-style: italic;">not</span> need to use +either of these to make declarations from one Pyrex module available to +another Pyrex module – you should use the <span style="font-weight: bold;">cimport</span> statement +for that. <a href="sharing.html">Sharing Declarations +Between Pyrex Modules</a>.</div><h3><a name="PublicDecls"></a>Public Declarations</h3> +You can make C types, variables and functions defined in a Pyrex module +accessible to C code that is linked with the module, by declaring them +with the <b><tt>public</tt></b> keyword: <blockquote><tt>cdef +public struct Bunny: # public type declaration<br> + int vorpalness<br><br>cdef public int spam # +public variable declaration</tt> <p><tt>cdef public +void grail(Bunny *): # public function declaration</tt> <br> +<tt> ...</tt></p> </blockquote> +If there are any <tt>public</tt> declarations in a Pyrex +module, a header file called <b><span style="font-style: italic;">modulename</span>.h</b> +file is generated containing equivalent C declarations for inclusion in +other C code.<br><br>Any +C code wanting to make use of these declarations will need to be +linked, either statically or dynamically, with the extension module.<br><br>If +the Pyrex module resides within a package, then the name of the .h file +consists of the full dotted name of the module, e.g. a module called <span style="font-weight: bold;">foo.spam</span> would have +a header file called <span style="font-weight: bold;">foo.spam.h</span>. +<h3><a name="C_API_Declarations"></a>C API +Declarations</h3><p>The other way of making declarations available to C code is to declare them with the <span style="font-family: monospace; font-weight: bold;">api</span> +keyword. You can use this keyword with C functions and extension types. A header file called "<span style="font-weight: bold;"><span style="font-style: italic;">modulename</span>_api.h</span>" +is produced containing declarations of the functions and extension types, and a function +called <span style="font-weight: bold;">import_<span style="font-style: italic;">modulename</span>()</span>.</p><p>C +code wanting to use these functions or extension types needs to include the header and call +the import_<span style="font-style: italic;">modulename</span>() +function. The other functions can then be called and the extension types used as usual.</p><p>Any +<span style="font-family: monospace;">public</span> +C type or extension type declarations in the Pyrex module are also made available when you +include <span style="font-style: italic;">modulename</span>_api.h.</p><table style="text-align: left; width: 100%;" border="0" cellpadding="5" cellspacing="2"><tbody><tr><td style="background-color: rgb(102, 204, 204);"><pre>delorean.pyx</pre></td><td style="background-color: rgb(255, 153, 0);"><pre>marty.c</pre></td></tr><tr><td style="vertical-align: top; background-color: rgb(102, 204, 204);"><pre>cdef public struct Vehicle:<br> int speed<br> float power<br><br>cdef api void activate(Vehicle *v):<br> if v.speed >= 88 \<br> and v.power >= 1.21:<br> print "Time travel achieved"</pre></td><td style="background-color: rgb(255, 153, 0);"><pre>#include "delorean_api.h"<br><br>Vehicle car;<br><br>int main(int argc, char *argv[]) {<br> import_delorean();<br> car.speed = atoi(argv[1]);<br> car.power = atof(argv[2]); <br> activate(&car);<br>}</pre></td></tr></tbody></table><br>Note +that any types defined in the Pyrex module that are used as argument or +return types of the exported functions will need to be declared <span style="font-family: monospace;">public</span>, +otherwise they won't be included in the generated header file, and you +will get errors when you try to compile a C file that uses the header.<br><br>Using the <span style="font-family: monospace;">api</span> method does not require the C code using the declarations to be linked +with the extension module in any way, as the Python import machinery is +used to make the connection dynamically. However, only functions can be +accessed this way, not variables.<br><br>You can use both <span style="font-family: monospace;">public</span> and <span style="font-family: monospace;">api</span> on the same +function to make it available by both methods, e.g.<br><pre style="margin-left: 40px;">cdef public api void belt_and_braces():<br> ...<br></pre>However, +note that you should include <span style="font-weight: bold;">either</span> +<span style="font-style: italic;">modulename</span>.h +<span style="font-weight: bold;">or</span> <span style="font-style: italic;">modulename</span>_api.h in +a given C file, <span style="font-style: italic;">not</span> +both, otherwise you may get conflicting dual definitions.<br><br>If +the Pyrex module resides within a package, then:<br><ul><li>The +name of the header file contains of the full dotted name of the module.</li><li>The +name of the importing function contains the full name with dots +replaced by double underscores.</li></ul>E.g. a module +called <span style="font-weight: bold;">foo.spam</span> +would have an API header file called <span style="font-weight: bold;">foo.spam_api.h</span> and +an importing function called <span style="font-weight: bold;">import_foo__spam()</span>.<br><h3><a name="Multiple_public_and_api_declarations"></a>Multiple public and api declarations</h3>You can declare a whole group of items as <span style="font-style: italic;">public</span> and/or <span style="font-style: italic;">api</span> all at once by enclosing them in a cdef block, for example,<br><pre style="margin-left: 40px;">cdef public api:<br> void order_spam(int tons)<br> char *get_lunch(float tomato_size)<br></pre>This can be a useful thing to do in a <span style="font-family: monospace;">.pxd</span> file (see <a href="sharing.html">Sharing Declarations +Between Pyrex Modules</a>) to make the module's public interface available by all three methods.<br><br><hr style="width: 100%; height: 2px;"><h2><a name="Acquiring_and_Releasing_the_GIL"></a>Acquiring and Releasing the GIL</h2>Pyrex +provides facilities for releasing the Global Interpreter Lock (GIL) +before calling C code, and for acquiring the GIL in functions that are +to be called back from C code that is executed without the GIL.<br><h3>Releasing the GIL</h3>You can release the GIL around a section of code using the<span style="font-family: monospace; font-weight: bold;"> with nogil </span>statement:<br><pre style="margin-left: 40px;">with nogil:<br> <code to be executed with the GIL released><br></pre>Code in the body of the statement <span style="font-style: italic;">must not manipulate Python objects</span>, +and must +not call anything that manipulates Python objects without first +re-acquiring the GIL. Pyrex attempts to check that these restrictions +are being followed as far as it can, but it may not catch all possible +forms of violation<span style="font-weight: bold;"></span>.<br><br>Any external C functions called inside the block must be declared as <span style="font-family: monospace;">nogil</span> (<a href="#nogil">see below</a>).<br><br><span style="font-weight: bold;">Note</span>: +It may be safe to do some things with Python objects under some +circumstances. Provided steps are taken (such as adequate locking) to +ensure that the objects involved cannot be deallocated by Python code +running in another thread, it is probably safe to access non-Python C +attributes of an extension type, and to pass references to Python +objects to another function that is safe to call with the GIL released.<br><br>However, in the absence of such locking, it is not safe to do <span style="font-style: italic;">anything</span> with Python objects with the GIL released -- not even look at them.<br><h3>Acquiring the GIL</h3>A +C function that is to be used as a callback from C code that is executed +without the GIL needs to acquire the GIL before it can manipulate +Python objects. This can be done by specifying<span style="font-family: monospace; font-weight: bold;"> with gil </span>in the function header:<br><pre style="margin-left: 40px;">cdef void my_callback(void *data) with gil:<br> ...<br></pre><h3><a name="nogil"></a>Declaring a function as callable without the GIL</h3>You can specify <span style="font-family: monospace; font-weight: bold;">nogil</span> in a C function header or function type to declare that it is safe to call without the GIL.<br><br><div style="margin-left: 40px;"><span style="font-family: monospace;">cdef extern int swizzle_the_knob() nogil</span><br></div><br>A block of external functions can be declared <span style="font-family: monospace;">nogil</span> at once.<br><br><div style="margin-left: 40px;"><span style="font-family: monospace;">cdef extern from "somewhere.h" nogil:</span><br style="font-family: monospace;"><div style="margin-left: 40px;"><span style="font-family: monospace;">...</span><br></div></div><br>Note that declaring a function <span style="font-family: monospace;">nogil</span> does <span style="font-style: italic;">not</span> +cause the GIL to be released before calling the function. It simply +allows the function to be called in situations where the GIL is not +held.<br><br>You can also declare a function implemented in Pyrex as <span style="font-family: monospace;">nogil</span>.<br><pre style="margin-left: 40px;">cdef void my_gil_free_func(int spam) nogil:<br> ...</pre>Such a function cannot have any Python local variables, it cannot return a +Python type, and the same restrictions apply to the body of the function as for a<span style="font-family: monospace;"> with nogil </span>block.<br><br>Declaring a function<span style="font-family: monospace;"> with gil </span>also implicitly makes its signature<span style="font-family: monospace;"> nogil</span>.<br><br> +<hr style="width: 100%; height: 2px;"><span style="font-weight: bold;">Footnotes</span> +<hr width="100%"><a name="Footnote1"></a>1. +A problem with const +could arise if you have something like <blockquote> <pre>cdef extern from "grail.h":<br> char *nun</pre> +</blockquote> where grail.h actually contains <blockquote> +<pre>extern const char *nun;</pre> </blockquote> and +you do <blockquote> <pre>cdef void languissement(char *s):<br> #something that doesn't change s</pre> +<pre>...</pre> <pre>languissement(nun)</pre> </blockquote>which +will cause the C compiler to complain. You can work around it by +casting away the constness: <blockquote> <pre>languissement(<char *>nun) <br></pre> +</blockquote>---</body></html>
\ No newline at end of file diff --git a/debian/pyrex/pyrex-0.9.9/Doc/Manual/sharing.html b/debian/pyrex/pyrex-0.9.9/Doc/Manual/sharing.html new file mode 100644 index 00000000..415bdfa1 --- /dev/null +++ b/debian/pyrex/pyrex-0.9.9/Doc/Manual/sharing.html @@ -0,0 +1,342 @@ +<!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en"> +<html><head> + + + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + + + <meta name="GENERATOR" content="Mozilla/4.61 (Macintosh; I; PPC) [Netscape]"> + <title>Sharing Declarations Between Pyrex Modules</title></head> +<body> + + +<h1> +<hr width="100%">Sharing Declarations Between Pyrex Modules +<hr width="100%"></h1> + + This section describes a new set of facilities introduced in Pyrex 0.8 +for making C declarations, functions and extension types in one Pyrex module available +for use in another Pyrex module. These facilities are closely modelled on +the Python import mechanism, and can be thought of as a compile-time version +of it. +<h2><a class="mozTocH2" name="mozTocId699652"></a> Contents</h2><ul id="mozToc"><!--mozToc h2 1 h3 2--><li><a href="#mozTocId989010"> Definition and Implementation files</a><ul><li><a href="#mozTocId411233"> What a Definition File contains</a></li><li><a href="#mozTocId20347"> What an Implementation File contains</a></li></ul></li><li><a href="#mozTocId950993"> The <span style="font-family: monospace;">cimport</span> statement</a><ul><li><a href="#mozTocId559554"> Search paths for definition files</a></li><li><a href="#mozTocId478514"> Using <span style="font-family: monospace;">cimport</span> to resolve naming + conflicts</a></li></ul></li><li><a href="#mozTocId937218">Sharing C Functions</a></li><li><a href="#mozTocId825278">Sharing Extension Types</a></li><li><a href="#mozTocId144977">Circular cimports</a></li></ul> + + + + + +<h2><a class="mozTocH2" name="mozTocId989010"></a> <a name="DefAndImpFiles"></a>Definition and Implementation files</h2> + + A Pyrex module can be split into two parts: a <i>definition file</i> with + a <tt>.pxd</tt> suffix, containing C declarations that are to be available + to other Pyrex modules, and an <i>implementation file</i> with a <tt>.pyx</tt> +suffix, containing everything else. When a module wants to use something +declared in another module's definition file, it imports it using the <a href="#CImportStatement"><b>cimport</b> statement</a>. +<h3><a class="mozTocH3" name="mozTocId411233"></a> <a name="WhatDefFileContains"></a>What a Definition File contains</h3> + + A definition file can contain: +<ul> + + <li> Any kind of C type declaration.</li> + + <li> <b>extern</b> C function or variable declarations.</li><li>Declarations of C functions defined in the module.</li> + + <li> The definition part of an extension type (<a href="#SharingExtensionTypes">see below</a>).</li> + + +</ul> + + It cannot contain any non-extern C variable declarations. +<p>It cannot contain the implementations of any C or Python functions, or +any Python class definitions, or any executable statements. </p> + + +<blockquote>NOTE: You don't need to (and shouldn't) declare anything in a +declaration file <b>public</b> in order to make it available to other Pyrex +modules; its mere presence in a definition file does that. You only need a +public declaration if you want to make something available to external C code.</blockquote> + + +<h3><a class="mozTocH3" name="mozTocId20347"></a> <a name="WhatImpFileContains"></a>What an Implementation File contains</h3> + + An implementation file can contain any kind of Pyrex statement, although + there are some restrictions on the implementation part of an extension type +if the corresponding definition file also defines that type (see below). + +<h2><a class="mozTocH2" name="mozTocId950993"></a> <a name="CImportStatement"></a>The <tt>cimport</tt> statement</h2> + + The <b>cimport</b> statement is used in a definition or implementation +file to gain access to names declared in another definition file. Its syntax +exactly parallels that of the normal Python import statement: +<blockquote><tt>cimport </tt><i>module</i><tt> [, </tt><i>module</i><tt>...]</tt></blockquote> + + +<blockquote><tt>from </tt><i>module</i><tt> cimport </tt><i>name</i><tt> +[as </tt><i>name</i><tt>] [, </tt><i>name</i><tt> [as </tt><i>name</i><tt>] + ...]</tt></blockquote> + + Here is an example. The file on the left is a definition file which exports + a C data type. The file on the right is an implementation file which imports + and uses it. <br> + + +<table cellpadding="5" cols="2" width="100%"> + + <tbody> + + <tr> + + <td bgcolor="#ffcc00" width="40%"><b><tt>dishes.pxd</tt></b></td> + + <td bgcolor="#5dbaca"><b><tt>restaurant.pyx</tt></b></td> + + </tr> + + <tr align="left" valign="top"> + + <td bgcolor="#ffcc18" width="40%"><tt>cdef enum otherstuff:</tt> <br> + + <tt> sausage, eggs, lettuce</tt> + <p><tt>cdef struct spamdish:</tt> <br> + + <tt> int oz_of_spam</tt> <br> + + <tt> otherstuff filler</tt></p> + + </td> + + <td bgcolor="#5dbaca"><tt>cimport dishes</tt> <br> + + <tt>from dishes cimport spamdish</tt> + <p><tt>cdef void prepare(spamdish *d):</tt> <br> + + <tt> d.oz_of_spam = 42</tt> <br> + + <tt> d.filler = dishes.sausage</tt> </p> + + + <p><tt>def serve():</tt> <br> + + <tt> cdef spamdish d</tt> <br> + + <tt> prepare(&d)</tt> <br> + + <tt> print "%d oz spam, filler no. %d" % \</tt> + <br> + + <tt> (d.oz_of_spam, + d.filler)</tt></p> + + </td> + + </tr> + + + </tbody> +</table> + + +<p>It is important to understand that the <b>cimport</b> statement can <i>only</i> +be used to import C data types, C functions and variables, and extension +types. It cannot be used to import any Python objects, and (with one exception) +it doesn't imply any Python import at run time. If you want to refer to any +Python names from a module that you have cimported, you will have to include +a regular <b>import</b> statement for it as well. </p> + + +<p>The exception is that when you use <b>cimport</b> to import an extension + type, its type object is imported at run time and made available by the +name under which you imported it. Using <b>cimport</b> to import extension +types is covered in more detail <a href="#SharingExtensionTypes">below</a>. +</p> + + +<h3><a class="mozTocH3" name="mozTocId559554"></a> <a name="SearchPaths"></a>Search paths for definition files</h3> + + When you <b>cimport</b> a module called <tt>modulename</tt>, the Pyrex +compiler searches for a file called <tt>modulename.pxd</tt> along the search +path for include files, as specified by <b>-I</b> command line options. +<p>Also, whenever you compile a file <tt>modulename.pyx</tt>, the corresponding + definition file <tt>modulename.pxd</tt> is first searched for along the +same path, and if found, it is processed before processing the <tt>.pyx</tt> +file. </p> + + +<h3><a class="mozTocH3" name="mozTocId478514"></a> <a name="ResolvingNamingConflicts"></a>Using cimport to resolve naming + conflicts</h3> + + The cimport mechanism provides a clean and simple way to solve the problem + of wrapping external C functions with Python functions of the same name. +All you need to do is put the extern C declarations into a .pxd file for +an imaginary module, and cimport that module. You can then refer to the C +functions by qualifying them with the name of the module. Here's an example: +<br> + + +<table cellpadding="5" cols="2" width="100%"> + + <tbody> + + <tr> + + <td bgcolor="#ffcc00" width="50%"><b><tt>c_lunch.pxd</tt></b></td> + + <td bgcolor="#5dbaca"><b><tt>lunch.pyx</tt></b></td> + + </tr> + + <tr align="left" valign="top"> + + <td bgcolor="#ffcc18" width="50%"><tt>cdef extern from "lunch.h":</tt> + <br> + + <tt> void eject_tomato(float)</tt></td> + + <td bgcolor="#5dbaca"><tt>cimport c_lunch</tt> + <p><tt>def eject_tomato(float speed):</tt> <br> + + <tt> c_lunch.eject_tomato(speed)</tt></p> + + </td> + + </tr> + + + </tbody> +</table> + + +<p>You don't need any <tt>c_lunch.pyx</tt> file, because the only things +defined in <tt>c_lunch.pxd</tt> are extern C entities. There won't be any +actual <tt>c_lunch</tt> module at run time, but that doesn't matter; the <tt>c_lunch.pxd</tt> file has done its job of providing an additional namespace at compile time.</p><h2><a class="mozTocH2" name="mozTocId937218"></a><a name="Sharing_C_Functions"></a>Sharing C Functions</h2><p>C +functions defined at the top level of a module can be made available +via cimport by putting headers for them in the .pxd file, for example,</p><table style="text-align: left; width: 100%;" border="0" cellpadding="5" cellspacing="2"><tbody><tr><td style="font-weight: bold; background-color: rgb(255, 204, 0);"><pre>volume.pxd</pre></td><td style="font-weight: bold; background-color: rgb(93, 186, 202);"><pre>spammery.pyx</pre></td></tr><tr><td style="vertical-align: top; background-color: rgb(255, 204, 0);"><pre>cdef float cube(float)</pre></td><td style="background-color: rgb(93, 186, 202);" colspan="1" rowspan="3"><pre>from volume cimport cube<br><br>def menu(description, size):<br> print description, ":", cube(size), \<br> "cubic metres of spam"<br><br>menu("Entree", 1)<br>menu("Main course", 3)<br>menu("Dessert", 2)</pre></td></tr><tr style="font-weight: bold;"><td style="vertical-align: top; background-color: rgb(153, 204, 51); height: 1px;"><pre>volume.pyx</pre></td></tr><tr><td style="vertical-align: top; background-color: rgb(153, 204, 51);"><pre>cdef float cube(float x):<br> return x * x * x</pre></td></tr></tbody></table><br><h2><a class="mozTocH2" name="mozTocId825278"></a><a name="Sharing_Extension_Types"></a>Sharing Extension Types</h2> + + An extension type can be made available via cimport by splitting its definition into two parts, one in +a definition file and the other in the corresponding implementation file. +<br> + + <br> + + The definition part of the extension type can only declare C attributes +and C methods, not Python methods, and it must declare <i>all</i> of that +type's C attributes and C methods.<br> + + <br> + + The implementation part must implement all of the C methods declared in +the definition part, and may not add any further C attributes or methods. It may also +define Python methods. +<p>Here is an example of a module which defines and exports an extension +type, and another module which uses it. <br> + + +<table cellpadding="5" cols="2" width="100%"> + + <tbody> + + <tr> + + <td bgcolor="#ffcc18" width="30%"><b><tt>Shrubbing.pxd</tt></b></td> + + <td bgcolor="#5dbaca" width="50%"><b><tt>Shrubbing.pyx</tt></b></td> + + </tr> + + <tr align="left" valign="top"> + + <td bgcolor="#ffcc18" width="30%"><tt>cdef class Shrubbery:</tt> <br> + + <tt> cdef int width</tt> <br> + + <tt> cdef int length</tt></td> + + <td bgcolor="#5dbaca" width="50%"><tt>cdef class Shrubbery:</tt> <br> + + <tt> def __cinit__(self, int w, int l):</tt> <br> + + <tt> self.width = w</tt> + <br> + + <tt> self.length = l</tt> + + <p><tt>def standard_shrubbery():</tt> <br> + + <tt> return Shrubbery(3, 7)</tt></p> + + </td> + + </tr> + + <tr> + + <td colspan="2" bgcolor="#8cbc1c" width="30%"><b><tt>Landscaping.pyx</tt></b></td> + + </tr> + + <tr> + + <td colspan="2" bgcolor="#99cc00" width="30%"><tt>cimport Shrubbing</tt> + <br> + + <tt>import Shrubbing</tt> + <p><tt>cdef Shrubbing.Shrubbery sh</tt> <br> + + <tt>sh = Shrubbing.standard_shrubbery()</tt> <br> + + <tt>print "Shrubbery size is %d x %d" % (sh.width, sh.length)</tt> + <br> + + </p> + + </td> + + </tr> + + + </tbody> +</table> + + </p> + + +<p>Some things to note about this example: </p> + + +<ul> + + <li> There is a <tt>cdef</tt> <tt>class</tt> <tt>Shrubbery</tt> declaration in both Shrubbing.pxd + and Shrubbing.pyx. When the Shrubbing module is compiled, these two declarations + are combined into one.</li> + + + <li> In Landscaping.pyx, the <tt>cimport</tt> <tt>Shrubbing</tt> declaration +allows us to refer to the Shrubbery type as <tt>Shrubbing.Shrubbery</tt>. +But it doesn't bind the name <tt>Shrubbing</tt> in Landscaping's module namespace + at run time, so to access <tt>Shrubbing.standard_shrubbery</tt> we also +need to <tt>import</tt> <tt>Shrubbing</tt>.</li> + + +</ul>If you are exporting an extension type that has a base class, the +base class must be declared in the definition part. Repeating the base +class in the implementation part is not necessary, but if you do, it +must match the base class in the definition part.<h2><a class="mozTocH2" name="mozTocId144977"></a><a name="CircularCImports"></a>Circular cimports</h2>If +you have two structs, unions or extension types defined in different +.pxd files, and they need to refer to each other, there is a potential +for problems with circular imports. These problems can be avoided by +placing forward declarations of all the structs, unions and extension +types defined in the .pxd file <span style="font-style: italic;">before</span> the first <span style="font-family: monospace;">cimport</span> statement.<br><br>For example:<br><br><table style="text-align: left; margin-left: 40px;" border="1" cellpadding="5" cellspacing="2"><tbody><tr><td style="vertical-align: top; white-space: nowrap; text-align: left; background-color: rgb(255, 204, 24); font-family: monospace;">foo.pxd</td><td style="vertical-align: top; white-space: nowrap; text-align: left; background-color: rgb(255, 204, 24); font-family: monospace;">blarg.pxd</td></tr><tr><td style="vertical-align: top; white-space: nowrap; text-align: left; font-family: monospace; background-color: rgb(255, 204, 24);">cdef struct Spam<br><br>from blarg cimport Eggs<br><br>cdef struct Spam:<br> Eggs *eggs</td><td style="vertical-align: top; white-space: nowrap; text-align: left; background-color: rgb(255, 204, 24); font-family: monospace;">cdef struct Eggs<br><br>from foo cimport Spam<br><br>cdef struct Eggs:<br> Spam *spam</td></tr></tbody></table><br>If +the forward declarations weren't present, a circular import problem +would occur, analogous to that which arises in Python when two modules +try to import names from each +other. Placing the forward declarations before the <span style="font-family: monospace;">cimport</span> statements ensures that all type names are known to the Pyrex compiler sufficiently far in advance.<br><br>Note +that any .pyx file is free to cimport anything it wants from any .pxd +file without needing this precaution. It's only when two .pxd files +import each other that circular +import issues arise. <hr width="100%">Back to the <a href="overview.html">Language Overview</a> +<br> + + <br> + +</body></html>
\ No newline at end of file diff --git a/debian/pyrex/pyrex-0.9.9/Doc/Manual/source_files.html b/debian/pyrex/pyrex-0.9.9/Doc/Manual/source_files.html new file mode 100644 index 00000000..0d47fdeb --- /dev/null +++ b/debian/pyrex/pyrex-0.9.9/Doc/Manual/source_files.html @@ -0,0 +1,78 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> +<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="content-type"><title>Source Files and Compilation</title></head> +<body> +<h1> +<hr style="width: 100%; height: 2px;"> +Source +Files and Compilation +<hr style="width: 100%; height: 2px;"> +</h1><ul id="mozToc"><!--mozToc h2 1 h3 2--><li><a href="#mozTocId581403">File Names and Extensions</a></li><li><a href="#mozTocId146379">Modules in Packages</a></li><li><a href="#mozTocId431365">Building an Extension</a><ul><li><a href="#mozTocId233830">Command Line</a></li><li><a href="#mozTocId49372">Calling the Pyrex compiler from Python</a></li><li><a href="#mozTocId11953">Using the distutils extension</a></li></ul></li><li><a href="#mozTocId559484">Distributing Pyrex modules</a></li></ul><h2><a class="mozTocH2" name="mozTocId581403"></a>File Names and Extensions</h2>Pyrex +source file names consist of the name of the module followed by a <span style="font-family: monospace;">.pyx</span> extension, +for example a module called <span style="font-family: monospace;">primes</span> +would have a source file named <span style="font-family: monospace;">primes.pyx</span>.<br><h2><a class="mozTocH2" name="mozTocId146379"></a>Modules in Packages</h2>If +your module is destined to live in a package, the Pyrex compiler needs +to know the fully-qualified name that the module will eventually have.<br><br>There are currently two ways to give it this information:<br><ol><li>Name the source file with the full dotted name of the module. For +example, a module called <span style="font-family: monospace;">primes</span> to be installed in a package called <span style="font-family: monospace;">numbers</span> would +have a source file called <span style="font-family: monospace;">numbers.primes.pyx</span>.<br><br></li><li>Place the source file in a <span style="font-style: italic;">package directory</span>. To Pyrex, a package directory is one that contains a file called either <span style="font-family: monospace;">__init__.py</span> or <span style="font-family: monospace;">__init__.pyx</span>. For example, a package called <span style="font-family: monospace;">numbers</span> containing a module called <span style="font-family: monospace;">primes</span> would have the source files laid out like this:</li></ol><div style="margin-left: 80px;"><span style="font-family: monospace;">numbers</span><br style="font-family: monospace;"><div style="margin-left: 40px;"><span style="font-family: monospace;">__init__.py</span><br style="font-family: monospace;"><span style="font-family: monospace;">primes.pyx</span><br></div></div><br>This will ensure that the __name__ properties of the module and any +classes defined in it are set correctly. If you don't do this, you may +find that pickling doesn't work, among other problems. It also ensures +that the Pyrex compiler has the right idea about the layout of the +module namespace, which can be important when accessing extension types +defined in other modules.<br> +<h2><a class="mozTocH2" name="mozTocId431365"></a>Building an Extension</h2>There are two steps involved in creating an extension module from Pyres sources:<br><ol><li>Use the Pyrex compiler to translate the .pyx file into a .c file.</li><li>Compile the .c file with a C compiler and link it with whatever libraries it needs, to produce an extension module.</li></ol>There +are a variety of ways of accomplishing these steps, either separately +or together. One way is to compile the Pyrex source manually from the +command line +with the Pyrex compiler, e.g.<br> +<br><div style="margin-left: 40px;"><span style="font-family: monospace;">pyrexc -r primes.pyx</span><br> +</div><br> +This will compile <span style="font-family: monospace;">primes.pyx</span> +and any other source files that it depends on, if any of them have +changed since the last compilation, and produce a file called <span style="font-family: monospace;">primes.c</span>, +which then needs to be compiled with the C compiler using whatever +options are appropriate on your platform for generating an extension +module.<br><br>You +can perform the C compilation using distutils and a <span style="font-family: monospace;">setup.py</span> file, or with a conventional +Makefile. There's a Makefile in the Demos directory (called <span style="font-family: monospace;">Makefile.nodistutils</span>) +that shows how to do this for Linux.<br><br>Another approach is to put code at the beginning of your <span style="font-family: monospace;">setup.py</span> file to import the Pyrex compiler and call it from Python. You can then follow this with a normal call to <span style="font-family: monospace;">setup()</span> to compile the resulting .c files.<br> +<br>You can also perform both steps at once in a <span style="font-family: monospace;">setup.py</span> file using the distutils +extension provided with Pyrex. See the <span style="font-family: monospace;">Setup.py</span> +file in the <span style="font-family: monospace;">Demos</span> +directory for an example of how to use it. A disadvantage of this +method is that you won't be able to take advantage of Pyrex's own +dependency checking features to compile only the Pyrex sources which +have changed.<br><h3><a class="mozTocH3" name="mozTocId233830"></a>Command Line</h3>You can run the Pyrex compiler from the command line using either the <span style="font-family: monospace;">pyrexc</span> shell command or the Python version of it, <span style="font-family: monospace;">pyrexc.py</span>.<br><br>The following command line options exist:<br><br><table style="text-align: left; margin-left: 40px;" border="1" cellpadding="2" cellspacing="2"><tbody><tr><td style="font-weight: bold;" align="left" nowrap="nowrap" valign="top">Short</td><td style="font-weight: bold;" align="left" nowrap="nowrap" valign="top">Long</td><td style="font-weight: bold;" align="left" nowrap="nowrap" valign="top">Description</td></tr><tr><td align="left" nowrap="nowrap" valign="top">-v</td><td align="left" nowrap="nowrap" valign="top">--version</td><td align="left" nowrap="nowrap" valign="top">Display the version number of the Pyrex compiler</td></tr><tr><td align="left" nowrap="nowrap" valign="top">-l</td><td align="left" nowrap="nowrap" valign="top">--create-listing</td><td align="left" nowrap="nowrap" valign="top">Produces a .lis file for each compiled .pyx file containing error messages</td></tr><tr><td align="left" nowrap="nowrap" valign="top">-I</td><td align="left" nowrap="nowrap" valign="top">--include-dir</td><td style="vertical-align: top; text-align: left; width: 200px;">Specifies +a directory to be searched for included files and top-level package +directories. Multiple -I options may be given, each specifying one +directory.</td></tr><tr><td align="left" nowrap="nowrap" valign="top">-o</td><td align="left" nowrap="nowrap" valign="top">--output-file</td><td style="vertical-align: top; text-align: left; width: 200px;">Specifies name of generated C file. Only meaningful when a single .pyx file is being compiled.</td></tr><tr><td align="left" nowrap="nowrap" valign="top">-r</td><td align="left" nowrap="nowrap" valign="top">--recursive</td><td style="vertical-align: top; text-align: left; width: 200px;">Compile the given .pyx files, plus those of any modules it depends on directly or indirectly via <a href="sharing.html#CImportStatement">cimport</a> statements. The include path specified by -I options is used to find the .pyx files of dependent modules.</td></tr><tr><td align="left" nowrap="nowrap" valign="top">-t</td><td align="left" nowrap="nowrap" valign="top">--timestamps</td><td style="vertical-align: top; text-align: left; width: 200px;">Use +modification times of files to decide whether to compile a .pyx file. +This is the default when -r is used, unless -f is also used.</td></tr><tr><td align="left" nowrap="nowrap" valign="top">-f</td><td align="left" nowrap="nowrap" valign="top">--force</td><td style="vertical-align: top; text-align: left; width: 200px;">Compile all .pyx files regardless of modification times. This is the default when -r is not given.</td></tr><tr><td align="left" nowrap="nowrap" valign="top">-q</td><td align="left" nowrap="nowrap" valign="top">--quiet</td><td style="vertical-align: top; text-align: left; width: 200px;">When -r is given, don't display the names of source files being compiled.</td></tr></tbody></table><br><h3><a class="mozTocH3" name="mozTocId49372"></a>Calling the Pyrex compiler from Python</h3>The module <span style="font-family: monospace;">Pyrex.Compiler.Main</span> exports the following classes and functions to facilitate invoking the compiler from another Python program.<br><br><span style="font-family: monospace;">compile(</span><span style="font-style: italic;">source</span> [, <span style="font-style: italic;">options</span>] [, <span style="font-style: italic;"> option</span> = <span style="font-style: italic;">value</span> ]...<span style="font-family: monospace;">)</span><br><br><div style="margin-left: 40px;">Compiles one or more Pyrex source files, which should be <span style="font-family: monospace;">.pyx</span> files. The <span style="font-style: italic;">source</span> argument may be either a single filename or a list of filenames.<br><br>Depending on the <span style="font-family: monospace;">recursive</span> option, +it may compile just the specified source files, or the specified source +files plus those of other modules that they depend on via <span style="font-style: italic;">cimport</span> statements. The options may be given either as keyword arguments or a <span style="font-family: monospace;">CompilationOptions</span> instance. If both are used, keyword arguments take precedence.<br><br>The return value depends on whether a list of sources was specifed and whether the <span style="font-family: monospace;">recursive</span> option is in effect. If a single source file is specified and the <span style="font-family: monospace;">recursive</span> option is false, the return value is a <span style="font-family: monospace;">CompilationResult</span> instance. Otherwise, the return value is a <span style="font-family: monospace;">CompilationResultSet</span><span style="font-family: monospace;"></span> containing a <span style="font-family: monospace;">CompilationResult</span> +for each of the modules which were actually compiled (which may or may +not include ones corresponding to the specified source files).<br><br>Note: +If you have more than one source file to compile, it is more efficient +to do so with a single call to compile rather than one call for each +source file. This is because, if more than one source cimports the same +.pxd file, the .pxd file is parsed only once instead of being +parsed each time it is cimported.<br></div><br><span style="font-family: monospace;">compile_single(</span><span style="font-style: italic;">source_path</span> [, <span style="font-style: italic;">options</span>] [, <span style="font-style: italic;"> option</span> = <span style="font-style: italic;">value</span> ]...<span style="font-family: monospace;">)</span><br><br><div style="margin-left: 40px;">Compiles just a single .pyx source file, specified as a string, with no dependency or timestamp checking (the <span style="font-family: monospace;">recursive</span> and <span style="font-family: monospace;">timestamps</span> options are ignored). Always returns a <span style="font-family: monospace;">CompilationResult</span>.</div><span style="font-family: monospace;"><br></span><span style="font-family: monospace;">compile_multiple(</span><span style="font-style: italic;">source_list</span> [, <span style="font-style: italic;">options</span>] [, <span style="font-style: italic;"> option</span> = <span style="font-style: italic;">value</span> ]...<span style="font-family: monospace;">)</span><br><br><div style="margin-left: 40px;">Compiles +a list of .pyx source files, with optional dependency and timestamp +checking as for compile. Always takes a list of source pathnames, and +always returns a <span style="font-family: monospace;">CompilationResultSet</span>.</div><span style="font-family: monospace;"><br>class CompilationOptions</span><br><br><div style="margin-left: 40px;">A collection of options to be passed to the <span style="font-family: monospace;">compile()</span> function. The following options may be specified as keyword arguments to either the <span style="font-family: monospace;">CompilationOptions</span> constructor or the <span style="font-family: monospace;">compile()</span> function.<br></div><div style="margin-left: 80px;"><dl><dt style="font-family: monospace;">show_version</dt><dd>Display the version number of the Pyrex compiler.<br></dd><dt style="font-family: monospace;">use_listing_file</dt><dd>Produce a .lis file for each .pyx file containing compilation errors.<br></dd><dt style="font-family: monospace;">include_path</dt><dd>A list of directories to search for included files and top-level package directories.<br></dd><dt style="font-family: monospace;">output_file</dt><dd>Use the given name for the generated .c file (only in non-recursive mode).<br></dd><dt style="font-family: monospace;">recursive</dt><dd>Compile the .pyx files of any cimported modules in addition to the one specified.<br></dd><dt style="font-family: monospace;">timestamps</dt><dd>Only +compile modified sources as determined by file modification times. This +may be true, false or None. If None, timestamps are used if and only if +recursive mode is in effect.<br></dd><dt style="font-family: monospace;">quiet</dt><dd>Don't display names of sources being compiled in recursive mode.</dd></dl></div><span style="font-family: monospace;">class CompilationResult</span><br><br><div style="margin-left: 40px;">An object providing information about the result of compiling a .pyx file. It has the following attributes:<br></div><div style="margin-left: 80px;"><dl><dt style="font-family: monospace;">c_file</dt><dd>Pathname of the generated C source file.<br></dd><dt style="font-family: monospace;">h_file</dt><dd>Pathname of the generated C header file, if any.<br></dd><dt style="font-family: monospace;">api_file</dt><dd>Pathname of the generated C API header file, if any.<br></dd><dt style="font-family: monospace;">listing_file</dt><dd>Pathname of the generated error message file, if any.<br></dd><dt style="font-family: monospace;">num_errors</dt><dd>Number of compilation errors.</dd></dl></div><span style="font-family: monospace;">class CompilationResultSet</span><div style="margin-left: 40px;"></div><div style="margin-left: 40px;">This is a mapping object whose keys are the pathnames of .pyx files and whose values are the corresponding <span style="font-family: monospace;">CompilationResult</span> instances. It also has the following additional attributes:<br><dl style="margin-left: 40px;"><dt style="font-family: monospace;">num_errors</dt><dd>Total number of compilation errors.</dd></dl></div><h3><a class="mozTocH3" name="mozTocId11953"></a>Using the distutils extension</h3>The +distutils extension provided with Pyrex allows you to pass .pyx files +directly to the Extension constructor in your setup file.<br><br>To use it, you need to put the following at the top of your setup.py file:<br><br><div style="margin-left: 40px; font-family: monospace;">from Pyrex.Distutils.extension import Extension<br>from Pyrex.Distutils import build_ext<br></div><br>and you need to specify the Pyrex version of the build_ext command class in your setup() call:<br><br><div style="margin-left: 40px; font-family: monospace;">setup(<br> ...<br> cmdclass = {'build_ext': build_ext}<br>)<br></div><br>Using +the distutils extension is not currently recommended, because it's +unable to automatically find cimported modules or check the timestamps +of .pxd files and included sources. It also makes it harder to turn off +the use of Pyrex for people who are only installing your module and not +modifying the sources.<br><h2><a class="mozTocH2" name="mozTocId559484"></a>Distributing Pyrex modules</h2>It +is strongly recommended that you distribute the generated .c files as +well as your Pyrex sources, so that users can install your module +without needing to have Pyrex available.<br><br>It is also recommended that Pyrex compilation <span style="font-style: italic;">not</span> +be enabled by default in the version you distribute. Even if the user +has Pyrex installed, he probably doesn't want to use it just to install +your module. Also, the version he has may not be the same one you used, +and may not compile your sources correctly.<br><br>---<br></body></html>
\ No newline at end of file diff --git a/debian/pyrex/pyrex-0.9.9/Doc/Manual/special_methods.html b/debian/pyrex/pyrex-0.9.9/Doc/Manual/special_methods.html new file mode 100644 index 00000000..087c51d7 --- /dev/null +++ b/debian/pyrex/pyrex-0.9.9/Doc/Manual/special_methods.html @@ -0,0 +1,1124 @@ +<!DOCTYPE doctype PUBLIC "-//w3c//dtd html 4.0 transitional//en"> +<html><head> + + + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + + + <meta name="GENERATOR" content="Mozilla/4.61 (Macintosh; I; PPC) [Netscape]"> + <title>Special Methods of Extenstion Types</title></head> +<body> + + +<h1> +<hr width="100%">Special Methods of Extension Types +<hr width="100%"></h1> + + This page describes the special methods currently supported by Pyrex extension + 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><span style="font-weight: bold;">Note:</span><i> Everything said on this page applies only to </i><span style="font-weight: bold;">extension</span><i style="font-weight: bold;"> +</i><span style="font-weight: bold;">types</span><i>, defined with the </i><span style="font-weight: bold; font-family: monospace;">cdef</span> <span style="font-weight: bold; font-family: monospace;">class</span><i> statement. It doesn't apply +to classes defined with the Python </i><span style="font-family: monospace;">class</span> <i>statement, where the normal + Python rules apply.</i> </p> + + +<h2><small>Declaration</small></h2> +Special methods of extension types must be declared with <span style="font-family: monospace; font-weight: bold;">def</span>, <span style="font-style: italic;">not</span> <span style="font-family: monospace;">cdef</span>.<br> + +<h2><font size="+1">Docstrings</font></h2> + + + Currently, docstrings are not fully supported in special methods of extension + types. You can place a docstring in the source to serve as a comment, but + it won't show up in the corresponding <span style="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.) +<h2> <font size="+1">Initialisation methods: <tt>__cinit__</tt> and <tt>__init__</tt></font></h2> + + There are two methods concerned with initialising the object<tt>.</tt> +<p>The <b><tt>__cinit__</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 __cinit__ +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>By the time your <tt>__cinit__</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>__cinit__</tt> method is guaranteed to be called exactly +once.<br> + +<br> + +If your extension type has a base type, the <tt>__cinit__</tt> method of the +base type is automatically called <i>before</i> your <tt>__cinit__</tt> method +is called; you cannot explicitly call the inherited <tt>__cinit__</tt> method. +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>Any initialisation which cannot safely be done in the <tt>__cinit__</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 +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> + + +<p>Any arguments passed to the constructor will be passed + to both the <tt>__cinit__</tt> method and the <tt>__init__</tt> method. +If you anticipate subclassing your extension type in Python, you may find +it useful to give the <tt>__cinit__</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 +class wouldn't expect to have to do. </p> + + +<h2> <font size="+1">Finalization method: <tt>__dealloc__</tt><tt></tt></font></h2> + + The counterpart to the <tt>__cinit__</tt> method is the <b><tt>__dealloc__</tt></b> +method, which should perform the inverse of the <tt>__cinit__</tt> method. +Any C data structures that you allocated in your <tt>__cinit__</tt> method +should be freed in your <tt>__dealloc__</tt> method. +<p>You need to be careful what you do in a <tt>__dealloc__</tt> method. By +the time your <tt>__dealloc__</tt> method is called, the object may already +have been partially destroyed and may not be in a valid state as far as Python +is concerned, so you should avoid invoking any Python operations which might +touch the object. In particular, don't call any other methods of the object +or do anything which might cause the object to be resurrected. It's best if +you stick to just deallocating C data. </p> + + +<p>You don't need to worry about deallocating Python attributes of your object, +because that will be done for you by Pyrex after your <tt>__dealloc__</tt> +method returns.<br> + + <br> + + <b>Note:</b> There is no <tt>__del__</tt> method for extension types.<br> + + </p> + + +<h2><font size="+1">Arithmetic methods</font></h2> + + Arithmetic operator methods, such as <tt>__add__</tt>, behave differently + from their Python counterparts. There are no separate "reversed" versions + of these methods (<tt>__radd__</tt>, etc.) Instead, if the first operand +cannot perform the operation, the <i>same</i> method of the second operand +is called, with the operands in the <i>same order</i>. +<p>This means that you can't rely on the first parameter of these methods + being "self", and you should test the types of <span style="font-weight: bold;">both</span> operands before deciding + what to do. If you can't handle the combination of types you've been given, + you should return <tt>NotImplemented</tt>. </p> + + +<p>This also applies to the in-place arithmetic method <tt>__ipow__</tt>. + It doesn't apply to any of the <i>other</i> in-place methods (<tt>__iadd__</tt>, + etc.) which always take self as the first argument. </p><h2><font size="+1">Rich comparisons</font></h2> + + There are no separate methods for the individual rich comparison operations + (<tt>__eq__</tt>, <tt>__le__</tt>, etc.) Instead there is a single method + <tt>__richcmp__</tt> which takes an integer indicating which operation is +to be performed, as follows: +<ul> + + + <ul> + + + <table nosave="" border="0" cellpadding="5" cellspacing="0"> + + <tbody> + + <tr nosave=""> + + <td nosave="" bgcolor="#ffcc33" width="30"> + <div align="right"><</div> + + </td> + + <td nosave="" bgcolor="#66ffff" width="30">0</td> + + <td><br> + + </td> + + <td nosave="" bgcolor="#ffcc33" width="30"> + <div align="right">==</div> + + </td> + + <td nosave="" bgcolor="#66ffff" width="30">2</td> + + <td><br> + + </td> + + <td nosave="" bgcolor="#ffcc33" width="30"> + <div align="right">></div> + + </td> + + <td nosave="" bgcolor="#66ffff" width="30">4</td> + + </tr> + + <tr nosave=""> + + <td nosave="" bgcolor="#ffcc33"> + <div align="right"><=</div> + + </td> + + <td nosave="" bgcolor="#66ffff">1</td> + + <td><br> + + </td> + + <td nosave="" bgcolor="#ffcc33"> + <div align="right">!=</div> + + </td> + + <td nosave="" bgcolor="#66ffff">3</td> + + <td><br> + + </td> + + <td nosave="" bgcolor="#ffcc33"> + <div align="right">>=</div> + + </td> + + <td nosave="" bgcolor="#66ffff">5</td> + + </tr> + + + </tbody> + </table> + + + </ul> + + +</ul> + + +<h2> <font size="+1">The __next__ method</font></h2> + + Extension types wishing to implement the iterator interface should define + a method called <b><tt>__next__</tt></b>, <i>not</i> <tt>next</tt>. The Python + system will automatically supply a <tt>next</tt> method which calls your +<span style="font-family: monospace;">__next__</span>. <b>Do NOT explicitly give your type a <tt>next</tt> method</b>, +or bad things could happen.<br><h2><small>Type Testing in Special Methods <span style="color: rgb(255, 0, 0);">(New in 0.9.7)</span></small></h2>When testing the types of operands to your special methods, the obvious way might appear to be to use the <span style="font-family: monospace;">isinstance</span> +function. However, this is not completely safe, because it's possible +for a class to override what gets returned by isinstance tests on its +instances. This is not a great problem in Python code, but in Pyrex it +could be disastrous, as we are relying on knowing the C layout of the +objects we're dealing with.<br><br>Pyrex provides an alternative function, <span style="font-family: monospace; font-weight: bold;">typecheck</span>, +which corresponds to PyObject_TypeCheck in the Python/C API. This is +safe to use, as it always tests the actual C type of the object.<br><br>Similarly, there is an <span style="font-family: monospace; font-weight: bold;">issubtype</span> function, corresponding to PyType_IsSubType, as a safe alternative to <span style="font-family: monospace;">issubclass</span>.<br><br>As an example, here's how you might write an __add__ method for an extension type called MyNumber:<br><br><div style="margin-left: 40px;"><span style="font-family: monospace;">def __add__(x, y):</span><br style="font-family: monospace;"><span style="font-family: monospace;"> if typecheck(x, MyNumber):</span><br style="font-family: monospace;"><span style="font-family: monospace;"> # we are the left operand<br> if typecheck(y, MyNumber):<br> # add ourselves to another MyNumber and return result<br> if typecheck(y, int):<br> # add ourselves to an int and return result<br style="font-family: monospace;"></span><span style="font-family: monospace;"> elseif typecheck(y, MyNumber):<br> # we are the right operand<br style="font-family: monospace;"></span><span style="font-family: monospace;"> if typecheck(x, int):<br> # add an int to ourselves and return the result<br style="font-family: monospace;"></span><span style="font-family: monospace;"> # Get here if unknown combination</span><br style="font-family: monospace;"><span style="font-family: monospace;"> return NotImplemented</span><br></div> +<h2> <font size="+1">Special Method Table</font></h2> + + This table lists all of the special methods together with their parameter + and return types. In the table below, a parameter name of <b>self</b> is used to indicate that the parameter has the type that the method + belongs to. Other parameters with no type specified in the table are generic Python objects. +<p>You don't have to declare your method as taking these parameter types. + If you declare different types, conversions will be performed as necessary. + <br> + + +<table nosave="" bgcolor="#ccffff" border="1" cellpadding="5" cellspacing="0"> + + <tbody> + + <tr nosave="" bgcolor="#ffcc33"> + + <td nosave=""><b>Name</b></td> + + <td><b>Parameters</b></td> + + <td><b>Return type</b></td> + + <td><b>Description</b></td> + + </tr> + + <tr nosave="" bgcolor="#66ffff"> + + <td colspan="4" nosave=""><b>General</b></td> + + </tr> + + <tr> + + <td><tt>__cinit__</tt></td> + + <td>self, ...</td> + + <td> </td> + + <td>Basic initialisation (no direct Python equivalent)</td> + + </tr> + + <tr> + + <td><tt>__init__</tt></td> + + <td>self, ...</td> + + <td> </td> + + <td>Further initialisation</td> + + </tr> + + <tr> + + <td><tt>__dealloc__</tt></td> + + <td>self</td> + + <td> </td> + + <td>Basic deallocation (no direct Python equivalent)</td> + + </tr> + + <tr> + + <td><tt>__cmp__</tt></td> + + <td>x, y</td> + + <td>int</td> + + <td>3-way comparison</td> + + </tr> + + <tr> + + <td><tt>__richcmp__</tt></td> + + <td>x, y, int op</td> + + <td>object</td> + + <td>Rich comparison (no direct Python equivalent)</td> + + </tr> + + <tr> + + <td><tt>__str__</tt></td> + + <td>self</td> + + <td>object</td> + + <td>str(self)</td> + + </tr> + + <tr> + + <td><tt>__repr__</tt></td> + + <td>self</td> + + <td>object</td> + + <td>repr(self)</td> + + </tr> + + <tr nosave=""> + + <td nosave=""><tt>__hash__</tt></td> + + <td>self</td> + + <td>int</td> + + <td>Hash function</td> + + </tr> + + <tr> + + <td><tt>__call__</tt></td> + + <td>self, ...</td> + + <td>object</td> + + <td>self(...)</td> + + </tr> + + <tr> + + <td><tt>__iter__</tt></td> + + <td>self</td> + + <td>object</td> + + <td>Return iterator for sequence</td> + + </tr> + + <tr> + + <td><tt>__getattr__</tt></td> + + <td>self, name</td> + + <td>object</td> + + <td>Get attribute</td> + + </tr> + + <tr> + + <td><tt>__setattr__</tt></td> + + <td>self, name, val</td> + + <td> </td> + + <td>Set attribute</td> + + </tr> + + <tr> + + <td><tt>__delattr__</tt></td> + + <td>self, name</td> + + <td> </td> + + <td>Delete attribute</td> + + </tr> + + <tr nosave="" bgcolor="#66ffff"> + + <td colspan="4" nosave=""><b>Arithmetic operators</b></td> + + </tr> + + <tr> + + <td><tt>__add__</tt></td> + + <td>x, y</td> + + <td>object</td> + + <td>binary + operator</td> + + </tr> + + <tr> + + <td><tt>__sub__</tt></td> + + <td>x, y</td> + + <td>object</td> + + <td>binary - operator</td> + + </tr> + + <tr> + + <td><tt>__mul__</tt></td> + + <td>x, y</td> + + <td>object</td> + + <td>* operator</td> + + </tr> + + <tr> + + <td><tt>__div__</tt></td> + + <td>x, y</td> + + <td>object</td> + + <td>/ operator for old-style division</td> + + </tr> + + <tr> + + <td><tt>__floordiv__</tt></td> + + <td>x, y</td> + + <td>object</td> + + <td>// operator</td> + + </tr> + + <tr> + + <td><tt>__truediv__</tt></td> + + <td>x, y</td> + + <td>object</td> + + <td>/ operator for new-style division</td> + + </tr> + + <tr> + + <td><tt>__mod__</tt></td> + + <td>x, y</td> + + <td>object</td> + + <td>% operator</td> + + </tr> + + <tr> + + <td><tt>__divmod__</tt></td> + + <td>x, y</td> + + <td>object</td> + + <td>combined div and mod</td> + + </tr> + + <tr> + + <td><tt>__pow__</tt></td> + + <td>x, y, z</td> + + <td>object</td> + + <td>** operator or pow(x, y, z)</td> + + </tr> + + <tr> + + <td><tt>__neg__</tt></td> + + <td>self</td> + + <td>object</td> + + <td>unary - operator</td> + + </tr> + + <tr> + + <td><tt>__pos__</tt></td> + + <td>self</td> + + <td>object</td> + + <td>unary + operator</td> + + </tr> + + <tr> + + <td><tt>__abs__</tt></td> + + <td>self</td> + + <td>object</td> + + <td>absolute value</td> + + </tr> + + <tr> + + <td><tt>__nonzero__</tt></td> + + <td>self</td> + + <td>int</td> + + <td>convert to boolean</td> + + </tr> + + <tr> + + <td><tt>__invert__</tt></td> + + <td>self</td> + + <td>object</td> + + <td>~ operator</td> + + </tr> + + <tr> + + <td><tt>__lshift__</tt></td> + + <td>x, y</td> + + <td>object</td> + + <td><< operator</td> + + </tr> + + <tr> + + <td><tt>__rshift__</tt></td> + + <td>x, y</td> + + <td>object</td> + + <td>>> operator</td> + + </tr> + + <tr> + + <td><tt>__and__</tt></td> + + <td>x, y</td> + + <td>object</td> + + <td>& operator</td> + + </tr> + + <tr> + + <td><tt>__or__</tt></td> + + <td>x, y</td> + + <td>object</td> + + <td>| operator</td> + + </tr> + + <tr> + + <td><tt>__xor__</tt></td> + + <td>x, y</td> + + <td>object</td> + + <td>^ operator</td> + + </tr> + + <tr nosave="" bgcolor="#66ffff"> + + <td colspan="4" nosave=""><b>Numeric conversions</b></td> + + </tr> + + <tr> + + <td><tt>__int__</tt></td> + + <td>self</td> + + <td>object</td> + + <td>Convert to integer</td> + + </tr> + + <tr> + + <td><tt>__long__</tt></td> + + <td>self</td> + + <td>object</td> + + <td>Convert to long integer</td> + + </tr> + + <tr> + + <td><tt>__float__</tt></td> + + <td>self</td> + + <td>object</td> + + <td>Convert to float</td> + + </tr> + + <tr> + + <td><tt>__oct__</tt></td> + + <td>self</td> + + <td>object</td> + + <td>Convert to octal</td> + + </tr> + + <tr> + + <td><tt>__hex__</tt></td> + + <td>self</td> + + <td>object</td> + + <td>Convert to hexadecimal</td> + + </tr> + + <tr><td><span style="font-family: monospace;">__index__</span> (2.5+ only)</td><td>self</td><td>object</td><td>Convert to sequence index</td></tr><tr nosave="" bgcolor="#66ffff"> + + <td colspan="4" nosave=""><b>In-place arithmetic operators</b></td> + + </tr> + + <tr> + + <td><tt>__iadd__</tt></td> + + <td>self, x</td> + + <td>object</td> + + <td>+= operator</td> + + </tr> + + <tr> + + <td><tt>__isub__</tt></td> + + <td>self, x</td> + + <td>object</td> + + <td>-= operator</td> + + </tr> + + <tr> + + <td><tt>__imul__</tt></td> + + <td>self, x</td> + + <td>object</td> + + <td>*= operator</td> + + </tr> + + <tr> + + <td><tt>__idiv__</tt></td> + + <td>self, x</td> + + <td>object</td> + + <td>/= operator for old-style division</td> + + </tr> + + <tr> + + <td><tt>__ifloordiv__</tt></td> + + <td>self, x</td> + + <td>object</td> + + <td>//= operator</td> + + </tr> + + <tr> + + <td><tt>__itruediv__</tt></td> + + <td>self, x</td> + + <td>object</td> + + <td>/= operator for new-style division</td> + + </tr> + + <tr> + + <td><tt>__imod__</tt></td> + + <td>self, x</td> + + <td>object</td> + + <td>%= operator</td> + + </tr> + + <tr> + + <td><tt>__ipow__</tt></td> + + <td>x, y, z</td> + + <td>object</td> + + <td>**= operator</td> + + </tr> + + <tr> + + <td><tt>__ilshift__</tt></td> + + <td>self, x</td> + + <td>object</td> + + <td><<= operator</td> + + </tr> + + <tr> + + <td><tt>__irshift__</tt></td> + + <td>self, x</td> + + <td>object</td> + + <td>>>= operator</td> + + </tr> + + <tr> + + <td><tt>__iand__</tt></td> + + <td>self, x</td> + + <td>object</td> + + <td>&= operator</td> + + </tr> + + <tr> + + <td><tt>__ior__</tt></td> + + <td>self, x</td> + + <td>object</td> + + <td>|= operator</td> + + </tr> + + <tr> + + <td><tt>__ixor__</tt></td> + + <td>self, x</td> + + <td>object</td> + + <td>^= operator</td> + + </tr> + + <tr nosave="" bgcolor="#66ffff"> + + <td colspan="4" nosave=""><b>Sequences and mappings</b></td> + + </tr> + + <tr> + + <td><tt>__len__</tt></td> + + <td>self</td> + + <td>int</td> + + <td>len(self)</td> + + </tr> + + <tr> + + <td><tt>__getitem__</tt></td> + + <td>self, x</td> + + <td>object</td> + + <td>self[x]</td> + + </tr> + + <tr> + + <td><tt>__setitem__</tt></td> + + <td>self, x, y</td> + + <td> </td> + + <td>self[x] = y</td> + + </tr> + + <tr> + + <td><tt>__delitem__</tt></td> + + <td>self, x</td> + + <td> </td> + + <td>del self[x]</td> + + </tr> + + <tr> + + <td><tt>__getslice__</tt></td> + + <td>self, Py_ssize_t i, Py_ssize_t j</td> + + <td>object</td> + + <td>self[i:j]</td> + + </tr> + + <tr> + + <td><tt>__setslice__</tt></td> + + <td>self, Py_ssize_t i, Py_ssize_t j, x</td> + + <td> </td> + + <td>self[i:j] = x</td> + + </tr> + + <tr> + + <td><tt>__delslice__</tt></td> + + <td>self, Py_ssize_t i, Py_ssize_t j</td> + + <td> </td> + + <td>del self[i:j]</td> + + </tr> + + <tr> + + <td><tt>__contains__</tt></td> + + <td>self, x</td> + + <td>int</td> + + <td>x in self</td> + + </tr> + + <tr nosave="" bgcolor="#66ffff"> + + <td colspan="4" nosave=""><b>Iterators</b></td> + + </tr> + + <tr> + + <td><tt>__next__</tt></td> + + <td>self</td> + + <td>object</td> + + <td>Get next item (called <tt>next</tt> in Python)</td> + + </tr> + + <tr nosave="" bgcolor="#66ffff"> + + <td colspan="4" nosave=""><b>Buffer interface</b> (no Python equivalents + - see note 1)</td> + + </tr> + + <tr> + + <td><tt>__getreadbuffer__</tt></td> + + <td>self, int i, void **p</td> + + <td> </td> + + <td> </td> + + </tr> + + <tr> + + <td><tt>__getwritebuffer__</tt></td> + + <td>self, int i, void **p</td> + + <td> </td> + + <td> </td> + + </tr> + + <tr> + + <td><tt>__getsegcount__</tt></td> + + <td>self, int *p</td> + + <td> </td> + + <td> </td> + + </tr> + + <tr> + + <td><tt>__getcharbuffer__</tt></td> + + <td>self, int i, char **p</td> + + <td> </td> + + <td> </td> + + </tr> + + <tr nosave="" bgcolor="#66ffff"> + + <td colspan="4" nosave=""><b>Descriptor objects</b> (see note 2)</td> + + </tr> + + <tr> + + <td><tt>__get__</tt></td> + + <td>self, instance, class</td> + + <td>object</td> + + <td>Get value of attribute</td> + + </tr> + + <tr> + + <td><tt>__set__</tt></td> + + <td>self, instance, value</td> + + <td> </td> + + <td>Set value of attribute</td> + + </tr> + + <tr> + + <td style="font-family: monospace;">__delete__</td> + + <td>self, instance</td> + + <td> </td> + + <td>Delete attribute</td> + + </tr> + + + </tbody> +</table> + + </p> + + +<p>Note 1: The buffer interface is intended for use by C code and is not +directly accessible from Python. It is described in the <a href="http://www.python.org/doc/current/api/api.html">Python/C API Reference +Manual</a> under sections <a href="http://www.python.org/doc/current/api/abstract-buffer.html">6.6</a> +and <a href="http://www.python.org/doc/current/api/buffer-structs.html">10.6</a>. + </p> + + +<p>Note 2: Descriptor objects are part of the support mechanism for new-style + Python classes. See the <a href="http://www.python.org/doc/2.2.1/whatsnew/sect-rellinks.html#SECTION000320000000000000000">discussion + of descriptors in the Python documentation</a>. See also <a href="http://www.python.org/peps/pep-0252.html">PEP 252, "Making Types Look +More Like Classes"</a>, and <a href="http://www.python.org/peps/pep-0253.html">PEP 253, "Subtyping Built-In +Types"</a>. </p> + + <br> + +</body></html>
\ No newline at end of file diff --git a/debian/pyrex/pyrex-0.9.9/Doc/Manual/using_with_c++.html b/debian/pyrex/pyrex-0.9.9/Doc/Manual/using_with_c++.html new file mode 100644 index 00000000..df95c8e7 --- /dev/null +++ b/debian/pyrex/pyrex-0.9.9/Doc/Manual/using_with_c++.html @@ -0,0 +1,7 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> +<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="content-type"><title>Using with C++</title></head><body><h1>Using Pyrex with C++</h1>This section describes some features of Pyrex that are designed to facilitate wrapping of libraries written in C++.<br><ul id="mozToc"><!--mozToc h2 1 h3 2--><li><a href="#mozTocId714434">Source Filenames</a></li><li><a href="#mozTocId758326">C++ Structs and Classes</a><ul><li><a href="#mozTocId52035">Inheritance</a></li><li><a href="#mozTocId470913">Instantiation</a></li><li><a href="#mozTocId84624">Disposal</a></li></ul></li><li><a href="#mozTocId214896">Overloaded Functions</a></li></ul><h2><a class="mozTocH2" name="mozTocId714434"></a>Source Filenames</h2>Pyrex source files that use C++ features should be named with an extension of "<span style="font-family: monospace;">.pyx+</span>". The corresponding generated C file will then have an extension of ".cpp", and should be compiled with a C++ compiler.<br><br>Note that this only applies to <span style="font-style: italic;">implementation</span> files, not definition files. Definition files should always have an extension of ".pxd", whether they use C++ features or not.<br><h2><a class="mozTocH2" name="mozTocId758326"></a>C++ Structs and Classes</h2>C++ structs and classes are declared using <span style="font-family: monospace;">cdef+ struct</span>, for example,<br><br><div style="margin-left: 40px;"><span style="font-family: monospace;">cdef extern from "somewhere.h":</span><br><br style="font-family: monospace;"><span style="font-family: monospace;"> cdef+ struct Shrubbery:</span><br><span style="font-family: monospace;"> __init__()</span><br style="font-family: monospace;"><span style="font-family: monospace;"> __init__(float width)</span><br style="font-family: monospace;"><span style="font-family: monospace;"> __init__(float width, int price)</span><br><span style="font-family: monospace;"> float width</span><br><span style="font-family: monospace;"> int height</span><br style="font-family: monospace;"><span style="font-family: monospace;"> void plant_with_rhododendrons(int howmany)</span><br></div><br>Some important things to note:<br><ul><li>All <span style="font-family: monospace;">cdef+ struct</span> declarations must appear inside a <span style="font-family: monospace;">cdef extern from</span> block.</li><li>In Pyrex, <span style="font-family: monospace;">struct</span> is used regardless of whether the type is declared as a "struct" or a "class" in C++.</li><li>Constructors are declared using the name <span style="font-family: monospace;">__init__</span>. There can be multiple constructors with different signatures. If no constructor is declared, a single constructor with no arguments is assumed.</li><li>Destructors are not declared in Pyrex.</li><li>Member functions are declared without "virtual", whether they are virtual in C++ or not.</li></ul>A whole <span style="font-family: monospace;">extern from</span> block can also be declared using<span style="font-family: monospace;"> cdef+</span> if desired. This can be convenient when declaring a number of C++ types at once.<br><br><div style="margin-left: 40px;"><span style="font-family: monospace;">cdef+ extern from "shrubbing.h":</span><br><br style="font-family: monospace;"><span style="font-family: monospace;"> struct Shrubbery:</span><br><span style="font-family: monospace;"> ...</span><br style="font-family: monospace;"></div><span style="font-family: monospace;"></span><br>The effect is the same as if <span style="font-family: monospace;">cdef+</span> had been used on all the contained struct declarations. Other declarations appearing in the block are treated as ordinary <span style="font-family: monospace;">cdef</span> declarations.<br><h3><a class="mozTocH3" name="mozTocId52035"></a>Inheritance</h3>A C++ struct may inherit from one or more base structs.<br><br><div style="margin-left: 40px;"><span style="font-family: monospace;">cdef+ extern from "shrubbing.h":</span><br><br style="font-family: monospace;"><span style="font-family: monospace;"> struct FancyShrubbery(Shrubbery):</span><br><span style="font-family: monospace;"> ...</span><br></div><h3><a class="mozTocH3" name="mozTocId470913"></a>Instantiation</h3>C++ structs can be instantiated using the <span style="font-family: monospace;">new</span> operator, similarly to C++.<br><br><div style="margin-left: 40px;"><span style="font-family: monospace;">cdef Shrubbery *sh1, *sh2, *sh3</span><br><span style="font-family: monospace;">sh1 = new </span><span style="font-family: monospace;">Shrubbery()</span><br><span style="font-family: monospace;">sh2 = new </span><span style="font-family: monospace;">Shrubbery(3.2)</span><br><span style="font-family: monospace;">sh3 = new </span><span style="font-family: monospace;">Shrubbery(4.3, 800)</span><br><span style="font-family: monospace;"></span></div><br>Note that parentheses are required even if there are no arguments.<br><h3><a class="mozTocH3" name="mozTocId84624"></a>Disposal</h3>The <span style="font-family: monospace;">del</span> statement can be applied to a pointer to a C++ struct to deallocate it. This is equivalent to <span style="font-family: monospace;">delete</span> in C++.<br><br><div style="margin-left: 40px;"><span style="font-family: monospace;">cdef Shrubbery *big_sh</span><br><span style="font-family: monospace;">big_sh = new </span><span style="font-family: monospace;">Shrubbery(42.0)</span><br><span style="font-family: monospace;">display_in_garden_show(big_sh)</span><br style="font-family: monospace;"><span style="font-family: monospace;">del big_sh</span><br></div><h2><a class="mozTocH2" name="mozTocId214896"></a>Overloaded Functions</h2>Apart +from the special case of C++ struct constructors, there is no special +support for dealing with overloaded functions in C++. You will need to +declare each version of the function with a different name in Pyrex and +use C name specifications to map them all to the same C++ name. For +example,<br><br><div style="margin-left: 40px;"><span style="font-family: monospace;">cdef extern from "shrubbing.h":</span><br style="font-family: monospace;"><br style="font-family: monospace;"><span style="font-family: monospace;"> void build_with_width "build_shrubbery" (float width)</span><br style="font-family: monospace;"><span style="font-family: monospace;"> void build_with_petunias "build_shrubbery" (int number_of_petunias)</span><br></div><br></body></html>
\ No newline at end of file diff --git a/debian/pyrex/pyrex-0.9.9/Doc/Release_Notes_0.9.9.html b/debian/pyrex/pyrex-0.9.9/Doc/Release_Notes_0.9.9.html new file mode 100644 index 00000000..6a85fc0c --- /dev/null +++ b/debian/pyrex/pyrex-0.9.9/Doc/Release_Notes_0.9.9.html @@ -0,0 +1,43 @@ +<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd"> +<html><head><meta content="text/html; charset=ISO-8859-1" http-equiv="content-type"><title>0.9.9 Release Notes</title></head><body><h1>Release Notes for Pyrex 0.9.9</h1><h2>C++ Features</h2>Some features for interfacing with C++ code have been introduced in this release. Structs declared with '<span style="font-family: monospace;">cdef+ struct</span>' may have constructors and member functions, there is a '<span style="font-family: monospace;">new</span>' operator for instantiating them, and they may be deallocated using the '<span style="font-family: monospace;">del</span>' operator. Details may be found in the <a href="LanguageOverview.html">Language Overview</a> under <a href="Manual/using_with_c++.html">Using Pyrex with C++</a>.<br><h2>Changes to Exception Semantics</h2>The +behaviour surrounding exceptions caught using a try-except statement +were previously an inconsistent mixture of Pyrex and Python semantics. +Attempts to make the behaviour match Python more closely were requiring +the generation of increasingly convoluted and inefficient code, so I +decided to backtrack and return to something simpler.<br><br>Pyrex no +longer places caught exceptions into the thread state. This ensures +that exceptions and tracebacks do not leak out of the except clause +that caught them, unless you do something to explicitly preserve them.<br><br>It also means that you <span style="font-style: italic;">cannot</span> retrieve an caught exception in Pyrex using <span style="font-family: monospace;">sys.exc_info()</span>. If you want to capture the exception, you need to bind it to a name in the <span style="font-family: monospace;">except</span> clause.<br><br>To capture the traceback, the syntax of the <span style="font-family: monospace;">except</span> clause has been extended to allow a third argument. For example,<br><pre style="margin-left: 40px;">try:<br> start_vehicle()<br>except HovercraftError, err, tb:<br> print "Can't start:", err<br> traceback.print_tb(tb)<br></pre>As previously, a <span style="font-family: monospace;">raise</span> statement with no arguments must be lexically enclosed in the <span style="font-family: monospace;">except</span> +clause which caught the exception that you are trying to re-raise. In +order to re-raise it from somewhere else, you will need to explicity +communicate the exception and traceback to that place and use an +ordinary <span style="font-family: monospace;">raise</span> statement.<br><h2>Planned Change to None-checking</h2>Currently, +an argument to a Python function that is declared as an extension type +will, by default, be allowed to receive the value None; to prevent +this, you must qualify the argument declaration with '<span style="font-family: monospace;">not None</span>'.<br><br>This +arrangement has proved to be error-prone, because it requires the +programmer to be aware of the 'not None' feature and to remember to use +it everywhere necessary. Failure to do so results in a Pyrex module +that is prone to being crashed hard if it is passed a None value that +it is not expecting.<br><br>To improve this situation, I am planning to make '<span style="font-family: monospace;">not None</span>' the default in a future release of Pyrex. In order to allow None as a legal argument value, it will be necessary to use an '<span style="font-family: monospace;">or None</span>' qualifier.<br><br>In release 0.9.9, the '<span style="font-family: monospace;">or None</span>' +qualifier may be used, but it is optional. In preparation for the +change of default, the Pyrex compiler will issue a warning (once per +run) if it encounters an extension type argument that is not qualified +with either 'or None' or 'not None'. For example, if <span style="font-family: monospace;">Spam</span> and <span style="font-family: monospace;">Eggs</span> are extension types and you have a function declared as<br><pre style="margin-left: 40px;">def frobulate(Spam s, Eggs e not None):<br> ...<br></pre>then in order to eliminate the warning, you will need to change it to<br><pre style="margin-left: 40px;">def frobulate(Spam s or None, Eggs e not None):<br> ...</pre>In a later release, when 'not None' has become the default, it will be possible to drop the 'not None' qualifiers.<br><h2>Non-GC Extension Types</h2>It +is now possible to define and extension type with Python attributes +that does not participate in cyclic garbage collection, using a new <span style="font-family: monospace;">nogc</span> option, for example:<br><pre style="margin-left: 40px;">cdef class Spam [nogc]:<br> """This class doesn't participate in GC even though<br> it has a Python attribute."""<br> object sausages</pre><h2>Other New Features</h2>Some other minor feature additions and modifications have been made.<br><ul><li><span style="font-family: monospace;">size_t </span>is now a built-in type and is the type returned by the <span style="font-family: monospace;">sizeof</span> operator. Also, the sizes of <span style="font-family: monospace;">size_t</span> and <span style="font-family: monospace;">Py_ssize_t</span> are now assumed to be somewhere between <span style="font-family: monospace;">long</span> and <span style="font-family: monospace;">long long</span>.<br><br></li><li>Operations +between two int types of the same rank now return an +unsigned result if either of the operands is unsigned; if the ranks +differ, the result has the same type as the wider-ranked operand. I +think this is the best +approximation of the ANSI C rules that is possible without knowing the +exact sizes of the types.<br><br><span style="font-family: monospace;"></span></li><li><span style="font-family: monospace;">PyString_InternFromString</span> is now exposed under the name <span style="font-family: monospace; font-weight: bold;">cintern</span><span style="font-weight: bold;"> </span>rather than <span style="font-family: monospace;">intern</span>, because it is not a complete replacement for the Python <span style="font-family: monospace;">intern</span> function (it can't handle strings containing null bytes).<br></li><li>The +size check that was previously generated when importing an extension +type has been disabled for the time being until I can think of +something better. It was generating too many false positives, for +example from different versions of numpy.<br><br></li><li>The <span style="font-family: monospace;">__fastcall</span> calling convention option is now supported. Also, Pyrex no longer assumes that <span style="font-family: monospace;">__cdecl</span> +is the default calling convention. To be considered compatible, two +function types must either be declared with the same calling +convention, or both must leave it unspecified.<br><br></li><li>As I have been threatening for some time, using <span style="font-family: monospace;">__new__</span> +as the name of the initialisation method of an extension type has +become an error rather than just a warning. In some future release, <span style="font-family: monospace;">__new__</span> will re-emerge with more Python-like semantics.</li></ul><br></body></html>
\ No newline at end of file diff --git a/debian/pyrex/pyrex-0.9.9/Doc/index.html b/debian/pyrex/pyrex-0.9.9/Doc/index.html new file mode 100644 index 00000000..e8246f5b --- /dev/null +++ b/debian/pyrex/pyrex-0.9.9/Doc/index.html @@ -0,0 +1,70 @@ +<!DOCTYPE html PUBLIC "-//w3c//dtd html 4.0 transitional//en"> +<html><head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="GENERATOR" content="Mozilla/4.51 (Macintosh; I; PPC) [Netscape]"> + <title>Pyrex - Front Page</title></head> + +<body> + +<table style="width: 100%;" cellpadding="10" cellspacing="0"> +<tbody><tr> +<td bgcolor="#ff9218" valign="top"><font face="Arial,Helvetica"><font size="+4">Pyrex</font></font></td> + +<td style="width: 200px; vertical-align: top; text-align: right; background-color: rgb(93, 186, 202);"><font face="Arial,Helvetica"><font size="+1">A +smooth blend of the finest Python </font></font> +<br><font face="Arial,Helvetica"><font size="+1">with the unsurpassed power </font></font> +<font face="Arial,Helvetica"><font size="+1">of raw C.</font></font></td> +</tr> +</tbody></table> + +<blockquote><font size="+1">Welcome to Pyrex, a language for writing Python +extension modules. Pyrex makes creating an extension module almost as +easy as creating a Python module.</font></blockquote> + +<h1> +<font face="Arial,Helvetica"><font size="+2">Documentation</font></font></h1> + +<blockquote> +<h2> +<font face="Arial,Helvetica"><font size="+1"><a href="About.html">About Pyrex</a></font></font></h2> + +<blockquote><font size="+1">Read this to find out what Pyrex is all about +and what it can do for you.</font></blockquote> + +<h2> +<font face="Arial,Helvetica"><font size="+1"><a href="LanguageOverview.html">Language +Overview</a></font></font></h2> + +<blockquote><font size="+1">A comined tutorial and reference manual describing of all the features of the Pyrex +language.</font></blockquote> + +<h2> +<font face="Arial,Helvetica"><font size="+1"><a href="FAQ.html">FAQ</a></font></font></h2> + +<blockquote><font size="+1">Want to know how to do something in Pyrex? Check +here first<font face="Arial,Helvetica">.</font></font></blockquote> +</blockquote> + +<h1> +<font face="Arial,Helvetica"><font size="+2">Other Resources</font></font></h1> + +<blockquote> +<h2> +<font face="Arial,Helvetica"><font size="+1"><a href="http://www.cosc.canterbury.ac.nz/%7Egreg/python/Pyrex/mpj17-pyrex-guide/">Michael's +Quick Guide to Pyrex</a></font></font></h2> + +<blockquote><font size="+1">This tutorial-style presentation will take you +through the steps of creating some Pyrex modules to wrap existing C libraries. +Contributed by <a href="mailto:[email protected]">Michael JasonSmith</a>.</font></blockquote> + +<h2> +<font face="Arial,Helvetica"><font size="+1"><a href="mailto:[email protected]">Mail +to the Author</a></font></font></h2> + +<blockquote><font size="+1">If you have a question that's not answered by +anything here, you're not sure about something, or you have a bug to report +or a suggestion to make, or anything at all to say about Pyrex, feel free +to email me:<font face="Arial,Helvetica"> </font><tt><a href="mailto:[email protected]">[email protected]</a></tt></font></blockquote> +</blockquote> + +</body></html>
\ No newline at end of file diff --git a/debian/pyrex/pyrex-0.9.9/Doc/primes.c b/debian/pyrex/pyrex-0.9.9/Doc/primes.c new file mode 100644 index 00000000..9a88b84c --- /dev/null +++ b/debian/pyrex/pyrex-0.9.9/Doc/primes.c @@ -0,0 +1 @@ +#include "Python.h"
static PyObject *__Pyx_UnpackItem(PyObject *, int);
static int __Pyx_EndUnpack(PyObject *, int);
static int __Pyx_PrintItem(PyObject *);
static int __Pyx_PrintNewline(void);
static void __Pyx_ReRaise(void);
static void __Pyx_RaiseWithTraceback(PyObject *, PyObject *, PyObject *);
static PyObject *__Pyx_Import(PyObject *name, PyObject *from_list);
static PyObject *__Pyx_GetExcValue(void);
static PyObject *__Pyx_GetName(PyObject *dict, char *name);
static PyObject *__pyx_m;
static PyObject *__pyx_d;
static PyObject *__pyx_b;
PyObject *__pyx_f_primes(PyObject *__pyx_self, PyObject *__pyx_args); /*proto*/
PyObject *__pyx_f_primes(PyObject *__pyx_self, PyObject *__pyx_args) {
int __pyx_v_kmax;
int __pyx_v_n;
int __pyx_v_k;
int __pyx_v_i;
int (__pyx_v_p[1000]);
PyObject *__pyx_v_result;
PyObject *__pyx_r;
PyObject *__pyx_1 = 0;
int __pyx_2;
int __pyx_3;
int __pyx_4;
PyObject *__pyx_5 = 0;
PyObject *__pyx_6 = 0;
if (!PyArg_ParseTuple(__pyx_args, "i", &__pyx_v_kmax)) return 0;
__pyx_v_result = Py_None; Py_INCREF(__pyx_v_result);
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":2 */
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":3 */
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":4 */
__pyx_1 = PyList_New(0); if (!__pyx_1) goto __pyx_L1;
Py_DECREF(__pyx_v_result);
__pyx_v_result = __pyx_1;
__pyx_1 = 0;
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":5 */
__pyx_2 = (__pyx_v_kmax > 1000);
if (__pyx_2) {
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":6 */
__pyx_v_kmax = 1000;
goto __pyx_L2;
}
__pyx_L2:;
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":7 */
__pyx_v_k = 0;
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":8 */
__pyx_v_n = 2;
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":9 */
while (1) {
__pyx_L3:;
__pyx_2 = (__pyx_v_k < __pyx_v_kmax);
if (!__pyx_2) break;
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":10 */
__pyx_v_i = 0;
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":11 */
while (1) {
__pyx_L5:;
if (__pyx_3 = (__pyx_v_i < __pyx_v_k)) {
__pyx_3 = ((__pyx_v_n % (__pyx_v_p[__pyx_v_i])) != 0);
}
if (!__pyx_3) break;
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":12 */
__pyx_v_i = (__pyx_v_i + 1);
}
__pyx_L6:;
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":13 */
__pyx_4 = (__pyx_v_i == __pyx_v_k);
if (__pyx_4) {
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":14 */
(__pyx_v_p[__pyx_v_k]) = __pyx_v_n;
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":15 */
__pyx_v_k = (__pyx_v_k + 1);
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":16 */
__pyx_1 = PyObject_GetAttrString(__pyx_v_result, "append"); if (!__pyx_1) goto __pyx_L1;
__pyx_5 = PyInt_FromLong(__pyx_v_n); if (!__pyx_5) goto __pyx_L1;
__pyx_6 = PyTuple_New(1); if (!__pyx_6) goto __pyx_L1;
PyTuple_SET_ITEM(__pyx_6, 0, __pyx_5);
__pyx_5 = 0;
__pyx_5 = PyObject_CallObject(__pyx_1, __pyx_6); if (!__pyx_5) goto __pyx_L1;
Py_DECREF(__pyx_6); __pyx_6 = 0;
Py_DECREF(__pyx_5); __pyx_5 = 0;
goto __pyx_L7;
}
__pyx_L7:;
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":17 */
__pyx_v_n = (__pyx_v_n + 1);
}
__pyx_L4:;
/* "ProjectsA:Python:Pyrex:Demos:primes.pyx":18 */
Py_INCREF(__pyx_v_result);
__pyx_r = __pyx_v_result;
goto __pyx_L0;
__pyx_r = Py_None; Py_INCREF(__pyx_r);
goto __pyx_L0;
__pyx_L1:;
Py_XDECREF(__pyx_1);
Py_XDECREF(__pyx_5);
Py_XDECREF(__pyx_6);
__pyx_r = 0;
__pyx_L0:;
Py_DECREF(__pyx_v_result);
return __pyx_r;
}
static struct PyMethodDef __pyx_methods[] = {
{"primes", (PyCFunction)__pyx_f_primes, METH_VARARGS, 0},
{0, 0, 0, 0}
};
void initprimes(void); /*proto*/
void initprimes(void) {
__pyx_m = Py_InitModule4("primes", __pyx_methods, 0, 0, PYTHON_API_VERSION);
__pyx_d = PyModule_GetDict(__pyx_m);
__pyx_b = PyImport_AddModule("__builtin__");
PyDict_SetItemString(__pyx_d, "__builtins__", __pyx_b);
}
/* Runtime support code */
\ No newline at end of file |