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

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

## Base object types and macros

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

type `PyObject`
  Part of the Limited API. (Only some members are part of the stable ABI.)

  全てのオブジェクト型はこの型を拡張したものです。 この型には、あるオブジェクトを指すポインタをオブジェクトとして Python から扱うのに必要な情報が入っています。 通常の "リリース" ビルドでは、この構造体にはオブジェクトの参照カウントとオブジェクトに対応する型オブジェクトだけが入っています。 実際には `PyObject` であることは宣言されていませんが、全ての Python オブジェクトへのポインタは `PyObject*` へキャストできます。 メンバにアクセスするには `Py_REFCNT` マクロと `Py_TYPE` マクロを使わなければなりません。

type `PyVarObject`
  Part of the Limited API. (Only some members are part of the stable ABI.)

  `PyObject` を拡張して、 `ob_size` フィールドを追加したものです。 この構造体は、 長さ (length) の概念を持つオブジェクトだけに対して使います。 この型が Python/C API で使われることはほとんどありません。 メンバにアクセスするには `Py_REFCNT` マクロ、 `Py_TYPE` マクロ、 `Py_SIZE` マクロを使わなければなりません。

`PyObject_HEAD`

  可変な長さを持たないオブジェクトを表現する新しい型を宣言するときに使うマクロです。 PyObject_HEAD マクロは次のように展開されます:

      PyObject ob_base;

  上にある `PyObject` のドキュメントを参照してください。

`PyObject_VAR_HEAD`

  インスタンスごとに異なる長さを持つオブジェクトを表現する新しい型を宣言するときに使うマクロです。 PyObject_VAR_HEAD マクロは次のように展開されます:

      PyVarObject ob_base;

  上にある `PyVarObject` のドキュメントを参照してください。

int `Py_Is`(const PyObject *x, const PyObject *y)
  Part of the Stable ABI since version 3.10.

  Test if the x object is the y object, the same as `x is y` in Python.

  バージョン 3.10 で追加.

int `Py_IsNone`(const PyObject *x)
  Part of the Stable ABI since version 3.10.

  Test if an object is the `None` singleton, the same as `x is None` in Python.

  バージョン 3.10 で追加.

int `Py_IsTrue`(const PyObject *x)
  Part of the Stable ABI since version 3.10.

  Test if an object is the `True` singleton, the same as `x is True` in Python.

  バージョン 3.10 で追加.

int `Py_IsFalse`(const PyObject *x)
  Part of the Stable ABI since version 3.10.

  Test if an object is the `False` singleton, the same as `x is False` in Python.

  バージョン 3.10 で追加.

PyTypeObject *`Py_TYPE`(const PyObject *o)

  Get the type of the Python object o.

  Return a borrowed reference.

  Use the `Py_SET_TYPE()` function to set an object type.

int `Py_IS_TYPE`(PyObject *o, PyTypeObject *type)

  Return non-zero if the object o type is type. Return zero otherwise. Equivalent to: `Py_TYPE(o) == type`.

  バージョン 3.9 で追加.

void `Py_SET_TYPE`(PyObject *o, PyTypeObject *type)

  Set the object o type to type.

  バージョン 3.9 で追加.

Py_ssize_t `Py_REFCNT`(const PyObject *o)

  Get the reference count of the Python object o.

  バージョン 3.10 で変更: `Py_REFCNT()` is changed to the inline static function. Use `Py_SET_REFCNT()` to set an object reference count.

void `Py_SET_REFCNT`(PyObject *o, Py_ssize_t refcnt)

  Set the object o reference counter to refcnt.

  バージョン 3.9 で追加.

Py_ssize_t `Py_SIZE`(const PyVarObject *o)

  Get the size of the Python object o.

  Use the `Py_SET_SIZE()` function to set an object size.

void `Py_SET_SIZE`(PyVarObject *o, Py_ssize_t size)

  Set the object o size to size.

  バージョン 3.9 で追加.

`PyObject_HEAD_INIT`(type)

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

      _PyObject_EXTRA_INIT
      1, type,

`PyVarObject_HEAD_INIT`(type, size)

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

      _PyObject_EXTRA_INIT
      1, type, size,

## Implementing functions and methods

type `PyCFunction`
  Part of the Stable ABI.

  Type of the functions used to implement most Python callables in C. Functions of this type take two `PyObject*` parameters and return one such value. If the return value is `NULL`, an exception shall have been set. If not `NULL`, the return value is interpreted as the return value of the function as exposed in Python. The function must return a new reference.

  関数のシグネチャは次のとおりです

      PyObject *PyCFunction(PyObject *self,
                            PyObject *args);

type `PyCFunctionWithKeywords`
  Part of the Stable ABI.

  Type of the functions used to implement Python callables in C with signature `METH_VARARGS | METH_KEYWORDS`. The function signature is:

      PyObject *PyCFunctionWithKeywords(PyObject *self,
                                        PyObject *args,
                                        PyObject *kwargs);

type `_PyCFunctionFast`

  Type of the functions used to implement Python callables in C with signature `METH_FASTCALL`. The function signature is:

      PyObject *_PyCFunctionFast(PyObject *self,
                                 PyObject *const *args,
                                 Py_ssize_t nargs);

type `_PyCFunctionFastWithKeywords`

  Type of the functions used to implement Python callables in C with signature `METH_FASTCALL | METH_KEYWORDS`. The function signature is:

      PyObject *_PyCFunctionFastWithKeywords(PyObject *self,
                                             PyObject *const *args,
                                             Py_ssize_t nargs,
                                             PyObject *kwnames);

