物件協議

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)

在檔案 fp 上列印物件 o。如果出錯，則返回 -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 是一個 UTF-8 編碼的位元組字串 const char*，而不是 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* 是一個 UTF-8 編碼的位元組字串 const char*，而不是 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* 是一個 UTF-8 編碼的位元組字串 const char*，而不是 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__ 描述符的 getter 的通用實現。它會在必要時建立字典。

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

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

在 3.3 版本中新增。

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

自 3.7 版本起，屬於 穩定的 ABI。

__dict__ 描述符的 setter 的通用實現。此實現不允許刪除字典。

在 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，如果結果為 false 則返回 0，否則返回 1。

注意

如果 o1 和 o2 是同一個物件，則對於 Py_EQ，PyObject_RichCompareBool() 將始終返回 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.__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 被認為是 true，則返回 1，否則返回 0。這等效於 Python 表示式 not not o。如果失敗，則返回 -1。

int PyObject_Not(PyObject *o)

屬於 穩定 ABI 的一部分。

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

PyObject *PyObject_Type(PyObject *o)

返回值：新引用。屬於 穩定 ABI 的一部分。

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

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 的一部分。

返回與物件 key 對應的 o 的元素，如果失敗則返回 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]。

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 版本中新增。