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

These functions are useful when creating your own extension functions
and methods.  Additional information and examples are available in
Python インタプリタの拡張と埋め込み.

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


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

書式文字列は、ゼロ個またはそれ以上の "書式単位 (format unit)" から成り
立ちます。 1つの書式単位は1つの 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" 構造体。これはロッ
  クします 根底 バッファ これにより、呼び出し元はその後、バッファを内
  部でも使用できるようになります:c:type:*Py_BEGIN_ALLOW_THREADS*  ブロ
  ック リスクなしに 可変 データが再サイズ化または破壊される。その結果
  、**電話をかけなければならない** "PyBuffer_Release()" データ処理が完
  了した後（または早期終了の場合）。

* その "es", "es#", "et" そして "et#" フォーマットは結果を割り当てます
  バッファ. **必ず電話をかけてください** "PyMem_Free()" データ処理が完
  了した後（または早期終了の場合）。

* 他の形式では "str" または 読み出し専用 *bytes-like オブジェクト*、例
  えば   "bytes", および提供する "const char *" ポインタ その バッファ
  . この場合 バッファ「借用」されています：これは対応するPythonオブジ
  ェクトによって管理され、このオブジェクトのライフサイクルを共有します
  。メモリを自分で解放する必要はありません。

  以下のことを確実にするため 根底 バッファ 安全に借りることができます,
  対象の "PyBufferProcs.bf_releasebuffer" フィールドは必須です。
  "NULL". これは一般的な 可変 次のようなオブジェクト "bytearray", また
  、いくつかの 読み出し専用 次のようなオブジェクト "memoryview" の
  "bytes".

  これに加えて "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*", ただし、それは 借用された バッファ. 結果は2つのC変数
   に格納されます。最初の変数はC文字列へのポインター、2つ目の変数はそ
   の長さです。文字列には埋め込まれたヌルバイトが含まれる可能性があり
   ます。Unicodeオブジェクトは、C文字列に変換されます "'utf-8'" エンコ
   ード。

"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ポインタへのオブジェクトへの参照を拒否する
   borrowed 文字列; 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]
   This format accepts any object which implements the read-write
   buffer interface. It fills a "Py_buffer" structure provided by the
   caller. The buffer may contain embedded null bytes. The caller has
   to call "PyBuffer_Release()" when it is done with the buffer.

"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
   で終端されたエンコード名文字列を指す 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 で変更: "u", "u#", "Z", and "Z#" are removed because
they used a legacy "Py_UNICODE*" representation.


数
--

These formats allow representing Python numbers or single characters
as C numbers. Formats that require "int", "float" or "complex" can
also use the corresponding special methods "__index__()",
"__float__()" or "__complex__()" to convert the Python object to the
required type.

For signed integer formats, "OverflowError" is raised if the value is
out of range for the C type. For unsigned integer formats, no range
checking is done --- the most significant bits are silently truncated
when the receiving field is too small to receive the value.

"b" ("int") [unsigned char]
   Convert a nonnegative Python integer to an unsigned tiny integer,
   stored in a C unsigned char.

"B" ("int") [unsigned char]
   Convert a Python integer to a tiny integer without overflow
   checking, stored in a 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のintを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]
   Convert a Python floating-point number to a C float.

"d" ("float") [double]
   Convert a Python floating-point number to a C double.

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


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

"O" (object) [PyObject *]
   Python オブジェクトを（変換なしで）C オブジェクトのポインターに格納
   します。 これにより、C プログラムは渡された実際のオブジェクトを受け
   取ります。新しい :term: 強参照 オブジェクトが作成されていません （
   すなわち、その参照カウント 増加しません)。その ポインタ 保存されて
   いない "NULL".

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

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

      status = converter(object, address);

   ここで *object* は変換対象の Python オブジェクトで、 *address* は
   "PyArg_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.

   Examples of converters: "PyUnicode_FSConverter()" and
   "PyUnicode_FSDecoder()".

   バージョン 3.1 で変更: "Py_CLEANUP_SUPPORTED" was added.

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

   Added in version 3.3.

