Doc/c-api/arg.rst

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