對象協(xié)議

PyObject* Py_NotImplemented

NotImplemented 單例，用于標(biāo)記某個操作沒有針對給定類型組合的實(shí)現(xiàn)。

Py_RETURN_NOTIMPLEMENTED

C 函數(shù)內(nèi)部應(yīng)正確處理 Py_NotImplemented 的返回過程（即增加 NotImplemented 的引用計數(shù)并返回之）。

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

將對象 o 寫入到文件 fp。 出錯時返回 -1 。 旗標(biāo)參數(shù)被用于啟用特定的輸出選項(xiàng)。 目前唯一支持的選項(xiàng)是 Py_PRINT_RAW；如果給出該選項(xiàng)，則將寫入對象的 str() 而不是 repr()。

int PyObject_HasAttr(PyObject?*o, PyObject?*attr_name)

如果 o 帶有屬性 attr_name，則返回 1，否則返回 0。這相當(dāng)于 Python 表達(dá)式 hasattr(o, attr_name)。 此函數(shù)總是成功。

注意，在調(diào)用 __getattr__() 和 __getattribute__() 方法時發(fā)生的異常將被抑制。若要獲得錯誤報告，請換用 PyObject_GetAttr() 。

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

如果 o 帶有屬性 attr_name，則返回 1，否則返回 0。這相當(dāng)于 Python 表達(dá)式 hasattr(o, attr_name)。 此函數(shù)總是成功。

注意，在調(diào)用 __getattr__() 和 __getattribute__() 方法并創(chuàng)建一個臨時字符串對象時，異常將被抑制。若要獲得錯誤報告，請換用 PyObject_GetAttrString() 。

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

Return value: New reference.

從對象 o 中讀取名為 attr_name 的屬性。成功返回屬性值，失敗則返回 NULL。 這相當(dāng)于 Python 表達(dá)式 o.attr_name。

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

Return value: New reference.

從對象 o 中讀取一個名為 attr_name 的屬性。成功時返回屬性值，失敗則返回 NULL。這相當(dāng)于 Python 表達(dá)式 o.attr_name。

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

Return value: New reference.

通用的屬性獲取函數(shù)，用于放入類型對象的 tp_getattro 槽中。它在類的字典中（位于對象的 MRO 中）查找某個描述符，并在對象的 __dict__ 中查找某個屬性。正如 實(shí)現(xiàn)描述器 所述，數(shù)據(jù)描述符優(yōu)先于實(shí)例屬性，而非數(shù)據(jù)描述符則不優(yōu)先。失敗則會觸發(fā) AttributeError 。

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

將對象 o 中名為 attr_name 的屬性值設(shè)為 v 。失敗時引發(fā)異常并返回 -1；成功時返 回``0`` 。這相當(dāng)于 Python 語句 o.attr_name = v。

如果 v 為 NULL，屬性將被刪除，但是此功能已被棄用，應(yīng)改用 PySequence_DelItem() 。

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

將對象 o 中名為 attr_name 的屬性值設(shè)為 v 。失敗時引發(fā)異常并返回 -1；成功時返 回``0`` 。這相當(dāng)于 Python 語句 o.attr_name = v。

如果 v 為 NULL，該屬性將被刪除，但是此功能已被棄用，應(yīng)改用 PySequence_DelItem() 。

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

通用的屬性設(shè)置和刪除函數(shù)，用于放入類型對象的 tp_setattro 槽。它在類的字典中（位于對象的MRO中）查找數(shù)據(jù)描述器，如果找到，則將比在實(shí)例字典中設(shè)置或刪除屬性優(yōu)先執(zhí)行。否則，該屬性將在對象的 __dict__ 中設(shè)置或刪除。如果成功將返回 0，否則將引發(fā) AttributeError 并返回 -1。

int PyObject_DelAttr(PyObject?*o, PyObject?*attr_name)

刪除對象 o 中名為 attr_name 的屬性。失敗時返回 -1。這相當(dāng)于 Python 語句 del o.attr_name。

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

