型オブジェクト

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)

Mark type as not watched. This undoes a previous call to PyType_Watch(). type must not be NULL.

An extension should never call this function with a watcher_id that was not returned to it by a previous call to PyType_AddWatcher().

On success, this function returns 0. On failure, this function returns -1 with an exception set.

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)

Return non-zero if the type object type sets the subclass flag flag. Subclass flags are denoted by Py_TPFLAGS_*_SUBCLASS. This function is used by many _Check functions for common types.

参考

PyObject_TypeCheck(), which is used as a slower alternative in _Check functions for types that don't come with subclass flags.

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.

Generic handler for the tp_alloc slot of a type object. Use Python's default memory allocation mechanism to allocate a new instance and initialize all its contents to NULL.

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

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

Generic handler for the tp_new slot of a type object. Create a new instance using the type's tp_alloc slot.

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() で型を作成したときに、その型に関連付けたモジュールオブジェクトを返します。

The returned reference is borrowed from type, and will be valid as long as you hold a reference to type. Do not release it with Py_DECREF() or similar.

指定された型にモジュールが関連付けられていない場合は、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() と組み合わせてモジュール状態を取得するために使うことを想定しています。

The returned reference is borrowed from type, and will be valid as long as you hold a reference to type. Do not release it with Py_DECREF() or similar.

Added in version 3.11.

int PyUnstable_Type_AssignVersionTag(PyTypeObject *type)

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

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

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

Added in version 3.12.

int PyType_SUPPORTS_WEAKREFS(PyTypeObject *type)

Return true if instances of type support creating weak references, false otherwise. This function always succeeds. type must not be 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).

Metaclasses that override tp_new are not supported, except if tp_new is NULL. (For backwards compatibility, other PyType_From* functions allow such metaclasses. They ignore tp_new, which may result in incomplete initialization. This is deprecated and in Python 3.14+ such metaclasses will not be supported.)

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 のインスタンスだけを返していました。

The tp_new of the metaclass is ignored. which may result in incomplete initialization. Creating classes whose metaclass overrides tp_new is deprecated and in Python 3.14+ it will be no longer allowed.

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 のインスタンスだけを返していました。

The tp_new of the metaclass is ignored. which may result in incomplete initialization. Creating classes whose metaclass overrides tp_new is deprecated and in Python 3.14+ it will be no longer allowed.

PyObject *PyType_FromSpec(PyType_Spec *spec)

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

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

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

The tp_new of the metaclass is ignored. which may result in incomplete initialization. Creating classes whose metaclass overrides tp_new is deprecated and in Python 3.14+ it will be no longer allowed.

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:

• The base is not variable-sized (its tp_itemsize is zero).

• 要求された 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:

• Py_tp_dealloc to set PyTypeObject.tp_dealloc

• Py_nb_add to set PyNumberMethods.nb_add

• Py_sq_length to set PySequenceMethods.sq_length

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

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

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

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

If it is not possible to switch to a MANAGED flag (for example, for vectorcall or to support Python older than 3.12), specify the offset in Py_tp_members. See PyMemberDef documentation for details.

The following fields cannot be set at all when creating a heap type:

• tp_vectorcall (use tp_new and/or tp_init)

• Internal fields: 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 でも利用できるようになりました。

void *pfunc

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

Slots other than Py_tp_doc may not be NULL.