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

Python のオブジェクト型の定義には、多数の構造体が使われます。 この節で
は、それらの構造体と使い方を説明します。


基本のオブジェクト型とマクロ
============================

すべての Python オブジェクトは、メモリ上の表現の先頭に少数の共通フィー
ルドを持ちます。 これらを表すのが "PyObject" 型と "PyVarObject" 型です
。 これらの型はマクロの展開によって定義され、そのマクロは他のすべての
Python オブジェクトの定義でも直接的または間接的に使われます。 その他の
マクロについては 参照カウント を参照してください。

type PyObject
    * 次に属します: Stable ABI (see below).*

   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. Nothing is actually declared to be a "PyObject", but
   every pointer to a Python object can be cast to a PyObject*.

   メンバーに直接アクセスしてはいけません。 代わりに "Py_REFCNT" や
   "Py_TYPE" などのマクロを使ってください。

   フリースレッドビルド用の Stable ABI ("abi3t") では、この構造体は不
   透明で、サイズやレイアウトは Python のバージョン間で変わる可能性が
   あります。 フリースレッドでないビルド用の Stable ABI ("abi3") では
   "ob_refcnt" フィールドと "ob_type" フィールドを利用できますが、直接
   使うことは推奨されません。

   Py_ssize_t ob_refcnt
       * 次に属します: Stable ABI.*

      "Py_REFCNT" が返す、オブジェクトの参照カウントです。 このフィー
      ルドを直接使わず、代わりに "Py_REFCNT"、"Py_INCREF()"、
      "Py_DecRef()" などの関数やマクロを使ってください。

      ビルド構成やプラットフォームによっては、フィールドの型は
      "Py_ssize_t" と異なる場合があります。

   PyTypeObject *ob_type
       * 次に属します: Stable ABI.*

      オブジェクトの型です。 このフィールドを直接使わず、代わりに
      "Py_TYPE" と "Py_SET_TYPE()" を使ってください。

   PyMutex ob_mutex

      *フリースレッド* ビルド ("Py_GIL_DISABLED" が定義されている場合)
      にだけ存在する、オブジェクトごとのロック です。

      このフィールドは **クリティカルセクション API 専用** です
      ("Py_BEGIN_CRITICAL_SECTION" / "Py_END_CRITICAL_SECTION")。
      "PyMutex_Lock" で直接ロックしては **いけません**。 デッドロック
      を引き起こす可能性があります。 独自のロックが必要なら、オブジェ
      クトの構造体に別の "PyMutex" フィールドを追加してください。

      Added in version 3.13.

type PyVarObject
    * 次に属します: Stable ABI (see below).*

   "PyObject" に "ob_size" フィールドを追加した型です。 何らかの *長さ
   * の概念を持つオブジェクトを対象としています。

   "PyObject" と同様に、メンバーに直接アクセスしてはいけません。 代わ
   りに "Py_SIZE"、"Py_REFCNT"、"Py_TYPE" などのマクロを使ってください
   。

   フリースレッドビルド用の Stable ABI ("abi3t") では、この構造体は不
   透明で、サイズやレイアウトは Python のバージョン間で変わる可能性が
   あります。 フリースレッドでないビルド用の Stable ABI ("abi3") では
   "ob_base" フィールドと "ob_size" フィールドを利用できますが、直接使
   うことは推奨されません。

   PyObject ob_base
       * 次に属します: Stable ABI.*

      共通のオブジェクトヘッダーです。 通常、このフィールドには直接ア
      クセスせず、代わりに "PyVarObject" を "PyObject" にキャストしま
      す。

   Py_ssize_t ob_size
       * 次に属します: Stable ABI.*

      サイズを保持するフィールドです。 その内容はオブジェクト内部の実
      装詳細として扱うべきです。

      このフィールドを直接使わず、代わりに "Py_SIZE" を使ってください
      。

      "PyObject_NewVar()" などのオブジェクト作成関数は、通常、このフィ
      ールドに要求されたサイズ (要素数) を設定します。 作成後は
      "Py_SET_SIZE" を使って "ob_size" に任意の値を格納できます。

      Python の "len()" 関数が返す、公開されたオブジェクトの長さを取得
      するには、代わりに "PyObject_Length()" を使ってください。

PyObject_HEAD

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

      PyObject ob_base;

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