刪除對象 o 中名為 attr_name 的屬性。失敗時返回 -1。這相當(dāng)于 Python 語句 del o.attr_name。

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

Return value: New reference.

__dict__ 描述符的獲取函數(shù)的一種通用實(shí)現(xiàn)。必要時會創(chuàng)建字典。

3.3 新版功能.

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

__dict__ 描述符設(shè)置函數(shù)的一種通用實(shí)現(xiàn)。這里不允許刪除字典。

3.3 新版功能.

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

Return value: New reference.

用 opid 指定的操作比較 o1 和 o2 的值，必須是 Py_LT 、 Py_LE 、 Py_EQ 、 Py_NE 、 Py_GT 或 Py_GE 之一，分別對應(yīng)于``<=`` 、== 、 != 、> 或 >=。這相當(dāng)于 Python 表達(dá)式 o1 op o2，其中 op 是對應(yīng)于 opid 的操作符。成功時返回比較值，失敗時返回 NULL。

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

用 opid 指定的操作比較 o1 和 o2 的值，必須是 Py_LT 、 Py_LE 、 Py_EQ 、 Py_NE 、 Py_GT 或 Py_GE 之一，分別對應(yīng)于 < 、<=、 == 、!= 、> 或 >=。錯誤時返回 -1，若結(jié)果為 false 則返回 0，否則返回 1。這相當(dāng)于 Python 表達(dá)式 o1 op o2，其中 op 是對應(yīng)于 opid 的操作符。

注解

如果 o1 和 o2 是同一個對象，PyObject_RichCompareBool() 為 Py_EQ 則返回 1 ，為 Py_NE 則返回 0。

PyObject* PyObject_Repr(PyObject?*o)

Return value: New reference.

計算對象 o 的字符串形式。 成功時返回字符串，失敗時返回 NULL。 這相當(dāng)于 Python 表達(dá)式 repr(o)。 由內(nèi)置函數(shù) repr() 調(diào)用。

在 3.4 版更改: 該函數(shù)現(xiàn)在包含一個調(diào)試斷言，用以確保不會靜默地丟棄活動的異常。

PyObject* PyObject_ASCII(PyObject?*o)

Return value: New reference.

與 PyObject_Repr() 一樣，計算對象 o 的字符串形式，但在 PyObject_Repr() 返回的字符串中用 \x、\u 或 \U 轉(zhuǎn)義非 ASCII 字符。這將生成一個類似于 Python 2 中由 PyObject_Repr() 返回的字符串。由內(nèi)置函數(shù) ascii() 調(diào)用。

PyObject* PyObject_Str(PyObject?*o)

Return value: New reference.

計算對象 o 的字符串形式。 成功時返回字符串，失敗時返回 NULL。 這相當(dāng)于 Python 表達(dá)式 str(o)。由內(nèi)置函數(shù) str() 調(diào)用，因此也由 print() 函數(shù)調(diào)用。

在 3.4 版更改: 該函數(shù)現(xiàn)在包含一個調(diào)試斷言，用以確保不會靜默地丟棄活動的異常。

PyObject* PyObject_Bytes(PyObject?*o)

Return value: New reference.

計算對象 o 的字節(jié)形式。失敗時返回 NULL，成功時返回一個字節(jié)串對象。這相當(dāng)于 o 不是整數(shù)時的 Python 表達(dá)式 bytes(o) 。與 bytes(o) 不同的是，當(dāng) o 是整數(shù)而不是初始為 0 的字節(jié)串對象時，會觸發(fā) TypeError。

int PyObject_IsSubclass(PyObject?*derived, PyObject?*cls)

如果 derived 類與 cls 類相同或?yàn)槠渑缮?，則返回 1，否則返回 0。 如果出錯則返回 -1。

如果 cls 是元組，則會對 cls 進(jìn)行逐項(xiàng)檢測。如果至少有一次檢測返回 1，結(jié)果將為 1，否則將是 0。

正如 PEP 3119 所述，如果 cls 帶有 __subclasscheck__() 方法，將會被調(diào)用以確定子類的狀態(tài)。 否則，如果 derived 是個直接或間接子類，即包含在 cls.__mro__ 中，那么它就是 cls 的一個子類。

