引数の解釈と値の構築
********************

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

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

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

以下のフォーマットはオブジェクトに連続したメモリチャンクとしてアクセス
するためのものです。返される unicode や bytes のために生のストレージを
用意する必要はありません。また、"es",  "es#", "et", "et#" フォーマット
の場合を除いて自分でメモリを解放する必要もありません。

"s" (文字列型または Unicode 型) [const char *]
   Python の文字列または Unicode オブジェクトを、キャラクタ文字列を指
   す C のポインタに変換します。変換先の文字列自体の記憶領域を提供する
   必要はありません; キャラクタ型ポインタ変数のアドレスを渡すと、すで
   に存在している文字列へのポインタをその変数に記録します。C 文字列は
   NUL で終端されています。Python の文字列型は、NUL バイトが途中に埋め
   込まれていてはなりません; もし埋め込まれていれば "TypeError" 例外を
   送出します。Unicode オブジェクトはデフォルトエンコーディングを使っ
   て C 文字列に変換されます。変換に失敗すると "UnicodeError" を送出し
   ます。

"s#" (文字列型、Unicode 型または任意の読み出しバッファ互換型) [const
char *, int (または "Py_ssize_t", 下記参照)]
   これは "s" の変化形で、値を二つの変数に記録します。一つ目の変数はキ
   ャラクタ文字列へのポインタで、二つ目はその長さです。この書式化単位
   の場合には、Python 文字列に null バイトが埋め込まれていてもかまいま
   せん。 Unicode オブジェクトの場合、デフォルトエンコーディングでの変
   換が可能ならば、変換したオブジェクトから文字列へのポインタを返しま
   す。その他の読み出しバッファ互換オブジェクトは生の内部データ表現へ
   の参照を返します。

   Python 2.5 から、長さの引数の型を、 "Python.h" を include する前に
   "PY_SSIZE_T_CLEAN" マクロを定義することで制御できるようになりました
   。もしこのマクロが定義されていた場合、長さは int ではなく
   "Py_ssize_t" になります。

"s*" (文字列型、Unicode 型、または任意のバッファ互換オブジェクト)
[Py_buffer]
   "s#" と似ていますが、呼び出し元から渡された Py_buffer 構造体に書き
   込みます。バッファーはロックされるので、呼び出し元はそのバッファー
   を "Py_BEGIN_ALLOW_THREADS" したブロック内でさえも利用することがで
   きます。その代わり、呼び出し元には、データを処理した後にその構造体
   に対して "PyBuffer_Release" する責任があります。

   バージョン 2.6 で追加.

"z" (文字列型または Unicode 型または "None") [const char *]
   "s" に似ていますが、Python オブジェクトは "None" でもよく、その場合
   には C のポインタは *NULL* にセットされます。

"z#" (文字列型、 "None" 、または任意の読み出しバッファ互換型) [const
char *, int]
   "s#" の "s" を "z" にしたような意味です。

"z*" (文字列型、Unicode型、 "None" または任意のバッファ互換型)
[Py_buffer]
   "s*" の "s" を "z" にしたような意味です。

   バージョン 2.6 で追加.

"u" (Unicode 型) [Py_UNICODE *]
   Python の Unicode オブジェクトを、NUL で終端された 16 ビットの
   Unicode (UTF-16) データに変換します。 "s" と同様に、 Unicode データ
   バッファ用に記憶領域を提供する必要はありません; "Py_UNICODE" 型ポイ
   ンタ変数のアドレスを渡すと、すでに存在している Unicode データへのポ
   インタをその変数に記録します。

"u#" (Unicode 型) [Py_UNICODE *, int]
   これは "u" の変化形で、値を二つの変数に記録します。一つ目の変数は
   Unicode データバッファへのポインタで、二つ目はその長さです。非
   Unicode のオブジェクトの場合、読み出しバッファのポインタを
   "Py_UNICODE" 型シーケンスへのポインタと解釈して扱います。

"es" (文字列型、Unicode 型またはキャラクタバッファ互換型) [const char
*encoding, char **buffer]
   これは "s" の変化形で、Unicode オブジェクトや Unicode に変換可能な
   オブジェクトをキャラクタ型バッファにエンコードするために用いられま
   す。NUL バイトが埋め込まれていない文字列でのみ動作します。

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

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

"et" (文字列型、Unicode 型またはキャラクタバッファ互換型) [const char
*encoding, char **buffer]
   "es" と同じです。ただし、8 ビット幅の文字列オブジェクトをエンコード
   し直さずに渡します。その代わり、実装では文字列オブジェクトがパラメ
   タに渡したエンコードを使っているものと仮定します。

"es#" (文字列型、Unicode 型またはキャラクタバッファ互換型) [const char
*encoding, char **buffer, int *buffer_length]
   "s#" の変化形で、Unicode オブジェクトや Unicode に変換可能なオブジ
   ェクトをキャラクタ型バッファにエンコードするために用いられます。
   "es" 書式化単位と違って、この変化形はバイトが埋め込まれていてもかま
   いません。

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

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

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

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

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

