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

これらの関数は、独自の拡張関数やメソッドを作成するときに便利です。 追
加の情報や例は Python インタプリタの拡張と埋め込み を参照してください
。

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


引数を解析する
==============

書式文字列は、0 個以上の「書式単位 (format unit)」からなります。 書式
単位は一つの Python オブジェクトを記述し、通常は単一の文字か、複数の書
式単位を丸括弧で囲んだものです。 丸括弧で囲まれた並びでない書式単位は
、一部の例外を除き、これらの関数に渡す一つのアドレス引数に対応します。
以下の説明では、引用符で囲んだものが書式単位、丸括弧内が対応する
Python オブジェクトの型、角括弧内がアドレスを渡す C 変数の型です。


文字列とバッファ
----------------

注釈:

  Python 3.12 以前では、以下で説明された全ての "#" の種類 ("s#", "y#"
  など) を使用するために "PY_SSIZE_T_CLEAN" マクロを "Python.h" のイン
  クルードの前に定義しなければなりません。これは Python 3.13 以降では
  不要です。

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

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

文字列とバッファをCに変換する方法は3つあります：

* "y*" や "s*" などの形式は "Py_buffer" 構造体に情報を設定します。 こ
  れによって内部バッファがロックされるので、呼び出し側は
  "Py_BEGIN_ALLOW_THREADS" ブロック内でも、可変データのサイズ変更や破
  棄の危険なしにバッファを使えます。 そのため、データの処理が完了した
  ときや途中で中止したときは、"PyBuffer_Release()" を **必ず呼び出す必
  要があります**。

* "es"、"es#"、"et"、"et#" 形式は、結果を格納するバッファを割り当てま
  す。 データの処理が完了したときや途中で中止したときは、
  "PyMem_Free()" を **必ず呼び出す必要があります**。

* ほかの形式は "str" または "bytes" などの読み取り専用の *bytes-like
  オブジェクト* を受け取り、そのバッファへの "const char *" ポインタを
  提供します。 この場合、バッファは「借用」されます。 対応する Python
  オブジェクトが管理し、そのオブジェクトと寿命を共有します。 メモリを
  自分で解放する必要はありません。

  内部バッファを安全に借用できるように、オブジェクトの
  "PyBufferProcs.bf_releasebuffer" フィールドは "NULL" でなければなり
  ません。 この条件により、"bytearray" のような一般的な可変オブジェク
  トだけでなく、"bytes" の "memoryview" のような一部の読み取り専用オブ
  ジェクトも受け付けません。

  この "bf_releasebuffer" の要件以外に、入力オブジェクトが不変かどうか
  を確認するチェックはありません。 例えば、書き込み可能なバッファの要
  求に応じるかどうかや、別のスレッドがデータを変更できるかどうかは確認
  しません。

"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 *,
"Py_ssize_t"]
   "s*" と同様ですが、借用バッファ を提供します。 結果は二つの C 変数
   に格納され、一つ目は C 文字列へのポインタ、二つ目はその長さです。
   文字列にはヌルバイトが埋め込まれていても構いません。 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 *, "Py_ssize_t"]
   "s#" に似ていますが、Python オブジェクトは "None" でもよく、その場
   合には C のポインタは "NULL" にセットされます。

"y" (読み出し専用の *bytes-like object*) [const char *]
   bytes-like オブジェクトを、借用した 文字列への C ポインタに変換しま
   す。 Unicode オブジェクトは受け付けません。 バイトバッファにはヌル
   バイトを埋め込めません。 含まれている場合は "ValueError" 例外を送出
   します。

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

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

"y#" (読み出し専用の *bytes-like object*) [const char *, "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") [PyObject *]
   Python オブジェクトとして Unicode オブジェクトを要求し、いかなる変
   換も行いません。オブジェクトが Unicode オブジェクトではない場合、
   "TypeError" が送出されます。C変数は PyObject* として宣言しても構い
   ません。

"w*" (読み書き可能な *bytes-like object*) [Py_buffer]
   この形式は、読み書き可能なバッファインターフェースを実装する任意の
   オブジェクトを受け付けます。 呼び出し側が用意した "Py_buffer" 構造
   体に情報を設定します。 バッファにはヌルバイトが埋め込まれていても構
   いません。 呼び出し側は、バッファを使い終わったら
   "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, "Py_ssize_t"
*buffer_length]
   "s#" の変種で、Unicode を文字バッファにエンコードするために使います
   。 "es" 形式と異なり、NUL 文字を含む入力データを受け付けます。

   この書式には三つの引数が必要です。一つ目は入力にのみ用いられ、 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, "Py_ssize_t" *buffer_length]
   "es#" と同じです。ただし、バイト文字列オブジェクトをエンコードし直
   さずに渡します。その代わり、実装ではバイト文字列オブジェクトがパラ
   メタに渡したエンコードを使っているものと仮定します。

