引数の解釈と値の構築

これらの関数は独自の拡張モジュール用の関数やメソッドを作成する際に便利です。詳しい情報や用例は Python インタプリタの拡張と埋め込み にあります。

最初に説明する 3 つの関数、 PyArg_ParseTuple(), PyArg_ParseTupleAndKeywords(),および PyArg_Parse() はいずれも 書式文字列 (format string) を使います。書式文字列は、関数が受け取るはずの引数に関する情報を伝えるのに用いられます。いずれの関数における書式文字列も、同じ書式を使っています。

引数を解析する

書式文字列は、ゼロ個またはそれ以上の "書式単位 (format unit)" から成り立ちます。 1つの書式単位は1つの Python オブジェクトを表します; 通常は単一の文字か、書式単位からなる文字列を括弧で囲ったものになります。例外として、括弧で囲われていない書式単位文字列が単一のアドレス引数に対応する場合がいくつかあります。以下の説明では、引用符のついた形式は書式単位です; (丸)括弧で囲った部分は書式単位に対応する Python のオブジェクト型です; [角] 括弧は値をアドレス渡しする際に使う C の変数型です。

文字列とバッファ

以下のフォーマットはオブジェクトに連続したメモリチャンクとしてアクセスするためのものです。返される unicode や bytes のために生のストレージを用意する必要はありません。

一般に、フォーマットがバッファにポインタをセットする時は、そのバッファは対応する Python オブジェクトにより管理され、バッファはそのオブジェクトのライフタイムを共有します。自分自身でメモリを解放する必要はありません。この例外は、 es, es#, et, et# だけです。

ただし、 Py_buffer 構造体に格納されたバッファーはロックされて、呼び出し側はそのバッファーを Py_BEGIN_ALLOW_THREADS ブロック内でも、 mutable なデータが破棄されたりリサイズされたりするリスク無しに利用することができます。そのかわりに、そのデータに対する処理が終わった場合 (もしくは処理せずに中断した場合) には 必ず PyBuffer_Release() を呼ばなければなりません。

特に言及されていない場合、バッファーは NUL 終端されていません。

Some formats require a read-only bytes-like object, and set a pointer instead of a buffer structure. They work by checking that the object's PyBufferProcs.bf_releasebuffer field is NULL, which disallows mutable objects such as bytearray.

注釈

全ての # 型のフォーマット (s#, y#, など) において、length 引数の型 (int か Py_ssize_t) は Python.h を include する前に PY_SSIZE_T_CLEAN マクロを定義することで制御します。マクロが定義されている場合、 length は int 型ではなく Py_ssize_t 型になります。この挙動は将来の Python バージョンで変更され、 Py_ssize_t のみがサポートされて int はサポートされなくなるでしょう。常に PY_SSIZE_T_CLEAN を定義したほうが良いです。

s (str) [const char *]

Unicode オブジェクトを、キャラクタ文字列を指す C のポインタに変換します。キャラクタ型ポインタ変数のアドレスを渡すと、すでに存在している文字列へのポインタをその変数に記録します。C 文字列は NUL で終端されています。Python の文字列型は、 null コードポイントが途中に埋め込まれていてはなりません; もし埋め込まれていれば ValueError 例外を送出します。Unicode オブジェクトは 'utf-8' を使って C 文字列に変換されます。変換に失敗すると UnicodeError を送出します。

注釈

このフォーマットは bytes-like objects をサポートしません。 ファイルシステムパスを受け取って C 言語の文字列に変換したい場合は、 O& フォーマットを、 converterPyUnicode_FSConverter() を指定して利用すると良いです。

バージョン 3.5 で変更: 以前は Python 文字列に null コードポイントが埋め込まれていたときに TypeError を送出していました。

s* (str または bytes-like object) [Py_buffer]

このフォーマットは Unicode オブジェクトと bytes-like object を受け付けて、呼び出し元から渡された Py_buffer 構造体に値を格納します。 結果の C 文字列は NUL バイトを含むかもしれません。 Unicode オブジェクトは 'utf-8' エンコーディングで C 文字列に変換されます。

s# (str, 読み出し専用の bytes-like object) [const char *, int or Py_ssize_t]

s* と同じですが、 mutable なオブジェクトを受け取りません。結果は2つのC変数に格納されます。1つ目はC文字列へのポインターで、2つ目はその長さです。受け取った文字列は null バイトを含むかもしれません。 Unicode オブジェクトは 'utf-8' エンコーディングを利用して C 文字列に変換されます。