"et#" (文字列型、Unicode 型またはキャラクタバッファ互換型) [const char
*encoding, char **buffer, int *buffer_length]
   "es#" と同じです。ただし、文字列オブジェクトをエンコードし直さずに
   渡します。その代わり、実装では文字列オブジェクトがパラメタに渡した
   エンコードを使っているものと仮定します。

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

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

   バージョン 2.3 で追加.

"h" (整数型) [short int]
   Python の整数を、 C の "short int" 型に変換します。

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

   バージョン 2.3 で追加.

"i" (整数型) [int]
   Python の整数を、 C の "int" 型に変換します。

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

   バージョン 2.3 で追加.

"l" (整数型) [long int]
   Python の整数を、 C の "long int" 型に変換します。

"k" (整数型) [unsigned long]
   Python の整数もしくは長整数を、オーバフローチェックを行わずに、 C
   の "unsigned long int" 型に変換します。

   バージョン 2.3 で追加.

"L" (整数型) [PY_LONG_LONG]
   Python の整数を、 C の "long long" 型に変換します。この書式化単位は
   、 "long long" 型 (または Windows の "_int64" 型) がサポートされて
   いるプラットフォームでのみ利用できます。

"K" (整数型) [unsigned PY_LONG_LONG]
   Python の整数もしくは長整数を、オーバフローチェックを行わずに、 C
   の "unsigned long long" 型に変換します。この書式化単位は、
   "unsigned long long" 型 (または Windows の "unsigned _int64" 型) が
   サポートされているプラットフォームでのみ利用できます。

   バージョン 2.3 で追加.

"n" (整数型) [Py_ssize_t]
   Python の整数もしくは長整数を C の "Py_ssize_t" 型に変換します。

   バージョン 2.5 で追加.

"c" (長さ 1 の文字列型) [char]
   長さ 1 の文字列として表現されている Python キャラクタを C の "char"
   型に変換します。

"f" (浮動小数点数型) [float]
   Python の浮動小数点型を、 C の "float" 型に変換します。

"d" (浮動小数点数型) [double]
   Python の浮動小数点型を、 C の "double" 型に変換します。

"D" (複素数型) [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* の内容を変更せずに例外を送
   出しなくてはなりません。

"S" (文字列型) [PyStringObject *]
   "O" に似ていますが、Python オブジェクトは文字列オブジェクトでなけれ
   ばなりません。オブジェクトが文字列オブジェクトでない場合には
   "TypeError" を送出します。 C 変数は "PyObject*" で宣言しておいても
   かまいません。

"U" (Unicode 型) [PyUnicodeObject *]
   "O" に似ていますが、Python オブジェクトは Unicode オブジェクトでな
   ければなりません。オブジェクトが Unicode オブジェクトでない場合には
   "TypeError" を送出します。 C 変数は "PyObject*" で宣言しておいても
   かまいません。

"t#" (読み出し専用キャラクタバッファ) [char *, int]
   "s#" に似ていますが、読み出し専用バッファインタフェースを実装してい
   る任意のオブジェクトを受理します。 "char*" 変数はバッファの最初のバ
   イトを指すようにセットされ、 "int" はバッファの長さにセットされます
   。単一セグメントからなるバッファオブジェクトだけを受理します; それ
   以外の場合には "TypeError" を送出します。

"w" (読み書き可能なキャラクタバッファ) [char *]
   "s" と同様ですが、読み書き可能なバッファインタフェースを実装してい
   る任意のオブジェクトを受理します。呼び出し側は何らかの別の手段でバ
   ッファの長さを決定するか、あるいは "w#" を使わねばなりません。単一
   セグメントからなるバッファオブジェクトだけを受理します; それ以外の
   場合には "TypeError" を送出します。

"w#" (読み書き可能なキャラクタバッファ) [char *, Py_ssize_t]
   "s#" に似ていますが、読み書き可能なバッファインタフェースを実装して
   いる任意のオブジェクトを受理します。 "char*" 変数はバッファの最初の
   バイトを指すようにセットされ、 "Py_ssize_t" はバッファの長さにセッ
   トされます。単一セグメントからなるバッファオブジェクトだけを受理し
   ます; それ以外の場合には "TypeError" を送出します。

"w*" (読み書き可能なバイト列バッファ) [Py_buffer]
   "s" に対する "s*" と同じ、 "w" のバージョンです。

   バージョン 2.6 で追加.

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

   注釈: Python のバージョン 1.5.2 より以前は、この書式化指定文字列
     はパラ メタ列ではなく、個別のパラメタが入ったタプルでなければなり
     ません でした。このため、以前は "TypeError" を引き起こしていたよ
     うなコー ドが現在は例外を出さずに処理されるかもしれません。とはい
     え、既存 のコードにとってこれは問題ないと思われます。

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

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

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

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

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

呼び出し側に提供される Python オブジェクトの参照は全て *借りた
(borrowed)* ものです; オブジェクトの参照カウントをデクリメントしてはな
りません!

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

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

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[], ...)

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

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

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

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

   "旧スタイル" の関数における引数リストを分析するために使われる関数で
   す --- 旧スタイルの関数は、引数解釈手法に "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)

   バージョン 2.2 で追加.

   バージョン 2.5 で変更: この関数は *min* と *max* に "int" を利用し
   ていました。この変更により、64 bitシステムを正しくサポートするため
   には修正が必要になるでしょう。

