物件協議

PyObject *Py_GetConstant(unsigned int constant_id)

自 3.13 版本起成為 穩定 ABI 的一部分。

獲取對常量的 強引用。

如果 constant_id 無效，則設定一個異常並返回 NULL。

constant_id 必須是以下常量識別符號之一

常量識別符號	值	返回物件
Py_CONSTANT_NONE	0	None
Py_CONSTANT_FALSE	1	False
Py_CONSTANT_TRUE	2	True
Py_CONSTANT_ELLIPSIS	3	Ellipsis
Py_CONSTANT_NOT_IMPLEMENTED	4	NotImplemented
Py_CONSTANT_ZERO	5	0
Py_CONSTANT_ONE	6	1
Py_CONSTANT_EMPTY_STR	7	''
Py_CONSTANT_EMPTY_BYTES	8	b''
Py_CONSTANT_EMPTY_TUPLE	9	()

數值僅適用於不能使用常量識別符號的專案。

在 3.13 版本加入。

CPython 實現細節： 在 CPython 中，所有這些常量都是 不朽的。

PyObject *Py_GetConstantBorrowed(unsigned int constant_id)

自 3.13 版本起成為 穩定 ABI 的一部分。

類似於 Py_GetConstant()，但返回一個 借用引用。

此函式主要用於向後相容：對於新程式碼，建議使用 Py_GetConstant()。

此引用是從直譯器借用的，並在直譯器終止之前有效。

在 3.13 版本加入。

PyObject *Py_NotImplemented

單例 NotImplemented，用於表示給定型別組合的操作未實現。

Py_RETURN_NOTIMPLEMENTED

正確處理從 C 函式內部返回 Py_NotImplemented（即，建立對 NotImplemented 的新 強引用 並返回它）。

Py_PRINT_RAW

用於列印物件的多個函式（如 PyObject_Print() 和 PyFile_WriteObject()）的標誌。如果傳入，這些函式將使用物件的 str() 而不是 repr()。

int PyObject_Print(PyObject *o, FILE *fp, int flags)

將物件 o 列印到檔案 fp 中。出錯時返回 -1。 flags 引數用於啟用某些列印選項。當前唯一支援的選項是 Py_PRINT_RAW；如果給定，則寫入物件的 str() 而不是 repr()。

int PyObject_HasAttrWithError(PyObject *o, PyObject *attr_name)

自 3.13 版本起成為 穩定 ABI 的一部分。

如果 o 具有屬性 attr_name，則返回 1，否則返回 0。這等同於 Python 表示式 hasattr(o, attr_name)。失敗時返回 -1。

在 3.13 版本加入。

int PyObject_HasAttrStringWithError(PyObject *o, const char *attr_name)

自 3.13 版本起成為 穩定 ABI 的一部分。

這與 PyObject_HasAttrWithError() 相同，但 attr_name 被指定為 const char* UTF-8 編碼位元組字串，而不是 PyObject*。

在 3.13 版本加入。

int PyObject_HasAttr(PyObject *o, PyObject *attr_name)

作為 穩定 ABI 的一部分。

如果 o 具有屬性 attr_name，則返回 1，否則返回 0。此函式總是成功。

備註

此函式呼叫 __getattr__() 和 __getattribute__() 方法時發生的異常不會傳播，而是交給 sys.unraisablehook()。為了進行正確的錯誤處理，請改用 PyObject_HasAttrWithError()、PyObject_GetOptionalAttr() 或 PyObject_GetAttr()。

int PyObject_HasAttrString(PyObject *o, const char *attr_name)

作為 穩定 ABI 的一部分。

這與 PyObject_HasAttr() 相同，但 attr_name 被指定為 const char* UTF-8 編碼位元組字串，而不是 PyObject*。

備註

此函式呼叫 __getattr__() 和 __getattribute__() 方法或在建立臨時 str 物件時發生的異常會被靜默忽略。為了進行正確的錯誤處理，請改用 PyObject_HasAttrStringWithError()、PyObject_GetOptionalAttrString() 或 PyObject_GetAttrString()。

PyObject *PyObject_GetAttr(PyObject *o, PyObject *attr_name)

返回值: 新引用。 穩定ABI 的一部分。

從物件 o 中檢索名為 attr_name 的屬性。成功時返回屬性值，失敗時返回 NULL。這等同於 Python 表示式 o.attr_name。

如果缺少屬性不應被視為失敗，則可以改用 PyObject_GetOptionalAttr()。

PyObject *PyObject_GetAttrString(PyObject *o, const char *attr_name)

