型別物件

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 的替代方法。返回的字典必須被視為只讀。

此函式適用於需要直接訪問字典且間接訪問（例如透過代理或 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 並設定異常。

在自由執行緒構建中，PyType_AddWatcher() 不是執行緒安全的，因此必須在啟動時（在生成第一個執行緒之前）呼叫它。

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* 的回撥函式將被呼叫。(如果連續修改 *type* 期間未呼叫 _PyType_Lookup()，回撥函式可能只被呼叫一次；這是一個實現細節，可能會發生變化。)

擴充套件不應使用並非由先前對 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 的預設記憶體分配機制為新例項分配記憶體，將記憶體清零，然後透過呼叫 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)

返回值: 新引用。 穩定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 呼叫約定傳遞方法定義類的地方獲取模組狀態。

返回的引用是從 *type* 借用的，只要您持有 *type* 的引用，它就有效。不要使用 Py_DECREF() 或類似函式釋放它。

在 3.11 版本中新增。

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

自 3.14 版本以來，作為 穩定 ABI 的一部分。

在 *type* 的 方法解析順序 中查詢第一個超類，其 Py_tp_token 令牌等於給定的令牌。

• 如果找到，將 *result* 設定為其新的 強引用 並返回 1。

• 如果未找到，將 *result* 設定為 NULL 並返回 0。

• 如果發生錯誤，將 *result* 設定為 NULL 並返回 -1，同時設定異常。

*result* 引數可以為 NULL，在這種情況下不設定 *result*。如果您只需要返回值，請使用此方法。

*token* 引數不能為 NULL。

在 3.14 版本加入。

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。

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

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

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

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

• 在新類上不呼叫 __new__()（它必須設定為 type.__new__）。

• 在新類上不呼叫 __init__()。

• 在任何基類上不呼叫 __init_subclass__()。

• 在新描述符上不呼叫 __set_name__()。

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 的類已被棄用。

在 3.14 版本中變更: 不再允許建立其元類重寫 tp_new 的類。

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 的類已被棄用。

在 3.14 版本中變更: 不再允許建立其元類重寫 tp_new 的類。

PyObject *PyType_FromSpec(PyType_Spec *spec)

返回值: 新引用。 穩定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)

自 3.14 版本以來，作為 穩定 ABI 的一部分。

使型別不可變：設定 Py_TPFLAGS_IMMUTABLETYPE 標誌。

*type* 的所有基類必須是不可變的。

成功時，返回 0。出錯時，設定異常並返回 -1。

在型別變為不可變之前，不得使用該型別。例如，在型別變為不可變之前，不得建立型別例項。

在 3.14 版本加入。

type PyType_Spec

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

定義型別行為的結構。

const char *name

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

int basicsize

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

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

如果是負數，其絕對值指定了類的例項除了超類之外還需要多少空間。使用 PyObject_GetTypeData() 獲取指向以這種方式保留的子類特定記憶體的指標。對於負數 basicsize，Python 會在需要時插入填充以滿足 tp_basicsize 的對齊要求。

在 3.12 版本中變更: 以前，此欄位不能為負數。

int itemsize

可變大小型別的一個元素的位元組大小。用於設定 PyTypeObject.tp_itemsize。有關注意事項，請參閱 tp_itemsize 文件。

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

• 基類不是可變大小的（其 tp_itemsize 為零）。

• 請求的 PyType_Spec.basicsize 為正數，表明基類的記憶體佈局已知。

• 請求的 PyType_Spec.basicsize 為零，表明子類不直接訪問例項的記憶體。

• 具有 Py_TPFLAGS_ITEMS_AT_END 標誌。

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_ 字首。例如，使用

• Py_tp_dealloc 設定 PyTypeObject.tp_dealloc

• Py_nb_add 設定 PyNumberMethods.nb_add

• Py_sq_length 設定 PySequenceMethods.sq_length

支援一個不對應 PyTypeObject 結構欄位的附加槽

• Py_tp_token

以下“偏移量”欄位無法使用 PyType_Slot 設定

• tp_weaklistoffset（如果可能，改用 Py_TPFLAGS_MANAGED_WEAKREF）

• tp_dictoffset（如果可能，改用 Py_TPFLAGS_MANAGED_DICT）

• tp_vectorcall_offset（在 PyMemberDef 中使用 "__vectorcalloffset__"）

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

建立堆型別時，以下內部欄位根本無法設定

• tp_dict、tp_mro、tp_cache、tp_subclasses 和 tp_weaklist。

在某些平臺上設定 Py_tp_bases 或 Py_tp_base 可能會出現問題。為避免問題，請改用 PyType_FromSpecWithBases() 的 *bases* 引數。

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

在 3.11 版本中變更: bf_getbuffer 和 bf_releasebuffer 現在在 受限 API 下可用。

在 3.14 版本中變更: 欄位 tp_vectorcall 現在可以使用 Py_tp_vectorcall 設定。有關詳細資訊，請參閱該欄位的文件。

void *pfunc

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

*pfunc* 值不能為 NULL，以下槽除外

• Py_tp_doc

• Py_tp_token (為了清晰起見，最好使用 Py_TP_USE_SPEC 而不是 NULL)

Py_tp_token

一個 槽，用於記錄類的靜態記憶體佈局 ID。

如果類的 PyType_Spec 是靜態分配的，則可以使用特殊值 Py_TP_USE_SPEC 將令牌設定為該規範

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

它也可以設定為任意指標，但您必須確保

• 指標的生命週期長於類，因此在類存在期間不會被其他東西重用。

• 它“屬於”類所在的擴充套件模組，因此不會與其他擴充套件衝突。

使用 PyType_GetBaseByToken() 檢查類的超類是否具有給定令牌——即檢查記憶體佈局是否相容。

要獲取給定類（不考慮超類）的令牌，請使用 PyType_GetSlot() 和 Py_tp_token。

在 3.14 版本加入。

Py_TP_USE_SPEC

用作 Py_tp_token 的值，將令牌設定為類的 PyType_Spec。展開為 NULL。

在 3.14 版本加入。