/Doc/c-api/arg.rst

  1.. highlightlang:: c
  2
  3.. _arg-parsing:
  4
  5Parsing arguments and building values
  6=====================================
  7
  8These functions are useful when creating your own extensions functions and
  9methods.  Additional information and examples are available in
 10:ref:`extending-index`.
 11
 12The first three of these functions described, :cfunc:`PyArg_ParseTuple`,
 13:cfunc:`PyArg_ParseTupleAndKeywords`, and :cfunc:`PyArg_Parse`, all use
 14*format strings* which are used to tell the function about the expected
 15arguments.  The format strings use the same syntax for each of these
 16functions.
 17
 18A format string consists of zero or more "format units."  A format unit
 19describes one Python object; it is usually a single character or a
 20parenthesized sequence of format units.  With a few exceptions, a format unit
 21that is not a parenthesized sequence normally corresponds to a single address
 22argument to these functions.  In the following description, the quoted form is
 23the format unit; the entry in (round) parentheses is the Python object type
 24that matches the format unit; and the entry in [square] brackets is the type
 25of the C variable(s) whose address should be passed.
 26
 27``s`` (string or Unicode object) [const char \*]
 28   Convert a Python string or Unicode object to a C pointer to a character
 29   string.  You must not provide storage for the string itself; a pointer to
 30   an existing string is stored into the character pointer variable whose
 31   address you pass.  The C string is NUL-terminated.  The Python string must
 32   not contain embedded NUL bytes; if it does, a :exc:`TypeError` exception is
 33   raised. Unicode objects are converted to C strings using the default
 34   encoding.  If this conversion fails, a :exc:`UnicodeError` is raised.
 35
 36``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int (or :ctype:`Py_ssize_t`, see below)]
 37   This variant on ``s`` stores into two C variables, the first one a pointer
 38   to a character string, the second one its length.  In this case the Python
 39   string may contain embedded null bytes.  Unicode objects pass back a
 40   pointer to the default encoded string version of the object if such a
 41   conversion is possible.  All other read-buffer compatible objects pass back
 42   a reference to the raw internal data representation.
 43
 44   Starting with Python 2.5 the type of the length argument can be controlled
 45   by defining the macro :cmacro:`PY_SSIZE_T_CLEAN` before including
 46   :file:`Python.h`.  If the macro is defined, length is a :ctype:`Py_ssize_t`
 47   rather than an int.
 48
 49``s*`` (string, Unicode, or any buffer compatible object) [Py_buffer \*]
 50   Similar to ``s#``, this code fills a Py_buffer structure provided by the
 51   caller.  The buffer gets locked, so that the caller can subsequently use
 52   the buffer even inside a ``Py_BEGIN_ALLOW_THREADS`` block; the caller is
 53   responsible for calling ``PyBuffer_Release`` with the structure after it
 54   has processed the data.
 55
 56   .. versionadded:: 2.6
 57
 58``z`` (string or ``None``) [const char \*]
 59   Like ``s``, but the Python object may also be ``None``, in which case the C
 60   pointer is set to *NULL*.
 61
 62``z#`` (string or ``None`` or any read buffer compatible object) [const char \*, int]
 63   This is to ``s#`` as ``z`` is to ``s``.
 64
 65``z*`` (string or ``None`` or any buffer compatible object) [Py_buffer*]
 66   This is to ``s*`` as ``z`` is to ``s``.
 67
 68   .. versionadded:: 2.6
 69
 70``u`` (Unicode object) [Py_UNICODE \*]
 71   Convert a Python Unicode object to a C pointer to a NUL-terminated buffer
 72   of 16-bit Unicode (UTF-16) data.  As with ``s``, there is no need to
 73   provide storage for the Unicode data buffer; a pointer to the existing
 74   Unicode data is stored into the :ctype:`Py_UNICODE` pointer variable whose
 75   address you pass.
 76
 77``u#`` (Unicode object) [Py_UNICODE \*, int]
 78   This variant on ``u`` stores into two C variables, the first one a pointer
 79   to a Unicode data buffer, the second one its length. Non-Unicode objects
 80   are handled by interpreting their read-buffer pointer as pointer to a
 81   :ctype:`Py_UNICODE` array.
 82
 83``es`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
 84   This variant on ``s`` is used for encoding Unicode and objects convertible
 85   to Unicode into a character buffer. It only works for encoded data without
 86   embedded NUL bytes.
 87
 88   This format requires two arguments.  The first is only used as input, and
 89   must be a :ctype:`const char\*` which points to the name of an encoding as
 90   a NUL-terminated string, or *NULL*, in which case the default encoding is
 91   used.  An exception is raised if the named encoding is not known to Python.
 92   The second argument must be a :ctype:`char\*\*`; the value of the pointer
 93   it references will be set to a buffer with the contents of the argument
 94   text.  The text will be encoded in the encoding specified by the first
 95   argument.
 96
 97   :cfunc:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy
 98   the encoded data into this buffer and adjust *\*buffer* to reference the
 99   newly allocated storage.  The caller is responsible for calling
100   :cfunc:`PyMem_Free` to free the allocated buffer after use.
101
102``et`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
103   Same as ``es`` except that 8-bit string objects are passed through without
104   recoding them.  Instead, the implementation assumes that the string object
105   uses the encoding passed in as parameter.
106
107``es#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length]
108   This variant on ``s#`` is used for encoding Unicode and objects convertible
109   to Unicode into a character buffer.  Unlike the ``es`` format, this variant
110   allows input data which contains NUL characters.
111
112   It requires three arguments.  The first is only used as input, and must be
113   a :ctype:`const char\*` which points to the name of an encoding as a
114   NUL-terminated string, or *NULL*, in which case the default encoding is
115   used.  An exception is raised if the named encoding is not known to Python.
116   The second argument must be a :ctype:`char\*\*`; the value of the pointer
117   it references will be set to a buffer with the contents of the argument
118   text.  The text will be encoded in the encoding specified by the first
119   argument.  The third argument must be a pointer to an integer; the
120   referenced integer will be set to the number of bytes in the output buffer.
121
122   There are two modes of operation:
123
124   If *\*buffer* points a *NULL* pointer, the function will allocate a buffer
125   of the needed size, copy the encoded data into this buffer and set
126   *\*buffer* to reference the newly allocated storage.  The caller is
127   responsible for calling :cfunc:`PyMem_Free` to free the allocated buffer
128   after usage.
129
130   If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer),
131   :cfunc:`PyArg_ParseTuple` will use this location as the buffer and
132   interpret the initial value of *\*buffer_length* as the buffer size.  It
133   will then copy the encoded data into the buffer and NUL-terminate it.  If
134   the buffer is not large enough, a :exc:`ValueError` will be set.
135
136   In both cases, *\*buffer_length* is set to the length of the encoded data
137   without the trailing NUL byte.
138
139``et#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer]
140   Same as ``es#`` except that string objects are passed through without
141   recoding them. Instead, the implementation assumes that the string object
142   uses the encoding passed in as parameter.
143
144``b`` (integer) [unsigned char]
145   Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
146   :ctype:`unsigned char`.
147
148``B`` (integer) [unsigned char]
149   Convert a Python integer to a tiny int without overflow checking, stored in
150   a C :ctype:`unsigned char`.
151
152   .. versionadded:: 2.3
153
154``h`` (integer) [short int]
155   Convert a Python integer to a C :ctype:`short int`.
156
157``H`` (integer) [unsigned short int]
158   Convert a Python integer to a C :ctype:`unsigned short int`, without
159   overflow checking.
160
161   .. versionadded:: 2.3
162
163``i`` (integer) [int]
164   Convert a Python integer to a plain C :ctype:`int`.
165
166``I`` (integer) [unsigned int]
167   Convert a Python integer to a C :ctype:`unsigned int`, without overflow
168   checking.
169
170   .. versionadded:: 2.3
171
172``l`` (integer) [long int]
173   Convert a Python integer to a C :ctype:`long int`.
174
175``k`` (integer) [unsigned long]
176   Convert a Python integer or long integer to a C :ctype:`unsigned long`
177   without overflow checking.
178
179   .. versionadded:: 2.3
180
181``L`` (integer) [PY_LONG_LONG]
182   Convert a Python integer to a C :ctype:`long long`.  This format is only
183   available on platforms that support :ctype:`long long` (or :ctype:`_int64`
184   on Windows).
185
186``K`` (integer) [unsigned PY_LONG_LONG]
187   Convert a Python integer or long integer to a C :ctype:`unsigned long long`
188   without overflow checking.  This format is only available on platforms that
189   support :ctype:`unsigned long long` (or :ctype:`unsigned _int64` on
190   Windows).
191
192   .. versionadded:: 2.3
193
194``n`` (integer) [Py_ssize_t]
195   Convert a Python integer or long integer to a C :ctype:`Py_ssize_t`.
196
197   .. versionadded:: 2.5
198
199``c`` (string of length 1) [char]
200   Convert a Python character, represented as a string of length 1, to a C
201   :ctype:`char`.
202
203``f`` (float) [float]
204   Convert a Python floating point number to a C :ctype:`float`.
205
206``d`` (float) [double]
207   Convert a Python floating point number to a C :ctype:`double`.
208
209``D`` (complex) [Py_complex]
210   Convert a Python complex number to a C :ctype:`Py_complex` structure.
211
212``O`` (object) [PyObject \*]
213   Store a Python object (without any conversion) in a C object pointer.  The
214   C program thus receives the actual object that was passed.  The object's
215   reference count is not increased.  The pointer stored is not *NULL*.
216
217``O!`` (object) [*typeobject*, PyObject \*]
218   Store a Python object in a C object pointer.  This is similar to ``O``, but
219   takes two C arguments: the first is the address of a Python type object,
220   the second is the address of the C variable (of type :ctype:`PyObject\*`)
221   into which the object pointer is stored.  If the Python object does not
222   have the required type, :exc:`TypeError` is raised.
223
224``O&`` (object) [*converter*, *anything*]
225   Convert a Python object to a C variable through a *converter* function.
226   This takes two arguments: the first is a function, the second is the
227   address of a C variable (of arbitrary type), converted to :ctype:`void \*`.
228   The *converter* function in turn is called as follows::
229
230      status = converter(object, address);
231
232   where *object* is the Python object to be converted and *address* is the
233   :ctype:`void\*` argument that was passed to the :cfunc:`PyArg_Parse\*`
234   function.  The returned *status* should be ``1`` for a successful
235   conversion and ``0`` if the conversion has failed.  When the conversion
236   fails, the *converter* function should raise an exception and leave the
237   content of *address* unmodified.
238
239``S`` (string) [PyStringObject \*]
240   Like ``O`` but requires that the Python object is a string object.  Raises
241   :exc:`TypeError` if the object is not a string object.  The C variable may
242   also be declared as :ctype:`PyObject\*`.
243
244``U`` (Unicode string) [PyUnicodeObject \*]
245   Like ``O`` but requires that the Python object is a Unicode object.  Raises
246   :exc:`TypeError` if the object is not a Unicode object.  The C variable may
247   also be declared as :ctype:`PyObject\*`.
248
249``t#`` (read-only character buffer) [char \*, int]
250   Like ``s#``, but accepts any object which implements the read-only buffer
251   interface.  The :ctype:`char\*` variable is set to point to the first byte
252   of the buffer, and the :ctype:`int` is set to the length of the buffer.
253   Only single-segment buffer objects are accepted; :exc:`TypeError` is raised
254   for all others.
255
256``w`` (read-write character buffer) [char \*]
257   Similar to ``s``, but accepts any object which implements the read-write
258   buffer interface.  The caller must determine the length of the buffer by
259   other means, or use ``w#`` instead.  Only single-segment buffer objects are
260   accepted; :exc:`TypeError` is raised for all others.
261
262``w#`` (read-write character buffer) [char \*, Py_ssize_t]
263   Like ``s#``, but accepts any object which implements the read-write buffer
264   interface.  The :ctype:`char \*` variable is set to point to the first byte
265   of the buffer, and the :ctype:`Py_ssize_t` is set to the length of the
266   buffer.  Only single-segment buffer objects are accepted; :exc:`TypeError`
267   is raised for all others.
268
269``w*`` (read-write byte-oriented buffer) [Py_buffer \*]
270   This is to ``w`` what ``s*`` is to ``s``.
271
272   .. versionadded:: 2.6
273
274``(items)`` (tuple) [*matching-items*]
275   The object must be a Python sequence whose length is the number of format
276   units in *items*.  The C arguments must correspond to the individual format
277   units in *items*.  Format units for sequences may be nested.
278
279   .. note::
280
281      Prior to Python version 1.5.2, this format specifier only accepted a
282      tuple containing the individual parameters, not an arbitrary sequence.
283      Code which previously caused :exc:`TypeError` to be raised here may now
284      proceed without an exception.  This is not expected to be a problem for
285      existing code.
286
287It is possible to pass Python long integers where integers are requested;
288however no proper range checking is done --- the most significant bits are
289silently truncated when the receiving field is too small to receive the value
290(actually, the semantics are inherited from downcasts in C --- your mileage
291may vary).
292
293A few other characters have a meaning in a format string.  These may not occur
294inside nested parentheses.  They are:
295
296``|``
297   Indicates that the remaining arguments in the Python argument list are
298   optional.  The C variables corresponding to optional arguments should be
299   initialized to their default value --- when an optional argument is not
300   specified, :cfunc:`PyArg_ParseTuple` does not touch the contents of the
301   corresponding C variable(s).
302
303``:``
304   The list of format units ends here; the string after the colon is used as
305   the function name in error messages (the "associated value" of the
306   exception that :cfunc:`PyArg_ParseTuple` raises).
307
308``;``
309   The list of format units ends here; the string after the semicolon is used
310   as the error message *instead* of the default error message.  ``:`` and
311   ``;`` mutually exclude each other.
312
313Note that any Python object references which are provided to the caller are
314*borrowed* references; do not decrement their reference count!
315
316Additional arguments passed to these functions must be addresses of variables
317whose type is determined by the format string; these are used to store values
318from the input tuple.  There are a few cases, as described in the list of
319format units above, where these parameters are used as input values; they
320should match what is specified for the corresponding format unit in that case.
321
322For the conversion to succeed, the *arg* object must match the format and the
323format must be exhausted.  On success, the :cfunc:`PyArg_Parse\*` functions
324return true, otherwise they return false and raise an appropriate exception.
325When the :cfunc:`PyArg_Parse\*` functions fail due to conversion failure in
326one of the format units, the variables at the addresses corresponding to that
327and the following format units are left untouched.
328
329
330.. cfunction:: int PyArg_ParseTuple(PyObject *args, const char *format, ...)
331
332   Parse the parameters of a function that takes only positional parameters
333   into local variables.  Returns true on success; on failure, it returns
334   false and raises the appropriate exception.
335
336
337.. cfunction:: int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)
338
339   Identical to :cfunc:`PyArg_ParseTuple`, except that it accepts a va_list
340   rather than a variable number of arguments.
341
342
343.. cfunction:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)
344
345   Parse the parameters of a function that takes both positional and keyword
346   parameters into local variables.  Returns true on success; on failure, it
347   returns false and raises the appropriate exception.
348
349
350.. cfunction:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)
351
352   Identical to :cfunc:`PyArg_ParseTupleAndKeywords`, except that it accepts a
353   va_list rather than a variable number of arguments.
354
355
356.. cfunction:: int PyArg_Parse(PyObject *args, const char *format, ...)
357
358   Function used to deconstruct the argument lists of "old-style" functions
359   --- these are functions which use the :const:`METH_OLDARGS` parameter
360   parsing method.  This is not recommended for use in parameter parsing in
361   new code, and most code in the standard interpreter has been modified to no
362   longer use this for that purpose.  It does remain a convenient way to
363   decompose other tuples, however, and may continue to be used for that
364   purpose.
365
366
367.. cfunction:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
368
369   A simpler form of parameter retrieval which does not use a format string to
370   specify the types of the arguments.  Functions which use this method to
371   retrieve their parameters should be declared as :const:`METH_VARARGS` in
372   function or method tables.  The tuple containing the actual parameters
373   should be passed as *args*; it must actually be a tuple.  The length of the
374   tuple must be at least *min* and no more than *max*; *min* and *max* may be
375   equal.  Additional arguments must be passed to the function, each of which
376   should be a pointer to a :ctype:`PyObject\*` variable; these will be filled
377   in with the values from *args*; they will contain borrowed references.  The
378   variables which correspond to optional parameters not given by *args* will
379   not be filled in; these should be initialized by the caller. This function
380   returns true on success and false if *args* is not a tuple or contains the
381   wrong number of elements; an exception will be set if there was a failure.
382
383   This is an example of the use of this function, taken from the sources for
384   the :mod:`_weakref` helper module for weak references::
385
386      static PyObject *
387      weakref_ref(PyObject *self, PyObject *args)
388      {
389          PyObject *object;
390          PyObject *callback = NULL;
391          PyObject *result = NULL;
392
393          if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
394              result = PyWeakref_NewRef(object, callback);
395          }
396          return result;
397      }
398
399   The call to :cfunc:`PyArg_UnpackTuple` in this example is entirely
400   equivalent to this call to :cfunc:`PyArg_ParseTuple`::
401
402      PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
403
404   .. versionadded:: 2.2
405
406   .. versionchanged:: 2.5
407      This function used an :ctype:`int` type for *min* and *max*. This might
408      require changes in your code for properly supporting 64-bit systems.
409
410
411.. cfunction:: PyObject* Py_BuildValue(const char *format, ...)
412
413   Create a new value based on a format string similar to those accepted by
414   the :cfunc:`PyArg_Parse\*` family of functions and a sequence of values.
415   Returns the value or *NULL* in the case of an error; an exception will be
416   raised if *NULL* is returned.
417
418   :cfunc:`Py_BuildValue` does not always build a tuple.  It builds a tuple
419   only if its format string contains two or more format units.  If the format
420   string is empty, it returns ``None``; if it contains exactly one format
421   unit, it returns whatever object is described by that format unit.  To
422   force it to return a tuple of size 0 or one, parenthesize the format
423   string.
424
425   When memory buffers are passed as parameters to supply data to build
426   objects, as for the ``s`` and ``s#`` formats, the required data is copied.
427   Buffers provided by the caller are never referenced by the objects created
428   by :cfunc:`Py_BuildValue`.  In other words, if your code invokes
429   :cfunc:`malloc` and passes the allocated memory to :cfunc:`Py_BuildValue`,
430   your code is responsible for calling :cfunc:`free` for that memory once
431   :cfunc:`Py_BuildValue` returns.
432
433   In the following description, the quoted form is the format unit; the entry
434   in (round) parentheses is the Python object type that the format unit will
435   return; and the entry in [square] brackets is the type of the C value(s) to
436   be passed.
437
438   The characters space, tab, colon and comma are ignored in format strings
439   (but not within format units such as ``s#``).  This can be used to make
440   long format strings a tad more readable.
441
442   ``s`` (string) [char \*]
443      Convert a null-terminated C string to a Python object.  If the C string
444      pointer is *NULL*, ``None`` is used.
445
446   ``s#`` (string) [char \*, int]
447      Convert a C string and its length to a Python object.  If the C string
448      pointer is *NULL*, the length is ignored and ``None`` is returned.
449
450   ``z`` (string or ``None``) [char \*]
451      Same as ``s``.
452
453   ``z#`` (string or ``None``) [char \*, int]
454      Same as ``s#``.
455
456   ``u`` (Unicode string) [Py_UNICODE \*]
457      Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a
458      Python Unicode object.  If the Unicode buffer pointer is *NULL*,
459      ``None`` is returned.
460
461   ``u#`` (Unicode string) [Py_UNICODE \*, int]
462      Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a
463      Python Unicode object.   If the Unicode buffer pointer is *NULL*, the
464      length is ignored and ``None`` is returned.
465
466   ``i`` (integer) [int]
467      Convert a plain C :ctype:`int` to a Python integer object.
468
469   ``b`` (integer) [char]
470      Convert a plain C :ctype:`char` to a Python integer object.
471
472   ``h`` (integer) [short int]
473      Convert a plain C :ctype:`short int` to a Python integer object.
474
475   ``l`` (integer) [long int]
476      Convert a C :ctype:`long int` to a Python integer object.
477
478   ``B`` (integer) [unsigned char]
479      Convert a C :ctype:`unsigned char` to a Python integer object.
480
481   ``H`` (integer) [unsigned short int]
482      Convert a C :ctype:`unsigned short int` to a Python integer object.
483
484   ``I`` (integer/long) [unsigned int]
485      Convert a C :ctype:`unsigned int` to a Python integer object or a Python
486      long integer object, if it is larger than ``sys.maxint``.
487
488   ``k`` (integer/long) [unsigned long]
489      Convert a C :ctype:`unsigned long` to a Python integer object or a
490      Python long integer object, if it is larger than ``sys.maxint``.
491
492   ``L`` (long) [PY_LONG_LONG]
493      Convert a C :ctype:`long long` to a Python long integer object. Only
494      available on platforms that support :ctype:`long long`.
495
496   ``K`` (long) [unsigned PY_LONG_LONG]
497      Convert a C :ctype:`unsigned long long` to a Python long integer object.
498      Only available on platforms that support :ctype:`unsigned long long`.
499
500   ``n`` (int) [Py_ssize_t]
501      Convert a C :ctype:`Py_ssize_t` to a Python integer or long integer.
502
503      .. versionadded:: 2.5
504
505   ``c`` (string of length 1) [char]
506      Convert a C :ctype:`int` representing a character to a Python string of
507      length 1.
508
509   ``d`` (float) [double]
510      Convert a C :ctype:`double` to a Python floating point number.
511
512   ``f`` (float) [float]
513      Same as ``d``.
514
515   ``D`` (complex) [Py_complex \*]
516      Convert a C :ctype:`Py_complex` structure to a Python complex number.
517
518   ``O`` (object) [PyObject \*]
519      Pass a Python object untouched (except for its reference count, which is
520      incremented by one).  If the object passed in is a *NULL* pointer, it is
521      assumed that this was caused because the call producing the argument
522      found an error and set an exception. Therefore, :cfunc:`Py_BuildValue`
523      will return *NULL* but won't raise an exception.  If no exception has
524      been raised yet, :exc:`SystemError` is set.
525
526   ``S`` (object) [PyObject \*]
527      Same as ``O``.
528
529   ``N`` (object) [PyObject \*]
530      Same as ``O``, except it doesn't increment the reference count on the
531      object.  Useful when the object is created by a call to an object
532      constructor in the argument list.
533
534   ``O&`` (object) [*converter*, *anything*]
535      Convert *anything* to a Python object through a *converter* function.
536      The function is called with *anything* (which should be compatible with
537      :ctype:`void \*`) as its argument and should return a "new" Python
538      object, or *NULL* if an error occurred.
539
540   ``(items)`` (tuple) [*matching-items*]
541      Convert a sequence of C values to a Python tuple with the same number of
542      items.
543
544   ``[items]`` (list) [*matching-items*]
545      Convert a sequence of C values to a Python list with the same number of
546      items.
547
548   ``{items}`` (dictionary) [*matching-items*]
549      Convert a sequence of C values to a Python dictionary.  Each pair of
550      consecutive C values adds one item to the dictionary, serving as key and
551      value, respectively.
552
553   If there is an error in the format string, the :exc:`SystemError` exception
554   is set and *NULL* returned.
555
556.. cfunction:: PyObject* Py_VaBuildValue(const char *format, va_list vargs)
557
558   Identical to :cfunc:`Py_BuildValue`, except that it accepts a va_list
559   rather than a variable number of arguments.