This function is the counterpart to PyArg_ParseTuple ( ) It is declared as follows:.
This function is a function PyArg_ParseTuple () pair. Function declaration as follows:
PyObject *Py_BuildValue(char *format, ...);
It recognizes a set of format units similar to the ones recognized by PyArg_ParseTuple (), but the arguments (which are input to the function, not
that it can be set the same format as the function unit identification PyArg_ParseTuple (), but the parameter (rather than input output functions)
output) must not be pointers, just values. It returns a new Python object, suitable for returning from a C function called from Python.
can not be a pointer, only the value. It returns a new Python object, suitable for returning from the Python call a C function.
One difference with PyArg_ParseTuple (): while the latter requires its first argument to be a tuple (since Python argument lists are always
and of PyArg_ParseTuple () except that: the tuple (since the parameters of Python which requires its first parameter list internally always expressed as tuples),
Represented aS tuples internally), Py_BuildValue () does not always Build A tuple. It builds A tuple format String the contains only IF the ITS TWO or More
The Py_BuildValue () does not always construct a tuple. When its format string format comprising two or more units configured when a tuple.
. 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
if the format string is empty, it returns None; if the format contains only a unit, it return means of the type described by the format consistent with the object.
format unit. To force it to return a tuple of size 0 or one, parenthesize the format string.
To be forced back tuple size 0 or 1, to give the format string parentheses.
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
following description, the format unit in quotes; in parenthesis is the format unit to be returned Python object type;
Will return; and The entry in [Square] The type of brackets IS The C value (S) to BE passed.
Bracketed values passed to a function of type C.
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
the format string space, tab, colon and comma will be ignore (similar except "s #" format cell). Using these characters can enhance the readability of the format string.
long format strings a tad more readable.
"s" (string) [char *]
Convert a null-terminated C string to a Python object. If the C string pointer is NULL, None is returned.
"s#" (string) [char *, int]
Convert a C string and its length to a Python object. If the C string pointer is NULL, the length is ignored and None is returned.
"z" (string or None) [char *]
Same as "s".
"z#" (string or None) [char *, int]
Same as "s#".
"i" (integer) [int]
Convert a plain C int to a Python integer object.
"b" (integer) [char]
Same as "i".
"h" (integer) [short int]
Same as "i".
"l" (integer) [long int]
Convert a C long int to a Python integer object.
"c" (string of length 1) [char]
Convert a C int representing a character to a Python string of length 1.
"d" (float) [double]
Convert a C double to a Python floating point number.
"f" (float) [float]
Same as "d".
"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, Py_BuildValue() will return NULL but won't raise an exception. If no exception has been raised yet, PyExc_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 void *) as its argument and should return a ``new'' Python object, or NULL if an error occurred.
"(items)" (tuple) [matching-items]
Convert a sequence of C values to a Python tuple with the same number of items.
"[items]" (list) [matching-items]
Convert a sequence of C values to a Python list with the same number of items.
"{items}" (dictionary) [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 PyExc_SystemError exception is raised and NULL returned.
Examples (to the left the call, to the right the resulting Python value):
Py_BuildValue("") None
Py_BuildValue("i", 123) 123
Py_BuildValue("iii", 123, 456, 789) (123, 456, 789)
Py_BuildValue("s", "hello") 'hello'
Py_BuildValue("ss", "hello", "world") ('hello', 'world')
Py_BuildValue("s#", "hello", 4) 'hell'
Py_BuildValue("()") ()
Py_BuildValue("(i)", 123) (123,)
Py_BuildValue("(ii)", 123, 456) (123, 456)
Py_BuildValue("(i,i)", 123, 456) (123, 456)
Py_BuildValue("[i,i]", 123, 456) [123, 456]
Py_BuildValue("{s:i,s:i}",
"abc", 123, "def", 456) {'abc': 123, 'def': 456}
Py_BuildValue("((ii)(ii)) (ii)",
1, 2, 3, 4, 5, 6) (((1, 2), (3, 4)), (5, 6))
