对象协议 — Python 文档
对象协议
- PyObject *Py_NotImplemented
NotImplemented
单例,用于表示没有为给定的类型组合实现操作。
- Py_RETURN_NOTIMPLEMENTED
- 正确处理从 C 函数中返回 Py_NotImplemented(即增加 NotImplemented 的引用计数并返回它)。
- int PyObject_Print(PyObject *o, FILE *fp, int flags)
- 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()。
- 从对象 o 中检索名为 attr_name 的属性。 成功时返回属性值,失败时返回
NULL
。 这相当于 Python 表达式o.attr_name
。
- 从对象 o 中检索名为 attr_name 的属性。 成功时返回属性值,失败时返回
NULL
。 这相当于 Python 表达式o.attr_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
。如果 v 是
NULL
,则删除该属性,但不推荐使用此功能,以支持使用 PyObject_DelAttr()。
- int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)
将对象 o 的名为 attr_name 的属性的值设置为值 v。 引发异常并在失败时返回
-1
; 成功返回0
。 这相当于 Python 语句o.attr_name = v
。如果 v 是
NULL
,则删除该属性,但不推荐使用此功能,而是使用 PyObject_DelAttrString()。
- 通用属性设置器和删除器函数,旨在放入类型对象的 tp_setattro 槽中。 它在对象的 MRO 中的类字典中查找数据描述符,如果找到,它优先于设置或删除实例字典中的属性。 否则,在对象的 __dict__(如果存在)中设置或删除该属性。 成功时,返回
0
,否则会引发 AttributeError 并返回-1
。
- 删除名为 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 版中的新功能。
- 使用 opid 指定的操作比较 o1 和 o2 的值,该操作必须是
Py_LT
、Py_LE
之一,Py_EQ
,Py_NE
,Py_GT
, orPy_GE
,对应<
,[X222X],[X] X234X]、!=
、>
或>=
。 这相当于 Python 表达式o1 op o2
,其中op
是对应于 opid 的运算符。 成功时返回比较值,失败时返回NULL
。
- 使用 opid 指定的操作比较 o1 和 o2 的值,该操作必须是
Py_LT
、Py_LE
之一,Py_EQ
,Py_NE
,Py_GT
, orPy_GE
,对应<
,[X222X],[X] X234X]、!=
、>
或>=
。 出错时返回-1
,如果结果为假则返回0
,否则返回1
。 这相当于 Python 表达式o1 op o2
,其中op
是对应于 opid 的运算符。
- 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 版更改: 此函数现在包含一个调试断言,以帮助确保它不会静默丢弃活动异常。
- 计算对象 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 中所述。 否则,derived 是 cls 的子类,如果它是直接或间接的子类,即 包含在
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 中所述。 否则,inst 是 cls 的实例,如果它的类是 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 版本变更: name 和 format 的类型由
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
。
- 当o为非
NULL
时,返回与对象o的对象类型对应的类型对象。 失败时,引发 SystemError 并返回NULL
。 这相当于 Python 表达式type(o)
。 此函数增加返回值的引用计数。 真的没有理由使用这个函数代替通用表达式o->ob_type
,它返回一个类型为PyTypeObject*
的指针,除非需要增加引用计数。
- int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)
- 如果对象 o 的类型为 type 或 type 的子类型,则返回 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 版中的新功能。
- 失败时返回与对象 key 或
NULL
对应的 o 的元素。 这相当于 Python 表达式o[key]
。
- 将对象 key 映射到值 v。 引发异常并在失败时返回
-1
; 成功返回0
。 这相当于 Python 语句o[key] = v
。
- 从对象 o 中删除对象 key 的映射。 失败时返回
-1
。 这相当于 Python 语句del o[key]
。
- 这等效于 Python 表达式
dir(o)
,返回一个(可能为空)适合对象参数的字符串列表,如果出现错误,则返回NULL
。 如果参数是NULL
,这就像Python的dir()
,返回当前本地人的名字; 在这种情况下,如果没有执行帧处于活动状态,则返回NULL
但 PyErr_Occurred() 将返回 false。
- 这相当于 Python 表达式
iter(o)
。 它为对象参数返回一个新的迭代器,如果对象已经是迭代器,则返回对象本身。 如果对象无法迭代,则引发 TypeError 并返回NULL
。