z (str または None) [const char *]

Like s, but the Python object may also be None, in which case the C pointer is set to NULL.

z* (str, bytes-like object または None) [Py_buffer]

Like s*, but the Python object may also be None, in which case the buf member of the Py_buffer structure is set to NULL.

z# (str, 読み出し専用の bytes-like object または None) [const char *, int]

Like s#, but the Python object may also be None, in which case the C pointer is set to NULL.

y (読み出し専用の bytes-like object) [const char *]

このフォーマットは bytes-like object をキャラクタ文字列を指す C のポインタに変換します; Unicode オブジェクトを受け付けません。バイトバッファは null バイトを含むべきではありません; null バイトを含む場合は ValueError 例外を送出します。

バージョン 3.5 で変更: 以前は bytes バッファにヌルバイトが埋め込まれていたときに TypeError を送出していました。

y* (bytes-like object) [Py_buffer]

s* の変形で、 Unicode オブジェクトを受け付けず、 bytes-like object のみを受け付けます。 バイナリデータを受け付ける目的には、このフォーマットを使うことを推奨します。

y# (読み出し専用の bytes-like object) [const char *, int]

s# の変形で、 Unicode オブジェクトを受け付けず、bytes-like object だけを受け付けます。

S (bytes) [PyBytesObject *]

Pythonオブジェクトとして、 bytes オブジェクトを要求し、いかなる変換も行いません。オブジェクトが bytes オブジェクトでなければ、 TypeError を送出します。C 変数は PyObject* と宣言しても構いません。

Y (bytearray) [PyByteArrayObject *]

Python オブジェクトとして bytearray オブジェクトを要求し、いかなる変換もおこないません。 もしオブジェクトが bytearray でなければ、 TypeError を送出します。C 変数は PyObject* として宣言しても構いません。

u (str) [const Py_UNICODE *]

Python Unicodeオブジェクトを NUL終端されたUnicode文字バッファへのポインタに変換します。 Py_UNICODE ポインタ変数へのアドレスを渡さなければならず、このアドレスに存在する Unicode バッファへのポインタが格納されます。 Py_UNICODE 文字のバイト幅はコンパイルオプション(16 または32ビットのどちらか)に依存することに注意してください。Python 文字列は null コードポイントを含んではなりません; null コードポイントを含む場合、 ValueError 例外が送出されます。

バージョン 3.5 で変更: 以前は Python 文字列に null コードポイントが埋め込まれていたときに TypeError を送出していました。

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Py_UNICODE APIの一部です。PyUnicode_AsWideCharString() を使用するように移行してください。

u# (str) [const Py_UNICODE *, int]

これは u のバリエーションで、値を二つの変数に記録します。一つ目の変数は Unicode データバッファへのポインタで、二つ目はその長さです。このフォーマットは null コードポイントを含むことができます。

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Py_UNICODE APIの一部です。PyUnicode_AsWideCharString() を使用するように移行してください。

Z (str または None) [const Py_UNICODE *]

Like u, but the Python object may also be None, in which case the Py_UNICODE pointer is set to NULL.

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Py_UNICODE APIの一部です。PyUnicode_AsWideCharString() を使用するように移行してください。

Z# (str または None) [const Py_UNICODE *, int]

Like u#, but the Python object may also be None, in which case the Py_UNICODE pointer is set to NULL.

Deprecated since version 3.3, will be removed in version 4.0: 古いスタイルの Py_UNICODE APIの一部です。PyUnicode_AsWideCharString() を使用するように移行してください。

U (str) [PyObject *]

Python オブジェクトとして Unicode オブジェクトを要求し、いかなる変換も行いません。オブジェクトが Unicode オブジェクトではない場合、 TypeError が送出されます。C変数は PyObject* として宣言しても構いません。

w* (読み書き可能な bytes-like object) [Py_buffer]

このフォーマットは、読み書き可能な buffer interface を実装したオブジェクトを受け付けます。 呼び出し元から渡された Py_buffer 構造体に値を格納します。バッファは nullバイトを含むかもしれず、呼び出し元はバッファを使い終わったら PyBuffer_Release() を呼び出さなければなりません。

es (str) [const char *encoding, char **buffer]

