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
  14 *format strings* which are used to tell the function about the expected
  15 arguments.  The format strings use the same syntax for each of these
  16 functions.
  17
  18 A format string consists of zero or more "format units."  A format unit
  19 describes one Python object; it is usually a single character or a
  20 parenthesized sequence of format units.  With a few exceptions, a format unit
  21 that is not a parenthesized sequence normally corresponds to a single address
  22 argument to these functions.  In the following description, the quoted form is
  23 the format unit; the entry in (round) parentheses is the Python object type
  24 that matches the format unit; and the entry in [square] brackets is the type
  25 of 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, int \*buffer_length]
 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
 287 It is possible to pass Python long integers where integers are requested;
 288 however no proper range checking is done --- the most significant bits are
 289 silently truncated when the receiving field is too small to receive the value
 290 (actually, the semantics are inherited from downcasts in C --- your mileage
 291 may vary).
 292
 293 A few other characters have a meaning in a format string.  These may not occur
 294 inside 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
 313 Note that any Python object references which are provided to the caller are
 314 *borrowed* references; do not decrement their reference count!
 315
 316 Additional arguments passed to these functions must be addresses of variables
 317 whose type is determined by the format string; these are used to store values
 318 from the input tuple.  There are a few cases, as described in the list of
 319 format units above, where these parameters are used as input values; they
 320 should match what is specified for the corresponding format unit in that case.
 321
 322 For the conversion to succeed, the *arg* object must match the format and the
 323 format must be exhausted.  On success, the :cfunc:`PyArg_Parse\*` functions
 324 return true, otherwise they return false and raise an appropriate exception.
 325 When the :cfunc:`PyArg_Parse\*` functions fail due to conversion failure in
 326 one of the format units, the variables at the addresses corresponding to that
 327 and 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.