| 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="number.html" /> |
| 13 | <link rel="prev" href="abstract.html" /> |
| 14 | <link rel="parent" href="abstract.html" /> |
| 15 | <link rel="next" href="number.html" /> |
| 16 | <meta name='aesop' content='information' /> |
| 17 | <title>6.1 Object Protocol </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="6. Abstract Objects Layer" |
| 25 | href="abstract.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="6. Abstract Objects Layer" |
| 28 | href="abstract.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="6.2 Number Protocol" |
| 31 | href="number.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="abstract.html">6. Abstract Objects Layer</A> |
| 46 | <b class="navlabel">Up:</b> |
| 47 | <a class="sectref" rel="parent" href="abstract.html">6. Abstract Objects Layer</A> |
| 48 | <b class="navlabel">Next:</b> |
| 49 | <a class="sectref" rel="next" href="number.html">6.2 Number Protocol</A> |
| 50 | </div> |
| 51 | <hr /></div> |
| 52 | </DIV> |
| 53 | <!--End of Navigation Panel--> |
| 54 | |
| 55 | <H1><A NAME="SECTION008100000000000000000"></A><A NAME="object"></A> |
| 56 | <BR> |
| 57 | 6.1 Object Protocol |
| 58 | </H1> |
| 59 | |
| 60 | <P> |
| 61 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-215' xml:id='l2h-215' class="cfunction">PyObject_Print</tt></b>(</nobr></td><td>PyObject *<var>o</var>, FILE *<var>fp</var>, int <var>flags</var>)</td></tr></table></dt> |
| 62 | <dd> |
| 63 | Print an object <var>o</var>, on file <var>fp</var>. Returns <code>-1</code> on |
| 64 | error. The flags argument is used to enable certain printing |
| 65 | options. The only option currently supported is |
| 66 | <tt class="constant">Py_PRINT_RAW</tt>; if given, the <tt class="function">str()</tt> of the |
| 67 | object is written instead of the <tt class="function">repr()</tt>. |
| 68 | </dd></dl> |
| 69 | |
| 70 | <P> |
| 71 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-216' xml:id='l2h-216' class="cfunction">PyObject_HasAttrString</tt></b>(</nobr></td><td>PyObject *<var>o</var>, char *<var>attr_name</var>)</td></tr></table></dt> |
| 72 | <dd> |
| 73 | Returns <code>1</code> if <var>o</var> has the attribute <var>attr_name</var>, and |
| 74 | <code>0</code> otherwise. This is equivalent to the Python expression |
| 75 | "<tt class="samp">hasattr(<var>o</var>, <var>attr_name</var>)</tt>". This function always |
| 76 | succeeds. |
| 77 | </dd></dl> |
| 78 | |
| 79 | <P> |
| 80 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-217' xml:id='l2h-217' class="cfunction">PyObject_GetAttrString</tt></b>(</nobr></td><td>PyObject *<var>o</var>, |
| 81 | char *<var>attr_name</var>)</td></tr></table></dt> |
| 82 | <dd> |
| 83 | <div class="refcount-info"> |
| 84 | <span class="label">Return value:</span> |
| 85 | <span class="value">New reference.</span> |
| 86 | </div> |
| 87 | Retrieve an attribute named <var>attr_name</var> from object <var>o</var>. |
| 88 | Returns the attribute value on success, or <tt class="constant">NULL</tt> on failure. |
| 89 | This is the equivalent of the Python expression |
| 90 | "<tt class="samp"><var>o</var>.<var>attr_name</var></tt>". |
| 91 | </dd></dl> |
| 92 | |
| 93 | <P> |
| 94 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-218' xml:id='l2h-218' class="cfunction">PyObject_HasAttr</tt></b>(</nobr></td><td>PyObject *<var>o</var>, PyObject *<var>attr_name</var>)</td></tr></table></dt> |
| 95 | <dd> |
| 96 | Returns <code>1</code> if <var>o</var> has the attribute <var>attr_name</var>, and |
| 97 | <code>0</code> otherwise. This is equivalent to the Python expression |
| 98 | "<tt class="samp">hasattr(<var>o</var>, <var>attr_name</var>)</tt>". This function always |
| 99 | succeeds. |
| 100 | </dd></dl> |
| 101 | |
| 102 | <P> |
| 103 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-219' xml:id='l2h-219' class="cfunction">PyObject_GetAttr</tt></b>(</nobr></td><td>PyObject *<var>o</var>, |
| 104 | PyObject *<var>attr_name</var>)</td></tr></table></dt> |
| 105 | <dd> |
| 106 | <div class="refcount-info"> |
| 107 | <span class="label">Return value:</span> |
| 108 | <span class="value">New reference.</span> |
| 109 | </div> |
| 110 | Retrieve an attribute named <var>attr_name</var> from object <var>o</var>. |
| 111 | Returns the attribute value on success, or <tt class="constant">NULL</tt> on failure. This |
| 112 | is the equivalent of the Python expression |
| 113 | "<tt class="samp"><var>o</var>.<var>attr_name</var></tt>". |
| 114 | </dd></dl> |
| 115 | |
| 116 | <P> |
| 117 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-220' xml:id='l2h-220' class="cfunction">PyObject_SetAttrString</tt></b>(</nobr></td><td>PyObject *<var>o</var>, |
| 118 | char *<var>attr_name</var>, PyObject *<var>v</var>)</td></tr></table></dt> |
| 119 | <dd> |
| 120 | Set the value of the attribute named <var>attr_name</var>, for object |
| 121 | <var>o</var>, to the value <var>v</var>. Returns <code>-1</code> on failure. This |
| 122 | is the equivalent of the Python statement |
| 123 | "<tt class="samp"><var>o</var>.<var>attr_name</var> = <var>v</var></tt>". |
| 124 | </dd></dl> |
| 125 | |
| 126 | <P> |
| 127 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-221' xml:id='l2h-221' class="cfunction">PyObject_SetAttr</tt></b>(</nobr></td><td>PyObject *<var>o</var>, |
| 128 | PyObject *<var>attr_name</var>, PyObject *<var>v</var>)</td></tr></table></dt> |
| 129 | <dd> |
| 130 | Set the value of the attribute named <var>attr_name</var>, for object |
| 131 | <var>o</var>, to the value <var>v</var>. Returns <code>-1</code> on failure. This |
| 132 | is the equivalent of the Python statement |
| 133 | "<tt class="samp"><var>o</var>.<var>attr_name</var> = <var>v</var></tt>". |
| 134 | </dd></dl> |
| 135 | |
| 136 | <P> |
| 137 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-222' xml:id='l2h-222' class="cfunction">PyObject_DelAttrString</tt></b>(</nobr></td><td>PyObject *<var>o</var>, char *<var>attr_name</var>)</td></tr></table></dt> |
| 138 | <dd> |
| 139 | Delete attribute named <var>attr_name</var>, for object <var>o</var>. Returns |
| 140 | <code>-1</code> on failure. This is the equivalent of the Python |
| 141 | statement: "<tt class="samp">del <var>o</var>.<var>attr_name</var></tt>". |
| 142 | </dd></dl> |
| 143 | |
| 144 | <P> |
| 145 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-223' xml:id='l2h-223' class="cfunction">PyObject_DelAttr</tt></b>(</nobr></td><td>PyObject *<var>o</var>, PyObject *<var>attr_name</var>)</td></tr></table></dt> |
| 146 | <dd> |
| 147 | Delete attribute named <var>attr_name</var>, for object <var>o</var>. Returns |
| 148 | <code>-1</code> on failure. This is the equivalent of the Python |
| 149 | statement "<tt class="samp">del <var>o</var>.<var>attr_name</var></tt>". |
| 150 | </dd></dl> |
| 151 | |
| 152 | <P> |
| 153 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-224' xml:id='l2h-224' class="cfunction">PyObject_RichCompare</tt></b>(</nobr></td><td>PyObject *<var>o1</var>, |
| 154 | PyObject *<var>o2</var>, int <var>opid</var>)</td></tr></table></dt> |
| 155 | <dd> |
| 156 | <div class="refcount-info"> |
| 157 | <span class="label">Return value:</span> |
| 158 | <span class="value">New reference.</span> |
| 159 | </div> |
| 160 | Compare the values of <var>o1</var> and <var>o2</var> using the operation |
| 161 | specified by <var>opid</var>, which must be one of |
| 162 | <tt class="constant">Py_LT</tt>, |
| 163 | <tt class="constant">Py_LE</tt>, |
| 164 | <tt class="constant">Py_EQ</tt>, |
| 165 | <tt class="constant">Py_NE</tt>, |
| 166 | <tt class="constant">Py_GT</tt>, or |
| 167 | <tt class="constant">Py_GE</tt>, corresponding to |
| 168 | <code><</code>, |
| 169 | <code><=</code>, |
| 170 | <code>==</code>, |
| 171 | <code>!=</code>, |
| 172 | <code>></code>, or |
| 173 | <code>>=</code> respectively. This is the equivalent of the Python expression |
| 174 | "<tt class="samp"><var>o1</var> op <var>o2</var></tt>", where <code>op</code> is the operator |
| 175 | corresponding to <var>opid</var>. Returns the value of the comparison on |
| 176 | success, or <tt class="constant">NULL</tt> on failure. |
| 177 | </dd></dl> |
| 178 | |
| 179 | <P> |
| 180 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-225' xml:id='l2h-225' class="cfunction">PyObject_RichCompareBool</tt></b>(</nobr></td><td>PyObject *<var>o1</var>, |
| 181 | PyObject *<var>o2</var>, int <var>opid</var>)</td></tr></table></dt> |
| 182 | <dd> |
| 183 | Compare the values of <var>o1</var> and <var>o2</var> using the operation |
| 184 | specified by <var>opid</var>, which must be one of |
| 185 | <tt class="constant">Py_LT</tt>, |
| 186 | <tt class="constant">Py_LE</tt>, |
| 187 | <tt class="constant">Py_EQ</tt>, |
| 188 | <tt class="constant">Py_NE</tt>, |
| 189 | <tt class="constant">Py_GT</tt>, or |
| 190 | <tt class="constant">Py_GE</tt>, corresponding to |
| 191 | <code><</code>, |
| 192 | <code><=</code>, |
| 193 | <code>==</code>, |
| 194 | <code>!=</code>, |
| 195 | <code>></code>, or |
| 196 | <code>>=</code> respectively. Returns <code>-1</code> on error, <code>0</code> if the |
| 197 | result is false, <code>1</code> otherwise. This is the equivalent of the |
| 198 | Python expression "<tt class="samp"><var>o1</var> op <var>o2</var></tt>", where |
| 199 | <code>op</code> is the operator corresponding to <var>opid</var>. |
| 200 | </dd></dl> |
| 201 | |
| 202 | <P> |
| 203 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-226' xml:id='l2h-226' class="cfunction">PyObject_Cmp</tt></b>(</nobr></td><td>PyObject *<var>o1</var>, PyObject *<var>o2</var>, int *<var>result</var>)</td></tr></table></dt> |
| 204 | <dd> |
| 205 | Compare the values of <var>o1</var> and <var>o2</var> using a routine provided |
| 206 | by <var>o1</var>, if one exists, otherwise with a routine provided by |
| 207 | <var>o2</var>. The result of the comparison is returned in |
| 208 | <var>result</var>. Returns <code>-1</code> on failure. This is the equivalent |
| 209 | of the Python statement<a id='l2h-227' xml:id='l2h-227'></a> "<tt class="samp"><var>result</var> = |
| 210 | cmp(<var>o1</var>, <var>o2</var>)</tt>". |
| 211 | </dd></dl> |
| 212 | |
| 213 | <P> |
| 214 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-228' xml:id='l2h-228' class="cfunction">PyObject_Compare</tt></b>(</nobr></td><td>PyObject *<var>o1</var>, PyObject *<var>o2</var>)</td></tr></table></dt> |
| 215 | <dd> |
| 216 | Compare the values of <var>o1</var> and <var>o2</var> using a routine provided |
| 217 | by <var>o1</var>, if one exists, otherwise with a routine provided by |
| 218 | <var>o2</var>. Returns the result of the comparison on success. On |
| 219 | error, the value returned is undefined; use |
| 220 | <tt class="cfunction">PyErr_Occurred()</tt> to detect an error. This is equivalent |
| 221 | to the Python expression<a id='l2h-229' xml:id='l2h-229'></a> "<tt class="samp">cmp(<var>o1</var>, |
| 222 | <var>o2</var>)</tt>". |
| 223 | </dd></dl> |
| 224 | |
| 225 | <P> |
| 226 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-230' xml:id='l2h-230' class="cfunction">PyObject_Repr</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table></dt> |
| 227 | <dd> |
| 228 | <div class="refcount-info"> |
| 229 | <span class="label">Return value:</span> |
| 230 | <span class="value">New reference.</span> |
| 231 | </div> |
| 232 | Compute a string representation of object <var>o</var>. Returns the |
| 233 | string representation on success, <tt class="constant">NULL</tt> on failure. This is the |
| 234 | equivalent of the Python expression "<tt class="samp">repr(<var>o</var>)</tt>". Called by |
| 235 | the <tt class="function">repr()</tt><a id='l2h-231' xml:id='l2h-231'></a> built-in function and by |
| 236 | reverse quotes. |
| 237 | </dd></dl> |
| 238 | |
| 239 | <P> |
| 240 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-232' xml:id='l2h-232' class="cfunction">PyObject_Str</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table></dt> |
| 241 | <dd> |
| 242 | <div class="refcount-info"> |
| 243 | <span class="label">Return value:</span> |
| 244 | <span class="value">New reference.</span> |
| 245 | </div> |
| 246 | Compute a string representation of object <var>o</var>. Returns the |
| 247 | string representation on success, <tt class="constant">NULL</tt> on failure. This is the |
| 248 | equivalent of the Python expression "<tt class="samp">str(<var>o</var>)</tt>". Called by |
| 249 | the <tt class="function">str()</tt><a id='l2h-233' xml:id='l2h-233'></a> built-in function and by the |
| 250 | <tt class="keyword">print</tt> statement. |
| 251 | </dd></dl> |
| 252 | |
| 253 | <P> |
| 254 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-234' xml:id='l2h-234' class="cfunction">PyObject_Unicode</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table></dt> |
| 255 | <dd> |
| 256 | <div class="refcount-info"> |
| 257 | <span class="label">Return value:</span> |
| 258 | <span class="value">New reference.</span> |
| 259 | </div> |
| 260 | Compute a Unicode string representation of object <var>o</var>. Returns |
| 261 | the Unicode string representation on success, <tt class="constant">NULL</tt> on failure. |
| 262 | This is the equivalent of the Python expression |
| 263 | "<tt class="samp">unicode(<var>o</var>)</tt>". Called by the |
| 264 | <tt class="function">unicode()</tt><a id='l2h-235' xml:id='l2h-235'></a> built-in function. |
| 265 | </dd></dl> |
| 266 | |
| 267 | <P> |
| 268 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-236' xml:id='l2h-236' class="cfunction">PyObject_IsInstance</tt></b>(</nobr></td><td>PyObject *<var>inst</var>, PyObject *<var>cls</var>)</td></tr></table></dt> |
| 269 | <dd> |
| 270 | Returns <code>1</code> if <var>inst</var> is an instance of the class <var>cls</var> |
| 271 | or a subclass of <var>cls</var>, or <code>0</code> if not. On error, returns |
| 272 | <code>-1</code> and sets an exception. If <var>cls</var> is a type object |
| 273 | rather than a class object, <tt class="cfunction">PyObject_IsInstance()</tt> |
| 274 | returns <code>1</code> if <var>inst</var> is of type <var>cls</var>. If <var>cls</var> |
| 275 | is a tuple, the check will be done against every entry in <var>cls</var>. |
| 276 | The result will be <code>1</code> when at least one of the checks returns |
| 277 | <code>1</code>, otherwise it will be <code>0</code>. If <var>inst</var> is not a class |
| 278 | instance and <var>cls</var> is neither a type object, nor a class object, |
| 279 | nor a tuple, <var>inst</var> must have a <tt class="member">__class__</tt> attribute |
| 280 | -- the class relationship of the value of that attribute with |
| 281 | <var>cls</var> will be used to determine the result of this function. |
| 282 | |
| 283 | <span class="versionnote">New in version 2.1.</span> |
| 284 | |
| 285 | <span class="versionnote">Changed in version 2.2: |
| 286 | Support for a tuple as the second argument added.</span> |
| 287 | |
| 288 | </dd></dl> |
| 289 | |
| 290 | <P> |
| 291 | Subclass determination is done in a fairly straightforward way, but |
| 292 | includes a wrinkle that implementors of extensions to the class system |
| 293 | may want to be aware of. If <tt class="class">A</tt> and <tt class="class">B</tt> are class |
| 294 | objects, <tt class="class">B</tt> is a subclass of <tt class="class">A</tt> if it inherits from |
| 295 | <tt class="class">A</tt> either directly or indirectly. If either is not a class |
| 296 | object, a more general mechanism is used to determine the class |
| 297 | relationship of the two objects. When testing if <var>B</var> is a |
| 298 | subclass of <var>A</var>, if <var>A</var> is <var>B</var>, |
| 299 | <tt class="cfunction">PyObject_IsSubclass()</tt> returns true. If <var>A</var> and |
| 300 | <var>B</var> are different objects, <var>B</var>'s <tt class="member">__bases__</tt> attribute |
| 301 | is searched in a depth-first fashion for <var>A</var> -- the presence of |
| 302 | the <tt class="member">__bases__</tt> attribute is considered sufficient for this |
| 303 | determination. |
| 304 | |
| 305 | <P> |
| 306 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-237' xml:id='l2h-237' class="cfunction">PyObject_IsSubclass</tt></b>(</nobr></td><td>PyObject *<var>derived</var>, |
| 307 | PyObject *<var>cls</var>)</td></tr></table></dt> |
| 308 | <dd> |
| 309 | Returns <code>1</code> if the class <var>derived</var> is identical to or |
| 310 | derived from the class <var>cls</var>, otherwise returns <code>0</code>. In |
| 311 | case of an error, returns <code>-1</code>. If <var>cls</var> |
| 312 | is a tuple, the check will be done against every entry in <var>cls</var>. |
| 313 | The result will be <code>1</code> when at least one of the checks returns |
| 314 | <code>1</code>, otherwise it will be <code>0</code>. If either <var>derived</var> or |
| 315 | <var>cls</var> is not an actual class object (or tuple), this function |
| 316 | uses the generic algorithm described above. |
| 317 | |
| 318 | <span class="versionnote">New in version 2.1.</span> |
| 319 | |
| 320 | <span class="versionnote">Changed in version 2.3: |
| 321 | Older versions of Python did not support a tuple |
| 322 | as the second argument.</span> |
| 323 | |
| 324 | </dd></dl> |
| 325 | |
| 326 | <P> |
| 327 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-238' xml:id='l2h-238' class="cfunction">PyCallable_Check</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table></dt> |
| 328 | <dd> |
| 329 | Determine if the object <var>o</var> is callable. Return <code>1</code> if the |
| 330 | object is callable and <code>0</code> otherwise. This function always |
| 331 | succeeds. |
| 332 | </dd></dl> |
| 333 | |
| 334 | <P> |
| 335 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-239' xml:id='l2h-239' class="cfunction">PyObject_Call</tt></b>(</nobr></td><td>PyObject *<var>callable_object</var>, |
| 336 | PyObject *<var>args</var>, |
| 337 | PyObject *<var>kw</var>)</td></tr></table></dt> |
| 338 | <dd> |
| 339 | Call a callable Python object <var>callable_object</var>, with arguments |
| 340 | given by the tuple <var>args</var>, and named arguments given by the |
| 341 | dictionary <var>kw</var>. If no named arguments are needed, <var>kw</var> may |
| 342 | be <tt class="constant">NULL</tt>. <var>args</var> must not be <tt class="constant">NULL</tt>, use an empty tuple if |
| 343 | no arguments are needed. Returns the result of the call on success, |
| 344 | or <tt class="constant">NULL</tt> on failure. This is the equivalent of the Python |
| 345 | expression "<tt class="samp">apply(<var>callable_object</var>, <var>args</var>, <var>kw</var>)</tt>" or "<tt class="samp"><var>callable_object</var>(*<var>args</var>, **<var>kw</var>)</tt>". |
| 346 | <a id='l2h-240' xml:id='l2h-240'></a> |
| 347 | <span class="versionnote">New in version 2.2.</span> |
| 348 | |
| 349 | </dd></dl> |
| 350 | |
| 351 | <P> |
| 352 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-241' xml:id='l2h-241' class="cfunction">PyObject_CallObject</tt></b>(</nobr></td><td>PyObject *<var>callable_object</var>, |
| 353 | PyObject *<var>args</var>)</td></tr></table></dt> |
| 354 | <dd> |
| 355 | <div class="refcount-info"> |
| 356 | <span class="label">Return value:</span> |
| 357 | <span class="value">New reference.</span> |
| 358 | </div> |
| 359 | Call a callable Python object <var>callable_object</var>, with arguments |
| 360 | given by the tuple <var>args</var>. If no arguments are needed, then |
| 361 | <var>args</var> may be <tt class="constant">NULL</tt>. Returns the result of the call on |
| 362 | success, or <tt class="constant">NULL</tt> on failure. This is the equivalent of the |
| 363 | Python expression "<tt class="samp">apply(<var>callable_object</var>, <var>args</var>)</tt>" or |
| 364 | "<tt class="samp"><var>callable_object</var>(*<var>args</var>)</tt>". |
| 365 | <a id='l2h-242' xml:id='l2h-242'></a></dd></dl> |
| 366 | |
| 367 | <P> |
| 368 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-243' xml:id='l2h-243' class="cfunction">PyObject_CallFunction</tt></b>(</nobr></td><td>PyObject *<var>callable</var>, |
| 369 | char *<var>format</var>, ...)</td></tr></table></dt> |
| 370 | <dd> |
| 371 | <div class="refcount-info"> |
| 372 | <span class="label">Return value:</span> |
| 373 | <span class="value">New reference.</span> |
| 374 | </div> |
| 375 | Call a callable Python object <var>callable</var>, with a variable |
| 376 | number of C arguments. The C arguments are described using a |
| 377 | <tt class="cfunction">Py_BuildValue()</tt> style format string. The format may be |
| 378 | <tt class="constant">NULL</tt>, indicating that no arguments are provided. Returns the |
| 379 | result of the call on success, or <tt class="constant">NULL</tt> on failure. This is the |
| 380 | equivalent of the Python expression "<tt class="samp">apply(<var>callable</var>, |
| 381 | <var>args</var>)</tt>" or "<tt class="samp"><var>callable</var>(*<var>args</var>)</tt>". |
| 382 | <a id='l2h-244' xml:id='l2h-244'></a></dd></dl> |
| 383 | |
| 384 | <P> |
| 385 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-245' xml:id='l2h-245' class="cfunction">PyObject_CallMethod</tt></b>(</nobr></td><td>PyObject *<var>o</var>, |
| 386 | char *<var>method</var>, char *<var>format</var>, |
| 387 | ...)</td></tr></table></dt> |
| 388 | <dd> |
| 389 | <div class="refcount-info"> |
| 390 | <span class="label">Return value:</span> |
| 391 | <span class="value">New reference.</span> |
| 392 | </div> |
| 393 | Call the method named <var>method</var> of object <var>o</var> with a variable |
| 394 | number of C arguments. The C arguments are described by a |
| 395 | <tt class="cfunction">Py_BuildValue()</tt> format string that should |
| 396 | produce a tuple. The format may be <tt class="constant">NULL</tt>, |
| 397 | indicating that no arguments are provided. Returns the result of the |
| 398 | call on success, or <tt class="constant">NULL</tt> on failure. This is the equivalent of |
| 399 | the Python expression "<tt class="samp"><var>o</var>.<var>method</var>(<var>args</var>)</tt>". |
| 400 | </dd></dl> |
| 401 | |
| 402 | <P> |
| 403 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-246' xml:id='l2h-246' class="cfunction">PyObject_CallFunctionObjArgs</tt></b>(</nobr></td><td>PyObject *<var>callable</var>, |
| 404 | ..., |
| 405 | <code>NULL</code>)</td></tr></table></dt> |
| 406 | <dd> |
| 407 | <div class="refcount-info"> |
| 408 | <span class="label">Return value:</span> |
| 409 | <span class="value">New reference.</span> |
| 410 | </div> |
| 411 | Call a callable Python object <var>callable</var>, with a variable |
| 412 | number of <tt class="ctype">PyObject*</tt> arguments. The arguments are provided |
| 413 | as a variable number of parameters followed by <tt class="constant">NULL</tt>. |
| 414 | Returns the result of the call on success, or <tt class="constant">NULL</tt> on failure. |
| 415 | |
| 416 | <span class="versionnote">New in version 2.2.</span> |
| 417 | |
| 418 | </dd></dl> |
| 419 | |
| 420 | <P> |
| 421 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-247' xml:id='l2h-247' class="cfunction">PyObject_CallMethodObjArgs</tt></b>(</nobr></td><td>PyObject *<var>o</var>, |
| 422 | PyObject *<var>name</var>, |
| 423 | ..., |
| 424 | <code>NULL</code>)</td></tr></table></dt> |
| 425 | <dd> |
| 426 | <div class="refcount-info"> |
| 427 | <span class="label">Return value:</span> |
| 428 | <span class="value">New reference.</span> |
| 429 | </div> |
| 430 | Calls a method of the object <var>o</var>, where the name of the method |
| 431 | is given as a Python string object in <var>name</var>. It is called with |
| 432 | a variable number of <tt class="ctype">PyObject*</tt> arguments. The arguments are |
| 433 | provided as a variable number of parameters followed by <tt class="constant">NULL</tt>. |
| 434 | Returns the result of the call on success, or <tt class="constant">NULL</tt> on failure. |
| 435 | |
| 436 | <span class="versionnote">New in version 2.2.</span> |
| 437 | |
| 438 | </dd></dl> |
| 439 | |
| 440 | <P> |
| 441 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-248' xml:id='l2h-248' class="cfunction">PyObject_Hash</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table></dt> |
| 442 | <dd> |
| 443 | Compute and return the hash value of an object <var>o</var>. On failure, |
| 444 | return <code>-1</code>. This is the equivalent of the Python expression |
| 445 | "<tt class="samp">hash(<var>o</var>)</tt>".<a id='l2h-249' xml:id='l2h-249'></a></dd></dl> |
| 446 | |
| 447 | <P> |
| 448 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-250' xml:id='l2h-250' class="cfunction">PyObject_IsTrue</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table></dt> |
| 449 | <dd> |
| 450 | Returns <code>1</code> if the object <var>o</var> is considered to be true, and |
| 451 | <code>0</code> otherwise. This is equivalent to the Python expression |
| 452 | "<tt class="samp">not not <var>o</var></tt>". On failure, return <code>-1</code>. |
| 453 | </dd></dl> |
| 454 | |
| 455 | <P> |
| 456 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-251' xml:id='l2h-251' class="cfunction">PyObject_Not</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table></dt> |
| 457 | <dd> |
| 458 | Returns <code>0</code> if the object <var>o</var> is considered to be true, and |
| 459 | <code>1</code> otherwise. This is equivalent to the Python expression |
| 460 | "<tt class="samp">not <var>o</var></tt>". On failure, return <code>-1</code>. |
| 461 | </dd></dl> |
| 462 | |
| 463 | <P> |
| 464 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-252' xml:id='l2h-252' class="cfunction">PyObject_Type</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table></dt> |
| 465 | <dd> |
| 466 | <div class="refcount-info"> |
| 467 | <span class="label">Return value:</span> |
| 468 | <span class="value">New reference.</span> |
| 469 | </div> |
| 470 | When <var>o</var> is non-<tt class="constant">NULL</tt>, returns a type object corresponding to |
| 471 | the object type of object <var>o</var>. On failure, raises |
| 472 | <tt class="exception">SystemError</tt> and returns <tt class="constant">NULL</tt>. This is equivalent to |
| 473 | the Python expression <code>type(<var>o</var>)</code>.<a id='l2h-253' xml:id='l2h-253'></a> This function increments the reference count of the return value. |
| 474 | There's really no reason to use this function instead of the |
| 475 | common expression <code><var>o</var>->ob_type</code>, which returns a pointer |
| 476 | of type <tt class="ctype">PyTypeObject*</tt>, except when the incremented reference |
| 477 | count is needed. |
| 478 | </dd></dl> |
| 479 | |
| 480 | <P> |
| 481 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-254' xml:id='l2h-254' class="cfunction">PyObject_TypeCheck</tt></b>(</nobr></td><td>PyObject *<var>o</var>, PyTypeObject *<var>type</var>)</td></tr></table></dt> |
| 482 | <dd> |
| 483 | Return true if the object <var>o</var> is of type <var>type</var> or a subtype |
| 484 | of <var>type</var>. Both parameters must be non-<tt class="constant">NULL</tt>. |
| 485 | |
| 486 | <span class="versionnote">New in version 2.2.</span> |
| 487 | |
| 488 | </dd></dl> |
| 489 | |
| 490 | <P> |
| 491 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-255' xml:id='l2h-255' class="cfunction">PyObject_Length</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table></dt> |
| 492 | <dd> |
| 493 | <dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-263' xml:id='l2h-263' class="cfunction">PyObject_Size</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table> |
| 494 | <dd> |
| 495 | Return the length of object <var>o</var>. If the object <var>o</var> provides |
| 496 | either the sequence and mapping protocols, the sequence length is |
| 497 | returned. On error, <code>-1</code> is returned. This is the equivalent |
| 498 | to the Python expression "<tt class="samp">len(<var>o</var>)</tt>".<a id='l2h-256' xml:id='l2h-256'></a></dd></dl> |
| 499 | |
| 500 | <P> |
| 501 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-257' xml:id='l2h-257' class="cfunction">PyObject_GetItem</tt></b>(</nobr></td><td>PyObject *<var>o</var>, PyObject *<var>key</var>)</td></tr></table></dt> |
| 502 | <dd> |
| 503 | <div class="refcount-info"> |
| 504 | <span class="label">Return value:</span> |
| 505 | <span class="value">New reference.</span> |
| 506 | </div> |
| 507 | Return element of <var>o</var> corresponding to the object <var>key</var> or |
| 508 | <tt class="constant">NULL</tt> on failure. This is the equivalent of the Python expression |
| 509 | "<tt class="samp"><var>o</var>[<var>key</var>]</tt>". |
| 510 | </dd></dl> |
| 511 | |
| 512 | <P> |
| 513 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-258' xml:id='l2h-258' class="cfunction">PyObject_SetItem</tt></b>(</nobr></td><td>PyObject *<var>o</var>, |
| 514 | PyObject *<var>key</var>, PyObject *<var>v</var>)</td></tr></table></dt> |
| 515 | <dd> |
| 516 | Map the object <var>key</var> to the value <var>v</var>. Returns <code>-1</code> on |
| 517 | failure. This is the equivalent of the Python statement |
| 518 | "<tt class="samp"><var>o</var>[<var>key</var>] = <var>v</var></tt>". |
| 519 | </dd></dl> |
| 520 | |
| 521 | <P> |
| 522 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-259' xml:id='l2h-259' class="cfunction">PyObject_DelItem</tt></b>(</nobr></td><td>PyObject *<var>o</var>, PyObject *<var>key</var>)</td></tr></table></dt> |
| 523 | <dd> |
| 524 | Delete the mapping for <var>key</var> from <var>o</var>. Returns <code>-1</code> on |
| 525 | failure. This is the equivalent of the Python statement "<tt class="samp">del |
| 526 | <var>o</var>[<var>key</var>]</tt>". |
| 527 | </dd></dl> |
| 528 | |
| 529 | <P> |
| 530 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-260' xml:id='l2h-260' class="cfunction">PyObject_AsFileDescriptor</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table></dt> |
| 531 | <dd> |
| 532 | Derives a file-descriptor from a Python object. If the object is an |
| 533 | integer or long integer, its value is returned. If not, the |
| 534 | object's <tt class="method">fileno()</tt> method is called if it exists; the method |
| 535 | must return an integer or long integer, which is returned as the |
| 536 | file descriptor value. Returns <code>-1</code> on failure. |
| 537 | </dd></dl> |
| 538 | |
| 539 | <P> |
| 540 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-261' xml:id='l2h-261' class="cfunction">PyObject_Dir</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table></dt> |
| 541 | <dd> |
| 542 | <div class="refcount-info"> |
| 543 | <span class="label">Return value:</span> |
| 544 | <span class="value">New reference.</span> |
| 545 | </div> |
| 546 | This is equivalent to the Python expression "<tt class="samp">dir(<var>o</var>)</tt>", |
| 547 | returning a (possibly empty) list of strings appropriate for the |
| 548 | object argument, or <tt class="constant">NULL</tt> if there was an error. If the argument |
| 549 | is <tt class="constant">NULL</tt>, this is like the Python "<tt class="samp">dir()</tt>", returning the names |
| 550 | of the current locals; in this case, if no execution frame is active |
| 551 | then <tt class="constant">NULL</tt> is returned but <tt class="cfunction">PyErr_Occurred()</tt> will |
| 552 | return false. |
| 553 | </dd></dl> |
| 554 | |
| 555 | <P> |
| 556 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-262' xml:id='l2h-262' class="cfunction">PyObject_GetIter</tt></b>(</nobr></td><td>PyObject *<var>o</var>)</td></tr></table></dt> |
| 557 | <dd> |
| 558 | <div class="refcount-info"> |
| 559 | <span class="label">Return value:</span> |
| 560 | <span class="value">New reference.</span> |
| 561 | </div> |
| 562 | This is equivalent to the Python expression "<tt class="samp">iter(<var>o</var>)</tt>". |
| 563 | It returns a new iterator for the object argument, or the object |
| 564 | itself if the object is already an iterator. Raises |
| 565 | <tt class="exception">TypeError</tt> and returns <tt class="constant">NULL</tt> if the object cannot be |
| 566 | iterated. |
| 567 | </dd></dl> |
| 568 | |
| 569 | <P> |
| 570 | |
| 571 | <DIV CLASS="navigation"> |
| 572 | <div class='online-navigation'> |
| 573 | <p></p><hr /> |
| 574 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 575 | <tr> |
| 576 | <td class='online-navigation'><a rel="prev" title="6. Abstract Objects Layer" |
| 577 | href="abstract.html"><img src='../icons/previous.png' |
| 578 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 579 | <td class='online-navigation'><a rel="parent" title="6. Abstract Objects Layer" |
| 580 | href="abstract.html"><img src='../icons/up.png' |
| 581 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 582 | <td class='online-navigation'><a rel="next" title="6.2 Number Protocol" |
| 583 | href="number.html"><img src='../icons/next.png' |
| 584 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 585 | <td align="center" width="100%">Python/C API Reference Manual</td> |
| 586 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 587 | href="contents.html"><img src='../icons/contents.png' |
| 588 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 589 | <td class='online-navigation'><img src='../icons/blank.png' |
| 590 | border='0' height='32' alt='' width='32' /></td> |
| 591 | <td class='online-navigation'><a rel="index" title="Index" |
| 592 | href="genindex.html"><img src='../icons/index.png' |
| 593 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 594 | </tr></table> |
| 595 | <div class='online-navigation'> |
| 596 | <b class="navlabel">Previous:</b> |
| 597 | <a class="sectref" rel="prev" href="abstract.html">6. Abstract Objects Layer</A> |
| 598 | <b class="navlabel">Up:</b> |
| 599 | <a class="sectref" rel="parent" href="abstract.html">6. Abstract Objects Layer</A> |
| 600 | <b class="navlabel">Next:</b> |
| 601 | <a class="sectref" rel="next" href="number.html">6.2 Number Protocol</A> |
| 602 | </div> |
| 603 | </div> |
| 604 | <hr /> |
| 605 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 606 | </DIV> |
| 607 | <!--End of Navigation Panel--> |
| 608 | <ADDRESS> |
| 609 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 610 | </ADDRESS> |
| 611 | </BODY> |
| 612 | </HTML> |