| 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| 2 | <html> |
| 3 | <head> |
| 4 | <link rel="STYLESHEET" href="api.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="api.html" title='Python/C API Reference Manual' /> |
| 8 | <link rel='contents' href='contents.html' title="Contents" /> |
| 9 | <link rel='index' href='genindex.html' title='Index' /> |
| 10 | <link rel='last' href='about.html' title='About this document...' /> |
| 11 | <link rel='help' href='about.html' title='About this document...' /> |
| 12 | <link rel="next" href="type-structs.html" /> |
| 13 | <link rel="prev" href="allocating-objects.html" /> |
| 14 | <link rel="parent" href="newTypes.html" /> |
| 15 | <link rel="next" href="type-structs.html" /> |
| 16 | <meta name='aesop' content='information' /> |
| 17 | <title>10.2 Common Object Structures </title> |
| 18 | </head> |
| 19 | <body> |
| 20 | <DIV CLASS="navigation"> |
| 21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> |
| 22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 23 | <tr> |
| 24 | <td class='online-navigation'><a rel="prev" title="10.1 Allocating Objects on" |
| 25 | href="allocating-objects.html"><img src='../icons/previous.png' |
| 26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 27 | <td class='online-navigation'><a rel="parent" title="10. Object Implementation Support" |
| 28 | href="newTypes.html"><img src='../icons/up.png' |
| 29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 30 | <td class='online-navigation'><a rel="next" title="10.3 Type Objects" |
| 31 | href="type-structs.html"><img src='../icons/next.png' |
| 32 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 33 | <td align="center" width="100%">Python/C API Reference Manual</td> |
| 34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 35 | href="contents.html"><img src='../icons/contents.png' |
| 36 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 37 | <td class='online-navigation'><img src='../icons/blank.png' |
| 38 | border='0' height='32' alt='' width='32' /></td> |
| 39 | <td class='online-navigation'><a rel="index" title="Index" |
| 40 | href="genindex.html"><img src='../icons/index.png' |
| 41 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 42 | </tr></table> |
| 43 | <div class='online-navigation'> |
| 44 | <b class="navlabel">Previous:</b> |
| 45 | <a class="sectref" rel="prev" href="allocating-objects.html">10.1 Allocating Objects on</A> |
| 46 | <b class="navlabel">Up:</b> |
| 47 | <a class="sectref" rel="parent" href="newTypes.html">10. Object Implementation Support</A> |
| 48 | <b class="navlabel">Next:</b> |
| 49 | <a class="sectref" rel="next" href="type-structs.html">10.3 Type Objects</A> |
| 50 | </div> |
| 51 | <hr /></div> |
| 52 | </DIV> |
| 53 | <!--End of Navigation Panel--> |
| 54 | |
| 55 | <H1><A NAME="SECTION0012200000000000000000"></A><A NAME="common-structs"></A> |
| 56 | <BR> |
| 57 | 10.2 Common Object Structures |
| 58 | </H1> |
| 59 | |
| 60 | <P> |
| 61 | There are a large number of structures which are used in the |
| 62 | definition of object types for Python. This section describes these |
| 63 | structures and how they are used. |
| 64 | |
| 65 | <P> |
| 66 | All Python objects ultimately share a small number of fields at the |
| 67 | beginning of the object's representation in memory. These are |
| 68 | represented by the <tt class="ctype">PyObject</tt> and <tt class="ctype">PyVarObject</tt> types, |
| 69 | which are defined, in turn, by the expansions of some macros also |
| 70 | used, whether directly or indirectly, in the definition of all other |
| 71 | Python objects. |
| 72 | |
| 73 | <P> |
| 74 | <dl><dt><b><tt class="ctype"><a id='l2h-920' xml:id='l2h-920'>PyObject</a></tt></b></dt> |
| 75 | <dd> |
| 76 | All object types are extensions of this type. This is a type which |
| 77 | contains the information Python needs to treat a pointer to an |
| 78 | object as an object. In a normal ``release'' build, it contains |
| 79 | only the objects reference count and a pointer to the corresponding |
| 80 | type object. It corresponds to the fields defined by the |
| 81 | expansion of the <code>PyObject_HEAD</code> macro. |
| 82 | </dl> |
| 83 | |
| 84 | <P> |
| 85 | <dl><dt><b><tt class="ctype"><a id='l2h-921' xml:id='l2h-921'>PyVarObject</a></tt></b></dt> |
| 86 | <dd> |
| 87 | This is an extension of <tt class="ctype">PyObject</tt> that adds the |
| 88 | <tt class="member">ob_size</tt> field. This is only used for objects that have |
| 89 | some notion of <em>length</em>. This type does not often appear in |
| 90 | the Python/C API. It corresponds to the fields defined by the |
| 91 | expansion of the <code>PyObject_VAR_HEAD</code> macro. |
| 92 | </dl> |
| 93 | |
| 94 | <P> |
| 95 | These macros are used in the definition of <tt class="ctype">PyObject</tt> and |
| 96 | <tt class="ctype">PyVarObject</tt>: |
| 97 | |
| 98 | <P> |
| 99 | <dl><dt><b><tt id='l2h-922' xml:id='l2h-922' class="macro">PyObject_HEAD</tt></b></dt> |
| 100 | <dd> |
| 101 | This is a macro which expands to the declarations of the fields of |
| 102 | the <tt class="ctype">PyObject</tt> type; it is used when declaring new types which |
| 103 | represent objects without a varying length. The specific fields it |
| 104 | expands to depend on the definition of |
| 105 | Py_TRACE_REFS. By default, that macro is not |
| 106 | defined, and PyObject_HEAD expands to: |
| 107 | <div class="verbatim"><pre> |
| 108 | int ob_refcnt; |
| 109 | PyTypeObject *ob_type; |
| 110 | </pre></div> |
| 111 | When Py_TRACE_REFS is defined, it expands to: |
| 112 | <div class="verbatim"><pre> |
| 113 | PyObject *_ob_next, *_ob_prev; |
| 114 | int ob_refcnt; |
| 115 | PyTypeObject *ob_type; |
| 116 | </pre></div> |
| 117 | </dl> |
| 118 | |
| 119 | <P> |
| 120 | <dl><dt><b><tt id='l2h-923' xml:id='l2h-923' class="macro">PyObject_VAR_HEAD</tt></b></dt> |
| 121 | <dd> |
| 122 | This is a macro which expands to the declarations of the fields of |
| 123 | the <tt class="ctype">PyVarObject</tt> type; it is used when declaring new types which |
| 124 | represent objects with a length that varies from instance to |
| 125 | instance. This macro always expands to: |
| 126 | <div class="verbatim"><pre> |
| 127 | PyObject_HEAD |
| 128 | int ob_size; |
| 129 | </pre></div> |
| 130 | Note that PyObject_HEAD is part of the expansion, and |
| 131 | that it's own expansion varies depending on the definition of |
| 132 | Py_TRACE_REFS. |
| 133 | </dl> |
| 134 | |
| 135 | <P> |
| 136 | PyObject_HEAD_INIT |
| 137 | |
| 138 | <P> |
| 139 | <dl><dt><b><tt class="ctype"><a id='l2h-924' xml:id='l2h-924'>PyCFunction</a></tt></b></dt> |
| 140 | <dd> |
| 141 | Type of the functions used to implement most Python callables in C. |
| 142 | Functions of this type take two <tt class="ctype">PyObject*</tt> parameters and |
| 143 | return one such value. If the return value is <tt class="constant">NULL</tt>, an exception |
| 144 | shall have been set. If not <tt class="constant">NULL</tt>, the return value is interpreted |
| 145 | as the return value of the function as exposed in Python. The |
| 146 | function must return a new reference. |
| 147 | </dl> |
| 148 | |
| 149 | <P> |
| 150 | <dl><dt><b><tt class="ctype"><a id='l2h-925' xml:id='l2h-925'>PyMethodDef</a></tt></b></dt> |
| 151 | <dd> |
| 152 | Structure used to describe a method of an extension type. This |
| 153 | structure has four fields: |
| 154 | |
| 155 | <P> |
| 156 | <div class="center"><table class="realtable"> |
| 157 | <thead> |
| 158 | <tr> |
| 159 | <th class="left" >Field</th> |
| 160 | <th class="left" >C Type</th> |
| 161 | <th class="left" >Meaning</th> |
| 162 | </tr> |
| 163 | </thead> |
| 164 | <tbody> |
| 165 | <tr><td class="left" valign="baseline"><tt class="member">ml_name</tt></td> |
| 166 | <td class="left" >char *</td> |
| 167 | <td class="left" >name of the method</td></tr> |
| 168 | <tr><td class="left" valign="baseline"><tt class="member">ml_meth</tt></td> |
| 169 | <td class="left" >PyCFunction</td> |
| 170 | <td class="left" >pointer to the C implementation</td></tr> |
| 171 | <tr><td class="left" valign="baseline"><tt class="member">ml_flags</tt></td> |
| 172 | <td class="left" >int</td> |
| 173 | <td class="left" >flag bits indicating how the call should be |
| 174 | constructed</td></tr> |
| 175 | <tr><td class="left" valign="baseline"><tt class="member">ml_doc</tt></td> |
| 176 | <td class="left" >char *</td> |
| 177 | <td class="left" >points to the contents of the docstring</td></tr></tbody> |
| 178 | </table></div> |
| 179 | </dl> |
| 180 | |
| 181 | <P> |
| 182 | The <tt class="member">ml_meth</tt> is a C function pointer. The functions may be of |
| 183 | different types, but they always return <tt class="ctype">PyObject*</tt>. If the |
| 184 | function is not of the <tt class="ctype">PyCFunction</tt>, the compiler will require |
| 185 | a cast in the method table. Even though <tt class="ctype">PyCFunction</tt> defines |
| 186 | the first parameter as <tt class="ctype">PyObject*</tt>, it is common that the method |
| 187 | implementation uses a the specific C type of the <var>self</var> object. |
| 188 | |
| 189 | <P> |
| 190 | The <tt class="member">ml_flags</tt> field is a bitfield which can include the |
| 191 | following flags. The individual flags indicate either a calling |
| 192 | convention or a binding convention. Of the calling convention flags, |
| 193 | only <tt class="constant">METH_VARARGS</tt> and <tt class="constant">METH_KEYWORDS</tt> can be |
| 194 | combined (but note that <tt class="constant">METH_KEYWORDS</tt> alone is equivalent |
| 195 | to <code><tt class="constant">METH_VARARGS</tt> | <tt class="constant">METH_KEYWORDS</tt></code>). |
| 196 | Any of the calling convention flags can be combined with a |
| 197 | binding flag. |
| 198 | |
| 199 | <P> |
| 200 | <dl><dt><b><tt id='l2h-926' xml:id='l2h-926'>METH_VARARGS</tt></b></dt> |
| 201 | <dd> |
| 202 | This is the typical calling convention, where the methods have the |
| 203 | type <tt class="ctype">PyCFunction</tt>. The function expects two |
| 204 | <tt class="ctype">PyObject*</tt> values. The first one is the <var>self</var> object for |
| 205 | methods; for module functions, it has the value given to |
| 206 | <tt class="cfunction">Py_InitModule4()</tt> (or <tt class="constant">NULL</tt> if |
| 207 | <tt class="cfunction">Py_InitModule()</tt> was used). The second parameter |
| 208 | (often called <var>args</var>) is a tuple object representing all |
| 209 | arguments. This parameter is typically processed using |
| 210 | <tt class="cfunction">PyArg_ParseTuple()</tt> or <tt class="cfunction">PyArg_UnpackTuple</tt>. |
| 211 | </dd></dl> |
| 212 | |
| 213 | <P> |
| 214 | <dl><dt><b><tt id='l2h-927' xml:id='l2h-927'>METH_KEYWORDS</tt></b></dt> |
| 215 | <dd> |
| 216 | Methods with these flags must be of type |
| 217 | <tt class="ctype">PyCFunctionWithKeywords</tt>. The function expects three |
| 218 | parameters: <var>self</var>, <var>args</var>, and a dictionary of all the |
| 219 | keyword arguments. The flag is typically combined with |
| 220 | <tt class="constant">METH_VARARGS</tt>, and the parameters are typically processed |
| 221 | using <tt class="cfunction">PyArg_ParseTupleAndKeywords()</tt>. |
| 222 | </dd></dl> |
| 223 | |
| 224 | <P> |
| 225 | <dl><dt><b><tt id='l2h-928' xml:id='l2h-928'>METH_NOARGS</tt></b></dt> |
| 226 | <dd> |
| 227 | Methods without parameters don't need to check whether arguments are |
| 228 | given if they are listed with the <tt class="constant">METH_NOARGS</tt> flag. They |
| 229 | need to be of type <tt class="ctype">PyCFunction</tt>. When used with object |
| 230 | methods, the first parameter is typically named <code>self</code> and will |
| 231 | hold a reference to the object instance. In all cases the second |
| 232 | parameter will be <tt class="constant">NULL</tt>. |
| 233 | </dd></dl> |
| 234 | |
| 235 | <P> |
| 236 | <dl><dt><b><tt id='l2h-929' xml:id='l2h-929'>METH_O</tt></b></dt> |
| 237 | <dd> |
| 238 | Methods with a single object argument can be listed with the |
| 239 | <tt class="constant">METH_O</tt> flag, instead of invoking |
| 240 | <tt class="cfunction">PyArg_ParseTuple()</tt> with a <code>"O"</code> argument. They have |
| 241 | the type <tt class="ctype">PyCFunction</tt>, with the <var>self</var> parameter, and a |
| 242 | <tt class="ctype">PyObject*</tt> parameter representing the single argument. |
| 243 | </dd></dl> |
| 244 | |
| 245 | <P> |
| 246 | <dl><dt><b><tt id='l2h-930' xml:id='l2h-930'>METH_OLDARGS</tt></b></dt> |
| 247 | <dd> |
| 248 | This calling convention is deprecated. The method must be of type |
| 249 | <tt class="ctype">PyCFunction</tt>. The second argument is <tt class="constant">NULL</tt> if no arguments |
| 250 | are given, a single object if exactly one argument is given, and a |
| 251 | tuple of objects if more than one argument is given. There is no |
| 252 | way for a function using this convention to distinguish between a |
| 253 | call with multiple arguments and a call with a tuple as the only |
| 254 | argument. |
| 255 | </dd></dl> |
| 256 | |
| 257 | <P> |
| 258 | These two constants are not used to indicate the calling convention |
| 259 | but the binding when use with methods of classes. These may not be |
| 260 | used for functions defined for modules. At most one of these flags |
| 261 | may be set for any given method. |
| 262 | |
| 263 | <P> |
| 264 | <dl><dt><b><tt id='l2h-931' xml:id='l2h-931'>METH_CLASS</tt></b></dt> |
| 265 | <dd> |
| 266 | The method will be passed the type object as the first parameter |
| 267 | rather than an instance of the type. This is used to create |
| 268 | <em>class methods</em>, similar to what is created when using the |
| 269 | <tt class="function">classmethod()</tt><a id='l2h-932' xml:id='l2h-932'></a> built-in |
| 270 | function. |
| 271 | |
| 272 | <span class="versionnote">New in version 2.3.</span> |
| 273 | |
| 274 | </dd></dl> |
| 275 | |
| 276 | <P> |
| 277 | <dl><dt><b><tt id='l2h-933' xml:id='l2h-933'>METH_STATIC</tt></b></dt> |
| 278 | <dd> |
| 279 | The method will be passed <tt class="constant">NULL</tt> as the first parameter rather than |
| 280 | an instance of the type. This is used to create <em>static |
| 281 | methods</em>, similar to what is created when using the |
| 282 | <tt class="function">staticmethod()</tt><a id='l2h-934' xml:id='l2h-934'></a> built-in |
| 283 | function. |
| 284 | |
| 285 | <span class="versionnote">New in version 2.3.</span> |
| 286 | |
| 287 | </dd></dl> |
| 288 | |
| 289 | <P> |
| 290 | One other constant controls whether a method is loaded in place of |
| 291 | another definition with the same method name. |
| 292 | |
| 293 | <P> |
| 294 | <dl><dt><b><tt id='l2h-935' xml:id='l2h-935'>METH_COEXIST</tt></b></dt> |
| 295 | <dd> |
| 296 | The method will be loaded in place of existing definitions. Without |
| 297 | <var>METH_COEXIST</var>, the default is to skip repeated definitions. Since |
| 298 | slot wrappers are loaded before the method table, the existence of a |
| 299 | <var>sq_contains</var> slot, for example, would generate a wrapped method |
| 300 | named <tt class="method">__contains__()</tt> and preclude the loading of a |
| 301 | corresponding PyCFunction with the same name. With the flag defined, |
| 302 | the PyCFunction will be loaded in place of the wrapper object and will |
| 303 | co-exist with the slot. This is helpful because calls to PyCFunctions |
| 304 | are optimized more than wrapper object calls. |
| 305 | |
| 306 | <span class="versionnote">New in version 2.4.</span> |
| 307 | |
| 308 | </dd></dl> |
| 309 | |
| 310 | <P> |
| 311 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-936' xml:id='l2h-936' class="cfunction">Py_FindMethod</tt></b>(</nobr></td><td>PyMethodDef table[], |
| 312 | PyObject *<var>ob</var>, char *<var>name</var>)</td></tr></table></dt> |
| 313 | <dd> |
| 314 | <div class="refcount-info"> |
| 315 | <span class="label">Return value:</span> |
| 316 | <span class="value">New reference.</span> |
| 317 | </div> |
| 318 | Return a bound method object for an extension type implemented in |
| 319 | C. This can be useful in the implementation of a |
| 320 | <tt class="member">tp_getattro</tt> or <tt class="member">tp_getattr</tt> handler that does not |
| 321 | use the <tt class="cfunction">PyObject_GenericGetAttr()</tt> function. |
| 322 | </dd></dl> |
| 323 | |
| 324 | <P> |
| 325 | |
| 326 | <DIV CLASS="navigation"> |
| 327 | <div class='online-navigation'> |
| 328 | <p></p><hr /> |
| 329 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 330 | <tr> |
| 331 | <td class='online-navigation'><a rel="prev" title="10.1 Allocating Objects on" |
| 332 | href="allocating-objects.html"><img src='../icons/previous.png' |
| 333 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 334 | <td class='online-navigation'><a rel="parent" title="10. Object Implementation Support" |
| 335 | href="newTypes.html"><img src='../icons/up.png' |
| 336 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 337 | <td class='online-navigation'><a rel="next" title="10.3 Type Objects" |
| 338 | href="type-structs.html"><img src='../icons/next.png' |
| 339 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 340 | <td align="center" width="100%">Python/C API Reference Manual</td> |
| 341 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 342 | href="contents.html"><img src='../icons/contents.png' |
| 343 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 344 | <td class='online-navigation'><img src='../icons/blank.png' |
| 345 | border='0' height='32' alt='' width='32' /></td> |
| 346 | <td class='online-navigation'><a rel="index" title="Index" |
| 347 | href="genindex.html"><img src='../icons/index.png' |
| 348 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 349 | </tr></table> |
| 350 | <div class='online-navigation'> |
| 351 | <b class="navlabel">Previous:</b> |
| 352 | <a class="sectref" rel="prev" href="allocating-objects.html">10.1 Allocating Objects on</A> |
| 353 | <b class="navlabel">Up:</b> |
| 354 | <a class="sectref" rel="parent" href="newTypes.html">10. Object Implementation Support</A> |
| 355 | <b class="navlabel">Next:</b> |
| 356 | <a class="sectref" rel="next" href="type-structs.html">10.3 Type Objects</A> |
| 357 | </div> |
| 358 | </div> |
| 359 | <hr /> |
| 360 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 361 | </DIV> |
| 362 | <!--End of Navigation Panel--> |
| 363 | <ADDRESS> |
| 364 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 365 | </ADDRESS> |
| 366 | </BODY> |
| 367 | </HTML> |