| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <link rel="STYLESHEET" href="ext.css" type='text/css' /> |
| 5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> |
| 6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> |
| 7 | <link rel="first" href="ext.html" title='Extending and Embedding the Python Interpreter' /> |
| 8 | <link rel='contents' href='contents.html' title="Contents" /> |
| 9 | <link rel='last' href='about.html' title='About this document...' /> |
| 10 | <link rel='help' href='about.html' title='About this document...' /> |
| 11 | <link rel="prev" href="dnt-basics.html" /> |
| 12 | <link rel="parent" href="defining-new-types.html" /> |
| 13 | <link rel="next" href="node26.html" /> |
| 14 | <meta name='aesop' content='information' /> |
| 15 | <title>2.2 Type Methods </title> |
| 16 | </head> |
| 17 | <body> |
| 18 | <DIV CLASS="navigation"> |
| 19 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> |
| 20 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 21 | <tr> |
| 22 | <td class='online-navigation'><a rel="prev" title="2.1.3 Supporting cyclic garbage" |
| 23 | href="node24.html"><img src='../icons/previous.png' |
| 24 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 25 | <td class='online-navigation'><a rel="parent" title="2. Defining New Types" |
| 26 | href="defining-new-types.html"><img src='../icons/up.png' |
| 27 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 28 | <td class='online-navigation'><a rel="next" title="2.2.1 Finalization and De-allocation" |
| 29 | href="node26.html"><img src='../icons/next.png' |
| 30 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 31 | <td align="center" width="100%">Extending and Embedding the Python Interpreter</td> |
| 32 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 33 | href="contents.html"><img src='../icons/contents.png' |
| 34 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 35 | <td class='online-navigation'><img src='../icons/blank.png' |
| 36 | border='0' height='32' alt='' width='32' /></td> |
| 37 | <td class='online-navigation'><img src='../icons/blank.png' |
| 38 | border='0' height='32' alt='' width='32' /></td> |
| 39 | </tr></table> |
| 40 | <div class='online-navigation'> |
| 41 | <b class="navlabel">Previous:</b> |
| 42 | <a class="sectref" rel="prev" href="node24.html">2.1.3 Supporting cyclic garbage</A> |
| 43 | <b class="navlabel">Up:</b> |
| 44 | <a class="sectref" rel="parent" href="defining-new-types.html">2. Defining New Types</A> |
| 45 | <b class="navlabel">Next:</b> |
| 46 | <a class="sectref" rel="next" href="node26.html">2.2.1 Finalization and De-allocation</A> |
| 47 | </div> |
| 48 | <hr /></div> |
| 49 | </DIV> |
| 50 | <!--End of Navigation Panel--> |
| 51 | |
| 52 | <H1><A NAME="SECTION004200000000000000000"></A><A NAME="dnt-type-methods"></A> |
| 53 | <BR> |
| 54 | 2.2 Type Methods |
| 55 | |
| 56 | </H1> |
| 57 | |
| 58 | <P> |
| 59 | This section aims to give a quick fly-by on the various type methods |
| 60 | you can implement and what they do. |
| 61 | |
| 62 | <P> |
| 63 | Here is the definition of <tt class="ctype">PyTypeObject</tt>, with some fields only |
| 64 | used in debug builds omitted: |
| 65 | |
| 66 | <P> |
| 67 | <div class="verbatim"> |
| 68 | <pre>typedef struct _typeobject { |
| 69 | PyObject_VAR_HEAD |
| 70 | char *tp_name; /* For printing, in format "<module>.<name>" */ |
| 71 | int tp_basicsize, tp_itemsize; /* For allocation */ |
| 72 | |
| 73 | /* Methods to implement standard operations */ |
| 74 | |
| 75 | destructor tp_dealloc; |
| 76 | printfunc tp_print; |
| 77 | getattrfunc tp_getattr; |
| 78 | setattrfunc tp_setattr; |
| 79 | cmpfunc tp_compare; |
| 80 | reprfunc tp_repr; |
| 81 | |
| 82 | /* Method suites for standard classes */ |
| 83 | |
| 84 | PyNumberMethods *tp_as_number; |
| 85 | PySequenceMethods *tp_as_sequence; |
| 86 | PyMappingMethods *tp_as_mapping; |
| 87 | |
| 88 | /* More standard operations (here for binary compatibility) */ |
| 89 | |
| 90 | hashfunc tp_hash; |
| 91 | ternaryfunc tp_call; |
| 92 | reprfunc tp_str; |
| 93 | getattrofunc tp_getattro; |
| 94 | setattrofunc tp_setattro; |
| 95 | |
| 96 | /* Functions to access object as input/output buffer */ |
| 97 | PyBufferProcs *tp_as_buffer; |
| 98 | |
| 99 | /* Flags to define presence of optional/expanded features */ |
| 100 | long tp_flags; |
| 101 | |
| 102 | char *tp_doc; /* Documentation string */ |
| 103 | |
| 104 | /* Assigned meaning in release 2.0 */ |
| 105 | /* call function for all accessible objects */ |
| 106 | traverseproc tp_traverse; |
| 107 | |
| 108 | /* delete references to contained objects */ |
| 109 | inquiry tp_clear; |
| 110 | |
| 111 | /* Assigned meaning in release 2.1 */ |
| 112 | /* rich comparisons */ |
| 113 | richcmpfunc tp_richcompare; |
| 114 | |
| 115 | /* weak reference enabler */ |
| 116 | long tp_weaklistoffset; |
| 117 | |
| 118 | /* Added in release 2.2 */ |
| 119 | /* Iterators */ |
| 120 | getiterfunc tp_iter; |
| 121 | iternextfunc tp_iternext; |
| 122 | |
| 123 | /* Attribute descriptor and subclassing stuff */ |
| 124 | struct PyMethodDef *tp_methods; |
| 125 | struct PyMemberDef *tp_members; |
| 126 | struct PyGetSetDef *tp_getset; |
| 127 | struct _typeobject *tp_base; |
| 128 | PyObject *tp_dict; |
| 129 | descrgetfunc tp_descr_get; |
| 130 | descrsetfunc tp_descr_set; |
| 131 | long tp_dictoffset; |
| 132 | initproc tp_init; |
| 133 | allocfunc tp_alloc; |
| 134 | newfunc tp_new; |
| 135 | freefunc tp_free; /* Low-level free-memory routine */ |
| 136 | inquiry tp_is_gc; /* For PyObject_IS_GC */ |
| 137 | PyObject *tp_bases; |
| 138 | PyObject *tp_mro; /* method resolution order */ |
| 139 | PyObject *tp_cache; |
| 140 | PyObject *tp_subclasses; |
| 141 | PyObject *tp_weaklist; |
| 142 | |
| 143 | } PyTypeObject; |
| 144 | </pre> |
| 145 | <div class="footer"> |
| 146 | <a href="typestruct.txt" type="text/plain">Download as text (original file name: <span class="file">typestruct.h</span>).</a> |
| 147 | </div></div> |
| 148 | |
| 149 | <P> |
| 150 | Now that's a <em>lot</em> of methods. Don't worry too much though - if |
| 151 | you have a type you want to define, the chances are very good that you |
| 152 | will only implement a handful of these. |
| 153 | |
| 154 | <P> |
| 155 | As you probably expect by now, we're going to go over this and give |
| 156 | more information about the various handlers. We won't go in the order |
| 157 | they are defined in the structure, because there is a lot of |
| 158 | historical baggage that impacts the ordering of the fields; be sure |
| 159 | your type initialization keeps the fields in the right order! It's |
| 160 | often easiest to find an example that includes all the fields you need |
| 161 | (even if they're initialized to <code>0</code>) and then change the values |
| 162 | to suit your new type. |
| 163 | |
| 164 | <P> |
| 165 | <div class="verbatim"><pre> |
| 166 | char *tp_name; /* For printing */ |
| 167 | </pre></div> |
| 168 | |
| 169 | <P> |
| 170 | The name of the type - as mentioned in the last section, this will |
| 171 | appear in various places, almost entirely for diagnostic purposes. |
| 172 | Try to choose something that will be helpful in such a situation! |
| 173 | |
| 174 | <P> |
| 175 | <div class="verbatim"><pre> |
| 176 | int tp_basicsize, tp_itemsize; /* For allocation */ |
| 177 | </pre></div> |
| 178 | |
| 179 | <P> |
| 180 | These fields tell the runtime how much memory to allocate when new |
| 181 | objects of this type are created. Python has some built-in support |
| 182 | for variable length structures (think: strings, lists) which is where |
| 183 | the <tt class="member">tp_itemsize</tt> field comes in. This will be dealt with |
| 184 | later. |
| 185 | |
| 186 | <P> |
| 187 | <div class="verbatim"><pre> |
| 188 | char *tp_doc; |
| 189 | </pre></div> |
| 190 | |
| 191 | <P> |
| 192 | Here you can put a string (or its address) that you want returned when |
| 193 | the Python script references <code>obj.__doc__</code> to retrieve the |
| 194 | doc string. |
| 195 | |
| 196 | <P> |
| 197 | Now we come to the basic type methods--the ones most extension types |
| 198 | will implement. |
| 199 | |
| 200 | <P> |
| 201 | |
| 202 | <p><br /></p><hr class='online-navigation' /> |
| 203 | <div class='online-navigation'> |
| 204 | <!--Table of Child-Links--> |
| 205 | <A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a> |
| 206 | |
| 207 | <UL CLASS="ChildLinks"> |
| 208 | <LI><A href="node26.html">2.2.1 Finalization and De-allocation</a> |
| 209 | <LI><A href="node27.html">2.2.2 Object Presentation</a> |
| 210 | <LI><A href="node28.html">2.2.3 Attribute Management</a> |
| 211 | <UL> |
| 212 | <LI><A href="node29.html">2.2.3.1 Generic Attribute Management</a> |
| 213 | <LI><A href="node30.html">2.2.3.2 Type-specific Attribute Management</a> |
| 214 | </ul> |
| 215 | <LI><A href="node31.html">2.2.4 Object Comparison</a> |
| 216 | <LI><A href="node32.html">2.2.5 Abstract Protocol Support</a> |
| 217 | <LI><A href="node33.html">2.2.6 More Suggestions</a> |
| 218 | </ul> |
| 219 | <!--End of Table of Child-Links--> |
| 220 | </div> |
| 221 | |
| 222 | <DIV CLASS="navigation"> |
| 223 | <div class='online-navigation'> |
| 224 | <p></p><hr /> |
| 225 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 226 | <tr> |
| 227 | <td class='online-navigation'><a rel="prev" title="2.1.3 Supporting cyclic garbage" |
| 228 | href="node24.html"><img src='../icons/previous.png' |
| 229 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 230 | <td class='online-navigation'><a rel="parent" title="2. Defining New Types" |
| 231 | href="defining-new-types.html"><img src='../icons/up.png' |
| 232 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 233 | <td class='online-navigation'><a rel="next" title="2.2.1 Finalization and De-allocation" |
| 234 | href="node26.html"><img src='../icons/next.png' |
| 235 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 236 | <td align="center" width="100%">Extending and Embedding the Python Interpreter</td> |
| 237 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 238 | href="contents.html"><img src='../icons/contents.png' |
| 239 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 240 | <td class='online-navigation'><img src='../icons/blank.png' |
| 241 | border='0' height='32' alt='' width='32' /></td> |
| 242 | <td class='online-navigation'><img src='../icons/blank.png' |
| 243 | border='0' height='32' alt='' width='32' /></td> |
| 244 | </tr></table> |
| 245 | <div class='online-navigation'> |
| 246 | <b class="navlabel">Previous:</b> |
| 247 | <a class="sectref" rel="prev" href="node24.html">2.1.3 Supporting cyclic garbage</A> |
| 248 | <b class="navlabel">Up:</b> |
| 249 | <a class="sectref" rel="parent" href="defining-new-types.html">2. Defining New Types</A> |
| 250 | <b class="navlabel">Next:</b> |
| 251 | <a class="sectref" rel="next" href="node26.html">2.2.1 Finalization and De-allocation</A> |
| 252 | </div> |
| 253 | </div> |
| 254 | <hr /> |
| 255 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 256 | </DIV> |
| 257 | <!--End of Navigation Panel--> |
| 258 | <ADDRESS> |
| 259 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 260 | </ADDRESS> |
| 261 | </BODY> |
| 262 | </HTML> |