PyObject_VAR_HEAD

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

      PyVarObject ob_base;

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

PyTypeObject PyBaseObject_Type
    * 次に属します: Stable ABI.*

   他のすべてのオブジェクトの基底クラスで、Python の "object" と同じで
   す。

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

   オブジェクト *x* がオブジェクト *y* かどうかを調べます。 Python の
   "x is y" と同じです。

   Added in version 3.10.

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

   オブジェクトが "None" シングルトンかどうかを調べます。 Python の "x
   is None" と同じです。

   Added in version 3.10.

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

   オブジェクトが "True" シングルトンかどうかを調べます。 Python の "x
   is True" と同じです。

   Added in version 3.10.

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

   オブジェクトが "False" シングルトンかどうかを調べます。 Python の
   "x is False" と同じです。

   Added in version 3.10.

PyTypeObject *Py_TYPE(PyObject *o)
    *戻り値: 借用参照。** 次に属します: Stable ABI (バージョン 3.14 よ
   り).*

   Python オブジェクト *o* の型を取得します。

   返される参照は *o* からの *借用参照* です。 "Py_DECREF()" などで解
   放しないでください。

   バージョン 3.11 で変更: "Py_TYPE()" が static なインライン関数にな
   りました。 引数の型は const PyObject* ではなくなりました。

int Py_IS_TYPE(PyObject *o, PyTypeObject *type)
    * 次に属します: Stable ABI (バージョン 3.15 より).*

   オブジェクト *o* の型が *type* ならゼロ以外、それ以外ならゼロを返し
   ます。 "Py_TYPE(o) == type" と同等です。

   Added in version 3.9.

void Py_SET_TYPE(PyObject *o, PyTypeObject *type)
    * This macro is available when compiling for the Stable ABI (バー
   ジョン 3.9 より).*

   オブジェクト *o* の型を *type* に設定します。 検証も参照カウントの
   操作も行いません。

   これは非常に低レベルの操作です。 代わりに
   "PyObject_SetAttrString()" などで Python の属性 "__class__" を設定
   することを検討してください。

   互換性のない型を代入すると、未定義の動作を引き起こす可能性がありま
   す。

   *type* が ヒープ型 である場合、呼び出し側はその型への新しい参照を作
   成する必要があります。 同様に、*o* の以前の型がヒープ型である場合は
   、その型への参照を解放する必要があります。

   Added in version 3.9.

Py_ssize_t Py_SIZE(PyVarObject *o)
    * 次に属します: Stable ABI (バージョン 3.15 より).*

   *o* の "ob_size" フィールドを取得します。

   バージョン 3.11 で変更: "Py_SIZE()" が static なインライン関数にな
   りました。 引数の型は const PyVarObject* ではなくなりました。

void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)
    * 次に属します: Stable ABI (バージョン 3.15 より).*

   *o* の "ob_size" フィールドを *size* に設定します。

   Added in version 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,


関数とメソッドの実装
====================

type PyCFunction
    * 次に属します: Stable ABI.*

   Python の呼び出し可能オブジェクトの多くを C で実装するための関数の
   型です。 この型の関数は 2 つの PyObject* 引数を受け取り、同じ型の値
   を返します。 戻り値が "NULL" の場合、例外が設定されていなければなり
   ません。 "NULL" でない場合は、Python に公開された関数の戻り値として
   扱われます。 この関数は新しい参照を返さなければなりません。

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

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

type PyCFunctionWithKeywords
    * 次に属します: Stable ABI.*

   METH_VARARGS | METH_KEYWORDS のシグネチャを持つ Python の呼び出し可
   能オブジェクトを C で実装するための関数の型です。 シグネチャは次の
   とおりです。

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

type PyCFunctionFast
    * 次に属します: Stable ABI (バージョン 3.13 より).*

   "METH_FASTCALL" のシグネチャを持つ Python の呼び出し可能オブジェク
   トを C で実装するための関数の型です。 シグネチャは次のとおりです。

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

type PyCFunctionFastWithKeywords
    * 次に属します: Stable ABI (バージョン 3.13 より).*

   METH_FASTCALL | METH_KEYWORDS のシグネチャを持つ Python の呼び出し
   可能オブジェクトを C で実装するための関数の型です。 シグネチャは次
   のとおりです。

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

