型オブジェクト

type PyTypeObject

次に属します: Limited API (不透明な構造体として).

組み込み型を記述する際に用いられる、オブジェクトを表す C 構造体です。

PyTypeObject PyType_Type

次に属します: Stable ABI.

型オブジェクト自身の型オブジェクトです。Python レイヤにおける type と同じオブジェクトです。

int PyType_Check(PyObject *o)

オブジェクト o が型オブジェクトであれば、標準の型オブジェクトから派生した型のインスタンスも含めてゼロ以外を返します。 それ以外の場合は 0 を返します。 この関数は常に成功します。

int PyType_CheckExact(PyObject *o)

オブジェクト o が標準の型オブジェクトのインスタンスであり、そのサブタイプのインスタンスではない場合にゼロ以外を返します。 それ以外の場合は 0 を返します。 この関数は常に成功します。

unsigned int PyType_ClearCache()

次に属します: Stable ABI.

内部の検索キャッシュをクリアします。現在のバージョンタグを返します。

unsigned long PyType_GetFlags(PyTypeObject *type)

次に属します: Stable ABI.

type の tp_flags メンバーを返します。 この関数は主に Py_LIMITED_API で使うことを想定しています。 個々のフラグビットは Python のリリース間で安定していることが保証されますが、tp_flags 自体へのアクセスは Limited API の一部ではありません。

Added in version 3.2.

バージョン 3.4 で変更: 返り値の型が long ではなく unsigned long になりました。

PyObject *PyType_GetDict(PyTypeObject *type)

型オブジェクトの内部の名前空間を返します。 通常は読み取り専用のプロキシ (cls.__dict__) を通じてのみ公開されるものです。 tp_dict に直接アクセスする代わりに使えます。 返された辞書は読み取り専用として扱わなければなりません。

この関数は、辞書への直接アクセスが必要で、プロキシや PyObject_GetAttr() などによる間接アクセスでは不十分な、特定の埋め込みや言語バインディングの用途を想定しています。

拡張モジュールで独自の型を設定するときは、引き続き直接または間接的に tp_dict を使ってください。

Added in version 3.12.

void PyType_Modified(PyTypeObject *type)

次に属します: Stable ABI.

内部の検索キャッシュを、その type とすべてのサブタイプに対して無効にします。この関数は type の属性や基底クラス列を変更したあとに手動で呼び出さなければなりません。

int PyType_AddWatcher(PyType_WatchCallback callback)

callback を型ウォッチャーとして登録します。 ゼロ以上の整数 ID を返します。 以後 PyType_Watch() を呼び出すときには、この ID を渡す必要があります。 エラー時 (例えば利用可能なウォッチャー ID が残っていない場合) は、例外を設定して -1 を返します。

フリースレッドビルドでは PyType_AddWatcher() はスレッドセーフではないため、起動時 (最初のスレッドを作成する前) に呼び出さなければなりません。

Added in version 3.12.

int PyType_ClearWatcher(int watcher_id)

watcher_id (PyType_AddWatcher() が以前返した値) で指定したウォッチャーを解除します。 成功すると 0、エラー時 (例えば watcher_id が一度も登録されていない場合) は -1 を返します。

拡張モジュールは、以前 PyType_AddWatcher() の呼び出しで受け取ったものでない watcher_id を渡して PyType_ClearWatcher を呼び出してはいけません。

Added in version 3.12.

int PyType_Watch(int watcher_id, PyObject *type)

type を監視対象にします。 PyType_Modified() が type の変更を報告するたびに、PyType_AddWatcher() から watcher_id を割り当てられたコールバックが呼び出されます。 ただし、type に対する一連の変更の間に _PyType_Lookup() が呼び出されなければ、コールバックは 1 度だけ呼び出されることがあります。 これは実装詳細であり、変更される可能性があります。

拡張モジュールは、以前 PyType_AddWatcher() の呼び出しで受け取ったものでない watcher_id を渡して PyType_Watch を呼び出してはいけません。

Added in version 3.12.

int PyType_Unwatch(int watcher_id, PyObject *type)

type を監視対象から外します。 以前の PyType_Watch() の呼び出しを取り消します。 type は NULL であってはいけません。

拡張モジュールは、以前 PyType_AddWatcher() の呼び出しで受け取ったものでない watcher_id を渡して、この関数を呼び出してはいけません。

成功すると 0 を返します。 失敗すると例外を設定して -1 を返します。

Added in version 3.12.

typedef int (*PyType_WatchCallback)(PyObject *type)

