共通のオブジェクト構造体 (common object structure)

Python では、オブジェクト型を定義する上で数多くの構造体が使われます。この節では三つの構造体とその利用方法について説明します。

全ての Python オブジェクトは、オブジェクトのメモリ内表現の先頭部分にある少数のフィールドを完全に共有しています。このフィールドは PyObject および PyVarObject 型で表現されます。 PyObject 型や PyVarObject 型もまた、他の全ての Python オブジェクトを定義する上で直接的・間接的に使われているマクロを使って定義されています。

PyObject

全てのオブジェクト型はこの型を拡張したものです。この型には、あるオブジェクトに対するオブジェクトとしてのポインタを Python から扱う必要がある際に必要な情報が入っています。通常に "リリースされている" ビルドでは、この構造体にはオブジェクトの参照カウントと、オブジェクトに対応する型オブジェクトだけが入っています。PyObject_HEAD マクロ展開で定義されているフィールドに対応します。

PyVarObject

PyObject を拡張して、 ob_size フィールドを追加したものです。この構造体は、 長さ (length) の概念を持つオブジェクトだけに対して使います。この型が Python/C API で使われることはほとんどありません。 PyObject_VAR_HEAD マクロ展開で定義されているフィールドに対応します。

これらのマクロは PyObject と PyVarObject の定義で使われています:

PyObject_HEAD

PyObject 型のフィールド宣言に展開されるマクロです; 可変でない長さを持つオブジェクトを表現する新たな型を宣言する場合に使います。展開によってどのフィールドが宣言されるかは、 Py_TRACE_REFS の定義に依存します。デフォルトでは、 Py_TRACE_REFS は定義されておらず、 PyObject_HEAD は以下のコードに展開されます:

Py_ssize_t ob_refcnt;
PyTypeObject *ob_type;

Py_TRACE_REFS が定義されている場合、以下のように展開されます:

PyObject *_ob_next, *_ob_prev;
Py_ssize_t ob_refcnt;
PyTypeObject *ob_type;

PyObject_VAR_HEAD

マクロです。 PyVarObject 型のフィールド宣言に展開されるマクロです; インスタンスによって可変の長さを持つオブジェクトを表現する新たな型を宣言する場合に使います。マクロは常に以下のように展開されます:

PyObject_HEAD
Py_ssize_t ob_size;

マクロ展開結果の一部に PyObject_HEAD が含まれており、 PyObject_HEAD の展開結果は Py_TRACE_REFS の定義に依存します。

Py_TYPE(o)

Python オブジェクトの ob_type メンバにアクセスするのに使うマクロです。 これは次のように展開されます:

(((PyObject*)(o))->ob_type)

バージョン 2.6 で追加.

Py_REFCNT(o)

Python オブジェクトの ob_refcnt メンバにアクセスするのに使うマクロです。 これは次のように展開されます:

(((PyObject*)(o))->ob_refcnt)

バージョン 2.6 で追加.

Py_SIZE(o)

Python オブジェクトの ob_size メンバにアクセスするのに使うマクロです。 これは次のように展開されます:

(((PyVarObject*)(o))->ob_size)

バージョン 2.6 で追加.

PyObject_HEAD_INIT(type)

新しい PyObject 型のための初期値に展開するマクロです。このマクロは次のように展開されます。

_PyObject_EXTRA_INIT
1, type,

PyVarObject_HEAD_INIT(type, size)

新しい、 ob_size フィールドを含む PyVarObject 型のための初期値に展開するマクロです。このマクロは次のように展開されます。

_PyObject_EXTRA_INIT
1, type, size,

PyCFunction

ほとんどの Python の呼び出し可能オブジェクトを C で実装する際に用いられている関数の型です。この型の関数は二つの PyObject* 型パラメタをとり、 PyObject* 型の値を返します。戻り値を NULL にする場合、例外をセットしておかなければなりません。 NULL でない値を返す場合、戻り値は Python に関数の戻り値として公開される値として解釈されます。この型の関数は新たな参照を返さなければなりません。

PyMethodDef

拡張型のメソッドを記述する際に用いる構造体です。この構造体には 4 つのフィールドがあります:

フィールド	C の型	意味
ml_name	char *	メソッド名
ml_meth	PyCFunction	C 実装へのポインタ
ml_flags	int	呼び出しをどのように行うかを示すフラグビット
ml_doc	char *	docstring の内容を指すポインタ

ml_meth は C の関数ポインタです。関数は別の型で定義されていてもかまいませんが、常に PyObject* を返します。関数が PyFunction でない場合、メソッドテーブル内でキャストを行うようコンパイラが要求することになるでしょう。 PyCFunction では最初のパラメタが PyObject* 型であると定義していますが、固有の C 型を self オブジェクトに使う実装はよく行われています。

ml_flags フィールドはビットフィールドで、以下のフラグが入ります。 個々のフラグは呼び出し規約 (calling convention) や束縛規約 (binding convention) を表します。 呼び出し規約フラグでは、 METH_VARARGS および METH_KEYWORDS だけが組み合わせられます。 呼び出し規約フラグは束縛規約フラグと組み合わせられます。

METH_VARARGS

PyCFunction 型のメソッドで典型的に使われる呼び出し規約です。関数は PyObject* 型の引数値を二つ要求します。最初の引数はメソッドの self オブジェクトです; モジュール関数の場合、これはモジュールオブジェクトです。第二のパラメタ (よく args と呼ばれます) は、全ての引数を表現するタプルオブジェクトです。パラメタは通常、 PyArg_ParseTuple() や PyArg_UnpackTuple() で処理されます。

METH_KEYWORDS

