型別物件

type PyTypeObject
屬於有限 API 的一部分 (作為一個不透明的結構體)。

用於描述內建型別的物件的 C 結構。

PyTypeObject PyType_Type
屬於穩定 ABI 的一部分。

這是型別物件的型別物件；它與 Python 層中的 type 物件相同。

int PyType_Check(PyObject *o)

如果物件 *o* 是型別物件，包括從標準型別物件派生的型別的例項，則返回非零值。在所有其他情況下返回 0。此函式總是成功。

int PyType_CheckExact(PyObject *o)

如果物件 *o* 是型別物件，但不是標準型別物件的子型別，則返回非零值。在所有其他情況下返回 0。此函式總是成功。

unsigned int PyType_ClearCache()
屬於穩定 ABI 的一部分。

清除內部查詢快取。返回當前版本標籤。

unsigned long PyType_GetFlags(PyTypeObject *type)
屬於穩定 ABI 的一部分。

返回 *type* 的 tp_flags 成員。此函式主要用於 Py_LIMITED_API；各個標誌位保證在 Python 版本之間穩定，但訪問 tp_flags 本身不是 有限 API 的一部分。

在 3.2 版本中加入。

在 3.4 版本中更改: 返回型別現在是 unsigned long 而不是 long。

PyObject *PyType_GetDict(PyTypeObject *type)

返回型別物件的內部名稱空間，該名稱空間僅透過只讀代理 (cls.__dict__) 公開。這是直接訪問 tp_dict 的替代方案。返回的字典必須被視為只讀。

此函式用於特定的嵌入和語言繫結情況，在這種情況下，直接訪問 dict 是必要的，而間接訪問 (例如透過代理或 PyObject_GetAttr()) 是不夠的。

擴充套件模組在設定自己的型別時應繼續直接或間接地使用 tp_dict。

在 3.12 版本中加入。

void PyType_Modified(PyTypeObject *type)
屬於穩定 ABI 的一部分。

使型別及其所有子型別的內部查詢快取無效。在手動修改型別的屬性或基類之後，必須呼叫此函式。

int PyType_AddWatcher(PyType_WatchCallback callback)

將 *callback* 註冊為型別監視器。返回一個非負整數 ID，該 ID 必須傳遞給將來對 PyType_Watch() 的呼叫。如果發生錯誤 (例如，沒有更多可用的監視器 ID)，則返回 -1 並設定一個異常。

在 3.12 版本中加入。

int PyType_ClearWatcher(int watcher_id)

清除由 *watcher_id* 標識的監視器 (先前從 PyType_AddWatcher() 返回)。成功返回 0，錯誤返回 -1 (例如，如果從未註冊 *watcher_id* )。

擴充套件不應使用未透過先前呼叫 PyType_AddWatcher() 返回給它的 *watcher_id* 呼叫 PyType_ClearWatcher。

在 3.12 版本中加入。

int PyType_Watch(int watcher_id, PyObject *type)

將 *type* 標記為已監視。每當 PyType_Modified() 報告對 *type* 的更改時，將呼叫由 PyType_AddWatcher() 授予 *watcher_id* 的回撥。(如果 _PyType_Lookup() 在對 *type* 的一系列連續修改之間未在 *type* 上呼叫，則回撥可能只被呼叫一次；這是一個實現細節，可能會發生變化。)

擴充套件不應使用未透過先前呼叫 PyType_AddWatcher() 返回給它的 *watcher_id* 呼叫 PyType_Watch。

在 3.12 版本中加入。

typedef int (*PyType_WatchCallback)(PyObject *type)

型別監視器回撥函式的型別。

回撥不得修改 *type* 或導致對 *type* 或其 MRO 中的任何型別呼叫 PyType_Modified()；違反此規則可能會導致無限遞迴。

在 3.12 版本中加入。

int PyType_HasFeature(PyTypeObject *o, int feature)

如果型別物件 *o* 設定了特性 *feature*，則返回非零值。型別特性由單位元標誌表示。