型ウォッチャーのコールバック関数の型。

コールバックは type を変更したり、type またはその MRO 内の型に対して PyType_Modified() が呼び出されるようにしたりしてはいけません。 この規則に違反すると、無限再帰を引き起こす可能性があります。

Added in version 3.12.

int PyType_HasFeature(PyTypeObject *o, int feature)

型オブジェクト o に機能 feature が設定されていれば、ゼロ以外を返します。 型の機能は、それぞれ 1 ビットのフラグで表します。

int PyType_FastSubclass(PyTypeObject *type, int flag)

型オブジェクト type にサブクラスフラグ flag が設定されていれば、ゼロ以外を返します。 サブクラスフラグは Py_TPFLAGS_*_SUBCLASS で表します。 この関数は、一般的な型の多くの _Check 関数で使われています。

参考

PyObject_TypeCheck() は、サブクラスフラグのない型の _Check 関数で、より低速な代替として使われます。

int PyType_IS_GC(PyTypeObject *o)

型オブジェクトが循環参照の検出をサポートしている場合に真を返します。 型のフラグ Py_TPFLAGS_HAVE_GC を調べます。

int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)

次に属します: Stable ABI.

a が b のサブタイプの場合に真を返します。

この関数が調べるのは実際のサブタイプ関係だけで、b の __subclasscheck__() は呼び出しません。 issubclass() と同じ検査を行うには PyObject_IsSubclass() を呼び出してください。

PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)

戻り値: 新しい参照。 次に属します: Stable ABI.

型オブジェクトの tp_alloc スロット用の汎用ハンドラです。 Python のデフォルトのメモリ割り当て機構を使って新しいインスタンスのメモリを割り当て、ゼロで埋めてから、PyObject_Init() または PyObject_InitVar() を呼び出すのと同じように初期化します。

オブジェクトのメモリを割り当てるためにこれを直接呼び出してはいけません。 代わりに型の tp_alloc スロットを呼び出してください。

ガベージコレクションをサポートする型 (Py_TPFLAGS_HAVE_GC フラグが設定されているもの) では、PyObject_GC_New または PyObject_GC_NewVar と同様に動作し、tp_free に設定した PyObject_GC_Del() と組み合わせて使う必要があります。 それ以外の型では、PyObject_New または PyObject_NewVar と同様に動作し、tp_free に設定した PyObject_Free() と組み合わせて使う必要があります。 いずれの場合も、初期化前にメモリがゼロで埋められることが保証される点が異なります。

PyObject *PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)

戻り値: 新しい参照。 次に属します: Stable ABI.

型オブジェクトの tp_new スロット用の汎用ハンドラです。 型の tp_alloc スロットを使って新しいインスタンスを作成し、作成したオブジェクトを返します。

int PyType_Ready(PyTypeObject *type)

次に属します: Stable ABI.

型オブジェクトの初期化を完了します。 すべての型オブジェクトについて、初期化を仕上げるために呼び出す必要があります。 この関数は、型の基底クラスから継承するスロットを追加します。 成功すると 0 を返し、エラー時は例外を設定して -1 を返します。

注釈

基底クラスのいずれかが GC プロトコルを実装しており、指定した型のフラグに Py_TPFLAGS_HAVE_GC が含まれていなければ、GC プロトコルの実装が基底クラスから自動的に継承されます。 一方、作成する型のフラグに Py_TPFLAGS_HAVE_GC が含まれている場合は、少なくとも tp_traverse ハンドラを実装して、自分で GC プロトコルを実装 しなければなりません。

PyObject *PyType_GetName(PyTypeObject *type)

戻り値: 新しい参照。 次に属します: Stable ABI (バージョン 3.11 より).

型の名前を返します。 型の __name__ 属性の取得と同等です。

Added in version 3.11.

PyObject *PyType_GetQualName(PyTypeObject *type)

戻り値: 新しい参照。 次に属します: Stable ABI (バージョン 3.11 より).

型の修飾名を返します。 型の __qualname__ 属性の取得と同等です。

Added in version 3.11.

PyObject *PyType_GetFullyQualifiedName(PyTypeObject *type)

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

型の完全修飾名を返します。 f"{type.__module__}.{type.__qualname__}" と同等ですが、type.__module__ が文字列でないか "builtins" の場合は type.__qualname__ と同等です。

Added in version 3.13.

PyObject *PyType_GetModuleName(PyTypeObject *type)

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

型のモジュール名を返します。 type.__module__ 属性の取得と同等です。

Added in version 3.13.

