#
1.9 任意の値を構築する

`Py_BuildValue()` は`PyArg_ParseTuple()` の 対極に位置するものです。この関数は以下のように定義されています:

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

`Py_BuildValue()` は、`PyArg_ParseTuple()` の認識する一連の書式化単位に似た書式化単位を認識します。ただし (関数への出力ではなく、入力に使われる) 引数はポインタではなく、 ただの値でなければなりません。 Python から呼び出された C 関数が返す値として適切な、新たな Python オブジェクトを返します。

`PyArg_ParseTuple()` とは一つ違う点があります: `PyArg_ParseTuple()` は第一引数をタプルにする必要があります (Python の引数リストは内部的には常にタプルとして表現されるからです) が、`Py_BuildValue()` はタプルを生成するとは限りません。 `Py_BuildValue()` は書式化文字列中に書式化単位が 二つかそれ以上入っている場合にのみタプルを構築します。 書式化文字列が空なら、`None` を返します。きっかり一つの 書式化単位なら、その書式化単位が記述している何らかのオブジェクト になります。サイズが 0 や 1 のタプル返させたいのなら、書式化 文字列を丸括弧で囲います。

以下に例を示します (左に呼び出し例を、右に構築される Python 値を示します):

        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))