返回值: 新引用。 穩定ABI 的一部分。

這與 PyObject_GetAttr() 相同，但 attr_name 被指定為 const char* UTF-8 編碼位元組字串，而不是 PyObject*。

如果缺少屬性不應被視為失敗，則可以改用 PyObject_GetOptionalAttrString()。

int PyObject_GetOptionalAttr(PyObject *obj, PyObject *attr_name, PyObject **result);

自 3.13 版本起成為 穩定 ABI 的一部分。

PyObject_GetAttr() 的變體，如果未找到屬性則不會引發 AttributeError。

如果找到屬性，則返回 1 並將 *result 設定為對該屬性的新 強引用。如果未找到屬性，則返回 0 並將 *result 設定為 NULL；AttributeError 被靜默。如果引發了除 AttributeError 之外的錯誤，則返回 -1 並將 *result 設定為 NULL。

在 3.13 版本加入。

int PyObject_GetOptionalAttrString(PyObject *obj, const char *attr_name, PyObject **result);

自 3.13 版本起成為 穩定 ABI 的一部分。

這與 PyObject_GetOptionalAttr() 相同，但 attr_name 被指定為 const char* UTF-8 編碼位元組字串，而不是 PyObject*。

在 3.13 版本加入。

PyObject *PyObject_GenericGetAttr(PyObject *o, PyObject *name)

返回值: 新引用。 穩定ABI 的一部分。

通用屬性獲取函式，旨在放入型別物件的 tp_getattro 槽中。它會在物件的 MRO 中的類字典中查詢描述符，以及在物件的 __dict__ 中查詢屬性（如果存在）。正如 實現描述符 中所述，資料描述符優先於例項屬性，而非資料描述符則不。否則，將引發 AttributeError。

int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)

作為 穩定 ABI 的一部分。

將物件 o 的名為 attr_name 的屬性的值設定為 v。失敗時引發異常並返回 -1；成功時返回 0。這等同於 Python 語句 o.attr_name = v。

如果 v 為 NULL，則刪除該屬性。此行為已棄用，建議改用 PyObject_DelAttr()，但目前沒有計劃將其移除。

int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)

作為 穩定 ABI 的一部分。

這與 PyObject_SetAttr() 相同，但 attr_name 被指定為 const char* UTF-8 編碼位元組字串，而不是 PyObject*。

如果 v 為 NULL，則刪除該屬性，但此功能已棄用，建議改用 PyObject_DelAttrString()。

傳遞給此函式的不同屬性名稱的數量應保持較小，通常透過使用靜態分配的字串作為 attr_name 來實現。對於在編譯時未知的屬性名稱，請直接呼叫 PyUnicode_FromString() 和 PyObject_SetAttr()。有關更多詳細資訊，請參閱 PyUnicode_InternFromString()，它可以在內部用於建立鍵物件。

int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)

作為 穩定 ABI 的一部分。

通用屬性設定器和刪除器函式，旨在放入型別物件的 tp_setattro 槽中。它會在物件的 MRO 中的類字典中查詢資料描述符，如果找到，它將優先於在例項字典中設定或刪除屬性。否則，屬性將在物件的 __dict__ 中設定或刪除（如果存在）。成功時返回 0，否則將引發 AttributeError 並返回 -1。

int PyObject_DelAttr(PyObject *o, PyObject *attr_name)

自 3.13 版本起成為 穩定 ABI 的一部分。

刪除物件 o 的名為 attr_name 的屬性。失敗時返回 -1。這等同於 Python 語句 del o.attr_name。

int PyObject_DelAttrString(PyObject *o, const char *attr_name)

自 3.13 版本起成為 穩定 ABI 的一部分。

這與 PyObject_DelAttr() 相同，但 attr_name 被指定為 const char* UTF-8 編碼位元組字串，而不是 PyObject*。

傳遞給此函式的不同屬性名稱的數量應保持較小，通常透過使用靜態分配的字串作為 attr_name 來實現。對於在編譯時未知的屬性名稱，請直接呼叫 PyUnicode_FromString() 和 PyObject_DelAttr()。有關更多詳細資訊，請參閱 PyUnicode_InternFromString()，它可以在內部用於建立查詢的鍵物件。

PyObject **PyObject_GenericGetDict(PyObject *o, void *context)

返回值：新引用。 自 3.10 版本起成為 穩定 ABI 的一部分。

一個用於 __dict__ 描述符獲取器的通用實現。如有必要，它會建立字典。