通常只有類對象才會被視為類，即 type 或派生類的實(shí)例。然而，對象可以通過擁有 __bases__ 屬性（必須是基類的元組）來覆蓋這一點(diǎn)。

int PyObject_IsInstance(PyObject?*inst, PyObject?*cls)

如果 inst 是 cls 類或其子類的實(shí)例，則返回 1，如果不是則返回``0``。 如果出錯則返回 -1 并設(shè)置一個異常。

如果 cls 是元組，則會對 cls 進(jìn)行逐項(xiàng)檢測。如果至少有一次檢測返回 1，結(jié)果將為 1，否則將是 0。

正如 PEP 3119 所述，如果 cls 帶有 __subclasscheck__() 方法，將會被調(diào)用以確定子類的狀態(tài)。 否則，如果 derived 是 cls 的子類，那么它就是 cls 的一個實(shí)例。

實(shí)例 inst 可以通過 __class__ 屬性來覆蓋其所屬類。

對象 cls 可以通過 __bases__ 屬性（必須是基類的元組）來覆蓋它是否被認(rèn)作類的狀態(tài)，及其基類。

int PyCallable_Check(PyObject?*o)

確定對象 o 是可調(diào)對象。如果對象是可調(diào)對象則返回 1 ，其他情況返回 0 。這個函數(shù)不會調(diào)用失敗。

PyObject* PyObject_Call(PyObject?*callable, PyObject?*args, PyObject?*kwargs)

Return value: New reference.

調(diào)用一個可調(diào)用的 Python 對象 callable，附帶由元組 args 所給出的參數(shù)，以及由字典 kwargs 所給出的關(guān)鍵字參數(shù)。

args must not be NULL, use an empty tuple if no arguments are needed. If no named arguments are needed, kwargs can be NULL.

Return the result of the call on success, or raise an exception and return NULL on failure.

這等價于 Python 表達(dá)式 callable(*args, **kwargs)。

PyObject* PyObject_CallObject(PyObject?*callable, PyObject?*args)

Return value: New reference.

Call a callable Python object callable, with arguments given by the tuple args. If no arguments are needed, then args can be NULL.

Return the result of the call on success, or raise an exception and return NULL on failure.

這等價于 Python 表達(dá)式 callable(*args)。

PyObject* PyObject_CallFunction(PyObject?*callable, const char?*format, ...)

Return value: New reference.

Call a callable Python object callable, with a variable number of C arguments. The C arguments are described using a Py_BuildValue() style format string. The format can be NULL, indicating that no arguments are provided.

Return the result of the call on success, or raise an exception and return NULL on failure.

這等價于 Python 表達(dá)式 callable(*args)。

Note that if you only pass PyObject * args, PyObject_CallFunctionObjArgs() is a faster alternative.

在 3.4 版更改: 這個 format 類型已從 char * 更改。

PyObject* PyObject_CallMethod(PyObject?*obj, const char?*name, const char?*format, ...)

Return value: New reference.

Call the method named name of object obj with a variable number of C arguments. The C arguments are described by a Py_BuildValue() format string that should produce a tuple.

The format can be NULL, indicating that no arguments are provided.

Return the result of the call on success, or raise an exception and return NULL on failure.

這和Python表達(dá)式``obj.name(arg1, arg2, ...)``是一樣的。

Note that if you only pass PyObject * args, PyObject_CallMethodObjArgs() is a faster alternative.

在 3.4 版更改: The types of name and format were changed from char *.

PyObject* PyObject_CallFunctionObjArgs(PyObject?*callable, ..., NULL)

Return value: New reference.

Call a callable Python object callable, with a variable number of PyObject* arguments. The arguments are provided as a variable number of parameters followed by NULL.

Return the result of the call on success, or raise an exception and return NULL on failure.

這和Python表達(dá)式``callable(arg1, arg2, ...)``是一樣的。