void *PyType_GetSlot(PyTypeObject *type, int slot)

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

与えられたスロットに格納されている関数ポインタを返します。返り値が NULL の場合は、スロットが NULL か、関数が不正な引数で呼ばれたことを示します。通常、呼び出し側は返り値のポインタを適切な関数型にキャストします。

slot 引数に指定できる値は PyType_Slot.slot を参照してください。

Added in version 3.4.

バージョン 3.10 で変更: PyType_GetSlot() がすべての型を受け付けるようになりました。 以前は ヒープ型 に限られていました。

PyObject *PyType_GetModule(PyTypeObject *type)

戻り値: 借用参照。 次に属します: Stable ABI (バージョン 3.10 より).

PyType_FromModuleAndSpec() で型を作成したときに、その型に関連付けたモジュールオブジェクトを返します。

返される参照は type からの 借用参照 で、type への参照を保持している間は有効です。 Py_DECREF() などで解放しないでください。

指定された型にモジュールが関連付けられていない場合は、TypeError を設定して NULL を返します。

This function is usually used to get the module in which a method is defined. Note that in such a method, PyType_GetModule(Py_TYPE(self)) may not return the intended result. Py_TYPE(self) may be a subclass of the intended class, and subclasses are not necessarily defined in the same module as their superclass. See PyCMethod to get the class that defines the method. See PyType_GetModuleByDef() for cases when PyCMethod cannot be used.

Added in version 3.9.

void *PyType_GetModuleState(PyTypeObject *type)

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

指定された型に関連付けられたモジュールオブジェクトの状態を返します。 PyType_GetModule() の結果に対して PyModule_GetState() を呼び出す処理の短縮形です。

指定された型にモジュールが関連付けられていない場合は、TypeError を設定して NULL を返します。

type にモジュールが関連付けられていても、その状態が NULL の場合は、例外を設定せずに NULL を返します。

Added in version 3.9.

PyObject *PyType_GetModuleByDef(PyTypeObject *type, struct PyModuleDef *def)

戻り値: 借用参照。 次に属します: Stable ABI (バージョン 3.13 より).

Find the first superclass whose module was created from the given PyModuleDef def, and return that module.

モジュールが見つからない場合は、TypeError を送出して NULL を返します。

この関数は、tp_init や nb_add などのスロットメソッドや、PyCMethod 呼び出し規約でメソッドの定義元クラスを渡せない場所で、 PyModule_GetState() と組み合わせてモジュール状態を取得するために使うことを想定しています。

返される参照は type からの 借用参照 で、type への参照を保持している間は有効です。 Py_DECREF() などで解放しないでください。

Added in version 3.11.

int PyType_GetBaseByToken(PyTypeObject *type, void *token, PyTypeObject **result)

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

Find the first superclass in type's method resolution order whose Py_tp_token token is equal to the given one.

• 見つかった場合は、*result にその型への新しい 強参照 を設定して 1 を返します。

• 見つからない場合は、*result に NULL を設定して 0 を返します。

• エラー時は *result に NULL を設定し、例外を設定して -1 を返します。

result 引数は NULL にできます。 その場合、*result は設定されません。 戻り値だけが必要な場合に使ってください。

The token argument may not be NULL.

Added in version 3.14.

int PyUnstable_Type_AssignVersionTag(PyTypeObject *type)

これは Unstable APIです。マイナーリリースで予告なく変更されることがあります。

指定された型へのバージョンタグの割り当てを試みます。

型がすでに有効なバージョンタグを持っていたか、新しいタグを割り当てられた場合は 1 を返します。 新しいタグを割り当てられなかった場合は 0 を返します。

Added in version 3.12.

int PyType_SUPPORTS_WEAKREFS(PyTypeObject *type)

type のインスタンスが弱参照の作成をサポートする場合は真、それ以外の場合は偽を返します。 この関数は常に成功します。 type は NULL であってはいけません。

参考

• 弱参照オブジェクト

• weakref

ヒープに割り当てられる型の作成

The following functions and structs are used to create heap types.

PyObject *PyType_FromMetaclass(PyTypeObject *metaclass, PyObject *module, PyType_Spec *spec, PyObject *bases)

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

spec から ヒープ型 を作成して返します (Py_TPFLAGS_HEAPTYPE を参照)。

The metaclass metaclass is used to construct the resulting type object. When metaclass is NULL, the metaclass is derived from bases (or Py_tp_base[s] slots if bases is NULL, see below).

tp_new をオーバーライドするメタクラスは、tp_new が NULL の場合を除いてサポートされません。

