共通のオブジェクト構造体 (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().

マクロ名	C の型	Python の型
Py_T_BYTE 次に属します: Stable ABI (バージョン 3.12 より).	char	int
Py_T_SHORT 次に属します: Stable ABI (バージョン 3.12 より).	short	int
Py_T_INT 次に属します: Stable ABI (バージョン 3.12 より).	int	int
Py_T_LONG 次に属します: Stable ABI (バージョン 3.12 より).	long	int
Py_T_LONGLONG 次に属します: Stable ABI (バージョン 3.12 より).	long long	int
Py_T_UBYTE 次に属します: Stable ABI (バージョン 3.12 より).	unsigned char	int
Py_T_UINT 次に属します: Stable ABI (バージョン 3.12 より).	unsigned int	int
Py_T_USHORT 次に属します: Stable ABI (バージョン 3.12 より).	unsigned short	int
Py_T_ULONG 次に属します: Stable ABI (バージョン 3.12 より).	unsigned long	int
Py_T_ULONGLONG 次に属します: Stable ABI (バージョン 3.12 より).	unsigned long long	int
Py_T_PYSSIZET 次に属します: Stable ABI (バージョン 3.12 より).	Py_ssize_t	int
Py_T_FLOAT 次に属します: Stable ABI (バージョン 3.12 より).	float	float
Py_T_DOUBLE 次に属します: Stable ABI (バージョン 3.12 より).	double	float
Py_T_BOOL 次に属します: Stable ABI (バージョン 3.12 より).	char (書き込まれる値は 0 または 1)	bool
Py_T_STRING 次に属します: Stable ABI (バージョン 3.12 より).	const char* (*)	str (RO)
Py_T_STRING_INPLACE 次に属します: Stable ABI (バージョン 3.12 より).	const char[] (*)	str (RO)
Py_T_CHAR 次に属します: Stable ABI (バージョン 3.12 より).	char (0-127)	str (**)
Py_T_OBJECT_EX 次に属します: Stable ABI (バージョン 3.12 より).	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 を返す必要があります。