diff options
Diffstat (limited to 'Doc/special_methods.html')
| -rw-r--r-- | Doc/special_methods.html | 598 |
1 files changed, 598 insertions, 0 deletions
diff --git a/Doc/special_methods.html b/Doc/special_methods.html new file mode 100644 index 000000000..b5ef495ee --- /dev/null +++ b/Doc/special_methods.html @@ -0,0 +1,598 @@ +<!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 class</span><i> statement. It doesn't apply +to classes defined with the Python </i><span style="font-family: monospace;">class</span><i><span style="font-family: monospace;"> </span>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>__new__</tt> and <tt>__init__</tt></font></h2> + There are two methods concerned with initialising the object<tt>.</tt> +<p>The <b><tt>__new__</tt></b> method is where you should perform basic C-level +initialisation of the object, including allocation of any C data structures +that your object will own. You need to be careful what you do in the __new__ +method, because the object may not yet be a valid Python object when it is +called. Therefore, you must not invoke any Python operations which might touch +the object; in particular, do not try to call any of its methods. </p> + <p>Unlike the corresponding method in Python, your <tt>__new__</tt> method + is <i>not</i> responsible for <i>creating</i> the object. By the time your + <tt>__new__</tt> method is called, memory has been allocated for the object +and any C attributes it has have been initialised to 0 or null. (Any Python +attributes have also been initialised to <tt>None</tt>, but you probably shouldn't +rely on that.) Your <tt>__new__</tt> method is guaranteed to be called exactly +once.<br> +<br> +If your extension type has a base type, the <tt>__new__</tt> method of the +base type is automatically called <i>before</i> your <tt>__new__</tt> method +is called; you cannot explicitly call the inherited <tt>__new__</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>Note that the first parameter of the <tt>__new__</tt> method is the object +to be initialised, not the class of the object as it is in Python. </p> + <p>Any initialisation which cannot safely be done in the <tt>__new__</tt> +method should be done in the <b><tt>__init__</tt></b> method. By the time + <tt>__init__</tt> is called, the object is a fully valid Python object and +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>Keep in mind that any arguments passed to the constructor will be passed + to the <tt>__new__</tt> method as well as the <tt>__init__</tt> method. +If you anticipate subclassing your extension type in Python, you may find +it useful to give the <tt>__new__</tt> method * and ** arguments so that +it can accept and ignore extra arguments. Otherwise, any Python subclass +which has an <tt>__init__</tt> with a different signature will have to override +<tt>__new__</tt> as well as <tt>__init__</tt>, which the writer of a Python +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>__new__</tt> method is the <b><tt>__dealloc__</tt></b> +method, which should perform the inverse of the <tt>__new__</tt> method. +Any C data structures that you allocated in your <tt>__new__</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. (Earlier +versions of the Pyrex documentation stated that there was, but this turned +out to be incorrect.)<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 both 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 (see note 3). +<h2> <font size="+1">Special Method Table</font></h2> + This table lists all of the special methods together with their parameter + and return types. A parameter named <b>self</b> is of the type the method + belongs to. Other untyped parameters 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>__new__</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 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, int i, int j</td> + <td>object</td> + <td>self[i:j]</td> + </tr> + <tr> + <td><tt>__setslice__</tt></td> + <td>self, int i, int j, x</td> + <td> </td> + <td>self[i:j] = x</td> + </tr> + <tr> + <td><tt>__delslice__</tt></td> + <td>self, int i, int 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> (no Python equivalents + - 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> + <p>Note 3: If your type defines a <tt>__new__</tt> method, any method called + <tt>new</tt> that you define will be overwritten with the system-supplied + <tt>new</tt> at module import time. </p> + <br> + <br> +</body></html>
\ No newline at end of file |