int PyType_IS_GC(PyTypeObject *o)

如果型別物件包含對迴圈檢測器的支援，則返回 true；這將測試型別標誌 Py_TPFLAGS_HAVE_GC。

int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)
屬於穩定 ABI 的一部分。

如果 *a* 是 *b* 的子型別，則返回 true。

此函式僅檢查實際的子型別，這意味著不會在 *b* 上呼叫 __subclasscheck__()。呼叫 PyObject_IsSubclass() 來執行與 issubclass() 相同的檢查。

PyObject *PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
返回值：新引用。 屬於 穩定 ABI 的一部分。

型別物件的 tp_alloc 插槽的通用處理程式。使用 Python 的預設記憶體分配機制來分配新的例項，並將所有內容初始化為 NULL。

PyObject *PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
返回值：新引用。 屬於 穩定 ABI 的一部分。

型別物件的 tp_new 插槽的通用處理程式。使用型別的 tp_alloc 插槽建立一個新例項。

int PyType_Ready(PyTypeObject *type)
屬於穩定 ABI 的一部分。

完成型別物件。應該在所有型別物件上呼叫此函式以完成它們的初始化。此函式負責從型別的基類新增繼承的槽。成功時返回 0，失敗時返回 -1 並設定一個異常。

注意

如果某些基類實現了 GC 協議，並且提供的型別在其標誌中不包含 Py_TPFLAGS_HAVE_GC，那麼將自動從其父類實現 GC 協議。相反，如果正在建立的型別在其標誌中包含 Py_TPFLAGS_HAVE_GC，那麼它必須透過至少實現 tp_traverse 處理程式來實現 GC 協議本身。

PyObject *PyType_GetName(PyTypeObject *type)
返回值：新引用。 自 3.11 版本起，屬於 穩定 ABI 的一部分。

返回型別的名稱。等效於獲取型別的 __name__ 屬性。

3.11 版本新增。

PyObject *PyType_GetQualName(PyTypeObject *type)
返回值：新引用。 自 3.11 版本起，屬於 穩定 ABI 的一部分。

返回型別的限定名稱。等效於獲取型別的 __qualname__ 屬性。

3.11 版本新增。

PyObject *PyType_GetFullyQualifiedName(PyTypeObject *type)
自 3.13 版本起，屬於 穩定 ABI 的一部分。

返回型別的完全限定名稱。等效於 f"{type.__module__}.{type.__qualname__}"，如果 type.__module__ 不是字串或等於 "builtins"，則等效於 type.__qualname__。

3.13 版本新增。

PyObject *PyType_GetModuleName(PyTypeObject *type)
自 3.13 版本起，屬於 穩定 ABI 的一部分。

返回型別的模組名稱。等效於獲取 type.__module__ 屬性。

3.13 版本新增。

void *PyType_GetSlot(PyTypeObject *type, int slot)
自 3.4 版本起，屬於 穩定 ABI 的一部分。

返回儲存在給定插槽中的函式指標。如果結果為 NULL，則表示該插槽為 NULL，或者該函式被呼叫時使用了無效的引數。呼叫者通常會將結果指標強制轉換為適當的函式型別。

有關 *slot* 引數的可能值，請參閱 PyType_Slot.slot。

3.4 版本新增。

在 3.10 版本中更改: PyType_GetSlot() 現在可以接受所有型別。以前，它僅限於 堆型別。

PyObject *PyType_GetModule(PyTypeObject *type)
自 3.10 版本起，屬於 穩定 ABI 的一部分。

當型別使用 PyType_FromModuleAndSpec() 建立時，返回與給定型別關聯的模組物件。

如果給定型別沒有關聯的模組，則設定 TypeError 並返回 NULL。

此函式通常用於獲取定義方法的模組。請注意，在此類方法中，PyType_GetModule(Py_TYPE(self)) 可能不會返回預期結果。Py_TYPE(self) 可能是預期類的子類，而子類不一定與其超類定義在同一模組中。請參閱 PyCMethod 以獲取定義該方法的類。對於無法使用 PyCMethod 的情況，請參閱 PyType_GetModuleByDef()。

