对象协议

PyObject *Py_NotImplemented

NotImplemented 单例,用于标记某个操作没有针对给定类型组合的实现。

Py_RETURN_NOTIMPLEMENTED

正确处理从 C 语言函数中返回 Py_NotImplemented 的问题(即新建一个指向 NotImplemented 的 strong reference 并返回它)。

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_HasAttr(PyObject *o, PyObject *attr_name)
穩定 ABI 的一部分.

如果 o 带有属性 attr_name,则返回 1,否则返回 0。这相当于 Python 表达式 hasattr(o, attr_name)。 此函数总是成功。

備註

在调用 __getattr__()__getattribute__() 方法时发生的异常将被静默地忽略。 想要进行适当的错误处理,请改用 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_GetAttrString()

PyObject *PyObject_GetAttr(PyObject *o, PyObject *attr_name)
回傳值:新的參照。穩定 ABI 的一部分.

从对象 o 中读取名为 attr_name 的属性。成功返回属性值,失败则返回 NULL。 这相当于 Python 表达式 o.attr_name

PyObject *PyObject_GetAttrString(PyObject *o, const char *attr_name)
回傳值:新的參照。穩定 ABI 的一部分.

这与 PyObject_GetAttr() 相同,但 attr_name 被指定为 const char* UTF-8 编码的字节串,而不是 PyObject*

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

如果 vNULL,该属性将被删除。 此行为已被弃用而应改用 PyObject_DelAttr(),但目前还没有移除它的计划。

int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)
穩定 ABI 的一部分.

这与 PyObject_SetAttr() 相同,但 attr_name 被指定为 const char* UTF-8 编码的字节串,而不是 PyObject*

如果 vNULL,该属性将被删除,但是此功能已被弃用而应改用 PyObject_DelAttrString()

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)

删除对象 o 中名为 attr_name 的属性。失败时返回 -1。这相当于 Python 语句 del o.attr_name

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

这与 PyObject_DelAttr() 相同,但 attr_name 被指定为 const char* UTF-8 编码的字节串,而不是 PyObject*

PyObject *PyObject_GenericGetDict(PyObject *o, void *context)
回傳值:新的參照。穩定 ABI 的一部分 自 3.10 版本開始.

__dict__ 描述符的获取函数的一种通用实现。必要时会创建该字典。

此函数还可能会被调用以获取对象 o__dict__。 当调用它时可传入 NULL 作为 context。 由于此函数可能需要为字典分配内存,所以在访问对象上的属性时调用 PyObject_GetAttr() 可能会更为高效。

当失败时,将返回 NULL 并设置一个异常。

在 3.3 版新加入.

int PyObject_GenericSetDict(PyObject *o, PyObject *value, void *context)
穩定 ABI 的一部分 自 3.7 版本開始.

__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 指定的操作来比较 o1o2 的值,操作必须为 Py_LT, Py_LE, Py_EQ, Py_NE, Py_GTPy_GE 中的一个,分别对应于 <, <=, ==, !=, >>=。 这等价于 Python 表达式 o1 op o2,其中 op 是与 opid 对应的运算符。 成功时返回比较结果值,失败时返回 NULL

int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)
穩定 ABI 的一部分.

使用 opid 所指定的操作,例如 PyObject_RichCompare() 来比较 o1o2 的值,但在出错时返回 -1,在结果为假值时返回 0,在其他情况下返回 1

備註

如果 o1o2 是同一个对象,PyObject_RichCompareBool() 将总是为 Py_EQ 返回 1 并为 Py_NE 返回 0

PyObject *PyObject_Format(PyObject *obj, PyObject *format_spec)
穩定 ABI 的一部分.

格式 obj 使用 format_spec。 这等价于 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 的字符串形式,但在 PyObject_Repr() 返回的字符串中用 \x\u\U 转义非 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,成功时返回一个字节串对象。这相当于 o 不是整数时的 Python 表达式 bytes(o) 。与 bytes(o) 不同的是,当 o 是整数而不是初始为 0 的字节串对象时,会触发 TypeError。

int PyObject_IsSubclass(PyObject *derived, PyObject *cls)
穩定 ABI 的一部分.

如果 derived 类与 cls 类相同或为其派生类,则返回 1,否则返回 0。 如果出错则返回 -1

如果 cls 是元组,则会对 cls 进行逐项检测。如果至少有一次检测返回 1,结果将为 1,否则将是 0

正如 PEP 3119 所述,如果 cls 带有 __subclasscheck__() 方法,将会被调用以确定子类的状态。 否则,如果 derived 是个直接或间接子类,即包含在 cls.__mro__ 中,那么它就是 cls 的一个子类。

通常只有类对象(即 type 或派生类的实例)才被视为类。 但是,对象可以通过设置 __bases__ 属性(必须是基类的元组)来覆盖这一点。

int PyObject_IsInstance(PyObject *inst, PyObject *cls)
穩定 ABI 的一部分.

如果 instcls 类或其子类的实例,则返回 1,如果不是则返回 0。 如果出错则返回 -1 并设置一个异常。

如果 cls 是元组,则会对 cls 进行逐项检测。如果至少有一次检测返回 1,结果将为 1,否则将是 0

正如 PEP 3119 所述,如果 cls 带有 __subclasscheck__() 方法,将会被调用以确定子类的状态。 否则,如果 derivedcls 的子类,那么它就是 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) 不是 hashable 并返回 -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,则返回 1,否则返回 0。这相当于 Python 表达式 not not o。 失败则返回 -1

PyObject *PyObject_Type(PyObject *o)
回傳值:新的參照。穩定 ABI 的一部分.

o 不为 NULL 时,返回一个与对象 o 的类型相对应的类型对象。 当失败时,将引发 SystemError 并返回 NULL。 这等同于 Python 表达式 type(o)。 该函数会新建一个指向返回值的 strong reference。 实际上没有多少理由使用此函数来替代 Py_TYPE() 函数,后者将返回一个 PyTypeObject* 类型的指针,除非是需要一个新的 strong reference

int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)

如果对象 otype 类型或其子类型,则返回非零,否则返回 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(),则返回当前 locals 的名字;这时如果没有活动的执行框架,则返回 NULL,但 PyErr_Occurred() 将返回 false。

PyObject *PyObject_GetIter(PyObject *o)
回傳值:新的參照。穩定 ABI 的一部分.

等同于 Python 表达式 iter(o)。为对象参数返回一个新的迭代器,如果该对象已经是一个迭代器,则返回对象本身。如果对象不能被迭代,会引发 TypeError ,并返回 NULL

PyObject *PyObject_GetAIter(PyObject *o)
回傳值:新的參照。穩定 ABI 的一部分 自 3.10 版本開始.

等同于 Python 表达式 aiter(o)。接受一个 AsyncIterable 对象,并为其返回一个 AsyncIterator。通常返回的是一个新迭代器,但如果参数是一个 AsyncIterator,将返回其自身。如果该对象不能被迭代,会引发 TypeError,并返回 NULL

在 3.10 版新加入.

void *PyObject_GetTypeData(PyObject *o, PyTypeObject *cls)
穩定 ABI 的一部分 自 3.12 版本開始.

获取一个指向为 cls 保留的子类专属数据的指针。

对象 o 必须为 cls 的实例,而 cls 必须使用负的 PyType_Spec.basicsize 来创建。 Python 不会检查这一点。

发生错误时,将设置异常并返回 NULL

在 3.12 版新加入.

Py_ssize_t PyType_GetTypeDataSize(PyTypeObject *cls)
穩定 ABI 的一部分 自 3.12 版本開始.

返回为 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 版新加入.