これは s の変化形で、Unicodeをキャラクタ型バッファにエンコードするために用いられます。NULバイトが埋め込まれていないデータでのみ動作します。

This format requires two arguments. The first is only used as input, and must be a const char* which points to the name of an encoding as a NUL-terminated string, or NULL, in which case 'utf-8' encoding is used. An exception is raised if the named encoding is not known to Python. The second argument must be a char**; the value of the pointer it references will be set to a buffer with the contents of the argument text. The text will be encoded in the encoding specified by the first argument.

PyArg_ParseTuple() を使うと、必要なサイズのバッファを確保し、そのバッファにエンコード後のデータをコピーして、 *buffer がこの新たに確保された記憶領域を指すように変更します。呼び出し側には、確保されたバッファを使い終わった後に PyMem_Free() で解放する責任があります。

et (str, bytes または bytearray) [const char *encoding, char **buffer]

es と同じです。ただし、バイト文字列オブジェクトをエンコードし直さずに渡します。その代わり、実装ではバイト文字列オブジェクトがパラメタに渡したエンコードを使っているものと仮定します。

es# (str) [const char *encoding, char **buffer, int *buffer_length]

s# の変化形で、Unicode をキャラクタ型バッファにエンコードするために用いられます。es 書式違って、この変化形はバイトが埋め込まれていてもかまいません。

It requires three arguments. The first is only used as input, and must be a const char* which points to the name of an encoding as a NUL-terminated string, or NULL, in which case 'utf-8' encoding is used. An exception is raised if the named encoding is not known to Python. The second argument must be a char**; the value of the pointer it references will be set to a buffer with the contents of the argument text. The text will be encoded in the encoding specified by the first argument. The third argument must be a pointer to an integer; the referenced integer will be set to the number of bytes in the output buffer.

この書式の処理には二つのモードがあります:

If *buffer points a NULL pointer, the function will allocate a buffer of the needed size, copy the encoded data into this buffer and set *buffer to reference the newly allocated storage. The caller is responsible for calling PyMem_Free() to free the allocated buffer after usage.

If *buffer points to a non-NULL pointer (an already allocated buffer), PyArg_ParseTuple() will use this location as the buffer and interpret the initial value of *buffer_length as the buffer size. It will then copy the encoded data into the buffer and NUL-terminate it. If the buffer is not large enough, a ValueError will be set.

どちらの場合も、 *buffer_length は終端の NUL バイトを含まないエンコード済みデータの長さにセットされます。

et# (str, bytes または bytearray) [const char *encoding, char **buffer, int *buffer_length]

es# と同じです。ただし、バイト文字列オブジェクトをエンコードし直さずに渡します。その代わり、実装ではバイト文字列オブジェクトがパラメタに渡したエンコードを使っているものと仮定します。

b (int) [unsigned char]

Python の非負の整数を、 C の unsigned char 型の小さな符号無し整数に変換します。

B (int) [unsigned char]

Python の整数を、オーバフローチェックを行わずに、 C の unsigned char 型の小さな整数に変換します。

h (int) [short int]

Python の整数を、 C の short int 型に変換します。

H (int) [unsigned short int]

Python の整数を、オーバフローチェックを行わずに、 C の unsigned short int 型に変換します。

i (int) [int]

Python の整数を、 C の int 型に変換します。

I (int) [unsigned int]

Python の整数を、オーバフローチェックを行わずに、 C の unsigned int 型に変換します。

l (int) [long int]

Python の整数を、 C の long int 型に変換します。

k (int) [unsigned long]

Python の整数を、オーバフローチェックを行わずに、 C の unsigned long 型に変換します。

L (int) [long long]

PythonのintをC long long へ変換する。

K (int) [unsigned long long]

PythonのintをC unsigned long long へオーバーフローの確認をせず変換する

n (int) [Py_ssize_t]

Python の整数をCの Py_ssize_t 型に変換します。

c (長さ 1 の、 bytes または bytearray) [char]

長さ 1 の bytes または bytearray オブジェクトとして表現されている Python バイトを C の char 型に変換します。

バージョン 3.3 で変更: bytearray を受け付けるようになりました。

C (長さ 1 の str) [int]

長さ 1 の str オブジェクトとして表現されている Python キャラクタを C の int 型に変換します。

f (float) [float]

Python の浮動小数点型を、 C の float 型に変換します。

d (float) [double]

