GNU Info
(python2.1-ext.info)Building Arbitrary Values
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.
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 `Py_BuildValue()'. In other words, if your code invokes
`malloc()' and passes the allocated memory to `Py_BuildValue()', your
code is responsible for calling `free()' for that memory once
`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' (string) {[char * }]'
Convert a null-terminated C string to a Python object. If the C
string pointer is `NULL', `None' is used.
``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#'.
``u' (Unicode string) {[Py_UNICODE * }]'
Convert a null-terminated buffer of Unicode (UCS-2) data to a
Python Unicode object. If the Unicode buffer pointer is `NULL',
`None' is returned.
``u#' (Unicode string) {[Py_UNICODE *, int }]'
Convert a Unicode (UCS-2) 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.
``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'.
``D' (complex) {[Py_complex * }]'
Convert a C `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, `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'.
``U' (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))
automatically generated by info2www version 1.2.2.9