此函式也可以用於獲取物件 o 的 __dict__。呼叫時將 context 傳入 NULL。由於此函式可能需要為字典分配記憶體，因此在訪問物件的屬性時呼叫 PyObject_GetAttr() 可能會更有效。

失敗時，返回 NULL 並設定異常。

在 3.3 版本加入。

int PyObject_GenericSetDict(PyObject *o, PyObject *value, void *context)

自 3.7 版本起成為 穩定ABI 的一部分。

一個用於 __dict__ 描述符設定器的通用實現。此實現不允許刪除字典。

在 3.3 版本加入。

PyObject **_PyObject_GetDictPtr(PyObject *obj)

返回指向物件 obj 的 __dict__ 的指標。如果沒有 __dict__，則返回 NULL 而不設定異常。

此函式可能需要為字典分配記憶體，因此在訪問物件的屬性時呼叫 PyObject_GetAttr() 可能會更有效。

PyObject *PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)

返回值: 新引用。 穩定ABI 的一部分。

使用 opid 指定的操作比較 o1 和 o2 的值，opid 必須是 Py_LT、Py_LE、Py_EQ、Py_NE、Py_GT 或 Py_GE 之一，分別對應 <、<=、==、!=、> 或 >=。這等同於 Python 表示式 o1 op o2，其中 op 是對應於 opid 的運算子。成功時返回比較結果的值，失敗時返回 NULL。

int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)

作為 穩定 ABI 的一部分。

使用 opid 指定的操作比較 o1 和 o2 的值，類似於 PyObject_RichCompare()，但錯誤時返回 -1，如果結果為假則返回 0，否則返回 1。

備註

如果 o1 和 o2 是相同的物件，則 PyObject_RichCompareBool() 對於 Py_EQ 總是返回 1，對於 Py_NE 總是返回 0。

PyObject *PyObject_Format(PyObject *obj, PyObject *format_spec)

作為 穩定 ABI 的一部分。

使用 format_spec 格式化 obj。這等同於 Python 表示式 format(obj, format_spec)。

format_spec 可以是 NULL。在這種情況下，此呼叫等同於 format(obj)。成功時返回格式化字串，失敗時返回 NULL。

PyObject *PyObject_Repr(PyObject *o)

返回值: 新引用。 穩定ABI 的一部分。

計算物件 o 的字串表示。成功時返回字串表示，失敗時返回 NULL。這等同於 Python 表示式 repr(o)。由內建函式 repr() 呼叫。

3.4 版本中已更改: 此函式現在包含一個除錯斷言，以幫助確保它不會靜默丟棄活動的異常。

PyObject *PyObject_ASCII(PyObject *o)

返回值: 新引用。 穩定ABI 的一部分。

與 PyObject_Repr() 相同，計算物件 o 的字串表示，但使用 \x、\u 或 \U 轉義 PyObject_Repr() 返回的字串中的非 ASCII 字元。這會生成一個類似於 Python 2 中 PyObject_Repr() 返回的字串。由內建函式 ascii() 呼叫。

PyObject *PyObject_Str(PyObject *o)

返回值: 新引用。 穩定ABI 的一部分。

計算物件 o 的字串表示。成功時返回字串表示，失敗時返回 NULL。這等同於 Python 表示式 str(o)。由內建函式 str() 呼叫，因此也由函式 print() 呼叫。

3.4 版本中已更改: 此函式現在包含一個除錯斷言，以幫助確保它不會靜默丟棄活動的異常。

PyObject *PyObject_Bytes(PyObject *o)

返回值: 新引用。 穩定ABI 的一部分。

計算物件 o 的位元組表示。失敗時返回 NULL，成功時返回位元組物件。這等同於 Python 表示式 bytes(o)，當 o 不是整數時。與 bytes(o) 不同，當 o 是整數而不是零初始化的位元組物件時，會引發 TypeError。

int PyObject_IsSubclass(PyObject *derived, PyObject *cls)

作為 穩定 ABI 的一部分。

如果類 derived 與類 cls 相同或派生自類 cls，則返回 1，否則返回 0。如果出錯，返回 -1。

如果 cls 是一個元組，則將對 cls 中的每個條目進行檢查。如果至少有一個檢查返回 1，則結果為 1，否則為 0。

如果 cls 具有 __subclasscheck__() 方法，則將呼叫它來確定子類狀態，如 PEP 3119 中所述。否則，如果 derived 是 cls 的直接或間接子類，即包含在 cls.__mro__ 中，則 derived 是 cls 的子類。

