Object Protocol

• 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)。此Function始终成功。

请注意，调用getattr()和getattribute()方法时发生的异常将被抑制。要获取错误报告，请改用PyObject_GetAttr()。

• int PyObject_HasAttrString(PyObject *o ，const char attr_name *)
  • 如果* o 具有属性 attr_name *，则返回1，否则返回0。这等效于 Python 表达式hasattr(o, attr_name)。此Function始终成功。

请注意，在调用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插槽中。它在对象的 MRO 中的类字典中查找 Descriptors，并在对象的dict(如果存在)中查找属性。如Implementing Descriptors所述，数据 Descriptors 优先于实例属性，而非数据 Descriptors 则不然。否则，将引发AttributeError。

• int PyObject_SetAttr(PyObject *o ，PyObject attr_name *，PyObject ** v *)
  • 将对象* o 的名为 attr_name 的属性的值设置为 v *的值。引发异常并在失败时返回-1；成功返回0。这等效于 Python 语句o.attr_name = v。

如果* v *为NULL，则删除该属性，但是不赞成使用此Function，而推荐使用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，则删除该属性，但是不赞成使用此Function，而推荐使用PyObject_DelAttrString()。

• int PyObject_GenericSetAttr(PyObject *o ，PyObject name *，PyObject ** value *)

  • 通用属性设置器和删除器函数，旨在将其放入类型对象的tp_setattro插槽中。它在对象的 MRO 中的类的词典中查找数据 Descriptors，如果找到该 Descriptors，则优先于设置或删除实例词典中的属性。否则，将在对象的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 *)

  • 删除对象* o 的名为 attr_name *的属性。失败时返回-1。这等效于 Python 语句del o.attr_name。

• PyObject * PyObject_GenericGetDict(PyObject o ，无效 上下文)

  • 返回值：新参考.

__dict__Descriptors 的获取程序的通用实现。如有必要，它将创建字典。

版本 3.3 中的新Function。

• int PyObject_GenericSetDict(PyObject *o ，PyObject value *，void ** context *)
  • __dict__Descriptors 的 setter 的通用实现。此实现不允许删除字典。

版本 3.3 中的新Function。

• PyObject * PyObject_RichCompare(PyObject *o1 ，PyObject o2 *，int * opid *)
  • 返回值：新参考.

使用* 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 *)
  • 使用* opid 指定的操作比较 o1 和 o2 的值，该操作必须是Py_LT，Py_LE，Py_EQ，Py_NE，Py_GT或Py_GE之一，与<，<=，==，!=，>对应或>=。错误时返回-1，如果结果为假，则返回0，否则返回1。这等效于 Python 表达式o1 op o2，其中op是与 opid *对应的运算符。

• PyObject * PyObject_Repr(PyObject ** o *)
  • 返回值：新参考.

计算对象* o *的字符串表示形式。成功返回字符串表示形式，失败返回NULL。这等效于 Python 表达式repr(o)。由repr()内置函数调用。

在版本 3.4 中进行了更改：此函数现在包括调试 assert，以帮助确保它不会静默丢弃活动异常。

• PyObject * PyObject_ASCII(PyObject ** o *)
  • 返回值：新参考.

作为PyObject_Repr()，计算对象* o *的字符串表示形式，但是使用\x，\u或\U进行转义，以转义PyObject_Repr()返回的字符串中的非 ASCII 字符。生成的字符串类似于 Python 2 中PyObject_Repr()返回的字符串。由ascii()内置函数调用。

• PyObject * PyObject_Str(PyObject ** o *)
  • 返回值：新参考.

计算对象* o *的字符串表示形式。成功返回字符串表示形式，失败返回NULL。这等效于 Python 表达式str(o)。由str()内置函数调用，因此也由print()函数调用。

在版本 3.4 中进行了更改：此函数现在包括调试 assert，以帮助确保它不会静默丢弃活动异常。

• PyObject * PyObject_Bytes(PyObject ** o *)
  • 返回值：新参考.