バージョン 3.12 で変更: 従来の "Py_UNICODE*" 表現を使っていたため、"u"
、"u#"、"Z"、"Z#" を削除しました。


数
--

これらの形式は、Python の数値や単一の文字を C の数値として表すためのも
のです。 "int"、"float"、"complex" を必要とする形式では、対応する特殊
メソッド "__index__()"、"__float__()"、"__complex__()" で Python オブ
ジェクトを必要な型に変換することもできます。

For signed integer formats, "OverflowError" is raised if the value is
out of range for the C type. For unsigned integer formats, the most
significant bits are silently truncated when the receiving field is
too small to receive the value, and "DeprecationWarning" is emitted
when the value is larger than the maximal value for the C type or less
than the minimal value for the corresponding signed integer type of
the same size.

"b" ("int") [unsigned char]
   負でない Python 整数を小さい符号なし整数に変換し、C の unsigned
   char に格納します。

"B" ("int") [unsigned char]
   Python 整数を、オーバーフローチェックなしに小さい整数に変換し、C の
   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 に変換します。

   バージョン 3.14 で変更: 可能であれば "__index__()" を使うようになり
   ました。

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

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

   バージョン 3.14 で変更: 可能であれば "__index__()" を使うようになり
   ました。

"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" 構造体に変換します。

バージョン 3.15 で非推奨: 符号なし整数の形式 "B"、"H"、"I"、"k"、"K"
では、値が C の型の最大値を超える場合、または同じサイズの対応する符号
付き整数型の最小値より小さい場合に "DeprecationWarning" を発生させます
。


その他のオブジェクト
--------------------

"O" (object) [PyObject *]
   Python オブジェクトを変換せずに C オブジェクトのポインタに格納しま
   す。これにより、C プログラムは渡されたオブジェクトそのものを受け取
   ります。オブジェクトへの新しい *強参照* は作成されません（つまり、
   参照カウントは増加しません）。格納されるポインタは "NULL" ではあり
   ません。

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

"O&" (オブジェクト) [*converter*, *address*]
   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" を返した場合、後で引数の解析
   に失敗すると、すでに割り当てたメモリを解放できるように再び呼び出さ
   れることがあります。 この 2 回目の呼び出しでは、"object" 引数は
   "NULL"、"address" は最初の呼び出しと同じ値になります。

   変換関数の例: "PyUnicode_FSConverter()" と "PyUnicode_FSDecoder()"
   。

   バージョン 3.1 で変更: "Py_CLEANUP_SUPPORTED" を追加しました。

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

   Added in version 3.3.

"(items)" (シーケンス) [*matching-items*]
   オブジェクトは、長さが "items" 内の書式単位の数と等しい Python のシ
   ーケンスでなければなりません ("str"、"bytes"、"bytearray" は除きま
   す)。 C の引数は "items" 内の各書式単位に対応している必要があります
   。 シーケンスの書式単位はネストできます。

   "items" に 借用バッファ ("s"、"s#"、"z"、"z#"、"y"、"y#") または *
   借用参照* ("S"、"Y"、"U"、"O"、"O!") を格納する書式単位が含まれる場
   合、オブジェクトは Python のタプルでなければなりません。 "items" 内
   の "O&" 書式単位の "converter" は、借用バッファや借用参照を格納して
   はいけません。

   バージョン 3.14 で変更: "str" と "bytearray" オブジェクトをシーケン
   スとして受け付けなくなりました。

   バージョン 3.14 で非推奨: "items" に借用バッファまたは借用参照を格
   納する書式単位が含まれる場合、タプル以外のシーケンスは非推奨になり
   ました。

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

"|"
   Python の引数リストの残りの引数が省略可能であることを示します。 省
   略可能な引数に対応する C 変数は、デフォルト値で初期化しておく必要が
   あります。 引数が省略された場合、"PyArg_ParseTuple()" は対応する C
   変数の内容を変更しません。 例えば、書式文字列 ""OO|OO"" は Python
   のシグネチャ "f(a, b, c=None, d=None)" に対応します。

"$"
   "PyArg_ParseTupleAndKeywords()" のみ: Python の引数リストの残りの引
   数がキーワード専用であることを示します。 "$" より前に "|" があれば
   省略可能で、なければ必須です。 "$" より後に "|" は指定できません。
   例えば書式文字列 ""O|O$O"" は Python のシグネチャ "f(a, b=None, *,
   c=None)" に対応し、""OO$OO"" は "f(a, b, *, c, d)" に対応します。

   Added in version 3.3.

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

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

