# 引数の解釈と値の構築

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

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

## 引数を解析する

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

### 文字列とバッファ

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

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

There are three ways strings and buffers can be converted to C:

- Formats such as `y*` and `s*` fill a `Py_buffer` structure. This locks the underlying buffer so that the caller can subsequently use the buffer even inside a `Py_BEGIN_ALLOW_THREADS` block without the risk of mutable data being resized or destroyed. As a result, you have to call `PyBuffer_Release()` after you have finished processing the data (or in any early abort case).

- The `es`, `es#`, `et` and `et#` formats allocate the result buffer. You have to call `PyMem_Free()` after you have finished processing the data (or in any early abort case).

- Other formats take a `str` or a read-only bytes-like object, such as `bytes`, and provide a `const char *` pointer to its buffer. In this case the buffer is "borrowed": it is managed by the corresponding Python object, and shares the lifetime of this object. You won't have to release any memory yourself.

  To ensure that the underlying buffer may be safely borrowed, the object's `PyBufferProcs.bf_releasebuffer` field must be `NULL`. This disallows common mutable objects such as `bytearray`, but also some read-only objects such as `memoryview` of `bytes`.

  Besides this `bf_releasebuffer` requirement, there is no check to verify whether the input object is immutable (e.g. whether it would honor a request for a writable buffer, or whether another thread can mutate the data).

注釈

For all `#` variants of formats (`s#`, `y#`, etc.), the macro `PY_SSIZE_T_CLEAN` must be defined before including `Python.h`. On Python 3.9 and older, the type of the length argument is `Py_ssize_t` if the `PY_SSIZE_T_CLEAN` macro is defined, or int otherwise.

`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`]

  Like `s*`, except that it provides a borrowed buffer. The result is stored into two C variables, the first one a pointer to a C string, the second one its length. The string may contain embedded null bytes. Unicode objects are converted to C strings using `'utf-8'` encoding.

`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 *]

  This format converts a bytes-like object to a C pointer to a borrowed character string; it does not accept Unicode objects. The bytes buffer must not contain embedded null bytes; if it does, a `ValueError` exception is raised.

  バージョン 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`) [const Py_UNICODE *]

  Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of Unicode characters. You must pass the address of a `Py_UNICODE` pointer variable, which will be filled with the pointer to an existing Unicode buffer. Please note that the width of a `Py_UNICODE` character depends on compilation options (it is either 16 or 32 bits). The Python string must not contain embedded null code points; if it does, a `ValueError` exception is raised.

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

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

`u#` (`str`) [const Py_UNICODE *, `Py_ssize_t`]

  This variant on `u` stores into two C variables, the first one a pointer to a Unicode data buffer, the second one its length. This variant allows null code points.

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

`Z` (`str` or `None`) [const Py_UNICODE *]

  Like `u`, but the Python object may also be `None`, in which case the `Py_UNICODE` pointer is set to `NULL`.

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

`Z#` (`str` or `None`) [const Py_UNICODE *, `Py_ssize_t`]

  Like `u#`, but the Python object may also be `None`, in which case the `Py_UNICODE` pointer is set to `NULL`.

  バージョン 3.3 で非推奨、バージョン 3.12 で削除予定: 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, `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#` と同じです。ただし、バイト文字列オブジェクトをエンコードし直さずに渡します。その代わり、実装ではバイト文字列オブジェクトがパラメタに渡したエンコードを使っているものと仮定します。

### 数

`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 の整数を、 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]

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

  Store a Python object (without any conversion) in a C object pointer. The C program thus receives the actual object that was passed. A new strong reference to the object is not created (i.e. its reference count is not increased). The pointer stored is not `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 内の個々の書式単位に対応づけできなければなりません。シーケンスの書式単位は入れ子構造にできます。

It is possible to pass "long" integers (integers whose value exceeds the platform's `LONG_MAX`) however no proper range checking is done --- the most significant bits are silently truncated when the receiving field is too small to receive the value (actually, the semantics are inherited from downcasts in C --- your mileage may vary).

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

`|`

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

`$`

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

  バージョン 3.3 で追加.

`:`

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

`;`

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

Note that any Python object references which are provided to the caller are borrowed references; do not release them (i.e. do not decrement their reference count)!

以下の関数に渡す補助引数 (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 *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. Empty names denote positional-only parameters. Returns true on success; on failure, it returns false and raises the appropriate exception.

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

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

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

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

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

  バージョン 3.2 で追加.

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

  Function used to deconstruct the argument lists of "old-style" functions --- these are functions which use the `METH_OLDARGS` parameter parsing method, which has been removed in Python 3. This is not recommended for use in parameter parsing in new code, and most code in the standard interpreter has been modified to no longer use this for that purpose. It does remain a convenient way to decompose other tuples, however, and may continue to be used for that purpose.

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

  A simpler form of parameter retrieval which does not use a format string to specify the types of the arguments. Functions which use this method to retrieve their parameters should be declared as `METH_VARARGS` in function or method tables. The tuple containing the actual parameters should be passed as args; it must actually be a tuple. The length of the tuple must be at least min and no more than max; min and max may be equal. Additional arguments must be passed to the function, each of which should be a pointer to a PyObject* variable; these will be filled in with the values from args; they will contain borrowed references. The variables which correspond to optional parameters not given by args will not be filled in; these should be initialized by the caller. This function returns true on success and false if args is not a tuple or contains the wrong number of elements; an exception will be set if there was a failure.

  This is an example of the use of this function, taken from the sources for the `_weakref` helper module for weak references:

      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, ...)
  戻り値: 新しい参照。 次に属します: 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 の整数オブジェクトに変換します。

  `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 *]

    Pass a Python object untouched but create a new strong reference to it (i.e. its reference count is incremented by one). If the object passed in is a `NULL` pointer, it is assumed that this was caused because the call producing the argument found an error and set an exception. Therefore, `Py_BuildValue()` will return `NULL` but won't raise an exception. If no exception has been raised yet, `SystemError` is set.

  `S` (object) [PyObject *]

    `O` と同じです。

  `N` (object) [PyObject *]

    Same as `O`, except it doesn't create a new strong reference. Useful when the object is created by a call to an object constructor in the argument list.

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