type PyCMethod

   METH_METHOD | METH_FASTCALL | METH_KEYWORDS のシグネチャを持つ
   Python の呼び出し可能オブジェクトを C で実装するための関数の型です
   。 シグネチャは次のとおりです。

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

   Added in version 3.9.

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

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

   const char *ml_name

      メソッドの名前。

      *ml_name* が "NULL" のエントリーは、"PyMethodDef" 配列の終端を示
      します。

   PyCFunction ml_meth

      C での実装へのポインタ。

   int ml_flags

      呼び出しの構成方法を示すフラグビット。

   const char *ml_doc

      ドキュメント文字列の内容へのポインタ。

"ml_meth" は C の関数ポインタです。 関数の型はさまざまですが、戻り値は
常に PyObject* です。 関数が "PyCFunction" 型でない場合、メソッドテー
ブル内でのキャストがコンパイラから要求されます。 "PyCFunction" では第
1 引数を PyObject* と定義していますが、メソッドの実装では *self* オブ
ジェクト固有の C 型を使うのが一般的です。

"ml_flags" フィールドは、次のフラグを含められるビットフィールドです。
各フラグは呼び出し規約または束縛の規約を示します。

次の呼び出し規約があります。

METH_VARARGS
    * 次に属します: Stable ABI.*

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

METH_KEYWORDS

   他のフラグとの特定の組み合わせでのみ使えます。 使えるのは
   METH_VARARGS | METH_KEYWORDS、METH_FASTCALL | METH_KEYWORDS、
   METH_METHOD | METH_FASTCALL | METH_KEYWORDS です。

METH_VARARGS | METH_KEYWORDS
   これらのフラグを持つメソッドは "PyCFunctionWithKeywords" 型でなけれ
   ばなりません。 この関数は *self*、*args*、*kwargs* の 3 引数を受け
   取ります。 *kwargs* はすべてのキーワード引数を含む辞書で、キーワー
   ド引数がなければ "NULL" の場合もあります。 通常は
   "PyArg_ParseTupleAndKeywords()" で引数を処理します。

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

   位置引数のみをサポートする高速な呼び出し規約です。 メソッドは
   "PyCFunctionFast" 型です。 第 1 引数は *self*、第 2 引数は引数を表
   す PyObject* 値の C 配列、第 3 引数は引数の個数 (配列の長さ) です。

   Added in version 3.7.

   バージョン 3.10 で変更: "METH_FASTCALL" が Stable ABI の一部になり
   ました。

METH_FASTCALL | METH_KEYWORDS
   "METH_FASTCALL" を拡張してキーワード引数もサポートするもので、メソ
   ッドは "PyCFunctionFastWithKeywords" 型です。 キーワード引数は
   vectorcall プロトコル と同じ方法で渡されます。 PyObject* 型の第 4
   引数が追加され、キーワード引数の名前 (文字列であることが保証されま
   す) のタプルを渡します。 キーワード引数がなければ "NULL" の場合もあ
   ります。 キーワード引数の値は *args* 配列の位置引数の後に格納されま
   す。

   Added in version 3.7.

METH_METHOD
    * 次に属します: Stable ABI (バージョン 3.7 より).*

   他のフラグとの組み合わせ METH_METHOD | METH_FASTCALL |
   METH_KEYWORDS でのみ使えます。

METH_METHOD | METH_FASTCALL | METH_KEYWORDS
   METH_FASTCALL | METH_KEYWORDS を拡張し、*定義元のクラス*、つまりそ
   のメソッドを含むクラスを扱えるようにしたものです。 定義元のクラスは
   "Py_TYPE(self)" の基底クラスである場合もあります。

   メソッドは "PyCMethod" 型でなければなりません。 これは
   "METH_FASTCALL | METH_KEYWORDS" と同じですが、"self" の後に
   "defining_class" 引数が追加されています。

   Added in version 3.9.

METH_NOARGS
    * 次に属します: Stable ABI.*

   引数を取らないメソッドに "METH_NOARGS" フラグを指定すると、引数が渡
   されたかどうかをメソッド内で確認する必要がなくなります。 このメソッ
   ドは "PyCFunction" 型でなければなりません。 第 1 引数は通常 *self*
   という名前で、モジュールまたはオブジェクトのインスタンスへの参照を
   保持します。 第 2 引数は常に "NULL" です。

   関数には 2 つの引数が必要です。 第 2 引数は使わないので、
   "Py_UNUSED" でコンパイラの警告を抑制できます。

