5.5 引数の解釈と値の構築
これらの関数は独自の拡張モジュール用の関数やメソッドを作成する際に
便利です。詳しい情報や用例は
Python インタプリタの拡張と埋め込み に
あります。
最初に説明する 3 つの関数、
PyArg_ParseTuple()、
PyArg_ParseTupleAndKeywords()、および
PyArg_Parse() はいずれも
書式化文字列 (format string) を使います。
書式化文字列は、関数が受け取るはずの引数に関する情報を伝えるのに
用いられます。いずれの関数における書式化文字列も、同じ書式を
使っています。
書式化文字列は、ゼロ個またはそれ以上の ``書式化単位 (format unit)''
から成り立ちます。一つの書式化単位は一つの Python オブジェクトを
表します; 通常は単一の文字か、書式化単位からなる文字列を括弧で
囲ったものになります。例外として、括弧で囲われていない
書式化単位文字列が単一のアドレス引数に対応する場合がいくつかあります。
以下の説明では、引用符のついた形式は書式化単位です;
(丸)括弧で囲った部分は書式化単位に対応する Python のオブジェクト型
です; [角] 括弧は値をアドレス渡しする際に使う C の変数型です。
- "s" (文字列型または Unicode オブジェクト型) [const char *]
- Python の文字列または Unicode オブジェクトを、キャラクタ文字列を
指す C のポインタに変換します。
変換先の文字列自体の記憶領域を提供する必要はありません;
キャラクタ型ポインタ変数のアドレスを渡すと、すでに存在している
文字列へのポインタをその変数に記録します。C 文字列は NUL で
終端されています。Python の文字列型は、NUL バイトが途中に埋め込まれて
いてはなりません; もし埋め込まれていればTypeError 例外を
送出します。Unicode オブジェクトはデフォルトエンコーディングを使って
C 文字列に変換されます。変換に失敗すると UnicodeError を
送出します。
- "s#" (文字列型、Unicode オブジェクト型または任意の読み出しバッファ互換型)
[const char *, int]
- これは "s" の変化形で、値を二つの変数に記録します。一つ目の変数は
キャラクタ文字列へのポインタで、二つ目はその長さです。
この書式化単位の場合には、Python 文字列に null バイトが埋め込まれて
いてもかまいません。 Unicode オブジェクトの場合、デフォルト
エンコーディングでの変換が可能ならば、変換したオブジェクトから文字列
へのポインタを返します。その他の読み出しバッファ互換オブジェクトは
生の内部データ表現への参照を返します。
- "z" (文字列型または
None) [const char *]
- "s" に似ていますが、Python オブジェクトは
None でも
よく、その場合には C のポインタは NULLにセットされます。
- "z#" (文字列型、
None、または任意の読み出しバッファ互換型) [const char *, int]
- "s#" の "s" を "z" にしたような意味です。
- "u" (Unicode オブジェクト型) [Py_UNICODE *]
- Python の Unicode オブジェクトを、NUL で終端された 16 ビットの
Unicode (UTF-16) データに変換します。"s" と同様に、
Unicode データバッファ用に記憶領域を提供する必要はありません;
Py_UNICODE 型ポインタ変数のアドレスを渡すと、すでに存在している
Unicode データへのポインタをその変数に記録します。
- "u#" (Unicode オブジェクト型) [Py_UNICODE *, int]
- これは "u" の変化形で、値を二つの変数に記録します。一つ目の変数は
Unicode データバッファへのポインタで、二つ目はその長さです。
非 Unicode のオブジェクトの場合、読み出しバッファのポインタを
Py_UNICODE 型シーケンスへのポインタと解釈して扱います。
- "es" (文字列型、Unicode オブジェクト型または任意の読み出しバッファ互換型)[const char *encoding, char **buffer]
- これは "s" の変化形で、Unicode オブジェクトや Unicode に
変換可能なオブジェクトをキャラクタ型バッファにエンコードするために
用いられます。NUL バイトが埋め込まれていない文字列でのみ動作します。
この書式化単位には二つの引数が必要です。一つ目は入力にのみ用いられ、
NUL で終端されたエンコード名文字列を指す const char* 型で
なければなりません。指定したエンコード名を Python が理解できない
場合には例外を送出します。第二の引数は char** でなければ
なりません; この引数が参照しているポインタの値は、引数に指定した
テキストの内容が入ったバッファへのポインタになります。
テキストは最初の引数に指定したエンコード方式でエンコードされます。
PyArg_ParseTuple() を使うと、必要なサイズのバッファを
確保し、そのバッファにエンコード後のデータをコピーして、
*buffer がこの新たに確保された記憶領域を指すように変更します。
呼び出し側には、確保されたバッファを使い終わった後に
PyMem_Free() で解放する責任があります。
- "et" (文字列型、Unicode オブジェクト型または文字列バッファ互換型) [const char *encoding, char **buffer]
- "es" と同じです。ただし、8 ビット幅の文字列オブジェクトを
エンコードし直さずに渡します。その代わり、実装では文字列オブジェクトが
パラメタに渡したエンコードを使っているものと仮定します。
- "es#" (文字列型、Unicode オブジェクト型または文字列バッファ互換型) [const char *encoding, char **buffer, int *buffer_length]
- "s#" の変化形で、Unicode オブジェクトや Unicode に
変換可能なオブジェクトをキャラクタ型バッファにエンコードするために
用いられます。"es" 書式化単位と違って、この変化形はバイトが埋め込まれて
いてもかまいません。
この書式化単位には三つの引数が必要です。一つ目は入力にのみ用いられ、
NUL で終端されたエンコード名文字列を指す const char* 型か
NULLでなければなりません。NULLの場合にはデフォルトエンコーディング
を使います。指定したエンコード名を Python が理解できない
場合には例外を送出します。第二の引数は char** でなければ
なりません; この引数が参照しているポインタの値は、引数に指定した
テキストの内容が入ったバッファへのポインタになります。
テキストは最初の引数に指定したエンコード方式でエンコードされます。
第三の引数は整数へのポインタでなければなりません; ポインタが参照
している整数の値は出力バッファ内のバイト数にセットされます。
この書式化単位の処理には二つのモードがあります:
*buffer がNULL ポインタを指している場合、関数は
必要なサイズのバッファを確保し、そのバッファにエンコード後の
データをコピーして、*buffer がこの新たに確保された
記憶領域を指すように変更します。
呼び出し側には、確保されたバッファを使い終わった後に
PyMem_Free() で解放する責任があります。
*buffer が非 NULL のポインタ (すでにメモリ確保済みの
バッファ) を指している場合、PyArg_ParseTuple()
はこのメモリ位置をバッファとして用い、*buffer_length
の初期値をバッファサイズとして用います。PyArg_ParseTuple()
は次にエンコード済みのデータをバッファにコピーして、NUL で終端
します。バッファの大きさが足りなければ ValueError
がセットされます。
どちらの場合も、 *buffer_length は終端の NUL バイトを
含まないエンコード済みデータの長さにセットされます。
- "et#" (文字列型、Unicode オブジェクト型または文字列バッファ互換型) [const char *encoding, char **buffer]
- "es#" と同じです。ただし、文字列オブジェクトを
エンコードし直さずに渡します。その代わり、実装では文字列オブジェクトが
パラメタに渡したエンコードを使っているものと仮定します。
- "b" (整数型) [char]
- Python の整数型を、 C の char 型の小さな整数に変換します。
- "B" (整数型) [unsigned char]
- Python の整数型を、オーバフローチェックを行わずに、 C の
unsigned char 型の小さな整数に変換します。
バージョン 2.3 で 新たに追加 された仕様です。
- "h" (整数型) [short int]
- Python の整数型を、 C の short int 型に変換します。
- "H" (整数型) [unsigned short int]
- Python の整数型を、オーバフローチェックを行わずに、 C の
unsigned short int 型に変換します。
バージョン 2.3 で 新たに追加 された仕様です。
- "i" (整数型) [int]
- Python の整数型を、 C の int 型に変換します。
- "I" (整数型) [unsigned int]
- Python の整数型を、オーバフローチェックを行わずに、 C の
unsigned int 型に変換します。
バージョン 2.3 で 新たに追加 された仕様です。
- "l" (整数型) [long int]
- Python の整数型を、 C の long int 型に変換します。
- "k" (整数型) [unsigned long]
- Python の整数型を、オーバフローチェックを行わずに、 C の
unsigned long int 型に変換します。
バージョン 2.3 で 新たに追加 された仕様です。
- "L" (整数型) [PY_LONG_LONG]
- Python の整数型を、 C の long long 型に変換します。
この書式化単位は、long long 型 (または Windows の
_int64 型) がサポートされているプラットフォームでのみ
利用できます。
Convert a Python integer to a C long long. This format is
only available on platforms that support long long (or
_int64 on Windows).
- "K" (整数型) [unsigned PY_LONG_LONG]
- Python の整数型を、オーバフローチェックを行わずに、 C の
unsigned long long 型に変換します。
この書式化単位は、unsigned long long 型 (または Windows の
unsigned _int64 型) がサポートされているプラットフォームでのみ
利用できます。
バージョン 2.3 で 新たに追加 された仕様です。
- "c" (長さ 1 の文字列型) [char]
- 長さ 1 の文字列として表現されている Python キャラクタを
C の char 型に変換します。
- "f" (浮動小数点型) [float]
- Python の浮動小数点型を、 C の float 型に変換します。
- "d" (浮動小数点型) [double]
- Python の浮動小数点型を、 C の double 型に変換します。
- "D" (複素数型) [Py_complex]
- Python の複素数型を、 C の Py_complex 構造体に変換します。
- "O" (オブジェクト) [PyObject *]
- Python オブジェクトを (一切変換を行わずに) C の Python オブジェクト型
ポインタに保存します。これにより、C プログラムは実際のオブジェクトを
受け渡しされます。オブジェクトの参照カウントは増加しません。
保存されるポインタが NULLになることはありません。
- "O!" (オブジェクト) [typeobject, PyObject *]
- Python オブジェクトを C の Python オブジェクト型ポインタに保存します。
"O" に似ていますが、二つの C の引数をとります: 一つ目の引数は
Python の型オブジェクトへのアドレスで、二つ目の引数は
オブジェクトへのポインタが保存されている (PyObject* の) C の
変数へのアドレスです。Python オブジェクトが指定した型ではない場合、
TypeError を送出します。
- "O&" (オブジェクト) [converter, anything]
- Python オブジェクトを converter 関数を介して C の変数に変換します。
二つの引数をとります: 一つ目は関数で、二つ目は (任意の型の) C 変数
へのアドレスをvoid * 型に変換したものです。
converter は以下のようにして呼び出されます:
status = converter(object,
address);
ここで object は変換対象の Python オブジェクトで、
address は PyArg_Parse*() に渡した void*
型の引数です。戻り値 status は変換に成功した際に 1、
失敗した場合には 0 になります。変換に失敗した場合、
converter 関数は例外を送出しなくてはなりません。
- "S" (文字列型) [PyStringObject *]
- "O" に似ていますが、Python オブジェクトは文字列オブジェクトで
なければなりません。
オブジェクトが文字列オブジェクトでない場合にはTypeError
を送出します。
C 変数は PyObject* で宣言しておいてもかまいません。
- "U" (Unicode 文字列型) [PyUnicodeObject *]
- "O" に似ていますが、Python オブジェクトは Unicode オブジェクトで
なければなりません。
オブジェクトが Unicode オブジェクトでない場合にはTypeError
を送出します。
C 変数は PyObject* で宣言しておいてもかまいません。
- "t#" (読み出し専用キャラクタバッファ) [char *, int]
- "s#" に似ていますが、読み出し専用バッファインタフェースを
実装している任意のオブジェクトを受理します。
char* 変数はバッファの最初のバイトを指すようにセットされ、
int はバッファの長さにセットされます。
単一セグメントからなるバッファオブジェクトだけを受理します;
それ以外の場合には TypeError を送出します。
- "w" (読み書き可能なキャラクタバッファ) [char *]
- "s" と同様ですが、読み書き可能なバッファインタフェースを
実装している任意のオブジェクトを受理します。
呼び出し側は何らかの別の手段でバッファの長さを決定するか、
あるいは"w#" を使わねばなりません。
単一セグメントからなるバッファオブジェクトだけを受理します;
それ以外の場合には TypeError を送出します。
- "w#" (読み書き可能なキャラクタバッファ) [char *, int]
- "s#" に似ていますが、読み書き可能なバッファインタフェースを
実装している任意のオブジェクトを受理します。
char* 変数はバッファの最初のバイトを指すようにセットされ、
int はバッファの長さにセットされます。
単一セグメントからなるバッファオブジェクトだけを受理します;
それ以外の場合には TypeError を送出します。
- "(items)" (タプル) [matching-items]
- オブジェクトはitems に入っている書式化単位の数だけの長さを持つ
Python のシーケンス型でなくてはなりません。各 C 引数は items 内の
個々の書式化単位に対応づけできねばなりません。
シーケンスの書式化単位は入れ子構造にできます。
注意:
Python のバージョン 1.5.2 より以前は、この書式化指定文字列は
パラメタ列ではなく、個別のパラメタが入ったタプルでなければなりません
でした。このため、以前は TypeError を引き起こしていたよう
なコードが現在は例外を出さずに処理されるかもしれません。
とはいえ、既存のコードにとってこれは問題ないと思われます。
Python 整数型を要求している場所に Python 長整数型を渡すのは
可能です; しかしながら、適切な値域チェックはまったく行われません --
値を受け取るためのフィールドが、値全てを受け取るには小さすぎる
場合、上桁のビット群は暗黙のうちに切り詰められます (実際のところ、
このセマンティクスは C のダウンキャスト (downcast) から継承して
います -- その恩恵は人それぞれかもしれませんが)。
その他、書式化文字列において意味を持つ文字がいくつかあります。
それらの文字は括弧による入れ子内には使えません。以下に文字を
示します:
- "|"
- Python 引数リスト中で、この文字以降の引数がオプションであることを
示します。
オプションの引数に対応する C の変数はデフォルトの値で初期化して
おかねばなりません -- オプションの引数が省略された場合、
PyArg_ParseTuple() は対応する C 変数の内容に
手を加えません。
- ":"
- この文字があると、書式化単位の記述はそこで終わります;
コロン以降の文字列は、エラーメッセージにおける関数名
(PyArg_ParseTuple() が送出する例外の
``付属値 (associated value)'') として使われます。
- ";"
- この文字があると、書式化単位の記述はそこで終わります;
セミコロン以降の文字列は、デフォルトエラーメッセージを
置き換える エラーメッセージとして使われます。
言うまでもなく、":" と ";" は相互に排他の文字です。
呼び出し側に提供される Python オブジェクトの参照は全て
借りた (borrowed) ものです; オブジェクトの参照カウントを
デクリメントしてはなりません!
以下の関数に渡す補助引数 (additional argument) は、書式化文字列から
決定される型へのアドレスでなければなりません; 補助引数に指定した
アドレスは、タプルから入力された値を保存するために使います。
上の書式化単位のリストで説明したように、補助引数を入力値として
使う場合がいくつかあります; その場合、対応する書式化単位
の指定する形式に従うようにせねばなりません。
変換を正しく行うためには、arg オブジェクトは
書式化文字に一致しなければならず、かつ書式化文字列内の
書式化単位に全て値が入るようにせねばなりません。
成功すると、PyArg_Parse*() 関数は真を返します。
それ以外の場合には偽を返し、適切な例外を送出します。
| int PyArg_ParseTuple( | PyObject *args, char *format,
...) |
-
固定引数のみを引数にとる関数のパラメタを解釈して、ローカルな
変数に変換します。
成功すると真を返します;失敗すると偽を返し、適切な例外を送出します。
| int PyArg_VaParse( | PyObject *args, char *format,
va_list vargs) |
-
PyArg_ParseTuple() と同じですが、可変長の引数では
なく va_list を引数にとります。
| int PyArg_ParseTupleAndKeywords( | PyObject *args,
PyObject *kw, char *format, char *keywords[],
...) |
-
固定引数およびキーワード引数をとる関数のパラメタを解釈して、ローカルな
変数に変換します。
成功すると真を返します;失敗すると偽を返し、適切な例外を送出します。
| int PyArg_VaParseTupleAndKeywords( | PyObject *args,
PyObject *kw, char *format, char *keywords[],
va_list vargs) |
-
PyArg_ParseTupleAndKeywords() と同じですが、可変長の引数では
なく va_list を引数にとります。
| int PyArg_Parse( | PyObject *args, char *format,
...) |
-
``旧形式'' の関数における引数リストを分析するために使われる
関数です -- 旧形式の関数は、引数解釈手法に
METH_OLDARGS を使います。
新たに書かれるコードでのパラメタ解釈にはこの関数の使用は奨められず、
標準のインタプリタにおけるほとんどのコードがもはや引数解釈の
ためにこの関数を使わないように変更済みです。
この関数を残しているのは、この関数が依然として引数以外のタプルを
分析する上で便利だからですが、この目的においては将来も使われ
つづけるかもしれません。
| int PyArg_UnpackTuple( | PyObject *args, char *name,
int min, int 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)
と全く等価です。
バージョン 2.2 で 新たに追加 された仕様です。
| PyObject* Py_BuildValue( | char *format,
...) |
-
戻り値:
新たな参照.
PyArg_Parse*() ファミリの関数が受け取るのと似た
形式の書式化文字列および値列に基づいて、新たな値を生成します。
生成した値を返します。エラーの場合にはNULL を返します;
NULL を返す場合、例外を送出するでしょう。
Py_BuildValue() は常にタプルを生成するとは限りません。
この関数がタプルを生成するのは、書式化文字列に二つ以上の書式化単位
が入っているときだけです。書式化文字列が空の場合、None
を返します; 書式化単位が厳密に一つだけ入っている場合、
書式化単位で指定されている何らかのオブジェクト単体を返します。
サイズがゼロや 1 のタプルを返すように強制するには、
丸括弧で囲われた書式化文字列を使います。
書式化単位 "s" や "s#" の場合のように、オブジェクトを
構築する際にデータを供給するためにメモリバッファをパラメタとして渡す
場合には、指定したデータはコピーされます。Py_BuildValue()
が生成したオブジェクトは、呼び出し側が提供したバッファを決して参照
しません。
別の言い方をすれば、malloc() を呼び出してメモリを確保し、
それを Py_BuildValue() に渡した場合、コード内で
Py_BuildValue() が返った後でfree() を
呼び出す責任があるということです。
以下の説明では、引用符のついた形式は書式化単位です;
(丸)括弧で囲った部分は書式化単位が返す Python のオブジェクト型
です; [角] 括弧は関数に渡す値の C 変数型です。
書式化文字列内では、("s#" のような書式化単位を除いて) スペース、
タブ、コロンおよびコンマは無視されます。
これらの文字を使うと、長い書式化文字列をちょっとだけ読みやすく
できます。
- "s" (文字列型) [char *]
- null 終端された C 文字列から Python オブジェクトに変換します。
C 文字列ポインタが NULLの場合、
None になります。
- "s#" (文字列型) [char *, int]
- C 文字列とその長さから Python オブジェクトに変換します。
C 文字列ポインタが NULLの場合、長さは無視され
None になります。
- "z" (string or
None) [char *]
- "s" と同じです。
- "z#" (string or
None) [char *, int]
- "s#" と同じです。
- "u" (Unicode string) [Py_UNICODE *]
- null 終端された Unicode (UCS-2 または UCS-4) データのバッファから
Python オブジェクトに変換します。
Unicode バッファポインタが NULLの場合、
None になります。
- "u#" (Unicode string) [Py_UNICODE *, int]
- null 終端された Unicode (UCS-2 または UCS-4) データのバッファと
その長さから Python オブジェクトに変換します。
Unicode バッファポインタが NULLの場合、長さは無視され
None になります。
- "i" (整数型) [int]
- 通常の C の int を Python の整数オブジェクトに変換します。
- "b" (整数型) [char]
- "i" と同じです。
- "h" (整数型) [short int]
- "i" と同じです。
- "l" (整数型) [long int]
- C の long int を Python の整数オブジェクトに変換します。
- "c" (string of length 1) [char]
- 文字を表す通常の C の int を、長さ 1 の Python の文字列
オブジェクトに変換します。
- "d" (浮動小数点型) [double]
- C の double を Python の浮動小数点数に変換します。
- "f" (浮動小数点型) [float]
- "d" と同じです。
- "D" (複素数型) [Py_complex *]
- C の Py_complex 構造体を Python の複素数に変換します。
- "O" (オブジェクト) [PyObject *]
- Python オブジェクトを手を加えずに渡します (ただし、参照カウントは
1 インクリメントします)。渡したオブジェクトが NULL ポインタ
の場合、この引数を生成するのに使った何らかの呼び出しがエラーに
なったのが原因であると仮定して、例外をセットします。
従ってこのとき Py_BuildValue() は NULL を返しますが
Py_BuildValue() 自体は例外を送出しません。
例外をまだ送出していなければSystemError をセットします。
- "S" (オブジェクト) [PyObject *]
- "O" と同じです。
- "N" (オブジェクト) [PyObject *]
- "O" と同じです。ただし、オブジェクトの参照カウントを
インクリメントしません。オブジェクトが引数リスト内のオブジェクト
コンストラクタ呼び出しによって生成されている場合に便利です。
- "O&" (オブジェクト) [converter, anything]
- anything を converter 関数を介して Python オブジェクトに
変換します。この関数は anything (void * と互換の型で
なければなりません) を引数にして呼び出され、``新たな'' オブジェクト
を返すか、失敗した場合には NULL を返すようにしなければなりません。
- "(items)" (タプル型) [matching-items]
- C の値からなる配列を、同じ要素数を持つ Python のタプルに変換します。
- "[items]" (リスト型) [matching-items]
- C の値からなる配列を、同じ要素数を持つ Python のリストに変換します。
- "{items}" (辞書型) [matching-items]
- C の値からなる配列を Python の辞書に変換します。一連のペアからなる
C の値が、それぞれキーおよび値となって辞書に追加されます。
書式化文字列に関するエラーが生じると、SystemError 例外を
セットして NULL を返します。
ご意見やご指摘をお寄せになりたい方は、 このドキュメントについて... をご覧ください。
