对象协议 — Python 文档

来自菜鸟教程
Python/docs/3.7/c-api/object
跳转至:导航、​搜索

对象协议

PyObject *Py_NotImplemented
NotImplemented 单例,用于表示没有为给定的类型组合实现操作。
Py_RETURN_NOTIMPLEMENTED
正确处理从 C 函数中返回 Py_NotImplemented(即增加 NotImplemented 的引用计数并返回它)。
int PyObject_Print(PyObject *o, FILE *fp, int flags)
在文件 fp 上打印对象 o。 出错时返回 -1。 flags 参数用于启用某些打印选项。 目前唯一支持的选项是Py_PRINT_RAW; 如果给定,则写入对象的 str() 而不是 repr()
int PyObject_HasAttr(PyObject *o, PyObject *attr_name)

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

请注意,调用 __getattr__()__getattribute__() 方法时发生的异常将被抑制。 要获得错误报告,请改用 PyObject_GetAttr()

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

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

请注意,调用 __getattr__()__getattribute__() 方法以及创建临时字符串对象时发生的异常将被抑制。 要获得错误报告,请改用 PyObject_GetAttrString()

PyObject *PyObject_GetAttr(PyObject *o, PyObject *attr_name)
从对象 o 中检索名为 attr_name 的属性。 成功时返回属性值,失败时返回 NULL。 这相当于 Python 表达式 o.attr_name
PyObject *PyObject_GetAttrString(PyObject *o, const char *attr_name)
从对象 o 中检索名为 attr_name 的属性。 成功时返回属性值,失败时返回 NULL。 这相当于 Python 表达式 o.attr_name
PyObject *PyObject_GenericGetAttr(PyObject *o, PyObject *name)
旨在放入类型对象的 tp_getattro 插槽的通用属性 getter 函数。 它在对象的 MRO 中的类字典中查找描述符以及对象的 __dict__(如果存在)中的属性。 如 实现描述符 中所述,数据描述符优先于实例属性,而非数据描述符则不然。 否则,会引发 AttributeError
int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)

将对象 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)

将对象 o 的名为 attr_name 的属性的值设置为值 v。 引发异常并在失败时返回 -1; 成功返回 0。 这相当于 Python 语句 o.attr_name = v

如果 vNULL,则删除该属性,但不推荐使用此功能,而是使用 PyObject_DelAttrString()

int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)
通用属性设置器和删除器函数,旨在放入类型对象的 tp_setattro 槽中。 它在对象的 MRO 中的类字典中查找数据描述符,如果找到,它优先于设置或删除实例字典中的属性。 否则,在对象的 __dict__(如果存在)中设置或删除该属性。 成功时,返回 0,否则会引发 AttributeError 并返回 -1
int PyObject_DelAttr(PyObject *o, PyObject *attr_name)
删除名为 attr_name 的属性,用于对象 o。 失败时返回 -1。 这相当于 Python 语句 del o.attr_name
int PyObject_DelAttrString(PyObject *o, const char *attr_name)
删除名为 attr_name 的属性,用于对象 o。 失败时返回 -1。 这相当于 Python 语句 del o.attr_name
PyObject *PyObject_GenericGetDict(PyObject *o, void *context)

__dict__ 描述符的 getter 的通用实现。 如有必要,它会创建字典。

3.3 版中的新功能。

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

__dict__ 描述符的 setter 的通用实现。 此实现不允许删除字典。

3.3 版中的新功能。

PyObject *PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)
使用 opid 指定的操作比较 o1o2 的值,该操作必须是 Py_LTPy_LE 之一, Py_EQ, Py_NE, Py_GT, or Py_GE,对应<,[X222X],[X] X234X]、!=>>=。 这相当于 Python 表达式 o1 op o2,其中 op 是对应于 opid 的运算符。 成功时返回比较值,失败时返回 NULL
int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)
使用 opid 指定的操作比较 o1o2 的值,该操作必须是 Py_LTPy_LE 之一, Py_EQ, Py_NE, Py_GT, or Py_GE,对应<,[X222X],[X] X234X]、!=>>=。 出错时返回 -1,如果结果为假则返回 0,否则返回 1。 这相当于 Python 表达式 o1 op o2,其中 op 是对应于 opid 的运算符。

笔记

