引数の解釈と値の構築

これらの関数は独自の拡張モジュール用の関数やメソッドを作成する際に便利です。詳しい情報や用例は 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 終端されていません。

いくつかのフォーマットは読み込み専用の bytes-like オブジェクト を必要とし、バッファ構造体の代わりにポインタをセットします。それらは、オブジェクトの PyBufferProcs.bf_releasebuffer フィールドが NULL であることをチェックして動きます。これは 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& フォーマットを、 converter に PyUnicode_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 *]
s に似ていますが、Python オブジェクトは None でもよく、その場合には C のポインタは NULL にセットされます。
z* (str, bytes-like object または None) [Py_buffer]
s* と同じですが、 Python の None オブジェクトを受け取ることができます。その場合、 Py_buffer 構造体の buf メンバーは NULL になります。
z# (str, 読み出し専用の bytes-like object または None) [const char *, int]
s# に似ていますが、Python オブジェクトは None でもよく、その場合には C のポインタは 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) [Py_UNICODE *]

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

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

バージョン 3.3 で非推奨、バージョン 4.0 で削除予定: Part of the old-style Py_UNICODE API; please migrate to using PyUnicode_AsWideCharString().

u# (str) [Py_UNICODE *, int]

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

バージョン 3.3 で非推奨、バージョン 4.0 で削除予定: Part of the old-style Py_UNICODE API; please migrate to using PyUnicode_AsWideCharString().

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

u に似ていますが、Python オブジェクトは None でもよく、その場合には Py_UNICODE ポインタは NULL にセットされます。

バージョン 3.3 で非推奨、バージョン 4.0 で削除予定: Part of the old-style Py_UNICODE API; please migrate to using PyUnicode_AsWideCharString().

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

u# に似ていますが、 Python オブジェクトは None でもよく、その場合には Py_UNICODE ポインタは NULL にセットされます。

バージョン 3.3 で非推奨、バージョン 4.0 で削除予定: Part of the old-style Py_UNICODE API; please migrate to using 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バイトが埋め込まれていないデータでのみ動作します。

この書式には二つの引数が必要です。一つ目は入力にのみ用いられ、 NUL で終端されたエンコード名文字列を指す const char* 型または、 'utf-8' が使われることを表す NULL でなければなりません。指定したエンコード名を Python が理解できない場合には例外を送出します。第二の引数は char** でなければなりません; この引数が参照しているポインタの値は、引数に指定したテキストの内容が入ったバッファへのポインタになります。テキストは最初の引数に指定したエンコード方式でエンコードされます。

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 書式違って、この変化形はバイトが埋め込まれていてもかまいません。

この書式には三つの引数が必要です。一つ目は入力にのみ用いられ、 NUL で終端されたエンコード名文字列を指す const char* 型か NULL でなければなりません。 NULL の場合には 'utf-8' を使います。指定したエンコード名を Python が理解できない場合には例外を送出します。第二の引数は char** でなければなりません; この引数が参照しているポインタの値は、引数に指定したテキストの内容が入ったバッファへのポインタになります。テキストは最初の引数に指定したエンコード方式でエンコードされます。第三の引数は整数へのポインタでなければなりません; ポインタが参照している整数の値は出力バッファ内のバイト数にセットされます。

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

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

*buffer が非 NULL のポインタ (すでにメモリ確保済みのバッファ) を指している場合、 PyArg_ParseTuple() はこのメモリ位置をバッファとして用い、 *buffer_length の初期値をバッファサイズとして用います。 PyArg_ParseTuple は次にエンコード済みのデータをバッファにコピーして、NUL で終端します。バッファの大きさが足りなければ ValueError がセットされます。

どちらの場合も、 *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 *]
Python オブジェクトを (一切変換を行わずに) C の Python オブジェクト型ポインタに保存します。これにより、C プログラムは実際のオブジェクトを受け渡しされます。オブジェクトの参照カウントは増加しません。保存されるポインタが 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 オブジェクトで、 address は PyArg_Parse*() に渡した void* 型の引数です。戻り値 status は変換に成功した際に 1,失敗した場合には 0 になります。変換に失敗した場合、 converter 関数は address の内容を変更せずに例外を送出しなくてはなりません。

もし converter が Py_CLEANUP_SUPPORTED を返すと、引数のパースが失敗した際に、コンバーターをもう一度呼び出し、すでに割り当てたメモリを開放するチャンスを与えます。二度目の呼び出しでは object 引数は NULL になり、address は最初の呼び出しと同じ値になります。

バージョン 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[], ...)

位置引数とキーワード引数の両者を取る関数の引数を解釈します。 keywords 引数は NULL で終端されたキーワード名の配列です。 空の名前は 位置引数のみ を示します。成功した場合、真を返します。失敗した場合は偽を返し、また適切な例外を発生させます。

バージョン 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 を超えてはなりません; min と max が等しくてもかまいません。補助引数を関数に渡さなければならず、各補助引数は 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.

PyArg_Parse*() ファミリの関数が受け取るのと似た形式の書式文字列および値列に基づいて、新たな値を生成します。生成した値を返します。エラーの場合には NULL を返します; NULL を返す場合、例外を送出するでしょう。

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

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

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

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

s (str または None) [char *]
null終端された C 文字列を、 'utf-8' エンコーディングを用いて、 Python str オブジェクトに変換します。もし C 文字列ポインタが NULL の場合、 None になります。
s# (str または None) [char *, int]
C 文字列とその長さを 'utf-8' エンコーディングを使って Python str オブジェクトに変換します。C 文字列ポインタが NULL の場合、長さは無視され、 None になります。
y (bytes) [char *]
C 文字列をPython bytes オブジェクトに変換します。もしC 文字列ポインタが NULL だった場合、None を返します。
y# (bytes) [char *, int]
これは C 文字列とその長さから Python オブジェクトに変換します。C 文字列ポインタが NULL の場合、長さは無視され None になります。
z (str または None) [char *]
s と同じです。
z# (str または None) [char *, int]
s# と同じです。
u (str) [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) [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) [char *]
s と同じです。
U# (str または None) [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 *]
Python オブジェクトを手を加えずに渡します (ただし、参照カウントは 1 インクリメントします)。渡したオブジェクトが NULL ポインタの場合、この引数を生成するのに使った何らかの呼び出しがエラーになったのが原因であると仮定して、例外をセットします。従ってこのとき Py_BuildValue() は NULL を返しますが例外は送出しません。例外をまだ送出していなければ SystemError をセットします。
S (object) [PyObject *]
O と同じです。
N (object) [PyObject *]
O と同じです。ただし、オブジェクトの参照カウントをインクリメントしません。オブジェクトが引数リスト内のオブジェクトコンストラクタ呼び出しによって生成されている場合に便利です。
O& (object) [converter, anything]
anything を converter 関数を介して Python オブジェクトに変換します。この関数は anything (void * と互換の型でなければなりません) を引数にして呼び出され、"新たな" オブジェクトを返すか、失敗した場合には NULL を返すようにしなければなりません。
(items) (tuple) [matching-items]
C の値からなる配列を、同じ要素数を持つ Python のタプルに変換します。
[items] (list) [matching-items]
C の値からなる配列を、同じ要素数を持つ Python のリストに変換します。
{items} (dict) [matching-items]
C の値からなる配列を Python の辞書に変換します。一連のペアからなる C の値が、それぞれキーおよび値となって辞書に追加されます。

書式文字列に関するエラーが生じると、 SystemError 例外をセットして NULL を返します。

PyObject* Py_VaBuildValue(const char *format, va_list vargs)

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