PyObject* PyObject_CallMethodObjArgs(PyObject?*obj, PyObject?*name, ..., NULL)

Return value: New reference.

Calls a method of the Python object obj, where the name of the method is given as a Python string object in name. It is called with a variable number of PyObject* arguments. The arguments are provided as a variable number of parameters followed by NULL.

Return the result of the call on success, or raise an exception and return NULL on failure.

Py_hash_t PyObject_Hash(PyObject?*o)

計算并返回對象的哈希值 o。 失敗時返回 -1。這相當(dāng)于 Python 表達(dá)式 hash(o)。

在 3.2 版更改: 現(xiàn)在的返回類型是 Py_hash_t。 這是一個帶符號整數(shù)，與 Py_ssize_t 大小相同。

Py_hash_t PyObject_HashNotImplemented(PyObject?*o)

設(shè)置一個 TypeError 表示 type(o) 是不可哈希的，并返回 -1 。該函數(shù)保存在 tp_hash 槽中時會受到特別對待，允許某個類型向解釋器顯式表明它不可散列。

int PyObject_IsTrue(PyObject?*o)

如果對象 o 被認(rèn)為是 true，則返回 1，否則返回 0。這相當(dāng)于 Python 表達(dá)式 not not o。 失敗則返回 -1。

int PyObject_Not(PyObject?*o)

如果對象 o 被認(rèn)為是 true，則返回 1，否則返回 0。這相當(dāng)于 Python 表達(dá)式 not not o。 失敗則返回 -1。

PyObject* PyObject_Type(PyObject?*o)

Return value: New reference.

When o is non-NULL, returns a type object corresponding to the object type of object o. On failure, raises SystemError and returns NULL. This is equivalent to the Python expression type(o). This function increments the reference count of the return value. There's really no reason to use this function instead of the common expression o->ob_type, which returns a pointer of type PyTypeObject*, except when the incremented reference count is needed.

int PyObject_TypeCheck(PyObject?*o, PyTypeObject?*type)

如果對象Return true if the object o 為 type 類型或 type 的子類型則返回真值。 兩個參數(shù)都必須非 NULL。

Py_ssize_t PyObject_Size(PyObject?*o)

Py_ssize_t PyObject_Length(PyObject?*o)

返回對象 o 的長度。 如果對象 o 支持序列和映射協(xié)議，則返回序列長度。 出錯時返回 -1。這等同于 Python 表達(dá)式 len(o)。

Py_ssize_t PyObject_LengthHint(PyObject?*o, Py_ssize_t?default)

Return an estimated length for the object o. First try to return its actual length, then an estimate using __length_hint__(), and finally return the default value. On error return -1. This is the equivalent to the Python expression operator.length_hint(o, default).

3.4 新版功能.

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

Return value: New reference.

返回對象 key 對應(yīng)的 o 元素，或在失敗時返回 NULL。這等同于 Python 表達(dá)式 o[key]。

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

Map the object key to the value v. Raise an exception and return -1 on failure; return 0 on success. This is the equivalent of the Python statement o[key] = v.

int PyObject_DelItem(PyObject?*o, PyObject?*key)

從對象 o 中移除對象 key 的映射。失敗時返回 -1。 這相當(dāng)于 Python 語句 del o[key]。

PyObject* PyObject_Dir(PyObject?*o)

Return value: New reference.

相當(dāng)于 Python 表達(dá)式 dir(o)，返回一個（可能為空）適合對象參數(shù)的字符串列表，如果出錯則返回 NULL。 如果參數(shù)為 NULL，類似 Python 的 dir()，則返回當(dāng)前 locals 的名字；這時如果沒有活動的執(zhí)行框架，則返回 NULL，但 PyErr_Occurred() 將返回 false。

PyObject* PyObject_GetIter(PyObject?*o)

Return value: New reference.

等同于 Python 表達(dá)式 iter(o)。為對象參數(shù)返回一個新的迭代器，如果該對象已經(jīng)是一個迭代器，則返回對象本身。如果對象不能被迭代，會引發(fā) TypeError ，并返回 NULL。