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

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

## Base object types and macros

All Python objects ultimately share a small number of fields at the beginning of the object's representation in memory. These are represented by the `PyObject` and `PyVarObject` types, which are defined, in turn, by the expansions of some macros also used, whether directly or indirectly, in the definition of all other Python objects.

type PyObject
  次に属します: Limited API. (いくつかのメンバーのみが安定 ABI です。)

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

type PyVarObject
  次に属します: Limited API. (いくつかのメンバーのみが安定 ABI です。)

  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. Access to the members must be done by using the macros `Py_REFCNT`, `Py_TYPE`, and `Py_SIZE`.

PyObject_HEAD

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

      PyObject ob_base;

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

PyObject_VAR_HEAD

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

      PyVarObject ob_base;

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

int Py_Is(PyObject *x, PyObject *y)
  次に属します: Stable ABI (バージョン 3.10 より).

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

  バージョン 3.10 で追加.

int Py_IsNone(PyObject *x)
  次に属します: Stable ABI (バージョン 3.10 より).

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

  バージョン 3.10 で追加.

int Py_IsTrue(PyObject *x)
  次に属します: Stable ABI (バージョン 3.10 より).

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

  バージョン 3.10 で追加.

int Py_IsFalse(PyObject *x)
  次に属します: Stable ABI (バージョン 3.10 より).

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

  バージョン 3.10 で追加.

PyTypeObject *Py_TYPE(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.

  バージョン 3.11 で変更: `Py_TYPE()` is changed to an inline static function. The parameter type is no longer const PyObject*.

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(PyObject *o)

  Get the reference count of the Python object o.

  Use the `Py_SET_REFCNT()` function to set an object reference count.

  バージョン 3.11 で変更: The parameter type is no longer const PyObject*.

  バージョン 3.10 で変更: `Py_REFCNT()` is changed to the inline static function.

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(PyVarObject *o)

  Get the size of the Python object o.

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

  バージョン 3.11 で変更: `Py_SIZE()` is changed to an inline static function. The parameter type is no longer const PyVarObject*.

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)

  This is a macro which expands to initialization values for a new `PyVarObject` type, including the `ob_size` field. This macro expands to:

      _PyObject_EXTRA_INIT
      1, type, size,

## Implementing functions and methods

type PyCFunction
  次に属します: 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
  次に属します: 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
  次に属します: Stable ABI (すべてのメンバーを含む).

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

  const char *ml_name

    Name of the method.

  PyCFunction ml_meth

    Pointer to the C implementation.

  int ml_flags

    Flags bits indicating how the call should be constructed.

  const char *ml_doc

    Points to the contents of the docstring.

The `ml_meth` is a C function pointer. The functions may be of different types, but they always return PyObject*. If the function is not of the `PyCFunction`, the compiler will require a cast in the method table. Even though `PyCFunction` defines the first parameter as PyObject*, it is common that the method implementation uses the specific C type of the self object.

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_KEYWORDS

  Can only be used in certain combinations with other flags: METH_VARARGS | METH_KEYWORDS, METH_FASTCALL | METH_KEYWORDS and METH_METHOD | METH_FASTCALL | METH_KEYWORDS.

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

  Can only be used in the combination with other flags: METH_METHOD | METH_FASTCALL | METH_KEYWORDS.

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

  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`.

  The function must have 2 parameters. Since the second parameter is unused, `Py_UNUSED` can be used to prevent a compiler warning.

METH_O

  Methods with a single object argument can be listed with the `METH_O` flag, instead of invoking `PyArg_ParseTuple()` with a `"O"` argument. They have the type `PyCFunction`, with the self parameter, and a PyObject* parameter representing the single argument.

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

METH_CLASS

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

METH_STATIC

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

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

METH_COEXIST

  The method will be loaded in place of existing definitions. Without METH_COEXIST, the default is to skip repeated definitions. Since slot wrappers are loaded before the method table, the existence of a sq_contains slot, for example, would generate a wrapped method named `__contains__()` and preclude the loading of a corresponding PyCFunction with the same name. With the flag defined, the PyCFunction will be loaded in place of the wrapper object and will co-exist with the slot. This is helpful because calls to PyCFunctions are optimized more than wrapper object calls.

PyObject *PyCMethod_New(PyMethodDef *ml, PyObject *self, PyObject *module, PyTypeObject *cls)
  戻り値: 新しい参照。 次に属します: Stable ABI (バージョン 3.9 より).

  Turn ml into a Python callable object. The caller must ensure that ml outlives the callable. Typically, ml is defined as a static variable.

  The self parameter will be passed as the self argument to the C function in `ml->ml_meth` when invoked. self can be `NULL`.

  The callable object's `__module__` attribute can be set from the given module argument. module should be a Python string, which will be used as name of the module the function is defined in. If unavailable, it can be set to `None` or `NULL`.

  参考

  `function.__module__`

  The cls parameter will be passed as the defining_class argument to the C function. Must be set if `METH_METHOD` is set on `ml->ml_flags`.

  バージョン 3.9 で追加.

PyObject *PyCFunction_NewEx(PyMethodDef *ml, PyObject *self, PyObject *module)
  戻り値: 新しい参照。 次に属します: Stable ABI.

  Equivalent to `PyCMethod_New(ml, self, module, NULL)`.

PyObject *PyCFunction_New(PyMethodDef *ml, PyObject *self)
  戻り値: 新しい参照。 次に属します: Stable ABI (バージョン 3.4 より).

  Equivalent to `PyCMethod_New(ml, self, NULL, NULL)`.

## Accessing attributes of extension types

type PyMemberDef
  次に属します: Stable ABI (すべてのメンバーを含む).

  Structure which describes an attribute of a type which corresponds to a C struct member. Its fields are:

  Field | C Type | Meaning
  --- | --- | ---
  `name` | const char * | name of the member
  `type` | int | the type of the member in the C struct
  `offset` | Py_ssize_t | the offset in bytes that the member is located on the type's object struct
  `flags` | int | flag bits indicating if the field should be read-only or writable
  `doc` | const char * | points to the contents of the docstring

  `type` can be one of many `T_` macros corresponding to various C types. When the member is accessed in Python, it will be converted to the equivalent Python type.

  マクロ名 | C の型
  --- | ---
  T_SHORT | short
  T_INT | int
  T_LONG | long
  T_FLOAT | 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` and `T_OBJECT_EX` differ in that `T_OBJECT` returns `None` if the member is `NULL` and `T_OBJECT_EX` raises an `AttributeError`. Try to use `T_OBJECT_EX` over `T_OBJECT` because `T_OBJECT_EX` handles use of the `del` statement on that attribute more correctly than `T_OBJECT`.

  `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
  次に属します: Stable ABI (すべてのメンバーを含む).

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

  Field | C Type | Meaning
  --- | --- | ---
  name | const char * | 属性名
  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 | const char * | 任意のドキュメンテーション文字列
  closure | void * | optional user data pointer, providing additional data for getter and setter

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

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

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

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

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

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