如果 o1o2 是同一个对象,则 PyObject_RichCompareBool() 将始终为 Py_EQ0 代表 Py_NE


PyObject *PyObject_Repr(PyObject *o)

计算对象 o 的字符串表示。 成功时返回字符串表示,失败时返回 NULL。 这相当于 Python 表达式 repr(o)。 由 repr() 内置函数调用。

3.4 版更改: 此函数现在包含一个调试断言,以帮助确保它不会静默丢弃活动异常。

PyObject *PyObject_ASCII(PyObject *o)

作为 PyObject_Repr(),计算对象 o 的字符串表示,但将 PyObject_Repr() 返回的字符串中的非 ASCII 字符转义为 \x\u\U 转义。 这会生成一个类似于 Python 2 中 PyObject_Repr() 返回的字符串。 由 ascii() 内置函数调用。

PyObject *PyObject_Str(PyObject *o)

计算对象 o 的字符串表示。 成功时返回字符串表示,失败时返回 NULL。 这相当于 Python 表达式 str(o)。 由 str() 内置函数调用,因此由 print() 函数调用。

3.4 版更改: 此函数现在包含一个调试断言,以帮助确保它不会静默丢弃活动异常。

PyObject *PyObject_Bytes(PyObject *o)
计算对象 o 的字节表示。 NULL 失败时返回,成功时返回一个字节对象。 当 o 不是整数时,这等效于 Python 表达式 bytes(o)。 与 bytes(o) 不同,当 o 是整数而不是零初始化字节对象时,会引发 TypeError。
int PyObject_IsSubclass(PyObject *derived, PyObject *cls)

如果类 派生 与类 cls 相同或派生自类,则返回 1,否则返回 0。 如果出现错误,返回 -1

如果 cls 是元组,则将对 cls 中的每个条目进行检查。 当至少一项检查返回 1 时,结果将为 1,否则为 0

如果 cls__subclasscheck__() 方法,它将被调用以确定子类状态,如 PEP 3119 中所述。 否则,derivedcls 的子类,如果它是直接或间接的子类,即 包含在 cls.__mro__ 中。

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

int PyObject_IsInstance(PyObject *inst, PyObject *cls)

如果 inst 是类 cls 的实例或 cls 的子类,则返回 1,否则返回 0。 出错时,返回 -1 并设置异常。

如果 cls 是元组,则将对 cls 中的每个条目进行检查。 当至少一项检查返回 1 时,结果将为 1,否则为 0

如果 cls__instancecheck__() 方法,它将被调用以确定子类状态,如 PEP 3119 中所述。 否则,instcls 的实例,如果它的类是 cls 的子类。

实例 inst 可以通过具有 __class__ 属性来覆盖被视为其类的内容。

如果对象 cls 被认为是一个类,那么它可以通过具有 __bases__ 属性(必须是基类的元组)来覆盖它的基类是什么。

int PyCallable_Check(PyObject *o)
确定对象 o 是否可调用。 如果对象可调用,则返回 1,否则返回 0。 此功能总是成功。
PyObject *PyObject_Call(PyObject *callable, PyObject *args, PyObject *kwargs)

调用一个可调用的 Python 对象 callable,参数由元组 args 给出,命名参数由字典 kwargs 给出。

args 不能是 NULL,如果不需要参数,请使用空元组。 如果不需要命名参数,kwargs 可以是 NULL

成功时返回调用结果,或引发异常并在失败时返回 NULL

这相当于 Python 表达式:callable(*args, **kwargs)

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

调用一个可调用的 Python 对象 callable,参数由元组 args 给出。 如果不需要参数,则 args 可以是 NULL

成功时返回调用结果,或引发异常并在失败时返回 NULL

这相当于 Python 表达式:callable(*args)

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

使用可变数量的 C 参数调用可调用 Python 对象 callable。 C 参数使用 Py_BuildValue() 样式格式字符串进行描述。 格式可以是NULL,表示不提供参数。

成功时返回调用结果,或引发异常并在失败时返回 NULL

这相当于 Python 表达式:callable(*args)

请注意,如果您只传递 PyObject * 参数,则 PyObject_CallFunctionObjArgs() 是一个更快的选择。

3.4 版本变更:格式的类型由char *变更。

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