"(items)" (sequence) [*matching-items*]
   The object must be a Python sequence (except "str", "bytes" or
   "bytearray") whose length is the number of format units in *items*.
   The C arguments must correspond to the individual format units in
   *items*.  Format units for sequences may be nested.

   If *items* contains format units which store a borrowed buffer
   ("s", "s#", "z", "z#", "y", or "y#") or a *borrowed reference*
   ("S", "Y", "U", "O", or "O!"), the object must be a Python tuple.
   The *converter* for the "O&" format unit in *items* must not store
   a borrowed buffer or a borrowed reference.

   バージョン 3.14 で変更: "str" and "bytearray" objects no longer
   accepted as a sequence.

   バージョン 3.14 で非推奨: Non-tuple sequences are deprecated if
   *items* contains format units which store a borrowed buffer or a
   borrowed reference.

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

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

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

   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.*

   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 specified as
   null-terminated ASCII or UTF-8 encoded C strings. Empty names
   denote positional-only parameters. Returns true on success; on
   failure, it returns false and raises the appropriate exception.

   注釈:

     The *keywords* parameter declaration is char *const* in C and
     const char *const* in C++. This can be overridden with the
     "PY_CXX_CONST" macro.

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

   バージョン 3.13 で変更: The *keywords* parameter has now type char
   *const* in C and const char *const* in C++, instead of char**.
   Added support for non-ASCII keyword parameter names.

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.*

   Parse the parameter of a function that takes a single positional
   parameter into a local variable.  Returns true on success; on
   failure, it returns false and raises the appropriate exception.

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

      // Function using METH_O calling convention
      static PyObject*
      my_function(PyObject *module, PyObject *arg)
      {
          int value;
          if (!PyArg_Parse(arg, "i:my_function", &value)) {
              return NULL;
          }
          // ... use value ...
      }

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

   パラメーターの取得方法のよりシンプルな形式で、使用しないもの a 書式
   文字列 引数の型を指定する 。関数 これを使用する メソッド 彼らの パ
   ラメータ 次のように宣言する必要があります "METH_VARARGS" に 関数 に
   メソッド テーブル。実際のパラメーターを含むタプルは *args* として渡
   す必要があります。必ずタプルでなければなりません。タプルの長さは、
   *min*以上で*max*以下でなければなりません。*min*と*max*は等しい場合
   もあります。関数には追加の引数を渡す必要があり、各引数はポインター
   でなければならない ～へ:c:expr:`PyObject*` 変数；これらは*args*の値
   で埋められる；これらは:term:を含む :term:`借用参照 <borrowed
   reference>`。*args* で指定されていないオプションパラメーターに対応
   する変数は初期化されません。これらの変数は呼び出し元で初期化する必
   要があります。これ 関数 成功した場合にtrueを返し、>>*<<args*がタプ
   ルでない場合または要素の数が間違っている場合にfalseを返します。失敗
   した場合、例外が設定されます。

   これは、この関数の使用例で、ソースコードから抜粋したものです
   :mod:>>`<<!_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

   The value to be inserted, if any, before char *const* in the
   *keywords* parameter declaration of "PyArg_ParseTupleAndKeywords()"
   and "PyArg_VaParseTupleAndKeywords()". Default empty for C and
   "const" for C++ (const char *const*). To override, define it to the
   desired value before including "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]
      Convert a C int to a Python "bool" object.

      Be aware that this format requires an "int" argument. Unlike
      most other contexts in C, variadic arguments are not coerced to
      a suitable type automatically. You can convert another type (for
      example, a pointer or a float) to a suitable "int" value using
      "(x) ? 1 : 0" or "!!x".

      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]
      Convert a C double to a Python floating-point number.

   "f" ("float") [float]
      Convert a C float to a Python floating-point number.

   "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 を受け
   取ります。