METH_O
    * 次に属します: Stable ABI.*

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

次の 2 つの定数は呼び出し規約ではなく、クラスのメソッドでの束縛を指定
します。 モジュールで定義する関数には使えません。 1 つのメソッドに設定
できるのは、どちらか 1 つだけです。

METH_CLASS
    * 次に属します: Stable ABI.*

   メソッドの第 1 引数には、型のインスタンスの代わりに型オブジェクトが
   渡されます。 組み込みデコレータ "@classmethod" で作成されるものと同
   様の *クラスメソッド* を作成するために使います。

METH_STATIC
    * 次に属します: Stable ABI.*

   メソッドの第 1 引数には、型のインスタンスの代わりに "NULL" が渡され
   ます。 組み込みデコレータ "@staticmethod" で作成されるものと同様の
   *静的メソッド* を作成するために使います。

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

METH_COEXIST
    * 次に属します: Stable ABI.*

   既存の定義を置き換えてメソッドを登録します。 *METH_COEXIST* がない
   場合、デフォルトでは重複する定義をスキップします。 スロットラッパー
   はメソッドテーブルより先に登録されるため、例えば *sq_contains* スロ
   ットがあると、"__contains__()" という名前のラップされたメソッドが生
   成され、同じ名前に対応する PyCFunction は登録されません。 このフラ
   グがある場合、ラッパーオブジェクトの代わりに PyCFunction が登録され
   、スロットと共存します。 PyCFunction の呼び出しはラッパーオブジェク
   トの呼び出しより最適化されているので、この方法が役立ちます。

PyTypeObject PyCMethod_Type

   The type object corresponding to Python C method objects. This is
   available as "types.BuiltinMethodType" in the Python layer.

int PyCMethod_Check(PyObject *op)

   *op* が "PyCMethod_Type" 型またはそのサブタイプのインスタンスなら真
   を返します。 この関数は常に成功します。

int PyCMethod_CheckExact(PyObject *op)

   "PyCMethod_Check()" と同じですが、サブタイプは対象にしません。

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

   *ml* を Python の *呼び出し可能* オブジェクトにします。 呼び出し側
   は、*ml* がその *呼び出し可能* オブジェクトより長く存続するようにし
   なければなりません。 通常、*ml* は静的変数として定義します。

   *self* 引数は、"ml->ml_meth" の C 関数を呼び出すときに、その関数の
   *self* 引数として渡されます。 *self* は "NULL" にできます。

   渡された *module* 引数から、*呼び出し可能* オブジェクトの
   "__module__" 属性を設定できます。 *module* は Python の文字列で、関
   数の定義元モジュールの名前として使われます。 名前が分からない場合は
   "None" または "NULL" にできます。

   参考: "function.__module__"

   *cls* 引数は C 関数の *defining_class* 引数として渡されます。
   "ml->ml_flags" に "METH_METHOD" が設定されている場合は、指定する必
   要があります。

   Added in version 3.9.

PyTypeObject PyCFunction_Type
    * 次に属します: Stable ABI.*

   Python の C 関数オブジェクトに対応する型オブジェクトです。 Python
   レベルでは "types.BuiltinFunctionType" として利用できます。

int PyCFunction_Check(PyObject *op)

   *op* が "PyCFunction_Type" 型またはそのサブタイプのインスタンスなら
   真を返します。 この関数は常に成功します。

int PyCFunction_CheckExact(PyObject *op)

   "PyCFunction_Check()" と同じですが、サブタイプは対象にしません。

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

   "PyCMethod_New(ml, self, module, NULL)" と同等です。

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

   "PyCMethod_New(ml, self, NULL, NULL)" と同等です。

int PyCFunction_GetFlags(PyObject *func)
    * 次に属します: Stable ABI.*

   "ml_flags" に渡された、*func* の関数フラグを取得します。

   *func* が C 関数オブジェクトでない場合、例外を設定して失敗します。
   *func* は "NULL" であってはいけません。

   成功すると関数のフラグを返し、失敗すると例外を設定して "-1" を返し
   ます。

