1.9 Building Arbitrary Values
This function is the counterpart to PyArg_ParseTuple(). It is
declared 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 output) must not be pointers, just
values. It returns a new Python object, suitable for returning from a C function called from
Python.
One difference with PyArg_ParseTuple(): while the latter
requires its first argument to be a tuple (since Python argument lists are always represented
as tuples internally), 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.
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))
|