计算对象* o 的字节表示形式。失败返回NULL，成功返回字节对象。当 o 不是整数时，这等效于 Python 表达式bytes(o)。与bytes(o)不同，当 o *是整数而不是零初始化字节对象时，引发 TypeError。

• int PyObject_IsSubclass(PyObject 派生，PyObject* cls *)
  • 如果类* derived 与类 cls 相同或从类 cls *派生，则返回1，否则返回0。发生错误时，返回-1。

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

如果* cls 具有subclasscheck()方法，则将如 PEP 3119中所述调用它以确定子类状态。否则， derived 是 cls *的子类，如果它是直接或间接子类，即包含在cls.__mro__中。

通常仅将类对象(即type的实例或派生类)视为类。但是，对象可以pass具有__bases__属性(必须是 Base Class 的 Tuples)来覆盖此属性。

• int PyObject_IsInstance(PyObject *inst ，PyObject cls *)
  • 如果* inst 是 cls 类的实例或 cls *的子类，则返回1；否则返回0。出错时，返回-1并设置一个异常。

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

如果* cls 具有instancecheck()方法，则将如 PEP 3119中所述调用它以确定子类状态。否则，如果 inst 是 cls 的实例，则其类是 cls *的子类。

• inst *实例可以pass具有__class__属性来覆盖被视为其类的实例。

如果对象* cls *被认为是类，并且可以pass具有__bases__属性(必须是 Base Class 的 Tuples)来覆盖其 Base Class，则可以覆盖该对象。

• int PyCallable_Check(PyObject ** o *)

  • 确定对象* o *是否可调用。如果对象可调用，则返回1，否则返回0。此Function始终成功。

• PyObject * PyObject_Call(PyObject *callable ，PyObject args *，PyObject ** kwargs *)

  • 返回值：新参考.

调用可调用的 Python 对象* callable ，其参数由 Tuples args 给出，命名参数由字典 kwargs *给出。

• args 不能为NULL，如果不需要任何参数，请使用一个空的 Tuples。如果不需要命名参数，则 kwargs *可以为NULL。

成功返回调用结果，或者引发异常，失败则返回NULL。

这等效于 Python 表达式：callable(*args, **kwargs)。

• PyObject * PyObject_CallObject(PyObject *callable ，PyObject args *)
  • 返回值：新参考.

使用 Tuples* args 给出的参数调用可调用的 Python 对象 callable 。如果不需要参数，则 args *可以为NULL。

成功返回调用结果，或者引发异常，失败则返回NULL。

这等效于 Python 表达式：callable(*args)。

• PyObject * PyObject_CallFunction(PyObject *callable ，const char format *，...)
  • 返回值：新参考.

使用可变数量的 C 参数调用可调用的 Python 对象* callable *。使用Py_BuildValue()样式格式字符串描述 C 参数。格式可以为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()格式的字符串描述，该字符串应产生一个 Tuples。

格式可以为NULL，表示未提供任何参数。

成功返回调用结果，或者引发异常，失败则返回NULL。

这等效于 Python 表达式：obj.name(arg1, arg2, ...)。

请注意，如果仅传递PyObject *参数，则PyObject_CallMethodObjArgs()是更快的选择。

在版本 3.4 中更改：名称和格式的类型已从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。

• PyObject * _PyObject_Vectorcall(PyObject *callable ，PyObject * const args *，size_t * nargsf *，PyObject ** kwnames *)
  • 如果可能，使用vectorcall调用可调用的 Python 对象* callable *。

• args *是带有位置参数的 C 数组。

• nargsf *是位置参数的数量加上可选的标志PY_VECTORCALL_ARGUMENTS_OFFSET(请参见下文)。要获取实际的参数数量，请使用PyVectorcall_NARGS(nargsf)。

• kwnames 可以是NULL(无关键字参数)或关键字名称的 Tuples。在后一种情况下，关键字参数的值存储在位置参数之后的 args 中。关键字参数的数量不影响 nargsf *。

• kwnames *必须仅包含str类型的对象(而不是子类)，并且所有键都必须是唯一的。

