diff options
Diffstat (limited to 'debian/pyrex/pyrex-0.9.9/Doc/Manual')
| -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 |
8 files changed, 0 insertions, 4095 deletions
diff --git a/debian/pyrex/pyrex-0.9.9/Doc/Manual/Limitations.html b/debian/pyrex/pyrex-0.9.9/Doc/Manual/Limitations.html deleted file mode 100644 index 74131730..00000000 --- a/debian/pyrex/pyrex-0.9.9/Doc/Manual/Limitations.html +++ /dev/null @@ -1,53 +0,0 @@ -<!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 deleted file mode 100644 index 132c2899..00000000 --- a/debian/pyrex/pyrex-0.9.9/Doc/Manual/basics.html +++ /dev/null @@ -1,1118 +0,0 @@ -<!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 deleted file mode 100644 index 3cd3dc42..00000000 --- a/debian/pyrex/pyrex-0.9.9/Doc/Manual/extension_types.html +++ /dev/null @@ -1,1079 +0,0 @@ -<!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 deleted file mode 100644 index 38f19270..00000000 --- a/debian/pyrex/pyrex-0.9.9/Doc/Manual/external.html +++ /dev/null @@ -1,294 +0,0 @@ -<!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 deleted file mode 100644 index 415bdfa1..00000000 --- a/debian/pyrex/pyrex-0.9.9/Doc/Manual/sharing.html +++ /dev/null @@ -1,342 +0,0 @@ -<!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 deleted file mode 100644 index 0d47fdeb..00000000 --- a/debian/pyrex/pyrex-0.9.9/Doc/Manual/source_files.html +++ /dev/null @@ -1,78 +0,0 @@ -<!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 deleted file mode 100644 index 087c51d7..00000000 --- a/debian/pyrex/pyrex-0.9.9/Doc/Manual/special_methods.html +++ /dev/null @@ -1,1124 +0,0 @@ -<!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 deleted file mode 100644 index df95c8e7..00000000 --- a/debian/pyrex/pyrex-0.9.9/Doc/Manual/using_with_c++.html +++ /dev/null @@ -1,7 +0,0 @@ -<!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 |