The bases argument can be used to specify base classes; it can either be only one class or a tuple of classes. If bases is NULL, the Py_tp_bases slot is used instead. If that also is NULL, the Py_tp_base slot is used instead. If that also is NULL, the new type derives from object.

The module argument can be used to record the module in which the new class is defined. It must be a module object or NULL. If not NULL, the module is associated with the new type and can later be retrieved with PyType_GetModule(). The associated module is not inherited by subclasses; it must be specified for each class individually.

この関数は新しい型に対して PyType_Ready() を呼び出します。

この関数の動作は、type() の呼び出しや class 文の使用と完全には一致 しない 点に注意してください。 利用者が指定した基底型やメタクラスを使う場合は、PyType_From* 関数よりも type (またはメタクラス) を 呼び出す 方法を推奨します。 具体的には、次の違いがあります。

• __new__() is not called on the new class (and it must be set to type.__new__).

• 新しいクラスの __init__() は呼び出されません。

• どの基底クラスの __init_subclass__() も呼び出されません。

• 新しいデスクリプタの __set_name__() は呼び出されません。

Added in version 3.12.

PyObject *PyType_FromModuleAndSpec(PyObject *module, PyType_Spec *spec, PyObject *bases)

戻り値: 新しい参照。 次に属します: Stable ABI (バージョン 3.10 より).

PyType_FromMetaclass(NULL, module, spec, bases) と同等です。

Added in version 3.9.

バージョン 3.10 で変更: bases 引数に単一のクラスを、tp_doc スロットに NULL を指定できるようになりました。

バージョン 3.12 で変更: 指定された基底クラスに対応するメタクラスを探して使うようになりました。 以前は type のインスタンスだけを返していました。

メタクラスの tp_new は 無視 されるため、初期化が不完全になる可能性があります。 メタクラスが tp_new をオーバーライドしているクラスの作成は非推奨です。

バージョン 3.14 で変更: メタクラスが tp_new をオーバーライドしているクラスは、作成できなくなりました。

PyObject *PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)

戻り値: 新しい参照。 次に属します: Stable ABI (バージョン 3.3 より).

PyType_FromMetaclass(NULL, NULL, spec, bases) と同等です。

Added in version 3.3.

バージョン 3.12 で変更: 指定された基底クラスに対応するメタクラスを探して使うようになりました。 以前は type のインスタンスだけを返していました。

メタクラスの tp_new は 無視 されるため、初期化が不完全になる可能性があります。 メタクラスが tp_new をオーバーライドしているクラスの作成は非推奨です。

バージョン 3.14 で変更: メタクラスが tp_new をオーバーライドしているクラスは、作成できなくなりました。

PyObject *PyType_FromSpec(PyType_Spec *spec)

戻り値: 新しい参照。 次に属します: Stable ABI.

PyType_FromMetaclass(NULL, NULL, spec, NULL) と同等です。

バージョン 3.12 で変更: Py_tp_base[s] スロットに指定された基底クラスに対応するメタクラスを探して使うようになりました。 以前は type のインスタンスだけを返していました。

メタクラスの tp_new は 無視 されるため、初期化が不完全になる可能性があります。 メタクラスが tp_new をオーバーライドしているクラスの作成は非推奨です。

バージョン 3.14 で変更: メタクラスが tp_new をオーバーライドしているクラスは、作成できなくなりました。

int PyType_Freeze(PyTypeObject *type)

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

Py_TPFLAGS_IMMUTABLETYPE フラグを設定して、型を変更不能にします。

type のすべての基底クラスが変更不能でなければなりません。

成功すると 0 を返します。 エラー時は例外を設定して -1 を返します。

変更不能にする前に型を使ってはいけません。 例えば、変更不能にする前にその型のインスタンスを作成してはいけません。

Added in version 3.14.

type PyType_Spec

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

Structure defining a type's behavior.

const char *name

Name of the type, used to set PyTypeObject.tp_name.

int basicsize

If positive, specifies the size of the instance in bytes. It is used to set PyTypeObject.tp_basicsize.

If zero, specifies that tp_basicsize should be inherited.

If negative, the absolute value specifies how much space instances of the class need in addition to the superclass. Use PyObject_GetTypeData() to get a pointer to subclass-specific memory reserved this way. For negative basicsize, Python will insert padding when needed to meet tp_basicsize's alignment requirements.

バージョン 3.12 で変更: 以前はこのフィールドを負にできませんでした。

int itemsize