int PyCFunction_GET_FLAGS(PyObject *func)

   "PyCFunction_GetFlags()" と同じですが、エラーや型のチェックを行いま
   せん。

PyCFunction PyCFunction_GetFunction(PyObject *func)
    * 次に属します: Stable ABI.*

   "ml_meth" に渡された、*func* の関数ポインタを取得します。

   *func* が C 関数オブジェクトでない場合、例外を設定して失敗します。
   *func* は "NULL" であってはいけません。

   成功すると関数ポインタを返し、失敗すると例外を設定して "NULL" を返
   します。

int PyCFunction_GET_FUNCTION(PyObject *func)

   "PyCFunction_GetFunction()" と同じですが、エラーや型のチェックを行
   いません。

PyObject *PyCFunction_GetSelf(PyObject *func)
    * 次に属します: Stable ABI.*

   *func* の「self」オブジェクトを取得します。 これは "PyCFunction" の
   第 1 引数に渡されるオブジェクトです。 "PyModuleDef" 上の
   "PyMethodDef" を介して作成した C 関数オブジェクトでは、作成されたモ
   ジュールオブジェクトになります。

   *func* が C 関数オブジェクトでない場合、例外を設定して失敗します。
   *func* は "NULL" であってはいけません。

   This function returns a *borrowed reference* to the "self" object
   on success, and "NULL" with an exception set on failure.

PyObject *PyCFunction_GET_SELF(PyObject *func)

   "PyCFunction_GetSelf()" と同じですが、エラーや型のチェックを行いま
   せん。

PyTypeObject *PyCFunction_GET_CLASS(PyObject *func)

   *func* の "ml_flags" に "METH_METHOD" が含まれる場合、定義元クラス
   への *借用参照* を返します。 それ以外の場合は、例外を設定せずに
   "NULL" を返します。

   *func* は C 関数オブジェクトでなければならず、"NULL" にしてはいけま
   せん。 この関数はエラーや型のチェックを行いません。

   Added in version 3.9.


拡張型の属性へのアクセス
========================

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

   C 構造体のメンバーに対応する、型の属性を記述する構造体です。 クラス
   を定義するときは、この構造体の NULL で終端した配列を "tp_members"
   スロットに設定します。

   フィールドは順に次のとおりです。

   const char *name

      メンバーの名前。 NULL 値は "PyMemberDef[]" 配列の終端を示します
      。

      文字列は静的に割り当てられている必要があります。 コピーは作成さ
      れません。

   int type

      C 構造体内のメンバーの型。 使用できる値は メンバーの型 を参照し
      てください。

   Py_ssize_t offset

      その型のオブジェクト構造体内での、メンバーのバイト単位のオフセッ
      ト。

   int flags

      メンバーのフラグ を 0 個以上、ビット OR で組み合わせた値。

   const char *doc

      ドキュメント文字列、または NULL。 文字列は静的に割り当てられてい
      る必要があり、コピーは作成されません。 通常は "PyDoc_STR" を使っ
      て定義します。

   デフォルト ("flags" が "0" の場合) では、メンバーは読み書きの両方を
   許可します。 読み取り専用にするには "Py_READONLY" フラグを使ってく
   ださい。 "Py_T_STRING" など、一部の型は "Py_READONLY" を暗黙に指定
   します。 削除できるのは "Py_T_OBJECT_EX" (および従来の "T_OBJECT")
   のメンバーだけです。

   ヒープに割り当てられた型 ("PyType_FromSpec()" などで作成したもの)
   では、型オブジェクトの "tp_vectorcall_offset" に対応する特殊メンバ
   ー ""__vectorcalloffset__"" の定義を "PyMemberDef" に含められます。
   このメンバーは "Py_T_PYSSIZET" と、"Py_READONLY" または
   "Py_READONLY | Py_RELATIVE_OFFSET" のいずれかで定義しなければなりま
   せん。 例えば次のようにします。

      static PyMemberDef spam_type_members[] = {
          {"__vectorcalloffset__", Py_T_PYSSIZET,
           offsetof(Spam_object, vectorcall), Py_READONLY},
          {NULL}  /* 終端 */
      };

   ("offsetof()" を使うには "#include <stddef.h>" が必要な場合がありま
   す。)

   従来のオフセット "tp_dictoffset" と "tp_weaklistoffset" も、
   ""__dictoffset__"" メンバーと ""__weaklistoffset__"" メンバーを使っ
   て同様に定義できます。 ただし、拡張モジュールでは代わりに
   "Py_TPFLAGS_MANAGED_DICT" と "Py_TPFLAGS_MANAGED_WEAKREF" を使うこ
   とを強く推奨します。

   バージョン 3.12 で変更: "PyMemberDef" が常に利用可能になりました。
   以前は ""structmember.h"" のインクルードが必要でした。

   バージョン 3.14 で変更: ""__vectorcalloffset__""、
   ""__dictoffset__""、""__weaklistoffset__"" で "Py_RELATIVE_OFFSET"
   を使えるようになりました。