PyObject* Py_BuildValue(const char *format, ...)
    *Return value: New reference.*

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

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

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

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

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

   "s" (文字列型) [char *]
      null 終端された C 文字列から Python オブジェクトに変換します。 C
      文字列ポインタが *NULL* の場合、 "None" になります。

   "s#" (文字列型) [char *, int]
      C 文字列とその長さから Python オブジェクトに変換します。 C 文字
      列ポインタが *NULL* の場合、長さは無視され "None" になります。

   "z" (文字列型または "None") [char *]
      "s" と同じです。

   "z#" (文字列型または "None") [char *, int]
      "s#" と同じです。

   "u" (Unicode 文字列型) [Py_UNICODE *]
      null 終端された Unicode (UCS-2 または UCS-4) データのバッファか
      ら Python Unicode オブジェクトに変換します。 Unicode バッファポ
      インタが *NULL* の場合、 "None" になります。

   "u#" (Unicode 文字列型) [Py_UNICODE *, int]
      Unicode (UCS-2 または UCS-4) データのバッファとその長さから
      Python Unicode オブジェクトに変換します。 Unicode バッファポイン
      タが *NULL* の場合、長さは無視され "None" になります。

   "i" (整数型) [int]
      通常の C の "int" を Python の整数オブジェクトに変換します。

   "b" (整数型) [char]
      通常のC の "char" を Python の整数オブジェクトに変換します。

   "h" (整数型) [short int]
      通常のC の "short int" を Python の整数オブジェクトに変換します
      。

   "l" (整数型) [long int]
      C の "long int" を Python の整数オブジェクトに変換します。

   "B" (整数型) [unsigned char]
      C の "unsigned char" を Python の整数オブジェクトに変換します。

   "H" (整数型) [unsigned short int]
      C の "unsigned short int" を Python の整数オブジェクトに変換しま
      す。

   "I" (整数型/長整数型) [unsigned int]
      C の "unsigned int" を Python の整数オブジェクト、あるいは、値が
      "sys.maxint" より大きければ長整数オブジェクトに変換します。

   "k" (整数型/長整数型) [unsigned long]
      C の "unsigned long" を Python の整数オブジェクト、あるいは、値
      が "sys.maxint" より大きければ長整数オブジェクトに変換します。

   "L" (長整数型) [PY_LONG_LONG]
      C の "long long" を Python の長整数オブジェクトに変換します。
      "long long" をサポートしているプラットフォームでのみ利用可能です
      。

   "K" (長整数型) [unsigned PY_LONG_LONG]
      C の "unsigned long long" を Python の長整数オブジェクトに変換し
      ます。 "long long" をサポートしているプラットフォームでのみ利用
      可能です。

   "n" (整数型) [Py_ssize_t]
      C の "Py_ssize_t" を Python の整数オブジェクト、あるいは長整数オ
      ブジェクトに変換します。

      バージョン 2.5 で追加.

   "c" (長さ 1 の文字列型) [char]
      文字を表す通常の C の "int" を、長さ 1 の Python の文字列オブジ
      ェクトに変換します。

   "d" (浮動小数点数型) [double]
      C の "double" を Python の浮動小数点数に変換します。

   "f" (浮動小数点数型) [float]
      "d" と同じです。

   "D" (複素数型) [Py_complex *]
      C の "Py_complex" 構造体を Python の複素数型に変換します。

   "O" (object) [PyObject *]
      Python オブジェクトを手を加えずに渡します (ただし、参照カウント
      は 1 インクリメントします)。渡したオブジェクトが *NULL* ポインタ
      の場合、この引数を生成するのに使った何らかの呼び出しがエラーにな
      ったのが原因であると仮定して、例外をセットします。従ってこのとき
      "Py_BuildValue()" は *NULL* を返しますが "Py_BuildValue()" 自体
      は例外を送出しません。例外をまだ送出していなければ "SystemError"
      をセットします。

   "S" (object) [PyObject *]
      "O" と同じです。

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

   "O&" (object) [*converter*, *anything*]
      *anything* を *converter* 関数を介して Python オブジェクトに変換
      します。この関数は *anything* ("void *" と互換の型でなければなり
      ません) を引数にして呼び出され、"新たな" オブジェクトを返すか、
      失敗した場合には *NULL* を返すようにしなければなりません。

   "(items)" (タプル型) [*matching-items*]
      C の値からなる配列を、同じ要素数を持つ Python のタプルに変換しま
      す。

   "[items]" (リスト型) [*matching-items*]
      C の値からなる配列を、同じ要素数を持つ Python のリストに変換しま
      す。

   "{items}" (辞書型) [*matching-items*]
      C の値からなる配列を Python の辞書に変換します。一連のペアからな
      る C の値が、それぞれキーおよび値となって辞書に追加されます。

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

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

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