Size of one element of a variable-size type, in bytes. Used to set PyTypeObject.tp_itemsize. See tp_itemsize documentation for caveats.

If zero, tp_itemsize is inherited. Extending arbitrary variable-sized classes is dangerous, since some types use a fixed offset for variable-sized memory, which can then overlap fixed-sized memory used by a subclass. To help prevent mistakes, inheriting itemsize is only possible in the following situations:

• 基底クラスが可変サイズではない (tp_itemsize がゼロである) 場合。

• 要求された PyType_Spec.basicsize が正で、基底クラスのメモリレイアウトを把握していると考えられる場合。

• 要求された PyType_Spec.basicsize がゼロで、サブクラスがインスタンスのメモリに直接アクセスしないと考えられる場合。

• Py_TPFLAGS_ITEMS_AT_END フラグがある場合。

unsigned int flags

Type flags, used to set PyTypeObject.tp_flags.

If the Py_TPFLAGS_HEAPTYPE flag is not set, PyType_FromSpecWithBases() sets it automatically.

PyType_Slot *slots

Array of PyType_Slot structures. Terminated by the special slot value {0, NULL}.

Each slot ID should be specified at most once.

type PyType_Slot

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

Structure defining optional functionality of a type, containing a slot ID and a value pointer.

int slot

A slot ID.

Slot IDs are named like the field names of the structures PyTypeObject, PyNumberMethods, PySequenceMethods, PyMappingMethods and PyAsyncMethods with an added Py_ prefix. For example, use:

• PyTypeObject.tp_dealloc の設定には Py_tp_dealloc

• PyNumberMethods.nb_add の設定には Py_nb_add

• PySequenceMethods.sq_length の設定には Py_sq_length

An additional slot is supported that does not correspond to a PyTypeObject struct field:

• Py_tp_token

次の「オフセット」フィールドは PyType_Slot では設定できません。

• tp_weaklistoffset (可能なら代わりに Py_TPFLAGS_MANAGED_WEAKREF を使ってください)

• tp_dictoffset (可能なら代わりに Py_TPFLAGS_MANAGED_DICT を使ってください)

• tp_vectorcall_offset (PyMemberDef で "__vectorcalloffset__" を使ってください)

MANAGED フラグに切り替えられない場合 (例えば vectorcall を使う場合や Python 3.12 より前をサポートする場合) は、Py_tp_members でオフセットを指定してください。 詳細は PyMemberDef のドキュメント を参照してください。

次の内部フィールドは、ヒープ型の作成時には一切設定できません。

• tp_dict, tp_mro, tp_cache, tp_subclasses, and tp_weaklist.

Setting Py_tp_bases or Py_tp_base may be problematic on some platforms. To avoid issues, use the bases argument of PyType_FromSpecWithBases() instead.

バージョン 3.9 で変更: PyBufferProcs のスロットは、制限のない API では設定できます。

バージョン 3.11 で変更: bf_getbuffer と bf_releasebuffer が Limited API でも利用できるようになりました。

バージョン 3.14 で変更: Py_tp_vectorcall で tp_vectorcall フィールドを設定できるようになりました。 詳細はフィールドの説明を参照してください。

void *pfunc

The desired value of the slot. In most cases, this is a pointer to a function.

pfunc values may not be NULL, except for the following slots:

• Py_tp_doc

• Py_tp_token (明確にするため、NULL より Py_TP_USE_SPEC を使うことを推奨します)

Py_tp_token

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

A slot that records a static memory layout ID for a class.

If the PyType_Spec of the class is statically allocated, the token can be set to the spec using the special value Py_TP_USE_SPEC:

static PyType_Slot foo_slots[] = {
   {Py_tp_token, Py_TP_USE_SPEC},

任意のポインタを設定することもできますが、次の条件を満たす必要があります。

• クラスが存在する間にポインタが他の用途に再利用されないよう、その参照先がクラスより長く存続すること。

• 他の拡張モジュールと競合しないよう、クラスが属する拡張モジュールにそのポインタが「属する」こと。

クラスの基底クラスが指定したトークンを持つかどうか、つまりメモリレイアウトに互換性があるかどうかを調べるには PyType_GetBaseByToken() を使ってください。

基底クラスを考慮せず、指定したクラスのトークンを取得するには、Py_tp_token を指定して PyType_GetSlot() を使ってください。

Added in version 3.14.

Py_TP_USE_SPEC

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

Used as a value with Py_tp_token to set the token to the class's PyType_Spec. Expands to NULL.

Added in version 3.14.