Py_BuildValue
(const char
*format, ...
)
¶
Return value: New reference.
Create a new value based on a format string similar to those accepted by the 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.
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.
-
Convert a null-terminated C string to a Python object. If the C string pointer is
NULL,
None
is used. -
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. -
Same as
s
. -
Same as
s#
. -
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. -
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. -
Convert a plain C
int
to a Python integer object. -
Convert a plain C
char
to a Python integer object. -
Convert a plain C
short int
to a Python integer object. -
Convert a C
long int
to a Python integer object. -
Convert a C
unsigned char
to a Python integer object. -
Convert a C
unsigned short int
to a Python integer object. -
Convert a C
unsigned int
to a Python integer object or a Python long integer object, if it is larger thansys.maxint
. -
Convert a C
unsigned long
to a Python integer object or a Python long integer object, if it is larger thansys.maxint
. -
Convert a C
long long
to a Python long integer object. Only available on platforms that supportlong long
. -
Convert a C
unsigned long long
to a Python long integer object. Only available on platforms that supportunsigned long long
. -
Convert a C
Py_ssize_t
to a Python integer or long integer.New in version 2.5.
-
Convert a C
int
representing a character to a Python string of length 1. -
Convert a C
double
to a Python floating point number. -
Same as
d
. -
Convert a C
Py_complex
structure to a Python complex number. -
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,SystemError
is set. -
Same as
O
. -
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. -
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. - Convert a sequence of C values to a Python tuple with the same number of items.
- Convert a sequence of C values to a Python list with the same number of 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.
s
(string) [char *]
s#
(string) [char *, int]
z
(string or
None
) [char *]
z#
(string or
None
) [char *, int]
u
(Unicode string) [Py_UNICODE *]
u#
(Unicode string) [Py_UNICODE *, int]
i
(integer) [int]
b
(integer) [char]
h
(integer) [short int]
l
(integer) [long int]
B
(integer) [unsigned char]
H
(integer) [unsigned short int]
I
(integer/long) [unsigned int]
k
(integer/long) [unsigned long]
L
(long) [PY_LONG_LONG]
K
(long) [unsigned PY_LONG_LONG]
n
(int) [Py_ssize_t]
c
(string of length 1) [char]
d
(float) [double]
f
(float) [float]
D
(complex) [Py_complex *]
O
(object) [PyObject *]
S
(object) [PyObject *]
N
(object) [PyObject *]
O&
(object) [
converter,
anything]
(items)
(tuple) [
matching-items]
[items]
(list) [
matching-items]
{items}
(dictionary) [
matching-items]
If there is an error in the format string, the SystemError
exception is set and NULL returned.
-
PyObject*
-
Identical to
Py_BuildValue()
, except that it accepts a va_list rather than a variable number of arguments.
Py_VaBuildValue
(const char
*format, va_list
vargs
)
¶