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

これらの関数は独自の拡張モジュール用の関数やメソッドを作成する際に便利
です。詳しい情報や用例は 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 or "Py_ssize_t"]
   "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 or
"Py_ssize_t"]
   "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 3.12: 古い
   スタイルの "Py_UNICODE" APIの一部です。
   "PyUnicode_AsWideCharString()" を使用するように移行してください。

"u#" ("str") [const Py_UNICODE *, int または "Py_ssize_t"]
   これは "u" のバリエーションで、値を二つの変数に記録します。一つ目の
   変数は Unicode データバッファへのポインタで、二つ目はその長さです。
   このフォーマットは null コードポイントを含むことができます。

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

"Z" ("str" または "None") [const Py_UNICODE *]
   "u" に似ていますが、Python オブジェクトは "None" でもよく、その場合
   には "Py_UNICODE" ポインタは "NULL" にセットされます。

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

"Z#" ("str" または "None") [const Py_UNICODE *, int または
"Py_ssize_t"]
   "u#" に似ていますが、 Python オブジェクトは "None" でもよく、その場
   合には "Py_UNICODE" ポインタは "NULL" にセットされます。

   Deprecated since version 3.3, will be removed in version 3.12: 古い
   スタイルの "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バイトが埋め込まれていないデータでのみ動作
   します。

   この書式には二つの引数が必要です。一つ目は入力にのみ用いられ、 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 または
"Py_ssize_t" *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 または "Py_ssize_t" *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 **p**redicate) に渡された値を判定
   し、その結果を等価な 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引数が
   キーワード専用であることを示します。 現在、すべてのキーワード専用引
   数は任意の引数でなければならず、そのため フォーマット文字列中の "|"
   は常に "$" より前に指定されなければなりません。

   バージョン 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") [const char *]
      null終端された C 文字列を、 "'utf-8'" エンコーディングを用いて、
      Python "str" オブジェクトに変換します。もし C 文字列ポインタが
      "NULL" の場合、 "None" になります。

   "s#" ("str" または "None") [const char *, int または "Py_ssize_t"]
      C 文字列とその長さを "'utf-8'" エンコーディングを使って Python
      "str" オブジェクトに変換します。C 文字列ポインタが "NULL" の場合
      、長さは無視され、 "None" になります。

   "y" ("bytes") [const char *]
      C 文字列をPython "bytes" オブジェクトに変換します。もしC 文字列
      ポインタが "NULL" だった場合、"None" を返します。

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

   "z" ("str" または "None") [const char *]
      "s" と同じです。

   "z#" ("str" または "None") [const char *, int または "Py_ssize_t"]
      "s#" と同じです。

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

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

   "U" ("str" または "None") [const char *]
      "s" と同じです。

   "U#" ("str" または "None") [const char *, int または "Py_ssize_t"]
      "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)
    *Return value: New reference.*

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