diff options
Diffstat (limited to 'debian/pyrex/pyrex-0.9.9/Doc/Manual/special_methods.html')
| -rw-r--r-- | debian/pyrex/pyrex-0.9.9/Doc/Manual/special_methods.html | 1124 |
1 files changed, 0 insertions, 1124 deletions
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 |