3.9 版本中新增。

void *PyType_GetModuleState(PyTypeObject *type)
自 3.10 版本起，屬於 穩定 ABI 的一部分。

返回與給定型別關聯的模組物件的狀態。這是在 PyType_GetModule() 的結果上呼叫 PyModule_GetState() 的快捷方式。

如果給定型別沒有關聯的模組，則設定 TypeError 並返回 NULL。

如果 type 有關聯的模組，但其狀態為 NULL，則返回 NULL，而不會設定異常。

3.9 版本中新增。

PyObject *PyType_GetModuleByDef(PyTypeObject *type, struct PyModuleDef *def)
自 3.13 版本起，屬於 穩定 ABI 的一部分。

查詢其模組是使用給定的 PyModuleDef def 建立的第一個超類，並返回該模組。

如果未找到模組，則會引發 TypeError 並返回 NULL。

此函式旨在與 PyModule_GetState() 一起使用，以從槽方法（例如 tp_init 或 nb_add）和其他無法使用 PyCMethod 呼叫約定傳遞方法定義類的地方獲取模組狀態。

3.11 版本新增。

int PyUnstable_Type_AssignVersionTag(PyTypeObject *type)
這是 不穩定 API。它可能會在次要版本中更改，恕不另行通知。

嘗試為給定型別分配版本標籤。

如果型別已經具有有效的版本標籤或已分配新標籤，則返回 1；如果無法分配新標籤，則返回 0。

在 3.12 版本中加入。

建立堆分配型別

以下函式和結構用於建立 堆型別。

PyObject *PyType_FromMetaclass(PyTypeObject *metaclass, PyObject *module, PyType_Spec *spec, PyObject *bases)
自 3.12 版本以來是 穩定 ABI 的一部分。

從 spec 建立並返回一個 堆型別（請參閱 Py_TPFLAGS_HEAPTYPE）。

元類 metaclass 用於構造生成的型別物件。當 metaclass 為 NULL 時，元類從 bases 派生（如果 bases 為 NULL，則從 Py_tp_base[s] 槽派生，見下文）。

不支援重寫 tp_new 的元類，除非 tp_new 為 NULL。（為了向後相容，其他 PyType_From* 函式允許使用此類元類。它們會忽略 tp_new，這可能會導致初始化不完整。這已被棄用，在 Python 3.14+ 中將不再支援此類元類。）

bases 引數可用於指定基類；它可以只是一個類或一個類元組。如果 bases 為 NULL，則使用 Py_tp_bases 槽。如果該槽也為 NULL，則使用 Py_tp_base 槽。如果該槽也為 NULL，則新型別從 object 派生。

module 引數可用於記錄新類定義的模組。它必須是模組物件或 NULL。如果不是 NULL，則該模組與新型別關聯，並且稍後可以使用 PyType_GetModule() 檢索。關聯的模組不會被子類繼承；它必須為每個類單獨指定。

此函式在新型別上呼叫 PyType_Ready()。

請注意，此函式不完全匹配呼叫 type() 或使用 class 語句的行為。對於使用者提供的基型別或元類，請優先 呼叫 type（或元類）而不是 PyType_From* 函式。具體來說

在 3.12 版本中加入。

PyObject *PyType_FromModuleAndSpec(PyObject *module, PyType_Spec *spec, PyObject *bases)
返回值：新引用。自 3.10 版本以來是 穩定 ABI 的一部分。

等效於 PyType_FromMetaclass(NULL, module, spec, bases)。

3.9 版本中新增。

在 3.10 版本中更改：該函式現在接受單個類作為 bases 引數，並接受 NULL 作為 tp_doc 槽。

3.12 版本更改: 該函式現在查詢並使用與提供的基類對應的元類。之前，僅返回 type 例項。

元類的 tp_new 是被忽略的，這可能會導致初始化不完整。建立其元類覆蓋 tp_new 的類已被棄用，並且在 Python 3.14+ 中將不再允許這樣做。

