引数の解釈と値の構築¶

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`または読み出し専用 :term:`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 predicate) に渡された値を判定し、その結果を等価な 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:を含む：借用参照 <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 を受け取ります。

引数の解釈と値の構築¶

引数を解析する¶

文字列とバッファ¶

数¶

その他のオブジェクト¶

API 関数¶

値の構築¶

目次

前のトピックへ

次のトピックへ

This page