Python の浮動小数点型を、 C の double 型に変換します。

D (complex) [Py_complex]

Python の複素数型を、 C の Py_complex 構造体に変換します。

その他のオブジェクト

O (object) [PyObject *]

Store a Python object (without any conversion) in a C object pointer. The C program thus receives the actual object that was passed. The object's reference count is not increased. The pointer stored is not NULL.

O! (object) [typeobject, PyObject *]

Python オブジェクトを C の Python オブジェクト型ポインタに保存します。 O に似ていますが、二つの C の引数をとります: 一つ目の引数は Python の型オブジェクトへのアドレスで、二つ目の引数はオブジェクトへのポインタが保存されている (PyObject* の) C の変数へのアドレスです。Python オブジェクトが指定した型ではない場合、 TypeError を送出します。

O& (object) [converter, anything]

Python オブジェクトを converter 関数を介して C の変数に変換します。二つの引数をとります: 一つ目は関数で、二つ目は (任意の型の) C 変数へのアドレスを void * 型に変換したものです。 converter は以下のようにして呼び出されます:

status = converter(object, address);

ここで object は変換対象の Python オブジェクトで、 addressPyArg_Parse*() に渡した void* 型の引数です。戻り値 status は変換に成功した際に 1,失敗した場合には 0 になります。変換に失敗した場合、 converter 関数は address の内容を変更せずに例外を送出しなくてはなりません。

If the converter returns Py_CLEANUP_SUPPORTED, it may get called a second time if the argument parsing eventually fails, giving the converter a chance to release any memory that it had already allocated. In this second call, the object parameter will be NULL; address will have the same value as in the original call.

バージョン 3.1 で変更: Py_CLEANUP_SUPPORTED の追加。

p (bool) [int]

真偽値が求められる箇所 (a boolean predicate) に渡された値を判定し、その結果を等価な C の true/false 整数値に変換します。 もし式が真なら int には 1 が、偽なら 0 が設定されます。この関数は任意の有効なPython値を受け付けます。 Pythonが値の真偽をどのように判定するかを知りたければ、 真理値判定 を参照してください。

バージョン 3.3 で追加.

(items) (tuple) [matching-items]

オブジェクトは items に入っている書式単位の数だけの長さを持つ Python のシーケンス型でなければなりません。各 C 引数は items 内の個々の書式単位に対応づけできなければなりません。シーケンスの書式単位は入れ子構造にできます。

"長" 整数 (プラットフォームの LONG_MAX を超える値の整数) を渡すのは可能です; しかしながら、適切な値域チェックはまったく行われません --- 値を受け取るためのフィールドが、値全てを受け取るには小さすぎる場合、上桁のビット群は暗黙のうちに切り詰められます (実際のところ、このセマンティクスは C のダウンキャスト (downcast) から継承しています --- その恩恵は人それぞれかもしれませんが)。

その他、書式文字列において意味を持つ文字がいくつかあります。それらの文字は括弧による入れ子内には使えません。以下に文字を示します:

|

Python 引数リスト中で、この文字以降の引数がオプションであることを示します。オプションの引数に対応する C の変数はデフォルトの値で初期化しておかなければなりません --- オプションの引数が省略された場合、 PyArg_ParseTuple() は対応する C 変数の内容に手を加えません。

$

PyArg_ParseTupleAndKeywords() でのみ使用可能: 後続のPython引数が keyword-onlyであることを示します。現在、すべてのkeyword-only 引数は任意の引数でなければならず、そのため フォーマット文字列中の | は常に $ より前に指定されなければなりません。

バージョン 3.3 で追加.

:

この文字があると、書式単位の記述はそこで終わります; コロン以降の文字列は、エラーメッセージにおける関数名 (PyArg_ParseTuple() が送出する例外の "付属値 (associated value)") として使われます。

;

この文字があると、書式単位の記述はそこで終わります; セミコロン以降の文字列は、デフォルトエラーメッセージを 置き換える エラーメッセージとして使われます。 :; は相互に排他の文字です。

呼び出し側に提供されるオブジェクトへの参照はすべて 借用 参照 (borrowed reference) になります; これらのオブジェクトの参照カウントをデクリメントしてはなりません!