type `PyCMethod`

  Type of the functions used to implement Python callables in C with signature `METH_METHOD | METH_FASTCALL | METH_KEYWORDS`. The function signature is:

      PyObject *PyCMethod(PyObject *self,
                          PyTypeObject *defining_class,
                          PyObject *const *args,
                          Py_ssize_t nargs,
                          PyObject *kwnames)

  バージョン 3.9 で追加.

type `PyMethodDef`
  Part of the Stable ABI (including all members).

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

  const char *`ml_name`

    メソッド名

  PyCFunction `ml_meth`

    C 実装へのポインタ

  int `ml_flags`

    flags bits indicating how the call should be constructed

  const char *`ml_doc`

    docstring の内容を指すポインタ

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

The `ml_flags` field is a bitfield which can include the following flags. The individual flags indicate either a calling convention or a binding convention.

There are these calling conventions:

`METH_VARARGS`

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

`METH_VARARGS | METH_KEYWORDS`

  Methods with these flags must be of type `PyCFunctionWithKeywords`. The function expects three parameters: self, args, kwargs where kwargs is a dictionary of all the keyword arguments or possibly `NULL` if there are no keyword arguments. The parameters are typically processed using `PyArg_ParseTupleAndKeywords()`.

`METH_FASTCALL`

  Fast calling convention supporting only positional arguments. The methods have the type `_PyCFunctionFast`. The first parameter is self, the second parameter is a C array of `PyObject*` values indicating the arguments and the third parameter is the number of arguments (the length of the array).

  バージョン 3.7 で追加.

  バージョン 3.10 で変更: `METH_FASTCALL` is now part of the stable ABI.

`METH_FASTCALL | METH_KEYWORDS`

  Extension of `METH_FASTCALL` supporting also keyword arguments, with methods of type `_PyCFunctionFastWithKeywords`. Keyword arguments are passed the same way as in the vectorcall protocol: there is an additional fourth `PyObject*` parameter which is a tuple representing the names of the keyword arguments (which are guaranteed to be strings) or possibly `NULL` if there are no keywords. The values of the keyword arguments are stored in the args array, after the positional arguments.

  バージョン 3.7 で追加.

`METH_METHOD | METH_FASTCALL | METH_KEYWORDS`

  Extension of `METH_FASTCALL | METH_KEYWORDS` supporting the defining class, that is, the class that contains the method in question. The defining class might be a superclass of `Py_TYPE(self)`.

  The method needs to be of type `PyCMethod`, the same as for `METH_FASTCALL | METH_KEYWORDS` with `defining_class` argument added after `self`.

  バージョン 3.9 で追加.

`METH_NOARGS`

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

`METH_O`

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

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

`METH_CLASS`

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

`METH_STATIC`

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

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

`METH_COEXIST`

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

## Accessing attributes of extension types

type `PyMemberDef`
  Part of the Stable ABI (including all members).

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

  フィールド | C の型 | 意味
  --- | --- | ---
  `name` | const char * | メンバ名
  `type` | int | C 構造体の中のメンバの型
  `offset` | Py_ssize_t | そのメンバの type object 構造体中の場所の offset バイト数
  `flags` | int | フィールドが読み出し専用か書込み可能なのかを示すビットフラグ
  `doc` | const 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 | const 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` can be `0` for write and read access or `READONLY` for read-only access. Using `T_STRING` for `type` implies `READONLY`. `T_STRING` data is interpreted as UTF-8. Only `T_OBJECT` and `T_OBJECT_EX` members can be deleted. (They are set to `NULL`).

  Heap allocated types (created using `PyType_FromSpec()` or similar), `PyMemberDef` may contain definitions for the special members `__dictoffset__`, `__weaklistoffset__` and `__vectorcalloffset__`, corresponding to `tp_dictoffset`, `tp_weaklistoffset` and `tp_vectorcall_offset` in type objects. These must be defined with `T_PYSSIZET` and `READONLY`, for example:

      static PyMemberDef spam_type_members[] = {
          {"__dictoffset__", T_PYSSIZET, offsetof(Spam_object, dict), READONLY},
          {NULL}  /* Sentinel */
      };

PyObject *`PyMember_GetOne`(const char *obj_addr, struct PyMemberDef *m)

  Get an attribute belonging to the object at address obj_addr. The attribute is described by `PyMemberDef` m. Returns `NULL` on error.

int `PyMember_SetOne`(char *obj_addr, struct PyMemberDef *m, PyObject *o)

  Set an attribute belonging to the object at address obj_addr to object o. The attribute to set is described by `PyMemberDef` m. Returns `0` if successful and a negative value on failure.

type `PyGetSetDef`
  Part of the Stable ABI (including all members).

  型のプロパティのようなアクセスを定義するための構造体です。 `PyTypeObject.tp_getset` スロットの説明も参照してください。

  フィールド | C の型 | 意味
  --- | --- | ---
  name | const char * | 属性名
  get | getter | C function to get the attribute
  集合 | setter | 属性をセット/削除する任意のC言語関数。省略された場合、属性は読み取り専用になります。
  doc | const char * | 任意のドキュメンテーション文字列
  closure | void * | getterとsetterの追加データを提供する、オプションの関数ポインタ。

  `get` 関数は `PyObject*` パラメータ (インスタンス) と関数ポインタ (関連する``closure``) を1つ受け取ります。

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

  成功または失敗時に `NULL` と例外の集合にされたときは新しい参照を返します。

  `set` 関数は `PyObject*` パラメータ (インスタンスとセットされるべき値) と関数ポインタ (関連する``closure``) を受け取ります。

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

  属性を削除する場合は、2 番目のパラメータに `NULL` を指定します。成功した場合は `0` を、失敗した場合は `-1` を例外として返します。