使用可变数量的 C 参数调用对象 obj 的名为 name 的方法。 C 参数由 Py_BuildValue() 格式字符串描述,该字符串应该生成一个元组。

格式可以是NULL,表示不提供参数。

成功时返回调用结果,或引发异常并在失败时返回 NULL

这相当于 Python 表达式:obj.name(arg1, arg2, ...)

请注意,如果您只传递 PyObject * 参数,则 PyObject_CallMethodObjArgs() 是一个更快的选择。

3.4 版本变更: nameformat 的类型由 char * 变更。

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

使用可变数量的 PyObject* 参数调用可调用 Python 对象 callable。 参数以可变数量的参数形式提供,后跟 NULL

成功时返回调用结果,或引发异常并在失败时返回 NULL

这相当于 Python 表达式:callable(arg1, arg2, ...)

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

调用 Python 对象 obj 的方法,其中方法的名称在 name 中作为 Python 字符串对象给出。 它使用可变数量的 PyObject* 参数调用。 参数以可变数量的参数形式提供,后跟 NULL

成功时返回调用结果,或引发异常并在失败时返回 NULL

Py_hash_t PyObject_Hash(PyObject *o)

计算并返回对象 o 的哈希值。 失败时,返回 -1。 这相当于 Python 表达式 hash(o)

3.2 版更改: 返回类型现在为 Py_hash_t。 这是一个与 Py_ssize_t 大小相同的有符号整数。

Py_hash_t PyObject_HashNotImplemented(PyObject *o)
设置 TypeError 指示 type(o) 不可哈希并返回 -1。 此函数在存储在 tp_hash 插槽中时会受到特殊处理,允许类型明确地向解释器指示它不可散列。
int PyObject_IsTrue(PyObject *o)
如果对象 o 被认为是真,则返回 1,否则返回 0。 这相当于 Python 表达式 not not o。 失败时,返回 -1
int PyObject_Not(PyObject *o)
如果对象 o 被认为是真,则返回 0,否则返回 1。 这相当于 Python 表达式 not o。 失败时,返回 -1
PyObject *PyObject_Type(PyObject *o)
o为非NULL时,返回与对象o的对象类型对应的类型对象。 失败时,引发 SystemError 并返回 NULL。 这相当于 Python 表达式 type(o)。 此函数增加返回值的引用计数。 真的没有理由使用这个函数代替通用表达式 o->ob_type,它返回一个类型为 PyTypeObject* 的指针,除非需要增加引用计数。
int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)
如果对象 o 的类型为 typetype 的子类型,则返回 true。 两个参数都必须是非 NULL
Py_ssize_t PyObject_Size(PyObject *o)


Py_ssize_t PyObject_Length(PyObject *o)

返回对象 o 的长度。 如果对象 o 提供序列和映射协议,则返回序列长度。 出错时,返回 -1。 这相当于 Python 表达式 len(o)
Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t default)

返回对象 o 的估计长度。 首先尝试返回其实际长度,然后使用 __length_hint__() 进行估计,最后返回默认值。 出错时返回 -1。 这相当于 Python 表达式 operator.length_hint(o, default)

3.4 版中的新功能。

PyObject *PyObject_GetItem(PyObject *o, PyObject *key)
失败时返回与对象 keyNULL 对应的 o 的元素。 这相当于 Python 表达式 o[key]
int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)
将对象 key 映射到值 v。 引发异常并在失败时返回 -1; 成功返回 0。 这相当于 Python 语句 o[key] = v
int PyObject_DelItem(PyObject *o, PyObject *key)
从对象 o 中删除对象 key 的映射。 失败时返回 -1。 这相当于 Python 语句 del o[key]
PyObject *PyObject_Dir(PyObject *o)
这等效于 Python 表达式 dir(o),返回一个(可能为空)适合对象参数的字符串列表,如果出现错误,则返回 NULL。 如果参数是NULL,这就像Python的dir(),返回当前本地人的名字; 在这种情况下,如果没有执行帧处于活动状态,则返回 NULLPyErr_Occurred() 将返回 false。
PyObject *PyObject_GetIter(PyObject *o)
这相当于 Python 表达式 iter(o)。 它为对象参数返回一个新的迭代器,如果对象已经是迭代器,则返回对象本身。 如果对象无法迭代,则引发 TypeError 并返回 NULL