通常只有類物件，即 type 或派生類的例項，才被視為類。然而，物件可以透過具有 __bases__ 屬性（必須是基類元組）來覆蓋此設定。

int PyObject_IsInstance(PyObject *inst, PyObject *cls)

作為 穩定 ABI 的一部分。

如果 inst 是類 cls 的例項或 cls 的子類，則返回 1，否則返回 0。出錯時，返回 -1 並設定異常。

如果 cls 是一個元組，則將對 cls 中的每個條目進行檢查。如果至少有一個檢查返回 1，則結果為 1，否則為 0。

如果 cls 具有 __instancecheck__() 方法，則將呼叫它來確定子類狀態，如 PEP 3119 中所述。否則，如果 inst 的類是 cls 的子類，則 inst 是 cls 的例項。

例項 inst 可以透過具有 __class__ 屬性來覆蓋被視為其類的物件。

物件 cls 可以透過具有 __bases__ 屬性（必須是基類元組）來覆蓋其是否被視為類以及其基類是什麼。

Py_hash_t PyObject_Hash(PyObject *o)

作為 穩定 ABI 的一部分。

計算並返回物件 o 的雜湊值。失敗時返回 -1。這等同於 Python 表示式 hash(o)。

3.2 版本中已更改: 返回型別現在是 Py_hash_t。這是一個帶符號整數，大小與 Py_ssize_t 相同。

Py_hash_t PyObject_HashNotImplemented(PyObject *o)

作為 穩定 ABI 的一部分。

設定一個 TypeError，指示 type(o) 不可 雜湊，並返回 -1。此函式在儲存到 tp_hash 槽中時會受到特殊處理，允許型別明確向直譯器指示其不可雜湊。

int PyObject_IsTrue(PyObject *o)

作為 穩定 ABI 的一部分。

如果物件 o 被認為是真的，則返回 1，否則返回 0。這等同於 Python 表示式 not not o。失敗時返回 -1。

int PyObject_Not(PyObject *o)

作為 穩定 ABI 的一部分。

如果物件 o 被認為是真的，則返回 0，否則返回 1。這等同於 Python 表示式 not o。失敗時返回 -1。

PyObject *PyObject_Type(PyObject *o)

返回值: 新引用。 穩定ABI 的一部分。

當 o 非 NULL 時，返回與物件 o 的物件型別對應的型別物件。失敗時，引發 SystemError 並返回 NULL。這等同於 Python 表示式 type(o)。此函式建立對返回值的新的 強引用。除了需要新的 強引用 之外，實在沒有理由使用此函式而不是 Py_TYPE() 函式，後者返回型別為 PyTypeObject* 的指標。

int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)

如果物件 o 是 type 型別或 type 的子型別，則返回非零值，否則返回 0。兩個引數都必須是非 NULL。

Py_ssize_t PyObject_Size(PyObject *o)

Py_ssize_t PyObject_Length(PyObject *o)

作為 穩定 ABI 的一部分。

返回物件 o 的長度。如果物件 o 提供序列和對映協議，則返回序列長度。錯誤時返回 -1。這等同於 Python 表示式 len(o)。

Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t defaultvalue)

返回物件 o 的估計長度。首先嚐試返回其實際長度，然後使用 __length_hint__() 進行估計，最後返回預設值。錯誤時返回 -1。這等同於 Python 表示式 operator.length_hint(o, defaultvalue)。

在 3.4 版本加入。

PyObject *PyObject_GetItem(PyObject *o, PyObject *key)

返回值: 新引用。 穩定ABI 的一部分。

返回 o 中與物件 key 對應的元素，失敗時返回 NULL。這等同於 Python 表示式 o[key]。

int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)

作為 穩定 ABI 的一部分。

將物件 key 對映到值 v。失敗時引發異常並返回 -1；成功時返回 0。這等同於 Python 語句 o[key] = v。此函式 不會 竊取對 v 的引用。

int PyObject_DelItem(PyObject *o, PyObject *key)

作為 穩定 ABI 的一部分。

從物件 o 中移除物件 key 的對映。失敗時返回 -1。這等同於 Python 語句 del o[key]。

int PyObject_DelItemString(PyObject *o, const char *key)

作為 穩定 ABI 的一部分。

這與 PyObject_DelItem() 相同，但 key 被指定為 const char* UTF-8 編碼位元組字串，而不是 PyObject*。

PyObject *PyObject_Dir(PyObject *o)

返回值: 新引用。 穩定ABI 的一部分。

