| .. highlightlang:: c |
| |
| .. _arg-parsing: |
| |
| Parsing arguments and building values |
| ===================================== |
| |
| These functions are useful when creating your own extensions functions and |
| methods. Additional information and examples are available in |
| :ref:`extending-index`. |
| |
| The first three of these functions described, :cfunc:`PyArg_ParseTuple`, |
| :cfunc:`PyArg_ParseTupleAndKeywords`, and :cfunc:`PyArg_Parse`, all use *format |
| strings* which are used to tell the function about the expected arguments. The |
| format strings use the same syntax for each of these functions. |
| |
| ----------------- |
| Parsing arguments |
| ----------------- |
| |
| A format string consists of zero or more "format units." A format unit |
| describes one Python object; it is usually a single character or a parenthesized |
| sequence of format units. With a few exceptions, a format unit that is not a |
| parenthesized sequence normally corresponds to a single address argument to |
| these functions. In the following description, the quoted form is the format |
| unit; the entry in (round) parentheses is the Python object type that matches |
| the format unit; and the entry in [square] brackets is the type of the C |
| variable(s) whose address should be passed. |
| |
| Strings and buffers |
| ------------------- |
| |
| These formats do not expect you to provide raw storage for the returned string |
| or bytes. Also, you won't have to release any memory yourself, except with |
| the ``es``, ``es#``, ``et`` and ``et#`` formats. |
| |
| However, when a :ctype:`Py_buffer` structure gets filled, the underlying |
| buffer is locked so that the caller can subsequently use the buffer even |
| inside a :ctype:`Py_BEGIN_ALLOW_THREADS` block without the risk of mutable data |
| being resized or destroyed. As a result, **you have to call** |
| :cfunc:`PyBuffer_Release` after you have finished processing the data (or |
| in any early abort case). |
| |
| Unless otherwise stated, buffers are not NUL-terminated. |
| |
| .. note:: |
| For all ``#`` variants of formats (``s#``, ``y#``, etc.), the type of |
| the length argument (int or :ctype:`Py_ssize_t`) is controlled by |
| defining the macro :cmacro:`PY_SSIZE_T_CLEAN` before including |
| :file:`Python.h`. If the macro was defined, length is a |
| :ctype:`Py_ssize_t` rather than an :ctype:`int`. This behavior will change |
| in a future Python version to only support :ctype:`Py_ssize_t` and |
| drop :ctype:`int` support. It is best to always define :cmacro:`PY_SSIZE_T_CLEAN`. |
| |
| |
| ``s`` (:class:`str`) [const char \*] |
| Convert a Unicode object to a C pointer to a character string. |
| A pointer to an existing string is stored in the character pointer |
| variable whose address you pass. The C string is NUL-terminated. |
| The Python string must not contain embedded NUL bytes; if it does, |
| a :exc:`TypeError` exception is raised. Unicode objects are converted |
| to C strings using ``'utf-8'`` encoding. If this conversion fails, a |
| :exc:`UnicodeError` is raised. |
| |
| .. note:: |
| This format does not accept bytes-like objects. If you want to accept |
| filesystem paths and convert them to C character strings, it is |
| preferable to use the ``O&`` format with :cfunc:`PyUnicode_FSConverter` |
| as *converter*. |
| |
| ``s*`` (:class:`str`, :class:`bytes`, :class:`bytearray` or buffer compatible object) [Py_buffer] |
| This format accepts Unicode objects as well as objects supporting the |
| buffer protocol. |
| It fills a :ctype:`Py_buffer` structure provided by the caller. |
| In this case the resulting C string may contain embedded NUL bytes. |
| Unicode objects are converted to C strings using ``'utf-8'`` encoding. |
| |
| ``s#`` (:class:`str`, :class:`bytes` or read-only buffer compatible object) [const char \*, int or :ctype:`Py_ssize_t`] |
| Like ``s*``, except that it doesn't accept mutable buffer-like objects |
| such as :class:`bytearray`. The result is stored into two C variables, |
| the first one a pointer to a C string, the second one its length. |
| The string may contain embedded null bytes. Unicode objects are converted |
| to C strings using ``'utf-8'`` encoding. |
| |
| ``z`` (:class:`str` or ``None``) [const char \*] |
| Like ``s``, but the Python object may also be ``None``, in which case the C |
| pointer is set to *NULL*. |
| |
| ``z*`` (:class:`str`, :class:`bytes`, :class:`bytearray`, buffer compatible object or ``None``) [Py_buffer] |
| Like ``s*``, but the Python object may also be ``None``, in which case the |
| ``buf`` member of the :ctype:`Py_buffer` structure is set to *NULL*. |
| |
| ``z#`` (:class:`str`, :class:`bytes`, read-only buffer compatible object or ``None``) [const char \*, int] |
| Like ``s#``, but the Python object may also be ``None``, in which case the C |
| pointer is set to *NULL*. |
| |
| ``y`` (:class:`bytes`) [const char \*] |
| This format converts a bytes-like object to a C pointer to a character |
| string; it does not accept Unicode objects. The bytes buffer must not |
| contain embedded NUL bytes; if it does, a :exc:`TypeError` |
| exception is raised. |
| |
| ``y*`` (:class:`bytes`, :class:`bytearray` or buffer compatible object) [Py_buffer] |
| This variant on ``s*`` doesn't accept Unicode objects, only objects |
| supporting the buffer protocol. **This is the recommended way to accept |
| binary data.** |
| |
| ``y#`` (:class:`bytes`) [const char \*, int] |
| This variant on ``s#`` doesn't accept Unicode objects, only bytes-like |
| objects. |
| |
| ``S`` (:class:`bytes`) [PyBytesObject \*] |
| Requires that the Python object is a :class:`bytes` object, without |
| attempting any conversion. Raises :exc:`TypeError` if the object is not |
| a bytes object. The C variable may also be declared as :ctype:`PyObject\*`. |
| |
| ``Y`` (:class:`bytearray`) [PyByteArrayObject \*] |
| Requires that the Python object is a :class:`bytearray` object, without |
| attempting any conversion. Raises :exc:`TypeError` if the object is not |
| a :class:`bytearray` object. The C variable may also be declared as :ctype:`PyObject\*`. |
| |
| ``u`` (:class:`str`) [Py_UNICODE \*] |
| Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of |
| Unicode characters. You must pass the address of a :ctype:`Py_UNICODE` |
| pointer variable, which will be filled with the pointer to an existing |
| Unicode buffer. Please note that the width of a :ctype:`Py_UNICODE` |
| character depends on compilation options (it is either 16 or 32 bits). |
| The Python string must not contain embedded NUL characters; if it does, |
| a :exc:`TypeError` exception is raised. |
| |
| .. note:: |
| Since ``u`` doesn't give you back the length of the string, and it |
| may contain embedded NUL characters, it is recommended to use ``u#`` |
| or ``U`` instead. |
| |
| ``u#`` (:class:`str`) [Py_UNICODE \*, int] |
| This variant on ``u`` stores into two C variables, the first one a pointer to a |
| Unicode data buffer, the second one its length. |
| |
| ``Z`` (:class:`str` or ``None``) [Py_UNICODE \*] |
| Like ``u``, but the Python object may also be ``None``, in which case the |
| :ctype:`Py_UNICODE` pointer is set to *NULL*. |
| |
| ``Z#`` (:class:`str` or ``None``) [Py_UNICODE \*, int] |
| Like ``u#``, but the Python object may also be ``None``, in which case the |
| :ctype:`Py_UNICODE` pointer is set to *NULL*. |
| |
| ``U`` (:class:`str`) [PyUnicodeObject \*] |
| Requires that the Python object is a Unicode object, without attempting |
| any conversion. Raises :exc:`TypeError` if the object is not a Unicode |
| object. The C variable may also be declared as :ctype:`PyObject\*`. |
| |
| ``w*`` (:class:`bytearray` or read-write byte-oriented buffer) [Py_buffer] |
| This format accepts any object which implements the read-write buffer |
| interface. It fills a :ctype:`Py_buffer` structure provided by the caller. |
| The buffer may contain embedded null bytes. The caller have to call |
| :cfunc:`PyBuffer_Release` when it is done with the buffer. |
| |
| ``es`` (:class:`str`) [const char \*encoding, char \*\*buffer] |
| This variant on ``s`` is used for encoding Unicode into a character buffer. |
| It only works for encoded data without embedded NUL bytes. |
| |
| This format requires two arguments. The first is only used as input, and |
| must be a :ctype:`const char\*` which points to the name of an encoding as a |
| NUL-terminated string, or *NULL*, in which case ``'utf-8'`` encoding is used. |
| An exception is raised if the named encoding is not known to Python. The |
| second argument must be a :ctype:`char\*\*`; the value of the pointer it |
| references will be set to a buffer with the contents of the argument text. |
| The text will be encoded in the encoding specified by the first argument. |
| |
| :cfunc:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy the |
| encoded data into this buffer and adjust *\*buffer* to reference the newly |
| allocated storage. The caller is responsible for calling :cfunc:`PyMem_Free` to |
| free the allocated buffer after use. |
| |
| ``et`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char \*encoding, char \*\*buffer] |
| Same as ``es`` except that byte string objects are passed through without |
| recoding them. Instead, the implementation assumes that the byte string object uses |
| the encoding passed in as parameter. |
| |
| ``es#`` (:class:`str`) [const char \*encoding, char \*\*buffer, int \*buffer_length] |
| This variant on ``s#`` is used for encoding Unicode into a character buffer. |
| Unlike the ``es`` format, this variant allows input data which contains NUL |
| characters. |
| |
| It requires three arguments. The first is only used as input, and must be a |
| :ctype:`const char\*` which points to the name of an encoding as a |
| NUL-terminated string, or *NULL*, in which case ``'utf-8'`` encoding is used. |
| An exception is raised if the named encoding is not known to Python. The |
| second argument must be a :ctype:`char\*\*`; the value of the pointer it |
| references will be set to a buffer with the contents of the argument text. |
| The text will be encoded in the encoding specified by the first argument. |
| The third argument must be a pointer to an integer; the referenced integer |
| will be set to the number of bytes in the output buffer. |
| |
| There are two modes of operation: |
| |
| If *\*buffer* points a *NULL* pointer, the function will allocate a buffer of |
| the needed size, copy the encoded data into this buffer and set *\*buffer* to |
| reference the newly allocated storage. The caller is responsible for calling |
| :cfunc:`PyMem_Free` to free the allocated buffer after usage. |
| |
| If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer), |
| :cfunc:`PyArg_ParseTuple` will use this location as the buffer and interpret the |
| initial value of *\*buffer_length* as the buffer size. It will then copy the |
| encoded data into the buffer and NUL-terminate it. If the buffer is not large |
| enough, a :exc:`ValueError` will be set. |
| |
| In both cases, *\*buffer_length* is set to the length of the encoded data |
| without the trailing NUL byte. |
| |
| ``et#`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char \*encoding, char \*\*buffer, int \*buffer_length] |
| Same as ``es#`` except that byte string objects are passed through without recoding |
| them. Instead, the implementation assumes that the byte string object uses the |
| encoding passed in as parameter. |
| |
| Numbers |
| ------- |
| |
| ``b`` (:class:`int`) [unsigned char] |
| Convert a nonnegative Python integer to an unsigned tiny int, stored in a C |
| :ctype:`unsigned char`. |
| |
| ``B`` (:class:`int`) [unsigned char] |
| Convert a Python integer to a tiny int without overflow checking, stored in a C |
| :ctype:`unsigned char`. |
| |
| ``h`` (:class:`int`) [short int] |
| Convert a Python integer to a C :ctype:`short int`. |
| |
| ``H`` (:class:`int`) [unsigned short int] |
| Convert a Python integer to a C :ctype:`unsigned short int`, without overflow |
| checking. |
| |
| ``i`` (:class:`int`) [int] |
| Convert a Python integer to a plain C :ctype:`int`. |
| |
| ``I`` (:class:`int`) [unsigned int] |
| Convert a Python integer to a C :ctype:`unsigned int`, without overflow |
| checking. |
| |
| ``l`` (:class:`int`) [long int] |
| Convert a Python integer to a C :ctype:`long int`. |
| |
| ``k`` (:class:`int`) [unsigned long] |
| Convert a Python integer to a C :ctype:`unsigned long` without |
| overflow checking. |
| |
| ``L`` (:class:`int`) [PY_LONG_LONG] |
| Convert a Python integer to a C :ctype:`long long`. This format is only |
| available on platforms that support :ctype:`long long` (or :ctype:`_int64` on |
| Windows). |
| |
| ``K`` (:class:`int`) [unsigned PY_LONG_LONG] |
| Convert a Python integer to a C :ctype:`unsigned long long` |
| without overflow checking. This format is only available on platforms that |
| support :ctype:`unsigned long long` (or :ctype:`unsigned _int64` on Windows). |
| |
| ``n`` (:class:`int`) [Py_ssize_t] |
| Convert a Python integer to a C :ctype:`Py_ssize_t`. |
| |
| ``c`` (:class:`bytes` of length 1) [char] |
| Convert a Python byte, represented as a :class:`bytes` object of length 1, |
| to a C :ctype:`char`. |
| |
| ``C`` (:class:`str` of length 1) [int] |
| Convert a Python character, represented as a :class:`str` object of |
| length 1, to a C :ctype:`int`. |
| |
| ``f`` (:class:`float`) [float] |
| Convert a Python floating point number to a C :ctype:`float`. |
| |
| ``d`` (:class:`float`) [double] |
| Convert a Python floating point number to a C :ctype:`double`. |
| |
| ``D`` (:class:`complex`) [Py_complex] |
| Convert a Python complex number to a C :ctype:`Py_complex` structure. |
| |
| Other objects |
| ------------- |
| |
| ``O`` (object) [PyObject \*] |
| Store a Python object (without any conversion) in a C object pointer. The C |
| program thus receives the actual object that was passed. The object's reference |
| count is not increased. The pointer stored is not *NULL*. |
| |
| ``O!`` (object) [*typeobject*, PyObject \*] |
| Store a Python object in a C object pointer. This is similar to ``O``, but |
| takes two C arguments: the first is the address of a Python type object, the |
| second is the address of the C variable (of type :ctype:`PyObject\*`) into which |
| the object pointer is stored. If the Python object does not have the required |
| type, :exc:`TypeError` is raised. |
| |
| ``O&`` (object) [*converter*, *anything*] |
| Convert a Python object to a C variable through a *converter* function. This |
| takes two arguments: the first is a function, the second is the address of a C |
| variable (of arbitrary type), converted to :ctype:`void \*`. The *converter* |
| function in turn is called as follows:: |
| |
| status = converter(object, address); |
| |
| where *object* is the Python object to be converted and *address* is the |
| :ctype:`void\*` argument that was passed to the :cfunc:`PyArg_Parse\*` function. |
| The returned *status* should be ``1`` for a successful conversion and ``0`` if |
| the conversion has failed. When the conversion fails, the *converter* function |
| should raise an exception and leave the content of *address* unmodified. |
| |
| If the *converter* returns ``Py_CLEANUP_SUPPORTED``, it may get called a |
| second time if the argument parsing eventually fails, giving the converter a |
| chance to release any memory that it had already allocated. In this second |
| call, the *object* parameter will be NULL; *address* will have the same value |
| as in the original call. |
| |
| .. versionchanged:: 3.1 |
| ``Py_CLEANUP_SUPPORTED`` was added. |
| |
| ``(items)`` (:class:`tuple`) [*matching-items*] |
| The object must be a Python sequence whose length is the number of format units |
| in *items*. The C arguments must correspond to the individual format units in |
| *items*. Format units for sequences may be nested. |
| |
| It is possible to pass "long" integers (integers whose value exceeds the |
| platform's :const:`LONG_MAX`) however no proper range checking is done --- the |
| most significant bits are silently truncated when the receiving field is too |
| small to receive the value (actually, the semantics are inherited from downcasts |
| in C --- your mileage may vary). |
| |
| A few other characters have a meaning in a format string. These may not occur |
| inside nested parentheses. They are: |
| |
| ``|`` |
| Indicates that the remaining arguments in the Python argument list are optional. |
| The C variables corresponding to optional arguments should be initialized to |
| their default value --- when an optional argument is not specified, |
| :cfunc:`PyArg_ParseTuple` does not touch the contents of the corresponding C |
| variable(s). |
| |
| ``:`` |
| The list of format units ends here; the string after the colon is used as the |
| function name in error messages (the "associated value" of the exception that |
| :cfunc:`PyArg_ParseTuple` raises). |
| |
| ``;`` |
| The list of format units ends here; the string after the semicolon is used as |
| the error message *instead* of the default error message. ``:`` and ``;`` |
| mutually exclude each other. |
| |
| Note that any Python object references which are provided to the caller are |
| *borrowed* references; do not decrement their reference count! |
| |
| Additional arguments passed to these functions must be addresses of variables |
| whose type is determined by the format string; these are used to store values |
| from the input tuple. There are a few cases, as described in the list of format |
| units above, where these parameters are used as input values; they should match |
| what is specified for the corresponding format unit in that case. |
| |
| For the conversion to succeed, the *arg* object must match the format |
| and the format must be exhausted. On success, the |
| :cfunc:`PyArg_Parse\*` functions return true, otherwise they return |
| false and raise an appropriate exception. When the |
| :cfunc:`PyArg_Parse\*` functions fail due to conversion failure in one |
| of the format units, the variables at the addresses corresponding to that |
| and the following format units are left untouched. |
| |
| API Functions |
| ------------- |
| |
| .. cfunction:: int PyArg_ParseTuple(PyObject *args, const char *format, ...) |
| |
| Parse the parameters of a function that takes only positional parameters into |
| local variables. Returns true on success; on failure, it returns false and |
| raises the appropriate exception. |
| |
| |
| .. cfunction:: int PyArg_VaParse(PyObject *args, const char *format, va_list vargs) |
| |
| Identical to :cfunc:`PyArg_ParseTuple`, except that it accepts a va_list rather |
| than a variable number of arguments. |
| |
| |
| .. cfunction:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...) |
| |
| Parse the parameters of a function that takes both positional and keyword |
| parameters into local variables. Returns true on success; on failure, it |
| returns false and raises the appropriate exception. |
| |
| |
| .. cfunction:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs) |
| |
| Identical to :cfunc:`PyArg_ParseTupleAndKeywords`, except that it accepts a |
| va_list rather than a variable number of arguments. |
| |
| |
| .. cfunction:: int PyArg_ValidateKeywordArguments(PyObject *) |
| |
| Ensure that the keys in the keywords argument dictionary are strings. This |
| is only needed if :cfunc:`PyArg_ParseTupleAndKeywords` is not used, since the |
| latter already does this check. |
| |
| .. versionadded:: 3.2 |
| |
| |
| .. XXX deprecated, will be removed |
| .. cfunction:: int PyArg_Parse(PyObject *args, const char *format, ...) |
| |
| Function used to deconstruct the argument lists of "old-style" functions --- |
| these are functions which use the :const:`METH_OLDARGS` parameter parsing |
| method. This is not recommended for use in parameter parsing in new code, and |
| most code in the standard interpreter has been modified to no longer use this |
| for that purpose. It does remain a convenient way to decompose other tuples, |
| however, and may continue to be used for that purpose. |
| |
| |
| .. cfunction:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...) |
| |
| A simpler form of parameter retrieval which does not use a format string to |
| specify the types of the arguments. Functions which use this method to retrieve |
| their parameters should be declared as :const:`METH_VARARGS` in function or |
| method tables. The tuple containing the actual parameters should be passed as |
| *args*; it must actually be a tuple. The length of the tuple must be at least |
| *min* and no more than *max*; *min* and *max* may be equal. Additional |
| arguments must be passed to the function, each of which should be a pointer to a |
| :ctype:`PyObject\*` variable; these will be filled in with the values from |
| *args*; they will contain borrowed references. The variables which correspond |
| to optional parameters not given by *args* will not be filled in; these should |
| be initialized by the caller. This function returns true on success and false if |
| *args* is not a tuple or contains the wrong number of elements; an exception |
| will be set if there was a failure. |
| |
| This is an example of the use of this function, taken from the sources for the |
| :mod:`_weakref` helper module for weak references:: |
| |
| static PyObject * |
| weakref_ref(PyObject *self, PyObject *args) |
| { |
| PyObject *object; |
| PyObject *callback = NULL; |
| PyObject *result = NULL; |
| |
| if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) { |
| result = PyWeakref_NewRef(object, callback); |
| } |
| return result; |
| } |
| |
| The call to :cfunc:`PyArg_UnpackTuple` in this example is entirely equivalent to |
| this call to :cfunc:`PyArg_ParseTuple`:: |
| |
| PyArg_ParseTuple(args, "O|O:ref", &object, &callback) |
| |
| |
| --------------- |
| Building values |
| --------------- |
| |
| .. cfunction:: PyObject* Py_BuildValue(const char *format, ...) |
| |
| Create a new value based on a format string similar to those accepted by the |
| :cfunc:`PyArg_Parse\*` family of functions and a sequence of values. Returns |
| the value or *NULL* in the case of an error; an exception will be raised if |
| *NULL* is returned. |
| |
| :cfunc:`Py_BuildValue` does not always build a tuple. It builds a tuple only if |
| its format string contains two or more format units. If the format string is |
| empty, it returns ``None``; if it contains exactly one format unit, it returns |
| whatever object is described by that format unit. To force it to return a tuple |
| of size 0 or one, parenthesize the format string. |
| |
| When memory buffers are passed as parameters to supply data to build objects, as |
| for the ``s`` and ``s#`` formats, the required data is copied. Buffers provided |
| by the caller are never referenced by the objects created by |
| :cfunc:`Py_BuildValue`. In other words, if your code invokes :cfunc:`malloc` |
| and passes the allocated memory to :cfunc:`Py_BuildValue`, your code is |
| responsible for calling :cfunc:`free` for that memory once |
| :cfunc:`Py_BuildValue` returns. |
| |
| In the following description, the quoted form is the format unit; the entry in |
| (round) parentheses is the Python object type that the format unit will return; |
| and the entry in [square] brackets is the type of the C value(s) to be passed. |
| |
| The characters space, tab, colon and comma are ignored in format strings (but |
| not within format units such as ``s#``). This can be used to make long format |
| strings a tad more readable. |
| |
| ``s`` (:class:`str` or ``None``) [char \*] |
| Convert a null-terminated C string to a Python :class:`str` object using ``'utf-8'`` |
| encoding. If the C string pointer is *NULL*, ``None`` is used. |
| |
| ``s#`` (:class:`str` or ``None``) [char \*, int] |
| Convert a C string and its length to a Python :class:`str` object using ``'utf-8'`` |
| encoding. If the C string pointer is *NULL*, the length is ignored and |
| ``None`` is returned. |
| |
| ``y`` (:class:`bytes`) [char \*] |
| This converts a C string to a Python :func:`bytes` object. If the C |
| string pointer is *NULL*, ``None`` is returned. |
| |
| ``y#`` (:class:`bytes`) [char \*, int] |
| This converts a C string and its lengths to a Python object. If the C |
| string pointer is *NULL*, ``None`` is returned. |
| |
| ``z`` (:class:`str` or ``None``) [char \*] |
| Same as ``s``. |
| |
| ``z#`` (:class:`str` or ``None``) [char \*, int] |
| Same as ``s#``. |
| |
| ``u`` (:class:`str`) [Py_UNICODE \*] |
| Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a Python |
| Unicode object. If the Unicode buffer pointer is *NULL*, ``None`` is returned. |
| |
| ``u#`` (:class:`str`) [Py_UNICODE \*, int] |
| Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a Python |
| Unicode object. If the Unicode buffer pointer is *NULL*, the length is ignored |
| and ``None`` is returned. |
| |
| ``U`` (:class:`str` or ``None``) [char \*] |
| Same as ``s``. |
| |
| ``U#`` (:class:`str` or ``None``) [char \*, int] |
| Same as ``s#``. |
| |
| ``i`` (:class:`int`) [int] |
| Convert a plain C :ctype:`int` to a Python integer object. |
| |
| ``b`` (:class:`int`) [char] |
| Convert a plain C :ctype:`char` to a Python integer object. |
| |
| ``h`` (:class:`int`) [short int] |
| Convert a plain C :ctype:`short int` to a Python integer object. |
| |
| ``l`` (:class:`int`) [long int] |
| Convert a C :ctype:`long int` to a Python integer object. |
| |
| ``B`` (:class:`int`) [unsigned char] |
| Convert a C :ctype:`unsigned char` to a Python integer object. |
| |
| ``H`` (:class:`int`) [unsigned short int] |
| Convert a C :ctype:`unsigned short int` to a Python integer object. |
| |
| ``I`` (:class:`int`) [unsigned int] |
| Convert a C :ctype:`unsigned int` to a Python integer object. |
| |
| ``k`` (:class:`int`) [unsigned long] |
| Convert a C :ctype:`unsigned long` to a Python integer object. |
| |
| ``L`` (:class:`int`) [PY_LONG_LONG] |
| Convert a C :ctype:`long long` to a Python integer object. Only available |
| on platforms that support :ctype:`long long` (or :ctype:`_int64` on |
| Windows). |
| |
| ``K`` (:class:`int`) [unsigned PY_LONG_LONG] |
| Convert a C :ctype:`unsigned long long` to a Python integer object. Only |
| available on platforms that support :ctype:`unsigned long long` (or |
| :ctype:`unsigned _int64` on Windows). |
| |
| ``n`` (:class:`int`) [Py_ssize_t] |
| Convert a C :ctype:`Py_ssize_t` to a Python integer. |
| |
| ``c`` (:class:`bytes` of length 1) [char] |
| Convert a C :ctype:`int` representing a byte to a Python :class:`bytes` object of |
| length 1. |
| |
| ``C`` (:class:`str` of length 1) [int] |
| Convert a C :ctype:`int` representing a character to Python :class:`str` |
| object of length 1. |
| |
| ``d`` (:class:`float`) [double] |
| Convert a C :ctype:`double` to a Python floating point number. |
| |
| ``f`` (:class:`float`) [float] |
| Convert a C :ctype:`float` to a Python floating point number. |
| |
| ``D`` (:class:`complex`) [Py_complex \*] |
| Convert a C :ctype:`Py_complex` structure to a Python complex number. |
| |
| ``O`` (object) [PyObject \*] |
| Pass a Python object untouched (except for its reference count, which is |
| incremented by one). If the object passed in is a *NULL* pointer, it is assumed |
| that this was caused because the call producing the argument found an error and |
| set an exception. Therefore, :cfunc:`Py_BuildValue` will return *NULL* but won't |
| raise an exception. If no exception has been raised yet, :exc:`SystemError` is |
| set. |
| |
| ``S`` (object) [PyObject \*] |
| Same as ``O``. |
| |
| ``N`` (object) [PyObject \*] |
| Same as ``O``, except it doesn't increment the reference count on the object. |
| Useful when the object is created by a call to an object constructor in the |
| argument list. |
| |
| ``O&`` (object) [*converter*, *anything*] |
| Convert *anything* to a Python object through a *converter* function. The |
| function is called with *anything* (which should be compatible with :ctype:`void |
| \*`) as its argument and should return a "new" Python object, or *NULL* if an |
| error occurred. |
| |
| ``(items)`` (:class:`tuple`) [*matching-items*] |
| Convert a sequence of C values to a Python tuple with the same number of items. |
| |
| ``[items]`` (:class:`list`) [*matching-items*] |
| Convert a sequence of C values to a Python list with the same number of items. |
| |
| ``{items}`` (:class:`dict`) [*matching-items*] |
| Convert a sequence of C values to a Python dictionary. Each pair of consecutive |
| C values adds one item to the dictionary, serving as key and value, |
| respectively. |
| |
| If there is an error in the format string, the :exc:`SystemError` exception is |
| set and *NULL* returned. |
| |
| .. cfunction:: PyObject* Py_VaBuildValue(const char *format, va_list vargs) |
| |
| Identical to :cfunc:`Py_BuildValue`, except that it accepts a va_list |
| rather than a variable number of arguments. |