注意：呼び出し元に渡されるPythonオブジェクトの参照はすべて*借用*された
参照です。これらを解放しないでください（つまり、参照カウントを減らさな
いでください）！

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

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


API 関数
--------

int PyArg_ParseTuple(PyObject *args, const char *format, ...)
    * 次に属します: Stable ABI.*

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

int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)
    * 次に属します: Stable ABI.*

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

int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *keywords, ...)
    * 次に属します: Stable ABI.*

   位置引数とキーワード引数を受け取る関数の引数を解析し、ローカル変数
   に格納します。 "keywords" 引数は、ヌル終端の ASCII または UTF-8 エ
   ンコード C 文字列で指定された仮引数名の配列で、"NULL" で終端する必
   要があります。 空の名前は 位置専用仮引数 を表します。 成功した場合
   は真を返し、失敗した場合は適切な例外を送出して偽を返します。

   注釈:

     "keywords" 引数の宣言は、C では char *const*、C++ では const char
     *const* です。 "PY_CXX_CONST" マクロで変更できます。

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

   バージョン 3.13 で変更: "keywords" 引数の型は char** ではなく、C で
   は char *const*、C++ では const char *const* になりました。 非
   ASCII のキーワード仮引数名をサポートするようになりました。

int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *const *keywords, va_list vargs)
    * 次に属します: Stable ABI.*

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

int PyArg_ValidateKeywordArguments(PyObject*)
    * 次に属します: Stable ABI.*

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

   Added in version 3.2.

int PyArg_Parse(PyObject *args, const char *format, ...)
    * 次に属します: Stable ABI.*

   一つの位置引数を受け取る関数の引数を解析し、ローカル変数に格納しま
   す。 成功した場合は真を返し、失敗した場合は適切な例外を送出して偽を
   返します。

   以下はプログラム例です:

      // METH_O 呼び出し規約を使う関数
      static PyObject*
      my_function(PyObject *module, PyObject *arg)
      {
          int value;
          if (!PyArg_Parse(arg, "i:my_function", &value)) {
              return NULL;
          }
          // ... value を使う ...
      }

int PyArg_ParseArray(PyObject *const *args, Py_ssize_t nargs, const char *format, ...)

   配列形式の引数だけを受け取る関数 (つまり "METH_FASTCALL" 呼び出し規
   約の関数) の引数を解析し、ローカル変数に格納します。 成功した場合は
   真を返し、失敗した場合は適切な例外を送出して偽を返します。

   Added in version 3.15.

int PyArg_ParseArrayAndKeywords(PyObject *const *args, Py_ssize_t nargs, PyObject *kwnames, const char *format, const char *const *kwlist, ...)

   配列形式の引数とキーワード引数を受け取る関数 (つまり
   "METH_FASTCALL" "|" "METH_KEYWORDS" 呼び出し規約の関数) の引数を解
   析し、ローカル変数に格納します。 成功した場合は真を返し、失敗した場
   合は適切な例外を送出して偽を返します。

   Added in version 3.15.

int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
    * 次に属します: Stable ABI.*

   引数の型を指定する書式文字列を使わない、より単純な引数の取得方法で
   す。 この方法で引数を取得する関数は、関数テーブルやメソッドテーブル
   で "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)

PY_CXX_CONST

   "PyArg_ParseTupleAndKeywords()" と
   "PyArg_VaParseTupleAndKeywords()" の "keywords" 引数の宣言で、char
   *const* の前に挿入する値を指定します。 デフォルトは C では空、C++
   では "const" です (const char *const*)。 変更するには "Python.h" を
   インクルードする前に、必要な値を定義してください。

   Added in version 3.13.


値の構築
========

PyObject *Py_BuildValue(const char *format, ...)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

   "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" or "None") [const char *, "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 *, "Py_ssize_t"]
      これは C 文字列とその長さから Python オブジェクトに変換します。C
      文字列ポインタが "NULL" の場合、長さは無視され "None" になります
      。

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

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

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

   "U#" ("str" または "None") [const char *, "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 の整数オブジェクトに変換します。

   "K" ("int") [unsigned long long]
      C unsigned long long をPythonのintオブジェクトへ変換する。

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

   "p" ("bool") [int]
      C の int を Python の "bool" オブジェクトに変換します。

      この形式には "int" 引数が必要です。 C のほかの多くの場面と異なり
      、可変長引数は適切な型に自動変換されません。 ポインタや浮動小数
      点数など別の型は、"(x) ? 1 : 0" または "!!x" で適切な "int" 値に
      変換できます。

      Added in version 3.14.

   "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)
    *戻り値: 新しい参照。** 次に属します: Stable ABI.*

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