| 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="prev" href="marshalling-utils.html" /> |
| 13 | <link rel="parent" href="utilities.html" /> |
| 14 | <link rel="next" href="abstract.html" /> |
| 15 | <meta name='aesop' content='information' /> |
| 16 | <title>5.5 Parsing arguments and building values |
| 17 | </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="5.4 Data marshalling support" |
| 25 | href="marshalling-utils.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="5. Utilities" |
| 28 | href="utilities.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. Abstract Objects Layer" |
| 31 | href="abstract.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="marshalling-utils.html">5.4 Data marshalling support</A> |
| 46 | <b class="navlabel">Up:</b> |
| 47 | <a class="sectref" rel="parent" href="utilities.html">5. Utilities</A> |
| 48 | <b class="navlabel">Next:</b> |
| 49 | <a class="sectref" rel="next" href="abstract.html">6. Abstract Objects Layer</A> |
| 50 | </div> |
| 51 | <hr /></div> |
| 52 | </DIV> |
| 53 | <!--End of Navigation Panel--> |
| 54 | |
| 55 | <H1><A NAME="SECTION007500000000000000000"></A><A NAME="arg-parsing"></A> |
| 56 | <BR> |
| 57 | 5.5 Parsing arguments and building values |
| 58 | |
| 59 | </H1> |
| 60 | |
| 61 | <P> |
| 62 | These functions are useful when creating your own extensions functions |
| 63 | and methods. Additional information and examples are available in |
| 64 | <em class="citetitle"><a |
| 65 | href="../ext/ext.html" |
| 66 | title="Extending and Embedding the Python |
| 67 | Interpreter" |
| 68 | >Extending and Embedding the Python |
| 69 | Interpreter</a></em>. |
| 70 | |
| 71 | <P> |
| 72 | The first three of these functions described, |
| 73 | <tt class="cfunction">PyArg_ParseTuple()</tt>, |
| 74 | <tt class="cfunction">PyArg_ParseTupleAndKeywords()</tt>, and |
| 75 | <tt class="cfunction">PyArg_Parse()</tt>, all use <em>format strings</em> which are |
| 76 | used to tell the function about the expected arguments. The format |
| 77 | strings use the same syntax for each of these functions. |
| 78 | |
| 79 | <P> |
| 80 | A format string consists of zero or more ``format units.'' A format |
| 81 | unit describes one Python object; it is usually a single character or |
| 82 | a parenthesized sequence of format units. With a few exceptions, a |
| 83 | format unit that is not a parenthesized sequence normally corresponds |
| 84 | to a single address argument to these functions. In the following |
| 85 | description, the quoted form is the format unit; the entry in (round) |
| 86 | parentheses is the Python object type that matches the format unit; |
| 87 | and the entry in [square] brackets is the type of the C variable(s) |
| 88 | whose address should be passed. |
| 89 | |
| 90 | <P> |
| 91 | <DL> |
| 92 | <DT><STRONG>"<tt class="samp">s</tt>" (string or Unicode object) [const char *]</STRONG></DT> |
| 93 | <DD>Convert a Python string or Unicode object to a C pointer to a |
| 94 | character string. You must not provide storage for the string |
| 95 | itself; a pointer to an existing string is stored into the character |
| 96 | pointer variable whose address you pass. The C string is |
| 97 | NUL-terminated. The Python string must not contain embedded NUL |
| 98 | bytes; if it does, a <tt class="exception">TypeError</tt> exception is raised. |
| 99 | Unicode objects are converted to C strings using the default |
| 100 | encoding. If this conversion fails, a <tt class="exception">UnicodeError</tt> is |
| 101 | raised. |
| 102 | |
| 103 | <P> |
| 104 | </DD> |
| 105 | <DT><STRONG>"<tt class="samp">s#</tt>" (string, Unicode or any read buffer compatible object) |
| 106 | [const char *, int]</STRONG></DT> |
| 107 | <DD>This variant on "<tt class="samp">s</tt>" stores into two C variables, the first one |
| 108 | a pointer to a character string, the second one its length. In this |
| 109 | case the Python string may contain embedded null bytes. Unicode |
| 110 | objects pass back a pointer to the default encoded string version of |
| 111 | the object if such a conversion is possible. All other read-buffer |
| 112 | compatible objects pass back a reference to the raw internal data |
| 113 | representation. |
| 114 | |
| 115 | <P> |
| 116 | </DD> |
| 117 | <DT><STRONG>"<tt class="samp">z</tt>" (string or <code>None</code>) [const char *]</STRONG></DT> |
| 118 | <DD>Like "<tt class="samp">s</tt>", but the Python object may also be <code>None</code>, in |
| 119 | which case the C pointer is set to <tt class="constant">NULL</tt>. |
| 120 | |
| 121 | <P> |
| 122 | </DD> |
| 123 | <DT><STRONG>"<tt class="samp">z#</tt>" (string or <code>None</code> or any read buffer |
| 124 | compatible object) [const char *, int]</STRONG></DT> |
| 125 | <DD>This is to "<tt class="samp">s#</tt>" as "<tt class="samp">z</tt>" is to "<tt class="samp">s</tt>". |
| 126 | |
| 127 | <P> |
| 128 | </DD> |
| 129 | <DT><STRONG>"<tt class="samp">u</tt>" (Unicode object) [Py_UNICODE *]</STRONG></DT> |
| 130 | <DD>Convert a Python Unicode object to a C pointer to a NUL-terminated |
| 131 | buffer of 16-bit Unicode (UTF-16) data. As with "<tt class="samp">s</tt>", there is |
| 132 | no need to provide storage for the Unicode data buffer; a pointer to |
| 133 | the existing Unicode data is stored into the <tt class="ctype">Py_UNICODE</tt> |
| 134 | pointer variable whose address you pass. |
| 135 | |
| 136 | <P> |
| 137 | </DD> |
| 138 | <DT><STRONG>"<tt class="samp">u#</tt>" (Unicode object) [Py_UNICODE *, int]</STRONG></DT> |
| 139 | <DD>This variant on "<tt class="samp">u</tt>" stores into two C variables, the first one |
| 140 | a pointer to a Unicode data buffer, the second one its length. |
| 141 | Non-Unicode objects are handled by interpreting their read-buffer |
| 142 | pointer as pointer to a <tt class="ctype">Py_UNICODE</tt> array. |
| 143 | |
| 144 | <P> |
| 145 | </DD> |
| 146 | <DT><STRONG>"<tt class="samp">es</tt>" (string, Unicode object or character buffer |
| 147 | compatible object) [const char *encoding, char **buffer]</STRONG></DT> |
| 148 | <DD>This variant on "<tt class="samp">s</tt>" is used for encoding Unicode and objects |
| 149 | convertible to Unicode into a character buffer. It only works for |
| 150 | encoded data without embedded NUL bytes. |
| 151 | |
| 152 | <P> |
| 153 | This format requires two arguments. The first is only used as |
| 154 | input, and must be a <tt class="ctype">const char*</tt> which points to the name of an |
| 155 | encoding as a NUL-terminated string, or <tt class="constant">NULL</tt>, in which case the |
| 156 | default encoding is used. An exception is raised if the named |
| 157 | encoding is not known to Python. The second argument must be a |
| 158 | <tt class="ctype">char**</tt>; the value of the pointer it references will be set |
| 159 | to a buffer with the contents of the argument text. The text will |
| 160 | be encoded in the encoding specified by the first argument. |
| 161 | |
| 162 | <P> |
| 163 | <tt class="cfunction">PyArg_ParseTuple()</tt> will allocate a buffer of the needed |
| 164 | size, copy the encoded data into this buffer and adjust |
| 165 | <var>*buffer</var> to reference the newly allocated storage. The caller |
| 166 | is responsible for calling <tt class="cfunction">PyMem_Free()</tt> to free the |
| 167 | allocated buffer after use. |
| 168 | |
| 169 | <P> |
| 170 | </DD> |
| 171 | <DT><STRONG>"<tt class="samp">et</tt>" (string, Unicode object or character buffer |
| 172 | compatible object) [const char *encoding, char **buffer]</STRONG></DT> |
| 173 | <DD>Same as "<tt class="samp">es</tt>" except that 8-bit string objects are passed |
| 174 | through without recoding them. Instead, the implementation assumes |
| 175 | that the string object uses the encoding passed in as parameter. |
| 176 | |
| 177 | <P> |
| 178 | </DD> |
| 179 | <DT><STRONG>"<tt class="samp">es#</tt>" (string, Unicode object or character buffer compatible |
| 180 | object) [const char *encoding, char **buffer, int *buffer_length]</STRONG></DT> |
| 181 | <DD>This variant on "<tt class="samp">s#</tt>" is used for encoding Unicode and objects |
| 182 | convertible to Unicode into a character buffer. Unlike the |
| 183 | "<tt class="samp">es</tt>" format, this variant allows input data which contains NUL |
| 184 | characters. |
| 185 | |
| 186 | <P> |
| 187 | It requires three arguments. The first is only used as input, and |
| 188 | must be a <tt class="ctype">const char*</tt> which points to the name of an encoding as a |
| 189 | NUL-terminated string, or <tt class="constant">NULL</tt>, in which case the default encoding |
| 190 | is used. An exception is raised if the named encoding is not known |
| 191 | to Python. The second argument must be a <tt class="ctype">char**</tt>; the value |
| 192 | of the pointer it references will be set to a buffer with the |
| 193 | contents of the argument text. The text will be encoded in the |
| 194 | encoding specified by the first argument. The third argument must |
| 195 | be a pointer to an integer; the referenced integer will be set to |
| 196 | the number of bytes in the output buffer. |
| 197 | |
| 198 | <P> |
| 199 | There are two modes of operation: |
| 200 | |
| 201 | <P> |
| 202 | If <var>*buffer</var> points a <tt class="constant">NULL</tt> pointer, the function will |
| 203 | allocate a buffer of the needed size, copy the encoded data into |
| 204 | this buffer and set <var>*buffer</var> to reference the newly allocated |
| 205 | storage. The caller is responsible for calling |
| 206 | <tt class="cfunction">PyMem_Free()</tt> to free the allocated buffer after usage. |
| 207 | |
| 208 | <P> |
| 209 | If <var>*buffer</var> points to a non-<tt class="constant">NULL</tt> pointer (an already |
| 210 | allocated buffer), <tt class="cfunction">PyArg_ParseTuple()</tt> will use this |
| 211 | location as the buffer and interpret the initial value of |
| 212 | <var>*buffer_length</var> as the buffer size. It will then copy the |
| 213 | encoded data into the buffer and NUL-terminate it. If the buffer |
| 214 | is not large enough, a <tt class="exception">ValueError</tt> will be set. |
| 215 | |
| 216 | <P> |
| 217 | In both cases, <var>*buffer_length</var> is set to the length of the |
| 218 | encoded data without the trailing NUL byte. |
| 219 | |
| 220 | <P> |
| 221 | </DD> |
| 222 | <DT><STRONG>"<tt class="samp">et#</tt>" (string, Unicode object or character buffer compatible |
| 223 | object) [const char *encoding, char **buffer]</STRONG></DT> |
| 224 | <DD>Same as "<tt class="samp">es#</tt>" except that string objects are passed through |
| 225 | without recoding them. Instead, the implementation assumes that the |
| 226 | string object uses the encoding passed in as parameter. |
| 227 | |
| 228 | <P> |
| 229 | </DD> |
| 230 | <DT><STRONG>"<tt class="samp">b</tt>" (integer) [char]</STRONG></DT> |
| 231 | <DD>Convert a Python integer to a tiny int, stored in a C <tt class="ctype">char</tt>. |
| 232 | |
| 233 | <P> |
| 234 | </DD> |
| 235 | <DT><STRONG>"<tt class="samp">B</tt>" (integer) [unsigned char]</STRONG></DT> |
| 236 | <DD>Convert a Python integer to a tiny int without overflow checking, |
| 237 | stored in a C <tt class="ctype">unsigned char</tt>. |
| 238 | <span class="versionnote">New in version 2.3.</span> |
| 239 | |
| 240 | <P> |
| 241 | </DD> |
| 242 | <DT><STRONG>"<tt class="samp">h</tt>" (integer) [short int]</STRONG></DT> |
| 243 | <DD>Convert a Python integer to a C <tt class="ctype">short int</tt>. |
| 244 | |
| 245 | <P> |
| 246 | </DD> |
| 247 | <DT><STRONG>"<tt class="samp">H</tt>" (integer) [unsigned short int]</STRONG></DT> |
| 248 | <DD>Convert a Python integer to a C <tt class="ctype">unsigned short int</tt>, without |
| 249 | overflow checking. |
| 250 | <span class="versionnote">New in version 2.3.</span> |
| 251 | |
| 252 | <P> |
| 253 | </DD> |
| 254 | <DT><STRONG>"<tt class="samp">i</tt>" (integer) [int]</STRONG></DT> |
| 255 | <DD>Convert a Python integer to a plain C <tt class="ctype">int</tt>. |
| 256 | |
| 257 | <P> |
| 258 | </DD> |
| 259 | <DT><STRONG>"<tt class="samp">I</tt>" (integer) [unsigned int]</STRONG></DT> |
| 260 | <DD>Convert a Python integer to a C <tt class="ctype">unsigned int</tt>, without |
| 261 | overflow checking. |
| 262 | <span class="versionnote">New in version 2.3.</span> |
| 263 | |
| 264 | <P> |
| 265 | </DD> |
| 266 | <DT><STRONG>"<tt class="samp">l</tt>" (integer) [long int]</STRONG></DT> |
| 267 | <DD>Convert a Python integer to a C <tt class="ctype">long int</tt>. |
| 268 | |
| 269 | <P> |
| 270 | </DD> |
| 271 | <DT><STRONG>"<tt class="samp">k</tt>" (integer) [unsigned long]</STRONG></DT> |
| 272 | <DD>Convert a Python integer or long integer to a C <tt class="ctype">unsigned long</tt> without |
| 273 | overflow checking. |
| 274 | <span class="versionnote">New in version 2.3.</span> |
| 275 | |
| 276 | <P> |
| 277 | </DD> |
| 278 | <DT><STRONG>"<tt class="samp">L</tt>" (integer) [PY_LONG_LONG]</STRONG></DT> |
| 279 | <DD>Convert a Python integer to a C <tt class="ctype">long long</tt>. This format is |
| 280 | only available on platforms that support <tt class="ctype">long long</tt> (or |
| 281 | <tt class="ctype">_int64</tt> on Windows). |
| 282 | |
| 283 | <P> |
| 284 | </DD> |
| 285 | <DT><STRONG>"<tt class="samp">K</tt>" (integer) [unsigned PY_LONG_LONG]</STRONG></DT> |
| 286 | <DD>Convert a Python integer or long integer to a C <tt class="ctype">unsigned long long</tt> |
| 287 | without overflow checking. This format is only available on |
| 288 | platforms that support <tt class="ctype">unsigned long long</tt> (or |
| 289 | <tt class="ctype">unsigned _int64</tt> on Windows). |
| 290 | <span class="versionnote">New in version 2.3.</span> |
| 291 | |
| 292 | <P> |
| 293 | </DD> |
| 294 | <DT><STRONG>"<tt class="samp">c</tt>" (string of length 1) [char]</STRONG></DT> |
| 295 | <DD>Convert a Python character, represented as a string of length 1, to |
| 296 | a C <tt class="ctype">char</tt>. |
| 297 | |
| 298 | <P> |
| 299 | </DD> |
| 300 | <DT><STRONG>"<tt class="samp">f</tt>" (float) [float]</STRONG></DT> |
| 301 | <DD>Convert a Python floating point number to a C <tt class="ctype">float</tt>. |
| 302 | |
| 303 | <P> |
| 304 | </DD> |
| 305 | <DT><STRONG>"<tt class="samp">d</tt>" (float) [double]</STRONG></DT> |
| 306 | <DD>Convert a Python floating point number to a C <tt class="ctype">double</tt>. |
| 307 | |
| 308 | <P> |
| 309 | </DD> |
| 310 | <DT><STRONG>"<tt class="samp">D</tt>" (complex) [Py_complex]</STRONG></DT> |
| 311 | <DD>Convert a Python complex number to a C <tt class="ctype">Py_complex</tt> structure. |
| 312 | |
| 313 | <P> |
| 314 | </DD> |
| 315 | <DT><STRONG>"<tt class="samp">O</tt>" (object) [PyObject *]</STRONG></DT> |
| 316 | <DD>Store a Python object (without any conversion) in a C object |
| 317 | pointer. The C program thus receives the actual object that was |
| 318 | passed. The object's reference count is not increased. The pointer |
| 319 | stored is not <tt class="constant">NULL</tt>. |
| 320 | |
| 321 | <P> |
| 322 | </DD> |
| 323 | <DT><STRONG>"<tt class="samp">O!</tt>" (object) [<var>typeobject</var>, PyObject *]</STRONG></DT> |
| 324 | <DD>Store a Python object in a C object pointer. This is similar to |
| 325 | "<tt class="samp">O</tt>", but takes two C arguments: the first is the address of a |
| 326 | Python type object, the second is the address of the C variable (of |
| 327 | type <tt class="ctype">PyObject*</tt>) into which the object pointer is stored. If |
| 328 | the Python object does not have the required type, |
| 329 | <tt class="exception">TypeError</tt> is raised. |
| 330 | |
| 331 | <P> |
| 332 | </DD> |
| 333 | <DT><STRONG>"<tt class="samp">O&</tt>" (object) [<var>converter</var>, <var>anything</var>]</STRONG></DT> |
| 334 | <DD>Convert a Python object to a C variable through a <var>converter</var> |
| 335 | function. This takes two arguments: the first is a function, the |
| 336 | second is the address of a C variable (of arbitrary type), converted |
| 337 | to <tt class="ctype">void *</tt>. The <var>converter</var> function in turn is called |
| 338 | as follows: |
| 339 | |
| 340 | <P> |
| 341 | <var>status</var><code> = </code><var>converter</var><code>(</code><var>object</var>, |
| 342 | <var>address</var><code>);</code> |
| 343 | |
| 344 | <P> |
| 345 | where <var>object</var> is the Python object to be converted and |
| 346 | <var>address</var> is the <tt class="ctype">void*</tt> argument that was passed to the |
| 347 | <tt class="cfunction">PyArg_Parse*()</tt> function. The returned <var>status</var> |
| 348 | should be <code>1</code> for a successful conversion and <code>0</code> if the |
| 349 | conversion has failed. When the conversion fails, the |
| 350 | <var>converter</var> function should raise an exception. |
| 351 | |
| 352 | <P> |
| 353 | </DD> |
| 354 | <DT><STRONG>"<tt class="samp">S</tt>" (string) [PyStringObject *]</STRONG></DT> |
| 355 | <DD>Like "<tt class="samp">O</tt>" but requires that the Python object is a string |
| 356 | object. Raises <tt class="exception">TypeError</tt> if the object is not a string |
| 357 | object. The C variable may also be declared as <tt class="ctype">PyObject*</tt>. |
| 358 | |
| 359 | <P> |
| 360 | </DD> |
| 361 | <DT><STRONG>"<tt class="samp">U</tt>" (Unicode string) [PyUnicodeObject *]</STRONG></DT> |
| 362 | <DD>Like "<tt class="samp">O</tt>" but requires that the Python object is a Unicode |
| 363 | object. Raises <tt class="exception">TypeError</tt> if the object is not a Unicode |
| 364 | object. The C variable may also be declared as <tt class="ctype">PyObject*</tt>. |
| 365 | |
| 366 | <P> |
| 367 | </DD> |
| 368 | <DT><STRONG>"<tt class="samp">t#</tt>" (read-only character buffer) [char *, int]</STRONG></DT> |
| 369 | <DD>Like "<tt class="samp">s#</tt>", but accepts any object which implements the |
| 370 | read-only buffer interface. The <tt class="ctype">char*</tt> variable is set to |
| 371 | point to the first byte of the buffer, and the <tt class="ctype">int</tt> is set to |
| 372 | the length of the buffer. Only single-segment buffer objects are |
| 373 | accepted; <tt class="exception">TypeError</tt> is raised for all others. |
| 374 | |
| 375 | <P> |
| 376 | </DD> |
| 377 | <DT><STRONG>"<tt class="samp">w</tt>" (read-write character buffer) [char *]</STRONG></DT> |
| 378 | <DD>Similar to "<tt class="samp">s</tt>", but accepts any object which implements the |
| 379 | read-write buffer interface. The caller must determine the length |
| 380 | of the buffer by other means, or use "<tt class="samp">w#</tt>" instead. Only |
| 381 | single-segment buffer objects are accepted; <tt class="exception">TypeError</tt> is |
| 382 | raised for all others. |
| 383 | |
| 384 | <P> |
| 385 | </DD> |
| 386 | <DT><STRONG>"<tt class="samp">w#</tt>" (read-write character buffer) [char *, int]</STRONG></DT> |
| 387 | <DD>Like "<tt class="samp">s#</tt>", but accepts any object which implements the |
| 388 | read-write buffer interface. The <tt class="ctype">char *</tt> variable is set to |
| 389 | point to the first byte of the buffer, and the <tt class="ctype">int</tt> is set to |
| 390 | the length of the buffer. Only single-segment buffer objects are |
| 391 | accepted; <tt class="exception">TypeError</tt> is raised for all others. |
| 392 | |
| 393 | <P> |
| 394 | </DD> |
| 395 | <DT><STRONG>"<tt class="samp">(<var>items</var>)</tt>" (tuple) [<var>matching-items</var>]</STRONG></DT> |
| 396 | <DD>The object must be a Python sequence whose length is the number of |
| 397 | format units in <var>items</var>. The C arguments must correspond to the |
| 398 | individual format units in <var>items</var>. Format units for sequences |
| 399 | may be nested. |
| 400 | |
| 401 | <P> |
| 402 | <span class="note"><b class="label">Note:</b> |
| 403 | Prior to Python version 1.5.2, this format specifier only |
| 404 | accepted a tuple containing the individual parameters, not an |
| 405 | arbitrary sequence. Code which previously caused |
| 406 | <tt class="exception">TypeError</tt> to be raised here may now proceed without an |
| 407 | exception. This is not expected to be a problem for existing code.</span> |
| 408 | </DD> |
| 409 | </DL> |
| 410 | |
| 411 | <P> |
| 412 | It is possible to pass Python long integers where integers are |
| 413 | requested; however no proper range checking is done -- the most |
| 414 | significant bits are silently truncated when the receiving field is |
| 415 | too small to receive the value (actually, the semantics are inherited |
| 416 | from downcasts in C -- your mileage may vary). |
| 417 | |
| 418 | <P> |
| 419 | A few other characters have a meaning in a format string. These may |
| 420 | not occur inside nested parentheses. They are: |
| 421 | |
| 422 | <P> |
| 423 | <DL> |
| 424 | <DT><STRONG>"<tt class="samp">|</tt>"</STRONG></DT> |
| 425 | <DD>Indicates that the remaining arguments in the Python argument list |
| 426 | are optional. The C variables corresponding to optional arguments |
| 427 | should be initialized to their default value -- when an optional |
| 428 | argument is not specified, <tt class="cfunction">PyArg_ParseTuple()</tt> does not |
| 429 | touch the contents of the corresponding C variable(s). |
| 430 | |
| 431 | <P> |
| 432 | </DD> |
| 433 | <DT><STRONG>"<tt class="samp">:</tt>"</STRONG></DT> |
| 434 | <DD>The list of format units ends here; the string after the colon is |
| 435 | used as the function name in error messages (the ``associated |
| 436 | value'' of the exception that <tt class="cfunction">PyArg_ParseTuple()</tt> |
| 437 | raises). |
| 438 | |
| 439 | <P> |
| 440 | </DD> |
| 441 | <DT><STRONG>"<tt class="samp">;</tt>"</STRONG></DT> |
| 442 | <DD>The list of format units ends here; the string after the semicolon |
| 443 | is used as the error message <em>instead</em> of the default error |
| 444 | message. Clearly, "<tt class="samp">:</tt>" and "<tt class="samp">;</tt>" mutually exclude each |
| 445 | other. |
| 446 | </DD> |
| 447 | </DL> |
| 448 | |
| 449 | <P> |
| 450 | Note that any Python object references which are provided to the |
| 451 | caller are <em>borrowed</em> references; do not decrement their |
| 452 | reference count! |
| 453 | |
| 454 | <P> |
| 455 | Additional arguments passed to these functions must be addresses of |
| 456 | variables whose type is determined by the format string; these are |
| 457 | used to store values from the input tuple. There are a few cases, as |
| 458 | described in the list of format units above, where these parameters |
| 459 | are used as input values; they should match what is specified for the |
| 460 | corresponding format unit in that case. |
| 461 | |
| 462 | <P> |
| 463 | For the conversion to succeed, the <var>arg</var> object must match the |
| 464 | format and the format must be exhausted. On success, the |
| 465 | <tt class="cfunction">PyArg_Parse*()</tt> functions return true, otherwise they |
| 466 | return false and raise an appropriate exception. |
| 467 | |
| 468 | <P> |
| 469 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-208' xml:id='l2h-208' class="cfunction">PyArg_ParseTuple</tt></b>(</nobr></td><td>PyObject *<var>args</var>, char *<var>format</var>, |
| 470 | ...)</td></tr></table></dt> |
| 471 | <dd> |
| 472 | Parse the parameters of a function that takes only positional |
| 473 | parameters into local variables. Returns true on success; on |
| 474 | failure, it returns false and raises the appropriate exception. |
| 475 | </dd></dl> |
| 476 | |
| 477 | <P> |
| 478 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-209' xml:id='l2h-209' class="cfunction">PyArg_VaParse</tt></b>(</nobr></td><td>PyObject *<var>args</var>, char *<var>format</var>, |
| 479 | va_list <var>vargs</var>)</td></tr></table></dt> |
| 480 | <dd> |
| 481 | Identical to <tt class="cfunction">PyArg_ParseTuple()</tt>, except that it accepts a |
| 482 | va_list rather than a variable number of arguments. |
| 483 | </dd></dl> |
| 484 | |
| 485 | <P> |
| 486 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-210' xml:id='l2h-210' class="cfunction">PyArg_ParseTupleAndKeywords</tt></b>(</nobr></td><td>PyObject *<var>args</var>, |
| 487 | PyObject *<var>kw</var>, char *<var>format</var>, char *keywords[], |
| 488 | ...)</td></tr></table></dt> |
| 489 | <dd> |
| 490 | Parse the parameters of a function that takes both positional and |
| 491 | keyword parameters into local variables. Returns true on success; |
| 492 | on failure, it returns false and raises the appropriate exception. |
| 493 | </dd></dl> |
| 494 | |
| 495 | <P> |
| 496 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-211' xml:id='l2h-211' class="cfunction">PyArg_VaParseTupleAndKeywords</tt></b>(</nobr></td><td>PyObject *<var>args</var>, |
| 497 | PyObject *<var>kw</var>, char *<var>format</var>, char *keywords[], |
| 498 | va_list <var>vargs</var>)</td></tr></table></dt> |
| 499 | <dd> |
| 500 | Identical to <tt class="cfunction">PyArg_ParseTupleAndKeywords()</tt>, except that it |
| 501 | accepts a va_list rather than a variable number of arguments. |
| 502 | </dd></dl> |
| 503 | |
| 504 | <P> |
| 505 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-212' xml:id='l2h-212' class="cfunction">PyArg_Parse</tt></b>(</nobr></td><td>PyObject *<var>args</var>, char *<var>format</var>, |
| 506 | ...)</td></tr></table></dt> |
| 507 | <dd> |
| 508 | Function used to deconstruct the argument lists of ``old-style'' |
| 509 | functions -- these are functions which use the |
| 510 | <tt class="constant">METH_OLDARGS</tt> parameter parsing method. This is not |
| 511 | recommended for use in parameter parsing in new code, and most code |
| 512 | in the standard interpreter has been modified to no longer use this |
| 513 | for that purpose. It does remain a convenient way to decompose |
| 514 | other tuples, however, and may continue to be used for that |
| 515 | purpose. |
| 516 | </dd></dl> |
| 517 | |
| 518 | <P> |
| 519 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>int <b><tt id='l2h-213' xml:id='l2h-213' class="cfunction">PyArg_UnpackTuple</tt></b>(</nobr></td><td>PyObject *<var>args</var>, char *<var>name</var>, |
| 520 | int <var>min</var>, int <var>max</var>, ...)</td></tr></table></dt> |
| 521 | <dd> |
| 522 | A simpler form of parameter retrieval which does not use a format |
| 523 | string to specify the types of the arguments. Functions which use |
| 524 | this method to retrieve their parameters should be declared as |
| 525 | <tt class="constant">METH_VARARGS</tt> in function or method tables. The tuple |
| 526 | containing the actual parameters should be passed as <var>args</var>; it |
| 527 | must actually be a tuple. The length of the tuple must be at least |
| 528 | <var>min</var> and no more than <var>max</var>; <var>min</var> and <var>max</var> may be |
| 529 | equal. Additional arguments must be passed to the function, each of |
| 530 | which should be a pointer to a <tt class="ctype">PyObject*</tt> variable; these |
| 531 | will be filled in with the values from <var>args</var>; they will contain |
| 532 | borrowed references. The variables which correspond to optional |
| 533 | parameters not given by <var>args</var> will not be filled in; these |
| 534 | should be initialized by the caller. |
| 535 | This function returns true on success and false if <var>args</var> is not |
| 536 | a tuple or contains the wrong number of elements; an exception will |
| 537 | be set if there was a failure. |
| 538 | |
| 539 | <P> |
| 540 | This is an example of the use of this function, taken from the |
| 541 | sources for the <tt class="module">_weakref</tt> helper module for weak references: |
| 542 | |
| 543 | <P> |
| 544 | <div class="verbatim"><pre> |
| 545 | static PyObject * |
| 546 | weakref_ref(PyObject *self, PyObject *args) |
| 547 | { |
| 548 | PyObject *object; |
| 549 | PyObject *callback = NULL; |
| 550 | PyObject *result = NULL; |
| 551 | |
| 552 | if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) { |
| 553 | result = PyWeakref_NewRef(object, callback); |
| 554 | } |
| 555 | return result; |
| 556 | } |
| 557 | </pre></div> |
| 558 | |
| 559 | <P> |
| 560 | The call to <tt class="cfunction">PyArg_UnpackTuple()</tt> in this example is |
| 561 | entirely equivalent to this call to <tt class="cfunction">PyArg_ParseTuple()</tt>: |
| 562 | |
| 563 | <P> |
| 564 | <div class="verbatim"><pre> |
| 565 | PyArg_ParseTuple(args, "O|O:ref", &object, &callback) |
| 566 | </pre></div> |
| 567 | |
| 568 | <P> |
| 569 | |
| 570 | <span class="versionnote">New in version 2.2.</span> |
| 571 | |
| 572 | </dd></dl> |
| 573 | |
| 574 | <P> |
| 575 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"><td><nobr>PyObject* <b><tt id='l2h-214' xml:id='l2h-214' class="cfunction">Py_BuildValue</tt></b>(</nobr></td><td>char *<var>format</var>, |
| 576 | ...)</td></tr></table></dt> |
| 577 | <dd> |
| 578 | <div class="refcount-info"> |
| 579 | <span class="label">Return value:</span> |
| 580 | <span class="value">New reference.</span> |
| 581 | </div> |
| 582 | Create a new value based on a format string similar to those |
| 583 | accepted by the <tt class="cfunction">PyArg_Parse*()</tt> family of functions and a |
| 584 | sequence of values. Returns the value or <tt class="constant">NULL</tt> in the case of an |
| 585 | error; an exception will be raised if <tt class="constant">NULL</tt> is returned. |
| 586 | |
| 587 | <P> |
| 588 | <tt class="cfunction">Py_BuildValue()</tt> does not always build a tuple. It |
| 589 | builds a tuple only if its format string contains two or more format |
| 590 | units. If the format string is empty, it returns <code>None</code>; if it |
| 591 | contains exactly one format unit, it returns whatever object is |
| 592 | described by that format unit. To force it to return a tuple of |
| 593 | size 0 or one, parenthesize the format string. |
| 594 | |
| 595 | <P> |
| 596 | When memory buffers are passed as parameters to supply data to build |
| 597 | objects, as for the "<tt class="samp">s</tt>" and "<tt class="samp">s#</tt>" formats, the required |
| 598 | data is copied. Buffers provided by the caller are never referenced |
| 599 | by the objects created by <tt class="cfunction">Py_BuildValue()</tt>. In other |
| 600 | words, if your code invokes <tt class="cfunction">malloc()</tt> and passes the |
| 601 | allocated memory to <tt class="cfunction">Py_BuildValue()</tt>, your code is |
| 602 | responsible for calling <tt class="cfunction">free()</tt> for that memory once |
| 603 | <tt class="cfunction">Py_BuildValue()</tt> returns. |
| 604 | |
| 605 | <P> |
| 606 | In the following description, the quoted form is the format unit; |
| 607 | the entry in (round) parentheses is the Python object type that the |
| 608 | format unit will return; and the entry in [square] brackets is the |
| 609 | type of the C value(s) to be passed. |
| 610 | |
| 611 | <P> |
| 612 | The characters space, tab, colon and comma are ignored in format |
| 613 | strings (but not within format units such as "<tt class="samp">s#</tt>"). This can |
| 614 | be used to make long format strings a tad more readable. |
| 615 | |
| 616 | <P> |
| 617 | <DL> |
| 618 | <DT><STRONG>"<tt class="samp">s</tt>" (string) [char *]</STRONG></DT> |
| 619 | <DD>Convert a null-terminated C string to a Python object. If the C |
| 620 | string pointer is <tt class="constant">NULL</tt>, <code>None</code> is used. |
| 621 | |
| 622 | <P> |
| 623 | </DD> |
| 624 | <DT><STRONG>"<tt class="samp">s#</tt>" (string) [char *, int]</STRONG></DT> |
| 625 | <DD>Convert a C string and its length to a Python object. If the C |
| 626 | string pointer is <tt class="constant">NULL</tt>, the length is ignored and <code>None</code> is |
| 627 | returned. |
| 628 | |
| 629 | <P> |
| 630 | </DD> |
| 631 | <DT><STRONG>"<tt class="samp">z</tt>" (string or <code>None</code>) [char *]</STRONG></DT> |
| 632 | <DD>Same as "<tt class="samp">s</tt>". |
| 633 | |
| 634 | <P> |
| 635 | </DD> |
| 636 | <DT><STRONG>"<tt class="samp">z#</tt>" (string or <code>None</code>) [char *, int]</STRONG></DT> |
| 637 | <DD>Same as "<tt class="samp">s#</tt>". |
| 638 | |
| 639 | <P> |
| 640 | </DD> |
| 641 | <DT><STRONG>"<tt class="samp">u</tt>" (Unicode string) [Py_UNICODE *]</STRONG></DT> |
| 642 | <DD>Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) |
| 643 | data to a Python Unicode object. If the Unicode buffer pointer |
| 644 | is <tt class="constant">NULL</tt>, <code>None</code> is returned. |
| 645 | |
| 646 | <P> |
| 647 | </DD> |
| 648 | <DT><STRONG>"<tt class="samp">u#</tt>" (Unicode string) [Py_UNICODE *, int]</STRONG></DT> |
| 649 | <DD>Convert a Unicode (UCS-2 or UCS-4) data buffer and its length |
| 650 | to a Python Unicode object. If the Unicode buffer pointer |
| 651 | is <tt class="constant">NULL</tt>, the length is ignored and <code>None</code> is returned. |
| 652 | |
| 653 | <P> |
| 654 | </DD> |
| 655 | <DT><STRONG>"<tt class="samp">i</tt>" (integer) [int]</STRONG></DT> |
| 656 | <DD>Convert a plain C <tt class="ctype">int</tt> to a Python integer object. |
| 657 | |
| 658 | <P> |
| 659 | </DD> |
| 660 | <DT><STRONG>"<tt class="samp">b</tt>" (integer) [char]</STRONG></DT> |
| 661 | <DD>Same as "<tt class="samp">i</tt>". |
| 662 | |
| 663 | <P> |
| 664 | </DD> |
| 665 | <DT><STRONG>"<tt class="samp">h</tt>" (integer) [short int]</STRONG></DT> |
| 666 | <DD>Same as "<tt class="samp">i</tt>". |
| 667 | |
| 668 | <P> |
| 669 | </DD> |
| 670 | <DT><STRONG>"<tt class="samp">l</tt>" (integer) [long int]</STRONG></DT> |
| 671 | <DD>Convert a C <tt class="ctype">long int</tt> to a Python integer object. |
| 672 | |
| 673 | <P> |
| 674 | </DD> |
| 675 | <DT><STRONG>"<tt class="samp">c</tt>" (string of length 1) [char]</STRONG></DT> |
| 676 | <DD>Convert a C <tt class="ctype">int</tt> representing a character to a Python |
| 677 | string of length 1. |
| 678 | |
| 679 | <P> |
| 680 | </DD> |
| 681 | <DT><STRONG>"<tt class="samp">d</tt>" (float) [double]</STRONG></DT> |
| 682 | <DD>Convert a C <tt class="ctype">double</tt> to a Python floating point number. |
| 683 | |
| 684 | <P> |
| 685 | </DD> |
| 686 | <DT><STRONG>"<tt class="samp">f</tt>" (float) [float]</STRONG></DT> |
| 687 | <DD>Same as "<tt class="samp">d</tt>". |
| 688 | |
| 689 | <P> |
| 690 | </DD> |
| 691 | <DT><STRONG>"<tt class="samp">D</tt>" (complex) [Py_complex *]</STRONG></DT> |
| 692 | <DD>Convert a C <tt class="ctype">Py_complex</tt> structure to a Python complex |
| 693 | number. |
| 694 | |
| 695 | <P> |
| 696 | </DD> |
| 697 | <DT><STRONG>"<tt class="samp">O</tt>" (object) [PyObject *]</STRONG></DT> |
| 698 | <DD>Pass a Python object untouched (except for its reference count, |
| 699 | which is incremented by one). If the object passed in is a |
| 700 | <tt class="constant">NULL</tt> pointer, it is assumed that this was caused because the |
| 701 | call producing the argument found an error and set an exception. |
| 702 | Therefore, <tt class="cfunction">Py_BuildValue()</tt> will return <tt class="constant">NULL</tt> but |
| 703 | won't raise an exception. If no exception has been raised yet, |
| 704 | <tt class="exception">SystemError</tt> is set. |
| 705 | |
| 706 | <P> |
| 707 | </DD> |
| 708 | <DT><STRONG>"<tt class="samp">S</tt>" (object) [PyObject *]</STRONG></DT> |
| 709 | <DD>Same as "<tt class="samp">O</tt>". |
| 710 | |
| 711 | <P> |
| 712 | </DD> |
| 713 | <DT><STRONG>"<tt class="samp">N</tt>" (object) [PyObject *]</STRONG></DT> |
| 714 | <DD>Same as "<tt class="samp">O</tt>", except it doesn't increment the reference count |
| 715 | on the object. Useful when the object is created by a call to an |
| 716 | object constructor in the argument list. |
| 717 | |
| 718 | <P> |
| 719 | </DD> |
| 720 | <DT><STRONG>"<tt class="samp">O&</tt>" (object) [<var>converter</var>, <var>anything</var>]</STRONG></DT> |
| 721 | <DD>Convert <var>anything</var> to a Python object through a |
| 722 | <var>converter</var> function. The function is called with |
| 723 | <var>anything</var> (which should be compatible with <tt class="ctype">void *</tt>) as |
| 724 | its argument and should return a ``new'' Python object, or <tt class="constant">NULL</tt> |
| 725 | if an error occurred. |
| 726 | |
| 727 | <P> |
| 728 | </DD> |
| 729 | <DT><STRONG>"<tt class="samp">(<var>items</var>)</tt>" (tuple) [<var>matching-items</var>]</STRONG></DT> |
| 730 | <DD>Convert a sequence of C values to a Python tuple with the same |
| 731 | number of items. |
| 732 | |
| 733 | <P> |
| 734 | </DD> |
| 735 | <DT><STRONG>"<tt class="samp">[<var>items</var>]</tt>" (list) [<var>matching-items</var>]</STRONG></DT> |
| 736 | <DD>Convert a sequence of C values to a Python list with the same |
| 737 | number of items. |
| 738 | |
| 739 | <P> |
| 740 | </DD> |
| 741 | <DT><STRONG>"<tt class="samp">{<var>items</var>}</tt>" (dictionary) [<var>matching-items</var>]</STRONG></DT> |
| 742 | <DD>Convert a sequence of C values to a Python dictionary. Each pair |
| 743 | of consecutive C values adds one item to the dictionary, serving |
| 744 | as key and value, respectively. |
| 745 | |
| 746 | <P> |
| 747 | </DD> |
| 748 | </DL> |
| 749 | |
| 750 | <P> |
| 751 | If there is an error in the format string, the |
| 752 | <tt class="exception">SystemError</tt> exception is set and <tt class="constant">NULL</tt> returned. |
| 753 | </dd></dl> |
| 754 | |
| 755 | <DIV CLASS="navigation"> |
| 756 | <div class='online-navigation'> |
| 757 | <p></p><hr /> |
| 758 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> |
| 759 | <tr> |
| 760 | <td class='online-navigation'><a rel="prev" title="5.4 Data marshalling support" |
| 761 | href="marshalling-utils.html"><img src='../icons/previous.png' |
| 762 | border='0' height='32' alt='Previous Page' width='32' /></A></td> |
| 763 | <td class='online-navigation'><a rel="parent" title="5. Utilities" |
| 764 | href="utilities.html"><img src='../icons/up.png' |
| 765 | border='0' height='32' alt='Up One Level' width='32' /></A></td> |
| 766 | <td class='online-navigation'><a rel="next" title="6. Abstract Objects Layer" |
| 767 | href="abstract.html"><img src='../icons/next.png' |
| 768 | border='0' height='32' alt='Next Page' width='32' /></A></td> |
| 769 | <td align="center" width="100%">Python/C API Reference Manual</td> |
| 770 | <td class='online-navigation'><a rel="contents" title="Table of Contents" |
| 771 | href="contents.html"><img src='../icons/contents.png' |
| 772 | border='0' height='32' alt='Contents' width='32' /></A></td> |
| 773 | <td class='online-navigation'><img src='../icons/blank.png' |
| 774 | border='0' height='32' alt='' width='32' /></td> |
| 775 | <td class='online-navigation'><a rel="index" title="Index" |
| 776 | href="genindex.html"><img src='../icons/index.png' |
| 777 | border='0' height='32' alt='Index' width='32' /></A></td> |
| 778 | </tr></table> |
| 779 | <div class='online-navigation'> |
| 780 | <b class="navlabel">Previous:</b> |
| 781 | <a class="sectref" rel="prev" href="marshalling-utils.html">5.4 Data marshalling support</A> |
| 782 | <b class="navlabel">Up:</b> |
| 783 | <a class="sectref" rel="parent" href="utilities.html">5. Utilities</A> |
| 784 | <b class="navlabel">Next:</b> |
| 785 | <a class="sectref" rel="next" href="abstract.html">6. Abstract Objects Layer</A> |
| 786 | </div> |
| 787 | </div> |
| 788 | <hr /> |
| 789 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> |
| 790 | </DIV> |
| 791 | <!--End of Navigation Panel--> |
| 792 | <ADDRESS> |
| 793 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. |
| 794 | </ADDRESS> |
| 795 | </BODY> |
| 796 | </HTML> |