以下の関数に渡す補助引数 (additional argument) は、書式文字列から決定される型へのアドレスでなければなりません; 補助引数に指定したアドレスは、タプルから入力された値を保存するために使います。上の書式単位のリストで説明したように、補助引数を入力値として使う場合がいくつかあります; その場合、対応する書式単位の指定する形式に従うようにしなければなりません。

変換を正しく行うためには、 arg オブジェクトは書式文字に一致しなければならず、かつ書式文字列内の書式単位に全て値が入るようにしなければなりません。成功すると、 PyArg_Parse*() 関数は真を返します。それ以外の場合には偽を返し、適切な例外を送出します。書式単位のどれかの変換失敗により PyArg_Parse*() が失敗した場合、失敗した書式単位に対応するアドレスとそれ以降のアドレスの内容は変更されません。

API 関数

int PyArg_ParseTuple(PyObject *args, const char *format, ...)

位置引数のみを引数にとる関数のパラメタを解釈して、ローカルな変数に変換します。成功すると真を返します;失敗すると偽を返し、適切な例外を送出します。

int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)

PyArg_ParseTuple() と同じですが、可変長の引数ではなく va_list を引数にとります。

int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)

Parse the parameters of a function that takes both positional and keyword parameters into local variables. The keywords argument is a NULL-terminated array of keyword parameter names. Empty names denote positional-only parameters. Returns true on success; on failure, it returns false and raises the appropriate exception.

バージョン 3.6 で変更: 位置引数のみ を追加した。

int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)

PyArg_ParseTupleAndKeywords() と同じですが、可変長の引数ではなく va_list を引数にとります。

int PyArg_ValidateKeywordArguments(PyObject *)

キーワード引数を格納した辞書のキーが文字列であることを確認します。この関数は PyArg_ParseTupleAndKeywords() を使用しないときにのみ必要で、その理由は後者の関数は同様のチェックを実施するためです。

バージョン 3.2 で追加.

int PyArg_Parse(PyObject *args, const char *format, ...)

"旧スタイル" の関数における引数リストを分析するために使われる関数です --- 旧スタイルの関数は、引数解釈手法に、Python 3 で削除された METH_OLDARGS を使います。新たに書かれるコードでのパラメタ解釈にはこの関数の使用は奨められず、標準のインタプリタにおけるほとんどのコードがもはや引数解釈のためにこの関数を使わないように変更済みです。この関数を残しているのは、この関数が依然として引数以外のタプルを分析する上で便利だからですが、この目的においては将来も使われつづけるかもしれません。

int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)

パラメータ取得を簡単にした形式で、引数の型を指定する書式文字列を使いません。パラメタの取得にこの手法を使う関数は、関数宣言テーブル、またはメソッド宣言テーブル内で METH_VARARGS として宣言しなければなりません。実引数の入ったタプルは args に渡します; このタプルは本当のタプルでなければなりません。タプルの長さは少なくとも min で、 max を超えてはなりません; minmax が等しくてもかまいません。補助引数を関数に渡さなければならず、各補助引数は PyObject* 変数へのポインタでなければなりません; これらの補助引数には、 args の値が入ります; 値の参照は借用参照です。オプションのパラメタに対応する変数のうち、 args に指定していないものには値が入りません; 呼び出し側はそれらの値を初期化しておかなければなりません。この関数は成功すると真を返し、 args がタプルでない場合や間違った数の要素が入っている場合に偽を返します; 何らかの失敗が起きた場合には例外をセットします。

この関数の使用例を以下に示します。この例は、弱参照のための _weakref 補助モジュールのソースコードからとったものです:

static PyObject *
weakref_ref(PyObject *self, PyObject *args)
{
    PyObject *object;
    PyObject *callback = NULL;
    PyObject *result = NULL;

    if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
        result = PyWeakref_NewRef(object, callback);
    }
    return result;
}

この例における PyArg_UnpackTuple() 呼び出しは、 PyArg_ParseTuple() を使った以下の呼び出しと全く等価です:

PyArg_ParseTuple(args, "O|O:ref", &object, &callback)

値の構築

PyObject* 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() は常にタプルを生成するとは限りません。この関数がタプルを生成するのは、書式文字列に二つ以上の書式単位が入っているときだけです。書式文字列が空の場合 None を返します; 書式単位が厳密に一つだけ入っている場合、書式単位で指定されている何らかのオブジェクト単体を返します。サイズがゼロや 1 のタプルを返すように強制するには、丸括弧で囲われた書式文字列を使います。