成功返回调用结果，或者引发异常，失败则返回NULL。

如果可调用对象支持，则使用 vectorcall 协议。否则，参数将转换为使用tp_call。

3.8 版的新Function。

• PY_VECTORCALL_ARGUMENTS_OFFSET
  • 如果在 vectorcall * nargsf 参数中设置，则允许被叫方临时更改args[-1]。换句话说， args *指向分配的向量中的参数 1(不是 0)。被呼叫者必须在返回之前恢复args[-1]的值。

只要他们能便宜地做到这一点(无需额外分配)，就会鼓励呼叫者使用PY_VECTORCALL_ARGUMENTS_OFFSET。这样做将允许诸如绑定方法之类的可调用对象廉价地进行其后续调用(包括前置* self *参数)。

3.8 版的新Function。

• Py_ssize_t PyVectorcall_NARGS(size_t * nargsf *)
  • 给定一个 vectorcall * nargsf *参数，返回参数的实际数量。目前相当于nargsf & ~PY_VECTORCALL_ARGUMENTS_OFFSET。

3.8 版的新Function。

• PyObject * _PyObject_FastCallDict(PyObject *callable ，PyObject * const args *，size_t * nargsf *，PyObject ** kwdict *)
  • 与_PyObject_Vectorcall()相同，除了关键字参数在* kwdict *中作为字典传递。如果没有关键字参数，则可能是NULL。

对于支持vectorcall的可调用对象，参数在内部转换为 vectorcall 约定。因此，与_PyObject_Vectorcall()相比，此函数会增加一些开销。仅当调用者已经有可用的字典时才应使用它。

3.8 版的新Function。

• 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 *被认为是 true，则返回1，否则返回0。这等效于 Python 表达式not not o。失败时，返回-1。

• int PyObject_Not(PyObject ** o *)

  • 如果对象* o *被认为是 true，则返回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 是 type 类型或 type *的子类型，则返回 true。这两个参数都不能为NULL。

• Py_ssize_t PyObject_Size(PyObject ** o *)

• Py_ssize_t PyObject_Length(PyObject ** o *)

  • 返回对象的长度* o 。如果对象 o *提供序列和 Map 协议，则返回序列长度。错误时，返回-1。这等效于 Python 表达式len(o)。

• Py_ssize_t PyObject_LengthHint(PyObject ** o *，Py_ssize_t * default *)
  • 返回对象* o *的估计长度。首先try返回其实际长度，然后使用length_hint()进行估算，最后返回默认值。错误返回-1。这等效于 Python 表达式operator.length_hint(o, default)。

3.4 版的新Function。

• PyObject * PyObject_GetItem(PyObject o ，PyObject 键)
  • 返回值：新参考.

失败时返回与对象* key 或NULL对应的 o *元素。这等效于 Python 表达式o[key]。

• int PyObject_SetItem(PyObject *o ，PyObject key *，PyObject ** v *)

  • 将对象* key Map 到值 v 。引发异常并在失败时返回-1；成功返回0。这等效于 Python 语句o[key] = v。该Function不会窃取 v *的引用。

• int PyObject_DelItem(PyObject *o ，PyObject key *)

  • 从对象* o 中删除对象 key *的 Map。失败返回-1。这等效于 Python 语句del o[key]。

• PyObject * PyObject_Dir(PyObject ** o *)

  • 返回值：新参考.

这等效于 Python 表达式dir(o)，返回适合对象参数的字符串列表(可能为空)，如果有错误，则返回NULL。如果参数为NULL，则类似于 Python dir()，返回当前本地名称。在这种情况下，如果没有执行框架处于活动状态，则返回NULL，但是PyErr_Occurred()将返回 false。

• PyObject * PyObject_GetIter(PyObject ** o *)
  • 返回值：新参考.

这等效于 Python 表达式iter(o)。它为对象参数返回一个新的迭代器，如果对象已经是一个迭代器，则返回对象本身。如果无法迭代该对象，则引发TypeError并返回NULL。