Commit | Line | Data |
---|---|---|
920dae64 AT |
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> |