共通のオブジェクト構造体 (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" ハンドラを実装する際に便利です。