書式単位 ss# の場合のように、オブジェクトを構築する際にデータを供給するためにメモリバッファをパラメタとして渡す場合には、指定したデータはコピーされます。 Py_BuildValue() が生成したオブジェクトは、呼び出し側が提供したバッファを決して参照しません。別の言い方をすれば、 malloc() を呼び出してメモリを確保し、それを Py_BuildValue() に渡した場合、コード内で Py_BuildValue() が返った後で free() を呼び出す責任があるということです。

以下の説明では、引用符のついた形式は書式単位です; (丸)括弧で囲った部分は書式単位が返す Python のオブジェクト型です; [角] 括弧は関数に渡す値の C 変数型です。

書式文字列内では、(s# のような書式単位を除いて) スペース、タブ、コロンおよびコンマは無視されます。これらの文字を使うと、長い書式文字列をちょっとだけ読みやすくできます。

s (str または None) [const char *]

Convert a null-terminated C string to a Python str object using 'utf-8' encoding. If the C string pointer is NULL, None is used.

s# (str または None) [const char *, int]

Convert a C string and its length to a Python str object using 'utf-8' encoding. If the C string pointer is NULL, the length is ignored and None is returned.

y (bytes) [const char *]

This converts a C string to a Python bytes object. If the C string pointer is NULL, None is returned.

y# (bytes) [const char *, int]

This converts a C string and its lengths to a Python object. If the C string pointer is NULL, None is returned.

z (str または None) [const char *]

s と同じです。

z# (str または None) [const char *, int]

s# と同じです。

u (str) [const wchar_t *]

Convert a null-terminated wchar_t buffer of Unicode (UTF-16 or UCS-4) data to a Python Unicode object. If the Unicode buffer pointer is NULL, None is returned.

u# (str) [const wchar_t *, int]

Convert a Unicode (UTF-16 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.

U (str または None) [const char *]

s と同じです。

U# (str または None) [const char *, int]

s# と同じです。

i (int) [int]

通常の C の int を Python の整数オブジェクトに変換します。

b (int) [char]

通常のC の char を Python の整数オブジェクトに変換します。

h (int) [short int]

通常のC の short int を Python の整数オブジェクトに変換します。

l (int) [long int]

C の long int を Python の整数オブジェクトに変換します。

B (int) [unsigned char]

C の unsigned char を Python の整数オブジェクトに変換します。

H (int) [unsigned short int]

C の unsigned short int を Python の整数オブジェクトに変換します。

I (int) [unsigned int]

C の unsigned int を Python の整数オブジェクトに変換します。

k (int) [unsigned long]

C の unsigned long を Python の整数オブジェクトに変換します。

L (int) [long long]

C long long をPythonのintオブジェクトへ変換する。

K (int) [unsigned long long]

C unsigned long long をPythonのintオブジェクトへ変換する。

n (int) [Py_ssize_t]

C の Py_ssize_t を Python の整数オブジェクトに変換します。

c (長さが 1 の bytes) [char]

バイトを表す通常の C の int を、長さ 1 の Python の bytes オブジェクトに変換します。

C (長さ 1 の str) [int]

文字を表す通常の C の int を、長さ 1 の Python の str オブジェクトに変換します。

d (float) [double]

C の double を Python の浮動小数点数に変換します。

f (float) [float]

C の float を Python の浮動小数点数に変換します。

D (complex) [Py_complex *]

C の Py_complex 構造体を Python の複素数型に変換します。

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, SystemError is set.

S (object) [PyObject *]

O と同じです。

N (object) [PyObject *]

O と同じです。ただし、オブジェクトの参照カウントをインクリメントしません。オブジェクトが引数リスト内のオブジェクトコンストラクタ呼び出しによって生成されている場合に便利です。

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]

C の値からなる配列を、同じ要素数を持つ Python のタプルに変換します。

[items] (list) [matching-items]

C の値からなる配列を、同じ要素数を持つ Python のリストに変換します。

{items} (dict) [matching-items]

C の値からなる配列を Python の辞書に変換します。一連のペアからなる C の値が、それぞれキーおよび値となって辞書に追加されます。

If there is an error in the format string, the SystemError exception is set and NULL returned.

PyObject* Py_VaBuildValue(const char *format, va_list vargs)
Return value: New reference.

Py_BuildValue() と同じですが、可変長引数の代わりに va_list を受け取ります。