這等同於 Python 表示式 dir(o)，返回一個（可能為空的）適合物件引數的字串列表，或者在出錯時返回 NULL。如果引數為 NULL，則類似於 Python 的 dir()，返回當前區域性變數的名稱；在這種情況下，如果沒有活動的執行幀，則返回 NULL，但 PyErr_Occurred() 將返回 false。

PyObject *PyObject_GetIter(PyObject *o)

返回值: 新引用。 穩定ABI 的一部分。

這等同於 Python 表示式 iter(o)。它為物件引數返回一個新的迭代器，如果物件本身已經是迭代器，則返回物件本身。如果物件不可迭代，則引發 TypeError 並返回 NULL。

PyObject *PyObject_SelfIter(PyObject *obj)

返回值: 新引用。 穩定ABI 的一部分。

這等同於 Python 的 __iter__(self): return self 方法。它旨在用於 迭代器 型別，用於 PyTypeObject.tp_iter 槽。

PyObject *PyObject_GetAIter(PyObject *o)

返回值：新引用。 自 3.10 版本起成為 穩定 ABI 的一部分。

這等同於 Python 表示式 aiter(o)。它接受一個 AsyncIterable 物件，並返回其 AsyncIterator。這通常是一個新的迭代器，但如果引數是一個 AsyncIterator，則返回自身。如果物件不可迭代，則引發 TypeError 並返回 NULL。

在 3.10 版本加入。

void *PyObject_GetTypeData(PyObject *o, PyTypeObject *cls)

自 3.12 版本起成為 穩定 ABI 的一部分。

獲取指向為 cls 保留的子類特定資料的指標。

物件 o 必須是 cls 的例項，並且 cls 必須使用負的 PyType_Spec.basicsize 建立。Python 不會檢查這一點。

出錯時，設定異常並返回 NULL。

3.12 新版功能.

Py_ssize_t PyType_GetTypeDataSize(PyTypeObject *cls)

自 3.12 版本起成為 穩定 ABI 的一部分。

返回為 cls 保留的例項記憶體空間的大小，即 PyObject_GetTypeData() 返回的記憶體大小。

這可能大於使用負的 PyType_Spec.basicsize 請求的大小；使用此更大的大小（例如與 memset()）是安全的。

型別 cls 必須 使用負的 PyType_Spec.basicsize 建立。Python 不會檢查這一點。

出錯時，設定異常並返回負值。

3.12 新版功能.

void *PyObject_GetItemData(PyObject *o)

獲取指向具有 Py_TPFLAGS_ITEMS_AT_END 的類的每項資料的指標。

出錯時，設定異常並返回 NULL。如果 o 未設定 Py_TPFLAGS_ITEMS_AT_END，則會引發 TypeError。

3.12 新版功能.

int PyObject_VisitManagedDict(PyObject *obj, visitproc visit, void *arg)

訪問 obj 的託管字典。

此函式只能在具有 Py_TPFLAGS_MANAGED_DICT 標誌的型別遍歷函式中呼叫。

在 3.13 版本加入。

void PyObject_ClearManagedDict(PyObject *obj)

清除 obj 的託管字典。

此函式只能在具有 Py_TPFLAGS_MANAGED_DICT 標誌的型別清除函式中呼叫。

在 3.13 版本加入。

int PyUnstable_Object_EnableDeferredRefcount(PyObject *obj)

這是一個 不穩定 API。它可能會在次要版本中未經警告而更改。

如果執行時支援，則在 obj 上啟用 延遲引用計數。在 自由執行緒 構建中，這允許直譯器避免對 obj 的引用計數調整，這可能會提高多執行緒效能。權衡是 obj 將僅由跟蹤垃圾回收器解除分配，而不是在直譯器不再對其有任何引用時解除分配。

如果 obj 上啟用了延遲引用計數，則此函式返回 1；如果不支援延遲引用計數，或者直譯器忽略了此提示（例如 obj 上已啟用延遲引用計數），則返回 0。此函式是執行緒安全的，並且不會失敗。

在啟用了 GIL 的構建中，此函式不執行任何操作，這些構建不支援延遲引用計數。如果 obj 不是垃圾回收器跟蹤的物件（參見 gc.is_tracked() 和 PyObject_GC_IsTracked()），此函式也不執行任何操作。

此函式旨在在 obj 建立後不久，由建立它的程式碼使用，例如在物件的 tp_new 槽中。

在 3.14 版本加入。

int PyUnstable_Object_IsUniqueReferencedTemporary(PyObject *obj)