PyObject *PyMember_GetOne(const char *obj_addr, struct PyMemberDef *m)
    * 次に属します: Stable ABI.*

   アドレス *obj_addr* にあるオブジェクトの属性を取得します。 属性は
   "PyMemberDef" *m* で記述します。 エラー時は "NULL" を返します。

   バージョン 3.12 で変更: "PyMember_GetOne" が常に利用可能になりまし
   た。 以前は ""structmember.h"" のインクルードが必要でした。

int PyMember_SetOne(char *obj_addr, struct PyMemberDef *m, PyObject *o)
    * 次に属します: Stable ABI.*

   アドレス *obj_addr* にあるオブジェクトの属性を、オブジェクト *o* に
   設定します。 設定する属性は "PyMemberDef" *m* で記述します。 成功す
   ると "0"、失敗すると負の値を返します。

   バージョン 3.12 で変更: "PyMember_SetOne" が常に利用可能になりまし
   た。 以前は ""structmember.h"" のインクルードが必要でした。


メンバーのフラグ
----------------

"PyMemberDef.flags" には次のフラグを使えます。

Py_READONLY
    * 次に属します: Stable ABI (バージョン 3.12 より).*

   書き込み不可。

Py_AUDIT_READ
    * 次に属します: Stable ABI (バージョン 3.12 より).*

   読み取り前に "object.__getattr__" 監査イベント を発行します。

Py_RELATIVE_OFFSET
    * 次に属します: Stable ABI (バージョン 3.12 より).*

   この "PyMemberDef" エントリーの "offset" が、"PyObject" からではな
   く、サブクラス固有のデータからのオフセットであることを示します。

   負の "basicsize" を使ってクラスを作成するとき、"Py_tp_members" "ス
   ロット" の一部としてのみ使えます。 この場合は指定が必須です。 クラ
   スの作成中、スロットから "tp_members" を設定する際に、Python はこの
   フラグをクリアし、"PyMemberDef.offset" を "PyObject" 構造体からのオ
   フセットに設定します。

バージョン 3.10 で変更: "#include "structmember.h"" で利用できる
"RESTRICTED"、"READ_RESTRICTED"、"WRITE_RESTRICTED" マクロは非推奨です
。 "READ_RESTRICTED" と "RESTRICTED" は "Py_AUDIT_READ" と同等で、
"WRITE_RESTRICTED" は何もしません。

バージョン 3.12 で変更: "READONLY" マクロの名前が "Py_READONLY" に変更
されました。 "PY_AUDIT_READ" マクロの名前も、接頭辞が "Py_" になるよう
変更されました。 新しい名前は常に利用できます。 以前は "#include
"structmember.h"" が必要でした。 このヘッダーは引き続き利用でき、従来
の名前を提供します。

PY_AUDIT_READ

   "Py_AUDIT_READ" の緩やかに非推奨となった別名です ("y" の大文字と小
   文字の違いに注意してください)。 "#include "structmember.h"" でのみ
   利用できます。

   バージョン 3.12 で ソフト非推奨 <Soft deprecated>: 代わりに
   "Py_AUDIT_READ" を使ってください。

PY_WRITE_RESTRICTED

   何の効果もないメンバーフラグで、後方互換性のためだけに残されていま
   す。 "#include "structmember.h"" でのみ利用できます。

   バージョン 3.15.2 で ソフト非推奨 <Soft deprecated>: 代わりに、この
   フラグを省いてください。


メンバーの型
------------

