Python in a Nutshell

Name

Py_BuildValue

Synopsis

PyObject* Py_BuildValue(char* format,...)

format is a C string that describes the Python object to build. The following arguments of Py_BuildValue are C values from which the result is built. The PyObject* result is a new reference. Table 24-2 lists the commonly used code strings, of which zero or more are joined into string format. Py_BuildValue builds and returns a tuple if format contains two or more format codes, or if format begins with ( and ends with ). Otherwise, the result is not a tuple. When you pass buffers, as for example in the case of format code s#, Py_BuildValue copies the data. You can therefore modify, abandon, or free( ) your original copy of the data after Py_BuildValue returns. Py_BuildValue always returns a new reference (except for format code N). Called with an empty format, Py_BuildValue("") returns a new reference to None.

Table 24-2. Format codes for Py_BuildValue

Code	C type	Meaning
c	char	A C char becomes a Python string of length 1
d	double	A C double becomes a Python float
D	Py_Complex	A C Py_Complex becomes a Python complex
i	int	A C int becomes a Python int
l	long	A C long becomes a Python int
N	PyObject*	Passes a Python object and steals a reference
O	PyObject*	Passes a Python object and INCREFs it as per normal rules
O&	convert + void*	Arbitrary conversion (see below)
s	char*	C null-terminated char* to Python string, or NULL to None
s#	char* + int	C char* and length to Python string, ...