這是一個 不穩定 API。它可能會在次要版本中未經警告而更改。

檢查 obj 是否是唯一的臨時物件。如果 obj 已知是唯一的臨時物件，則返回 1，否則返回 0。此函式不會失敗，但檢查是保守的，即使 obj 是唯一的臨時物件，在某些情況下也可能返回 0。

如果一個物件是唯一的臨時物件，則保證當前程式碼是唯一引用該物件的。對於 C 函式的引數，應使用此方法而不是檢查引用計數是否為 1。從 Python 3.14 開始，直譯器透過在可能時 借用 引用，內部避免在將物件載入到運算元堆疊時進行一些引用計數修改，這意味著引用計數為 1 本身並不能保證函式引數是唯一引用的。

在下面的示例中，my_func 被呼叫，其引數是唯一的臨時物件。

my_func([1, 2, 3])

在下面的示例中，my_func 沒有被呼叫，其引數是唯一的臨時物件，即使其引用計數為 1。

my_list = [1, 2, 3]
my_func(my_list)

另請參閱函式 Py_REFCNT()。

在 3.14 版本加入。

int PyUnstable_IsImmortal(PyObject *obj)

這是一個 不穩定 API。它可能會在次要版本中未經警告而更改。

如果 obj 是 不朽的，此函式返回非零值，否則返回零。此函式不會失敗。

備註

在一個 CPython 版本中不朽的物件不能保證在另一個版本中也是不朽的。

在 3.14 版本加入。

int PyUnstable_TryIncRef(PyObject *obj)

這是一個 不穩定 API。它可能會在次要版本中未經警告而更改。

如果 obj 的引用計數不為零，則將其引用計數加一。如果物件引用計數成功遞增，則返回 1。否則，此函式返回 0。

必須在此函式之前在 obj 上呼叫過 PyUnstable_EnableTryIncRef()，否則此函式在 自由執行緒 構建中可能會錯誤地返回 0。

此函式在邏輯上等同於以下 C 程式碼，但在 自由執行緒 構建中它會原子地執行

if (Py_REFCNT(op) > 0) {
   Py_INCREF(op);
   return 1;
}
return 0;

這旨在作為管理弱引用而不產生 Python 弱引用物件 開銷的構建塊。

通常，正確使用此函式需要 obj 的解除分配器 (tp_dealloc) 的支援。例如，以下草圖可以適用於實現一個“弱對映”，其作用類似於特定型別的 WeakValueDictionary

PyMutex mutex;

PyObject *
add_entry(weakmap_key_type *key, PyObject *value)
{
    PyUnstable_EnableTryIncRef(value);
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    weakmap_add_entry(weakmap, key, value);
    PyMutex_Unlock(&mutex);
    Py_RETURN_NONE;
}

PyObject *
get_value(weakmap_key_type *key)
{
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    PyObject *result = weakmap_find(weakmap, key);
    if (PyUnstable_TryIncRef(result)) {
        // `result` is safe to use
        PyMutex_Unlock(&mutex);
        return result;
    }
    // if we get here, `result` is starting to be garbage-collected,
    // but has not been removed from the weakmap yet
    PyMutex_Unlock(&mutex);
    return NULL;
}

// tp_dealloc function for weakmap values
void
value_dealloc(PyObject *value)
{
    weakmap_type weakmap = ...;
    PyMutex_Lock(&mutex);
    weakmap_remove_value(weakmap, value);

    ...
    PyMutex_Unlock(&mutex);
}

在 3.14 版本加入。

void PyUnstable_EnableTryIncRef(PyObject *obj)

這是一個 不穩定 API。它可能會在次要版本中未經警告而更改。

在 obj 上啟用後續的 PyUnstable_TryIncRef() 呼叫。呼叫此函式時，呼叫者必須持有對 obj 的 強引用。

在 3.14 版本加入。

int PyUnstable_Object_IsUniquelyReferenced(PyObject *op)

這是一個 不穩定 API。它可能會在次要版本中未經警告而更改。

確定 op 是否只有一份引用。

在啟用 GIL 的構建中，此函式等同於 Py_REFCNT(op) == 1。

在 自由執行緒 構建中，此函式檢查 op 的 引用計數 是否等於一，並額外檢查 op 是否僅被當前執行緒使用。在自由執行緒構建中，Py_REFCNT(op) == 1 不是執行緒安全的；優先使用此函式。

呼叫者必須持有 附加執行緒狀態，儘管此函式不會呼叫 Python 直譯器。此函式不會失敗。

在 3.14 版本加入。