PyObject *PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
返回值：新引用。自 3.3 版本以來，屬於穩定 ABI 的一部分。

等價於 PyType_FromMetaclass(NULL, NULL, spec, bases)。

在 3.3 版本中新增。

3.12 版本更改: 該函式現在查詢並使用與提供的基類對應的元類。之前，僅返回 type 例項。

元類的 tp_new 是被忽略的，這可能會導致初始化不完整。建立其元類覆蓋 tp_new 的類已被棄用，並且在 Python 3.14+ 中將不再允許這樣做。

PyObject *PyType_FromSpec(PyType_Spec *spec)
返回值：新引用。 屬於 穩定 ABI 的一部分。

等價於 PyType_FromMetaclass(NULL, NULL, spec, NULL)。

3.12 版本更改: 該函式現在查詢並使用與 Py_tp_base[s] 插槽中提供的基類對應的元類。之前，僅返回 type 例項。

元類的 tp_new 是被忽略的，這可能會導致初始化不完整。建立其元類覆蓋 tp_new 的類已被棄用，並且在 Python 3.14+ 中將不再允許這樣做。

type PyType_Spec
屬於穩定 ABI 的一部分（包括所有成員）。

定義型別的行為的結構。

const char *name

型別的名稱，用於設定 PyTypeObject.tp_name。

int basicsize

如果為正數，則指定例項的大小（以位元組為單位）。它用於設定 PyTypeObject.tp_basicsize。

如果為零，則指定應繼承 tp_basicsize。

如果為負數，則絕對值指定該類例項除了超類之外還需要多少空間。使用 PyObject_GetTypeData() 獲取指向以此方式保留的子類特定記憶體的指標。

3.12 版本更改: 之前，此欄位不能為負數。

int itemsize

可變大小型別的一個元素的大小（以位元組為單位）。用於設定 PyTypeObject.tp_itemsize。請參閱 tp_itemsize 文件瞭解注意事項。

如果為零，則繼承 tp_itemsize。擴充套件任意可變大小的類是危險的，因為某些型別對可變大小的記憶體使用固定偏移量，這可能會與子類使用的固定大小的記憶體重疊。為了幫助防止錯誤，僅在以下情況下才能繼承 itemsize

unsigned int flags

型別標誌，用於設定 PyTypeObject.tp_flags。

如果未設定 Py_TPFLAGS_HEAPTYPE 標誌，則 PyType_FromSpecWithBases() 會自動設定該標誌。

PyType_Slot *slots

PyType_Slot 結構的陣列。以特殊槽值 {0, NULL} 終止。

每個槽 ID 最多應指定一次。

type PyType_Slot
屬於穩定 ABI 的一部分（包括所有成員）。

定義型別的可選功能的結構，包含一個槽 ID 和一個值指標。

int slot

一個槽 ID。

槽 ID 的命名類似於 PyTypeObject、PyNumberMethods、PySequenceMethods、PyMappingMethods 和 PyAsyncMethods 結構的欄位名稱，並添加了 Py_ 字首。例如，使用

以下“offset”欄位不能使用 PyType_Slot 設定

如果無法切換到 MANAGED 標誌（例如，對於 vectorcall 或為了支援低於 3.12 的 Python 版本），請在 Py_tp_members 中指定偏移量。有關詳細資訊，請參閱 PyMemberDef 文件。

在建立堆型別時，以下欄位完全不能設定

在某些平臺上，設定 Py_tp_bases 或 Py_tp_base 可能會有問題。為了避免問題，請使用 PyType_FromSpecWithBases() 的 bases 引數來代替。

3.9 版本變更: PyBufferProcs 中的槽位可以在無限制 API 中設定。

3.11 版本變更: bf_getbuffer 和 bf_releasebuffer 現在可以在 有限 API 下使用。

void *pfunc

槽位的期望值。在大多數情況下，這是一個指向函式的指標。

除了 Py_tp_doc 之外的槽位不能為 NULL。