The Py_BuildValue() Function

1.9 The Py_BuildValue() Function

This function is the counterpart to PyArg_ParseTuple(). It is declared as follows:
这个函数与函数PyArg_ParseTuple()配对。函数声明如下：

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
它与函数PyArg_ParseTuple()都可以识别相同的格式单元集，但是参数（输入而非输出函数）

output) must not be pointers, just values. It returns a new Python object, suitable for returning from a C function called from Python.
不能是指针，只能是数值。它返回一个新的Python对象，适合从Python调用C函数中返回。

One difference with PyArg_ParseTuple(): while the latter requires its first argument to be a tuple (since Python argument lists are always
与PyArg_ParseTuple()不同的是：后者要求它的第一个参数为元组（因为Python的参数列表在内部总是表现为元组），
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

而Py_BuildValue()不总是构造一个元组。当它的格式字符串包含两个或以上的格式单元时才构造一个元组。

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
如果格式字符串为空，它返回None；如果只包含一个格式单元，则它返回由格式单元描述类型相一致的对象。
format unit. To force it to return a tuple of size 0 or one, parenthesize the format string.

 

要强制返回大小为0或1的元组，则给给格式字符串加上括号。
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
下面的描述，引号内的是格式单元；圆括号内的是格式单元将要返回的Python对象类型；
will return; and the entry in [square] brackets is the type of the C value(s) to be passed.

方括号内的是传递给函数的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
格式字符串中的空格，制表符，冒号和逗号将被忽略（在类似"s#"格式单元中的除外）。使用这些字符可以增强格式字符串的可读性。
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))