このフラグを持つメソッドは PyCFunctionWithKeywords 型でなければなりません。 PyCFunctionWithKeywords は三つのパラメタ: self 、 args 、およびキーワード引数全てからなる辞書、を要求します。このフラグは通常 METH_VARARGS と組み合わされ、パラメタは PyArg_ParseTupleAndKeywords() で処理されます。

METH_NOARGS

引数のないメソッドは、 METH_NOARGS フラグをつけた場合、必要な引数が指定されているかをチェックしなくなります。こうしたメソッドは PyCFunction 型でなくてはなりません。第一のパラメタは self になり、モジュールかオブジェクトインスタンスへの参照を保持することになります。いずれにせよ、第二のパラメタは NULL になります。

METH_O

単一のオブジェクト引数だけをとるメソッドは、 PyArg_ParseTuple() を引数 "O" にして呼び出す代わりに、 METH_O フラグつきで指定できます。メソッドは PyCFunction 型で、 self パラメタと単一の引数を表現する PyObject* パラメタを伴います。

METH_OLDARGS

この呼び出し規約は撤廃されました。メソッドは PyCFunction 型でなければなりません。第二引数は、引数がない場合には NULL 、単一の引数の場合にはその引数オブジェクト、複数個の引数の場合には引数オブジェクトからなるタプルです。この呼び出し規約を使うと、複数個の引数の場合と、単一のタプルが唯一引数の場合を区別できなくなってしまいます。

以下の二つの定数は、呼び出し規約を示すものではなく、クラスのメソッドとして使う際の束縛方式を示すものです。モジュールに対して定義された関数で用いてはなりません。メソッドに対しては、最大で一つしかこのフラグをセットできません。

METH_CLASS

メソッドの最初の引数には、型のインスタンスではなく型オブジェクトが渡されます。このフラグは組み込み関数 classmethod() を使って生成するのと同じ クラスメソッド (class method) を生成するために使われます。

バージョン 2.3 で追加.

METH_STATIC

メソッドの最初の引数には、型のインスタンスではなく NULL が渡されます。このフラグは、 staticmethod() を使って生成するのと同じ 静的メソッド (static method) を生成するために使われます。

バージョン 2.3 で追加.

もう一つの定数は、あるメソッドを同名の別のメソッド定義と置き換えるかどうかを制御します。

METH_COEXIST

メソッドを既存の定義を置き換える形でロードします。 METH_COEXIST を指定しなければ、デフォルトの設定にしたがって、定義が重複しないようスキップします。スロットラッパはメソッドテーブルよりも前にロードされるので、例えば sq_contains スロットはラップしているメソッド __contains__() を生成し、同名の PyCFunction のロードを阻止します。このフラグを定義すると、 PyCFunction はラッパオブジェクトを置き換える形でロードされ、スロットと連立します。 PyCFunctions の呼び出しはラッパオブジェクトの呼び出しよりも最適化されているので、こうした仕様が便利になります。

バージョン 2.4 で追加.

PyMemberDef

type の C 構造体のメンバとして格納されている、ある型の属性を表す構造体です。この構造体のフィールドは以下のとおりです:

フィールド	C の型	意味
name	char *	メンバ名
type	int	C 構造体の中のメンバの型
offset	Py_ssize_t	そのメンバの type object 構造体中の場所の offset バイト数
flags	int	フィールドが読み込み専用か書込み可能なのかを示すビットフラグ
doc	char *	docstring の内容を指すポインタ

type はたくさんのCの型を意味する T_ マクロのうちの1つです。メンバが Python からアクセスされるとき、そのメンバは対応する Python の型に変換されます。

マクロ名	C type
T_SHORT	short
T_INT	int
T_LONG	long型
T_FLOAT	float
T_DOUBLE	double
T_STRING	char *
T_OBJECT	PyObject *
T_OBJECT_EX	PyObject *
T_CHAR	char
T_BYTE	char
T_UBYTE	unsigned char
T_UINT	unsigned int
T_USHORT	unsigned short
T_ULONG	unsigned long
T_BOOL	char
T_LONGLONG	long long
T_ULONGLONG	unsigned long long
T_PYSSIZET	Py_ssize_t

T_OBJECT と T_OBJECT_EX については、 T_OBJECT がメンバが NULL だったときに None を返すのに対し、 T_OBJECT_EX は AttributeError を発生させる点が異なります。 T_OBJECT_EX は属性に対する del 文をより正しくあつかうので、できれば T_OBJECT よりも T_OBJECT_EX を使ってください。

flags には読み書きアクセス可能なら 0 で、読み込み専用なら READONLY を設定します。 type に T_STRING を使うと、 READONLY 扱いになります。 T_OBJECT メンバと T_OBJECT_EX メンバだけが削除できます (NULL が代入されます)。

PyGetSetDef

Structure to define property-like access for a type. See also description of the PyTypeObject.tp_getset slot.

フィールド	C の型	意味
名前	char *	attribute name
get	getter	C Function to get the attribute
集合	setter	optional C function to set or delete the attribute, if omitted the attribute is readonly
doc	char *	optional docstring
closure	void *	optional function pointer, providing additional data for getter and setter

The get function takes one PyObject* parameter (the instance) and a function pointer (the associated closure):

typedef PyObject *(*getter)(PyObject *, void *);

It should return a new reference on success or NULL with a set exception on failure.

set functions take two PyObject* parameters (the instance and the value to be set) and a function pointer (the associated closure):

typedef int (*setter)(PyObject *, PyObject *, void *);

In case the attribute should be deleted the second parameter is NULL. Should return 0 on success or -1 with a set exception on failure.

PyObject* Py_FindMethod(PyMethodDef table[], PyObject *ob, char *name)

Return value: New reference.

C で実装された拡張型の束縛メソッドオブジェクトを返します。 PyObject_GenericGetAttr() 関数を使わない tp_getattro や tp_getattr ハンドラを実装する際に便利です。