"PyMemberDef.type" には、各種の C の型に対応する以下のマクロのいずれか
を指定できます。 Python からメンバーにアクセスすると、対応する Python
の型に変換されます。 Python から設定するときは、C の型に変換されます。
変換できない場合は "TypeError" や "ValueError" などの例外が送出されま
す。

Unless marked (D), attributes defined this way cannot be deleted using
e.g. "del" or "delattr()".

These values are available when compiling for the Stable ABI since
version 3.12.

+-----------------------------------+-----------------------------------+-----------------------------------+
| マクロ名                          | C の型                            | Python の型                       |
|===================================|===================================|===================================|
| Py_T_BYTE                         | char                              | "int"                             |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Py_T_SHORT                        | short                             | "int"                             |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Py_T_INT                          | int                               | "int"                             |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Py_T_LONG                         | long                              | "int"                             |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Py_T_LONGLONG                     | long long                         | "int"                             |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Py_T_UBYTE                        | unsigned char                     | "int"                             |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Py_T_UINT                         | unsigned int                      | "int"                             |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Py_T_USHORT                       | unsigned short                    | "int"                             |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Py_T_ULONG                        | unsigned long                     | "int"                             |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Py_T_ULONGLONG                    | unsigned long long                | "int"                             |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Py_T_PYSSIZET                     | Py_ssize_t                        | "int"                             |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Py_T_FLOAT                        | float                             | "float"                           |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Py_T_DOUBLE                       | double                            | "float"                           |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Py_T_BOOL                         | char (書き込まれる値は 0 または   | "bool"                            |
|                                   | 1)                                |                                   |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Py_T_STRING                       | const char* (*)                   | "str" (RO)                        |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Py_T_STRING_INPLACE               | const char[] (*)                  | "str" (RO)                        |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Py_T_CHAR                         | char (0-127)                      | "str" (**)                        |
+-----------------------------------+-----------------------------------+-----------------------------------+
| Py_T_OBJECT_EX                    | PyObject*                         | "object" (D)                      |
+-----------------------------------+-----------------------------------+-----------------------------------+

   (*): ゼロで終端された UTF-8 エンコードの C 文字列です。
   "Py_T_STRING" では C 側の表現はポインタで、"Py_T_STRING_INPLACE" で
   は文字列を構造体に直接格納します。

   (**): 長さ 1 の文字列です。 ASCII だけを受け付けます。

   (RO): "Py_READONLY" が暗黙に指定されます。

   (D): 削除できます。 削除するとポインタは "NULL" になります。 "NULL"
   ポインタを読み取ると "AttributeError" が送出されます。

Added in version 3.12: 以前のバージョンでは、これらのマクロは
"#include "structmember.h"" でのみ利用でき、"Py_" 接頭辞のない名前 (例
えば "T_INT") が使われていました。 このヘッダーは引き続き利用でき、従
来の名前に加えて、次の非推奨の型も含みます。

T_OBJECT

   "Py_T_OBJECT_EX" と似ていますが、"NULL" は "None" に変換されます。
   このため Python では、属性を削除すると実質的に "None" を設定するこ
   とになるという、意外な動作になります。

T_NONE

   常に "None"。 "Py_READONLY" とともに使わなければなりません。


ゲッターとセッターの定義
------------------------

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

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

   const char *name

      属性名

   getter get

      属性を取得する C 関数。

   setter set

      属性を設定または削除する、省略可能な C 関数。 "NULL" なら属性は
      読み取り専用になります。

   const char *doc

      任意のドキュメンテーション文字列

   void *closure

      ゲッターとセッターに追加データを提供する、省略可能なユーザーデー
      タポインタ。

typedef PyObject *(*getter)(PyObject*, void*)
    * 次に属します: Stable ABI.*

   "get" 関数は、PyObject* 引数 (インスタンス) とユーザーデータポイン
   タ (対応する "closure") を受け取ります。

   成功すると新しい参照を返し、失敗すると例外を設定して "NULL" を返す
   必要があります。

typedef int (*setter)(PyObject*, PyObject*, void*)
    * 次に属します: Stable ABI.*

   "set" 関数は、2 つの PyObject* 引数 (インスタンスと設定する値) とユ
   ーザーデータポインタ (対応する "closure") を受け取ります。

   属性を削除する場合、第 2 引数は "NULL" です。 成功すると "0" を返し
   、失敗すると例外を設定して "-1" を返す必要があります。
