对象协议¶
-
PyObject *Py_GetConstant(unsigned int constant_id)¶
- 属于 稳定 ABI 自 3.13 版起.
获取一个指向常量的 strong reference。
如果 constant_id 无效则设置一个异常并返回
NULL
。constant_id 必须是下列常量标识符之一:
常量标识符
值
返回的对象
-
Py_CONSTANT_NONE¶
0
-
Py_CONSTANT_FALSE¶
1
-
Py_CONSTANT_TRUE¶
2
-
Py_CONSTANT_ELLIPSIS¶
3
-
Py_CONSTANT_NOT_IMPLEMENTED¶
4
-
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
()
仅对无法使用常量标识符的项目才会给出数字值。
Added in version 3.13.
CPython 实现细节: 在 CPython 中,所有这些常量都属于 immortal 对象。
-
Py_CONSTANT_NONE¶
-
PyObject *Py_GetConstantBorrowed(unsigned int constant_id)¶
- 属于 稳定 ABI 自 3.13 版起.
类似于
Py_GetConstant()
,但会返回一个 borrowed reference。此函数的主要目的是用于向下兼容:对于新代码推荐使用
Py_GetConstant()
。该引用是从解释器借入的,并将保持可用直到解释器最终化。
Added in version 3.13.
-
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_HasAttrWithError(PyObject *o, PyObject *attr_name)¶
- 属于 稳定 ABI 自 3.13 版起.
如果 o 具有属性 attr_name 则返回
1
,否则返回0
。 这相当于 Python 表达式hasattr(o, attr_name)
。 当失败时,将返回-1
。Added in version 3.13.
-
int PyObject_HasAttrStringWithError(PyObject *o, const char *attr_name)¶
- 属于 稳定 ABI 自 3.13 版起.
这与
PyObject_HasAttrWithError()
相同,但 attr_name 被指定为 const char* UTF-8 编码的字节串,而不是 PyObject*。Added in version 3.13.
-
int PyObject_HasAttr(PyObject *o, PyObject *attr_name)¶
- 属于 稳定 ABI.
如果 o 具有属性 attr_name 则返回
1
,否则返回0
。 此函数总是会成功执行。备注
当其调用
__getattr__()
和__getattribute__()
方法时发生的异常将被静默地忽略。 想要进行适当的错误处理,请改用PyObject_HasAttrWithError()
,PyObject_GetOptionalAttr()
或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_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 被指定为 const char* UTF-8 编码的字节串,而不是 PyObject*。如果缺少属性不应被视为执行失败,你可以改用
PyObject_GetOptionalAttrString()
。
-
int PyObject_GetOptionalAttr(PyObject *obj, PyObject *attr_name, PyObject **result);¶
- 属于 稳定 ABI 自 3.13 版起.
PyObject_GetAttr()
的变化形式,它在未找到键时不会引发AttributeError
。如果找到该属性,则返回
1
并将 *result 设为指向该属性的新 strong reference。 如果未找到该属性,则返回0
并将 *result 设为NULL
;AttributeError
会被静默。 如果引发了AttributeError
以外的错误,则返回-1
并将 *result 设为NULL
。Added in version 3.13.
-
int PyObject_GetOptionalAttrString(PyObject *obj, const char *attr_name, PyObject **result);¶
- 属于 稳定 ABI 自 3.13 版起.
这与
PyObject_GetOptionalAttr()
相同,但 attr_name 被指定为 const char* UTF-8 编码的字节串,而不是 PyObject*。Added in version 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)¶
- 属于 稳定 ABI 自 3.13 版起.
删除对象 o 中名为 attr_name 的属性。失败时返回
-1
。这相当于 Python 语句del o.attr_name
。
-
int PyObject_DelAttrString(PyObject *o, const char *attr_name)¶
- 属于 稳定 ABI 自 3.13 版起.
这与
PyObject_DelAttr()
相同,但 attr_name 被指定为 const char* UTF-8 编码的字节串,而不是 PyObject*。传给该函数的不同属性名称应当保持在较少的数量,通过是通过使用静态分配的字符串作为 attr_name 来做到这一点。 对于编译时未知的属性名称,建议直接调用
PyUnicode_FromString()
和PyObject_DelAttr()
。 更多相关细节,请参阅PyUnicode_InternFromString()
,它可在内部用于创建供查找的键对象。
-
PyObject *PyObject_GenericGetDict(PyObject *o, void *context)¶
- 返回值:新的引用。 属于 稳定 ABI 自 3.10 版起.
__dict__
描述符的获取函数的一种通用实现。必要时会创建该字典。此函数还可能会被调用以获取对象 o 的
__dict__
。 当调用它时可传入NULL
作为 context。 由于此函数可能需要为字典分配内存,所以在访问对象上的属性时调用PyObject_GetAttr()
可能会更为高效。当失败时,将返回
NULL
并设置一个异常。Added in version 3.3.
-
int PyObject_GenericSetDict(PyObject *o, PyObject *value, void *context)¶
- 属于 稳定 ABI 自 3.7 版起.
__dict__
描述符设置函数的一种通用实现。这里不允许删除该字典。Added in version 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 的值,操作必须为
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 所指定的操作,例如
PyObject_RichCompare()
来比较 o1 和 o2 的值,但在出错时返回-1
,在结果为假值时返回0
,在其他情况下返回1
。
备注
如果 o1 和 o2 是同一个对象,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
。如果 cls 具有
__subclasscheck__()
方法,它将被调用以确定 PEP 3119 所描述的子类状态。 在其他情况下,如果 derived 是一个直接或间接子类即包含在cls.__mro__
中则它就是 cls 的子类。通常只有类对象,即
type
或其派生类的实例才会被视为类。 但是,对象可以通过设置__bases__
属性(它必须是由基类组成的元组)来覆盖此定义。
-
int PyObject_IsInstance(PyObject *inst, PyObject *cls)¶
- 属于 稳定 ABI.
如果 inst 是 cls 类或其子类的实例,则返回
1
,如果不是则返回0
。 如果出错则返回-1
并设置一个异常。如果 cls 是元组,则会对 cls 进行逐项检测。如果至少有一次检测返回
1
,结果将为1
,否则将是0
。如果 cls 具有
__instancecheck__()
方法,它将被调用以确定 PEP 3119 所描述的子类状态。 在其他情况下,如果 inst 的类是 cls 的子类则它就是 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)¶
如果对象 o 是 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)
。Added in version 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
。Added in version 3.10.
-
void *PyObject_GetTypeData(PyObject *o, PyTypeObject *cls)¶
- 属于 稳定 ABI 自 3.12 版起.
获取一个指向为 cls 保留的子类专属数据的指针。
对象 o 必须为 cls 的实例,而 cls 必须使用负的
PyType_Spec.basicsize
来创建。 Python 不会检查这一点。发生错误时,将设置异常并返回
NULL
。Added in version 3.12.
-
Py_ssize_t PyType_GetTypeDataSize(PyTypeObject *cls)¶
- 属于 稳定 ABI 自 3.12 版起.
返回为 cls 保留的实例内存空间大小,即
PyObject_GetTypeData()
所返回的内存大小。这可能会大于使用
-PyType_Spec.basicsize
请求到的大小;可以安全地使用这个更大的值 (例如通过memset()
)。类型 cls 必须 使用负的
PyType_Spec.basicsize
来创建。 Python 不会检查这一点。当失败时,将设置异常并返回一个负值。
Added in version 3.12.
-
void *PyObject_GetItemData(PyObject *o)¶
使用
Py_TPFLAGS_ITEMS_AT_END
获取一个指向类的单独条目数据的指针。出错时,将设置异常并返回
NULL
。 如果 o 没有设置Py_TPFLAGS_ITEMS_AT_END
则会引发TypeError
。Added in version 3.12.
-
int PyObject_VisitManagedDict(PyObject *obj, visitproc visit, void *arg)¶
访问被管理的 obj 的字典。
此函数必须只在设置了
Py_TPFLAGS_MANAGED_DICT
旗标的类型的遍历函数中被调用。Added in version 3.13.
-
void PyObject_ClearManagedDict(PyObject *obj)¶
清空被管理的 obj 的字典。.
此函数必须只在设置了
Py_TPFLAGS_MANAGED_DICT
旗标的类型的遍历函数中被调用。Added in version 3.13.