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

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

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

PyObject

   All object types are extensions of this type.  This is a type which
   contains the information Python needs to treat a pointer to an
   object as an object.  In a normal 「release」 build, it contains
   only the object’s reference count and a pointer to the
   corresponding type object.  It corresponds to the fields defined by
   the expansion of the "PyObject_HEAD" macro.

PyVarObject

   This is an extension of "PyObject" that adds the "ob_size" field.
   This is only used for objects that have some notion of *length*.
   This type does not often appear in the Python/C API.  It
   corresponds to the fields defined by the expansion of the
   "PyObject_VAR_HEAD" macro.

These macros are used in the definition of "PyObject" and
"PyVarObject":

PyObject_HEAD

   This is a macro which expands to the declarations of the fields of
   the "PyObject" type; it is used when declaring new types which
   represent objects without a varying length.  The specific fields it
   expands to depend on the definition of "Py_TRACE_REFS".  By
   default, that macro is not defined, and "PyObject_HEAD" expands to:

      Py_ssize_t ob_refcnt;
      PyTypeObject *ob_type;

   When "Py_TRACE_REFS" is defined, it expands to:

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

PyObject_VAR_HEAD

   This is a macro which expands to the declarations of the fields of
   the "PyVarObject" type; it is used when declaring new types which
   represent objects with a length that varies from instance to
   instance. This macro always expands to:

      PyObject_HEAD
      Py_ssize_t ob_size;

   Note that "PyObject_HEAD" is part of the expansion, and that its
   own expansion varies depending on the definition of
   "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 で実装する際に用い
   られている関数の型です。この型の関数は 2 つの "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

   This is the typical calling convention, where the methods have the
   type "PyCFunction". The function expects two "PyObject*" values.
   The first one is the *self* object for methods; for module
   functions, it is the module object.  The second parameter (often
   called *args*) is a tuple object representing all arguments.  This
   parameter is typically processed using "PyArg_ParseTuple()" or
   "PyArg_UnpackTuple()".

METH_KEYWORDS

   Methods with these flags must be of type "PyCFunctionWithKeywords".
   The function expects three parameters: *self*, *args*, and a
   dictionary of all the keyword arguments.  The flag is typically
   combined with "METH_VARARGS", and the parameters are typically
   processed using "PyArg_ParseTupleAndKeywords()".

METH_NOARGS

   Methods without parameters don’t need to check whether arguments
   are given if they are listed with the "METH_NOARGS" flag.  They
   need to be of type "PyCFunction".  The first parameter is typically
   named "self" and will hold a reference to the module or object
   instance.  In all cases the second parameter will be *NULL*.

METH_O

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

METH_OLDARGS

   This calling convention is deprecated.  The method must be of type
   "PyCFunction".  The second argument is *NULL* if no arguments are
   given, a single object if exactly one argument is given, and a
   tuple of objects if more than one argument is given.  There is no
   way for a function using this convention to distinguish between a
   call with multiple arguments and a call with a tuple as the only
   argument.

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

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 の型             |
   +=================+====================+
   | T_SHORT         | short              |
   +-----------------+--------------------+
   | T_INT           | int                |
   +-----------------+--------------------+
   | T_LONG          | long               |
   +-----------------+--------------------+
   | T_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" は "T_OBJECT" よ
   り属性に対する "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 の型             | 意味                                |
   +===============+====================+=====================================+
   | name          | char *             | attribute name                      |
   +---------------+--------------------+-------------------------------------+
   | get           | getter             | C Function to get the attribute     |
   +---------------+--------------------+-------------------------------------+
   | set           | 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.*

   Return a bound method object for an extension type implemented in
   C.  This can be useful in the implementation of a "tp_getattro" or
   "tp_getattr" handler that does not use the
   "PyObject_GenericGetAttr()" function.
