Type Objects¶

也许Python对象系统最重要的结构之一是定义一个新类型的结构：PyTypeObject结构。类型对象可以使用PyObject_*()或PyType_*()函数来处理，但不能提供大多数Python应用程序很有趣的东西。这些对象是对象行为的基础，因此对于解释器本身和实现新类型的任何扩展模块都非常重要。

与大多数标准类型相比，类型对象相当大。大小的原因是每个类型对象存储大量的值，主要是C函数指针，每个函数指针实现类型功能的一小部分。在本节中详细检查类型对象的字段。将按照它们在结构中出现的顺序来描述字段。

typedefs：unaryfunc，binaryfunc，ternaryfunc，inquiry，intargfunc，intintargfunc，intobjargproc，intintobjargproc，objobjargproc，destructor，freefunc，printfunc，getattrfunc，getattrofunc，setattrfunc，setattrofunc，reprfunc，hashfunc

PyTypeObject的结构定义可以在Include/object.h中找到。为了方便参考，这里重复的定义：

typedef struct _typeobject {
    PyObject_VAR_HEAD
    const char *tp_name; /* For printing, in format "<module>.<name>" */
    Py_ssize_t tp_basicsize, tp_itemsize; /* For allocation */

    /* Methods to implement standard operations */

    destructor tp_dealloc;
    printfunc tp_print;
    getattrfunc tp_getattr;
    setattrfunc tp_setattr;
    PyAsyncMethods *tp_as_async; /* formerly known as tp_compare (Python 2)
                                    or tp_reserved (Python 3) */
    reprfunc tp_repr;

    /* Method suites for standard classes */

    PyNumberMethods *tp_as_number;
    PySequenceMethods *tp_as_sequence;
    PyMappingMethods *tp_as_mapping;

    /* More standard operations (here for binary compatibility) */

    hashfunc tp_hash;
    ternaryfunc tp_call;
    reprfunc tp_str;
    getattrofunc tp_getattro;
    setattrofunc tp_setattro;

    /* Functions to access object as input/output buffer */
    PyBufferProcs *tp_as_buffer;

    /* Flags to define presence of optional/expanded features */
    unsigned long tp_flags;

    const char *tp_doc; /* Documentation string */

    /* call function for all accessible objects */
    traverseproc tp_traverse;

    /* delete references to contained objects */
    inquiry tp_clear;

    /* rich comparisons */
    richcmpfunc tp_richcompare;

    /* weak reference enabler */
    Py_ssize_t tp_weaklistoffset;

    /* Iterators */
    getiterfunc tp_iter;
    iternextfunc tp_iternext;

    /* Attribute descriptor and subclassing stuff */
    struct PyMethodDef *tp_methods;
    struct PyMemberDef *tp_members;
    struct PyGetSetDef *tp_getset;
    struct _typeobject *tp_base;
    PyObject *tp_dict;
    descrgetfunc tp_descr_get;
    descrsetfunc tp_descr_set;
    Py_ssize_t tp_dictoffset;
    initproc tp_init;
    allocfunc tp_alloc;
    newfunc tp_new;
    freefunc tp_free; /* Low-level free-memory routine */
    inquiry tp_is_gc; /* For PyObject_IS_GC */
    PyObject *tp_bases;
    PyObject *tp_mro; /* method resolution order */
    PyObject *tp_cache;
    PyObject *tp_subclasses;
    PyObject *tp_weaklist;
    destructor tp_del;

    /* Type attribute cache version tag. Added in version 2.6 */
    unsigned int tp_version_tag;

    destructor tp_finalize;

} PyTypeObject;

类型对象结构扩展了PyVarObject结构。ob_size字段用于动态类型（由type_new()创建，通常从类语句调用）。注意，PyType_Type（元类型）初始化tp_itemsize，这意味着它的实例类型对象）必须具有ob_size字段。

PyObject* PyObject._ob_next¶

PyObject* PyObject._ob_prev¶

这些字段仅在定义宏Py_TRACE_REFS时存在。它们对NULL的初始化由PyObject_HEAD_INIT宏来处理。对于静态分配的对象，这些字段始终保持NULL。对于动态分配的对象，这两个字段用于将对象链接到堆上的所有活对象的双向链表中。这可以用于各种调试目的；目前唯一的用途是在设置环境变量 PYTHONDUMPREFS时，打印运行结束时仍然存在的对象。

这些字段不会由子类型继承。

Py_ssize_t PyObject.ob_refcnt¶

这是类型对象的引用计数，由PyObject_HEAD_INIT宏初始化为1。请注意，对于静态分配类型对象，类型的实例（ob_type指向类型的对象）不计为引用。但对于动态分配的类型对象，实例do计为引用。

此字段不由子类型继承。

PyTypeObject* PyObject.ob_type¶

这是类型的类型，换句话说它的元类型。它由PyObject_HEAD_INIT宏的参数初始化，其值通常应为&PyType_Type。然而，对于必须在Windows上可用的动态可加载扩展模块（至少），编译器会声明这不是有效的初始化程序。因此，约定是将NULL传递给PyObject_HEAD_INIT宏，并在执行任何其他操作之前在模块初始化函数的开始处显式初始化此字段。这通常这样做：

Foo_Type.ob_type = &PyType_Type;

这应该在创建类型的任何实例之前完成。PyType_Ready()检查ob_type是否NULL，如果是，将其初始化为基础的ob_type类。PyType_Ready()不会更改此字段（如果它不为零）。

此字段由子类继承。

Py_ssize_t PyVarObject.ob_size¶

对于静态分配类型对象，应将其初始化为零。对于动态分配的类型对象，此字段具有特殊的内部含义。

此字段不由子类型继承。

const char* PyTypeObject.tp_name¶

指向包含类型名称的NUL终止字符串。对于可作为模块全局变量访问的类型，字符串应为完整的模块名称，后跟一个点，后跟类型名称；对于内建类型，它应该只是类型名称。如果模块是包的子模块，则完整包名称是完整模块名称的一部分。For example, a type named T defined in module M in subpackage Q in package P should have the tp_name initializer "P.Q.M.T".

对于动态分配的类型对象，这应该只是类型名称，并且模块名称显式存储在类型dict中作为键'__module__'的值。

对于静态分配的类型对象，tp_name字段应包含一个点。最后一个点之前的所有内容都可以作为__module__属性访问，并且最后一个点之后的所有内容都可以作为__name__属性访问。

如果没有点，则整个tp_name字段可作为__name__属性访问，并且__module__属性未定义（除非明确设置字典，如上所述）。这意味着你的类型不可能泡菜。

此字段不由子类型继承。

Py_ssize_t PyTypeObject.tp_basicsize¶

Py_ssize_t PyTypeObject.tp_itemsize¶

这些字段允许计算类型的实例的大小（以字节为单位）。

有两种类型：具有固定长度实例的类型具有零个tp_itemsize字段，具有可变长度实例的类型具有非零的tp_itemsize字段。对于具有固定长度实例的类型，所有实例具有相同的大小，在tp_basicsize中给出。

对于具有可变长度实例的类型，实例必须具有ob_size字段，实例大小为tp_basicsize加N次tp_itemsize N是对象的“长度”。N的值通常存储在实例的ob_size字段中。有例外：例如，ints使用负值ob_size来表示负数，N是abs(ob_size)。此外，在实例布局中存在ob_size字段并不意味着实例结构是可变长度的（例如，列表类型的结构具有固定长度的实例，但是这些实例具有有意义的ob_size字段）。

基本大小包括由宏PyObject_HEAD或PyObject_VAR_HEAD（无论用于声明实例结构）声明的实例中的字段，而这又包括_ob_prev和_ob_next字段（如果它们存在）。这意味着，为tp_basicsize获取初始化器的唯一正确方法是在用于声明实例布局的结构上使用sizeof操作符号。基本大小不包括GC标头大小。

这些字段由子类型单独继承。如果基类型具有非零tp_itemsize，则通常不太可能将tp_itemsize设置为子类型中的不同的非零值（尽管这取决于实现的基础类型）。

关于对齐的注释：如果变量项需要特定的对齐，则应该通过tp_basicsize的值来处理。示例：假设一个类型实现double的数组。tp_itemsize是sizeof(double)。这是程序员的责任，tp_basicsize是sizeof(double)的倍数（假设这是double的对齐要求）。

destructor PyTypeObject.tp_dealloc¶

指向实例析构函数的指针。除非该类型保证其实例不会被释放（如单例None和Ellipsis的情况），否则必须定义此函数。

当新的引用计数为零时，析构函数由Py_DECREF()和Py_XDECREF()宏调用。在这一点上，实例仍然存在，但没有提到它。析构函数应释放实例拥有的所有引用，释放实例所拥有的所有内存缓冲区（使用与用于分配缓冲区的分配函数相对应的释放函数），最后（作为其最后一个动作）调用类型的tp_free函数。如果类型不是子类型（未设置Py_TPFLAGS_BASETYPE标志位），则允许直接调用对象取消分配器，而不是通过tp_free。The object deallocator should be the one used to allocate the instance; this is normally PyObject_Del() if the instance was allocated using PyObject_New() or PyObject_VarNew(), or PyObject_GC_Del() if the instance was allocated using PyObject_GC_New() or PyObject_GC_NewVar().

此字段由子类继承。

printfunc PyTypeObject.tp_print¶: 保留槽，以前用于Python 2.x中的打印格式。

getattrfunc PyTypeObject.tp_getattr¶

指向get-attribute-string函数的可选指针。

此字段已弃用。当定义它时，它应该指向一个与tp_getattro函数相同的函数，但是使用C字符串而不是Python字符串对象来给出属性名称。声明与PyObject_GetAttrString()相同。

This field is inherited by subtypes together with tp_getattro: a subtype inherits both tp_getattr and tp_getattro from its base type when the subtype’s tp_getattr and tp_getattro are both NULL.

setattrfunc PyTypeObject.tp_setattr¶

用于设置和删除属性的函数的可选指针。

此字段已弃用。当定义它时，它应该指向一个与tp_setattro函数相同的函数，但是使用C字符串而不是Python字符串对象来给出属性名称。声明与PyObject_SetAttrString()相同，但必须支持将v设置为NULL以删除属性。

This field is inherited by subtypes together with tp_setattro: a subtype inherits both tp_setattr and tp_setattro from its base type when the subtype’s tp_setattr and tp_setattro are both NULL.

PyAsyncMethods* tp_as_async¶: 指向包含仅与在C级别实现awaitable和asynchronous iterator协议的对象相关的字段的附加结构的指针。有关详细信息，请参见Async Object Structures。
版本3.5中的新功能：以前称为tp_compare和tp_reserved。

reprfunc PyTypeObject.tp_repr¶

指向实现内建函数repr()的函数的可选指针。

声明与PyObject_Repr()相同；它必须返回一个字符串或Unicode对象。理想情况下，此函数应返回一个字符串，当传递给eval()时，给定一个合适的环境，返回一个具有相同值的对象。如果这不可行，它应该返回一个以'<'开头，以'>'结尾的字符串，从中可以得到对象的类型和值推断。

When this field is not set, a string of the form <%s object at %p> is returned, where %s is replaced by the type name, and %p by the object’s memory address.

此字段由子类继承。

PyNumberMethods* tp_as_number¶

指向包含仅与实现数字协议的对象相关的字段的附加结构的指针。这些字段记录在Number Object Structures中。

tp_as_number字段不会继承，但包含的字段会单独继承。

PySequenceMethods* tp_as_sequence¶

指向包含仅与实现序列协议的对象相关的字段的附加结构的指针。这些字段记录在Sequence Object Structures中。

tp_as_sequence字段未被继承，但包含的字段单独继承。

PyMappingMethods* tp_as_mapping¶

指向包含仅与实现映射协议的对象相关的字段的附加结构的指针。这些字段记录在Mapping Object Structures中。

不继承tp_as_mapping字段，但包含的字段单独继承。

hashfunc PyTypeObject.tp_hash¶

指向实现内建函数hash()的函数的可选指针。

声明与PyObject_Hash()相同；它必须返回一个类型Py_hash_t的值。值-1不应作为正常返回值返回；当在计算散列值期间发生错误时，函数应设置异常并返回-1。

此字段可以显式设置为PyObject_HashNotImplemented()，以阻止父类型的哈希方法的继承。这被解释为在Python级别的__哈希__ = 无，导致isinstance（o，容器.Hashable）可以正确返回False。请注意，反之亦然 - 在Python级别设置__哈希__ = 无将tp_hash插槽设置为PyObject_HashNotImplemented()。

当未设置此字段时，尝试获取对象的散列引发TypeError。

This field is inherited by subtypes together with tp_richcompare: a subtype inherits both of tp_richcompare and tp_hash, when the subtype’s tp_richcompare and tp_hash are both NULL.

ternaryfunc PyTypeObject.tp_call¶

指向实现调用对象的函数的可选指针。如果对象不可调用，则应为NULL。声明与PyObject_Call()相同。

此字段由子类继承。

reprfunc PyTypeObject.tp_str¶

指向实现内建操作str()的函数的可选指针。（注意str现在是一个类型，str()调用该类型的构造函数。这个构造函数调用PyObject_Str()来做实际工作，而PyObject_Str()会调用这个处理器。

声明与PyObject_Str()相同；它必须返回一个字符串或Unicode对象。此函数应返回对象的“友好”字符串表示形式，因为这是将通过print()函数使用的表示形式。

当未设置此字段时，调用PyObject_Repr()以返回字符串表示形式。

此字段由子类继承。

getattrofunc PyTypeObject.tp_getattro¶

一个指向get-attribute函数的可选指针。

声明与PyObject_GetAttr()相同。将此字段设置为PyObject_GenericGetAttr()通常很方便，它实现了查找对象属性的常规方法。

This field is inherited by subtypes together with tp_getattr: a subtype inherits both tp_getattr and tp_getattro from its base type when the subtype’s tp_getattr and tp_getattro are both NULL.

setattrofunc PyTypeObject.tp_setattro¶

用于设置和删除属性的函数的可选指针。

声明与PyObject_SetAttr()相同，但必须支持将v设置为NULL以删除属性。将此字段设置为PyObject_GenericSetAttr()通常很方便，它实现了设置对象属性的常规方法。

This field is inherited by subtypes together with tp_setattr: a subtype inherits both tp_setattr and tp_setattro from its base type when the subtype’s tp_setattr and tp_setattro are both NULL.

PyBufferProcs* PyTypeObject.tp_as_buffer¶

指向包含仅与实现缓冲区接口的对象相关的字段的附加结构的指针。这些字段记录在Buffer Object Structures中。

不继承tp_as_buffer字段，但包含的字段单独继承。

unsigned long PyTypeObject.tp_flags¶

该字段是各种标志的位掩码。一些标志表示某些情况下的变量语义；其他用于指示类型对象中的某些字段（或在通过tp_as_number，tp_as_sequence，tp_as_mapping和tp_as_buffer）是有效的；如果这样的标志位是清除的，则它不能访问的保护类型字段必须被认为具有零或NULL值。

这个领域的继承是复杂的。大多数标志位是单独继承的，即如果基本类型具有设置的标志位，则子类型继承此标志位。如果扩展结构被继承，则关于扩展结构的标志位被严格地继承，即将标志位的基本类型的值与指向扩展结构的指针一起复制到子类型中。Py_TPFLAGS_HAVE_GC标志位与tp_traverse和tp_clear字段一起继承，即如果子类型中的Py_TPFLAGS_HAVE_GC标志位清零，并且子类型中的tp_traverse和tp_clear字段存在且NULL t9 >值。

以下位掩码当前已定义；这些可以使用|操作符号进行OR运算以形成tp_flags字段的值。宏PyType_HasFeature()采用类型和标志值tp和f，并检查tp-> ； tp_flags ＆amp； f不为零。

Py_TPFLAGS_HEAPTYPE¶: 当类型对象本身在堆上分配时，该位置位。在这种情况下，它的实例的ob_type字段被认为是对类型的引用，并且当创建新实例时，类型对象被INCREF'，并在实例被销毁时被DECREF这不适用于子类型的实例；只有实例的ob_type引用的类型获得INCREF'ed或DECREF'）。

Py_TPFLAGS_BASETYPE¶: 当该类型可以用作另一类型的基本类型时，该位置位。如果该位清零，则不能对类型进行子类型化（类似于Java中的“final”类）。

Py_TPFLAGS_READY¶: 当类型对象由PyType_Ready()完全初始化时，该位置1。

Py_TPFLAGS_READYING¶: 在PyType_Ready()正在初始化类型对象的过程中，该位置位。

Py_TPFLAGS_HAVE_GC¶: 当对象支持垃圾容器时，该位置位。如果设置此位，则必须使用PyObject_GC_New()创建实例，并使用PyObject_GC_Del()来销毁实例。有关详细信息，请参见Supporting Cyclic Garbage Collection。该位还意味着在类型对象中存在GC相关字段tp_traverse和tp_clear。

Py_TPFLAGS_DEFAULT¶: 这是与类型对象及其扩展结构中某些字段的存在相关的所有位的位掩码。目前，它包括以下位：Py_TPFLAGS_HAVE_STACKLESS_EXTENSION，Py_TPFLAGS_HAVE_VERSION_TAG。

Py_TPFLAGS_LONG_SUBCLASS¶

Py_TPFLAGS_LIST_SUBCLASS¶

Py_TPFLAGS_TUPLE_SUBCLASS¶

Py_TPFLAGS_BYTES_SUBCLASS¶

Py_TPFLAGS_UNICODE_SUBCLASS¶

Py_TPFLAGS_DICT_SUBCLASS¶

Py_TPFLAGS_BASE_EXC_SUBCLASS¶

Py_TPFLAGS_TYPE_SUBCLASS¶: 这些标志由诸如PyLong_Check()的函数使用，以快速确定类型是否是内建类型的子类；这种特定检查比通用检查更快，例如PyObject_IsInstance()。从内置函数继承的自定义类型应正确设置其tp_flags，或者与这些类型交互的代码将根据使用的检查类型而有所不同。

Py_TPFLAGS_HAVE_FINALIZE¶: 当tp_finalize插槽存在于类型结构中时，该位置1。
版本3.4中的新功能。

const char* PyTypeObject.tp_doc¶

一个可选的指向NUL终止的C字符串的指针，给出这个类型对象的docstring。这将作为类型和类型的实例的__doc__属性公开。

此字段为而不是由子类继承。

traverseproc PyTypeObject.tp_traverse¶

指向垃圾收集器的遍历函数的可选指针。这仅在Py_TPFLAGS_HAVE_GC标志位置1时使用。有关Python的垃圾容器方案的更多信息，请参见Supporting Cyclic Garbage Collection一节。

tp_traverse指针被垃圾收集器用来检测参考周期。tp_traverse函数的典型实现只是调用每个作为Python对象的实例成员的Py_VISIT()。例如，这是来自_thread扩展模块的函数local_traverse()：

static int
local_traverse(localobject *self, visitproc visit, void *arg)
{
    Py_VISIT(self->args);
    Py_VISIT(self->kw);
    Py_VISIT(self->dict);
    return 0;
}

请注意，Py_VISIT()仅在可以参与参考循环的成员上调用。虽然还有一个self->key成员，但它只能是NULL或一个Python字符串，因此不能作为参考周期的一部分。

另一方面，即使你知道一个成员永远不能成为一个循环的一部分，作为一个调试助手，你可能想访问它，无论如何只是因为gc模块的get_referents()

请注意，Py_VISIT()需要访问和arg参数到local_traverse()

此字段由子类型与tp_clear和Py_TPFLAGS_HAVE_GC标志位一起继承：标志位tp_traverse和tp_clear

inquiry PyTypeObject.tp_clear¶

一个指向垃圾回收器清除函数的可选指针。这仅在Py_TPFLAGS_HAVE_GC标志位置1时使用。

tp_clear成员函数用于中断垃圾回收器检测到的循环垃圾中的参考循环。总之，系统中的所有tp_clear功能必须组合以中断所有参考周期。这是微妙的，如果在任何疑问提供tp_clear函数。例如，元组类型不实现tp_clear函数，因为可以证明没有参考循环可以完全由元组组成。因此，其他类型的tp_clear函数必须足以断开包含元组的任何循环。这不是立即显而易见的，很少有很好的理由避免实现tp_clear。

tp_clear的实现应该删除实例对其可能是Python对象的成员的引用，并将其指向这些成员的指针设置为NULL，如以下示例所示：

static int
local_clear(localobject *self)
{
    Py_CLEAR(self->key);
    Py_CLEAR(self->args);
    Py_CLEAR(self->kw);
    Py_CLEAR(self->dict);
    return 0;
}

应该使用Py_CLEAR()宏，因为清除引用是微妙的：对包含对象的引用不能递减，直到包含对象的指针设置为NULL t3 >。这是因为减少引用计数可能导致包含的对象变成垃圾，触发回收链活动，可能包括调用任意Python代码（由于finalizers或weakref回调，与包含的对象相关联）。如果这样的代码可能再次引用self，那么重要的是指向包含的对象的指针是NULL，那么self知道包含的对象不能再被使用。Py_CLEAR()宏以安全顺序执行操作。

因为tp_clear函数的目标是中断引用循环，因此不必清除包含的对象，如Python字符串或Python整数，这些对象不能参与循环。另一方面，可以方便地清除所有包含的Python对象，并编写类型的tp_dealloc函数来调用tp_clear。

有关Python的垃圾容器方案的更多信息，请参见Supporting Cyclic Garbage Collection一节。

此字段由子类型与tp_traverse和Py_TPFLAGS_HAVE_GC标志位一起继承：标志位tp_traverse和tp_clear

richcmpfunc PyTypeObject.tp_richcompare¶

指向丰富比较函数的可选指针，其声明为PyObject * tp_richcompare（PyObject * a， t4> * b， int op）第一个参数被保证为由PyTypeObject定义的类型的实例。

函数应该返回比较结果（通常Py_True或Py_False）。如果比较未定义，则必须返回Py_NotImplemented，如果出现另一个错误，则必须返回NULL并设置异常条件。

注意

如果你想实现一种类型，只有有限的一组比较是有意义的（例如。==和!=，但不是<和朋友），直接在富比较函数中引用TypeError 。

This field is inherited by subtypes together with tp_hash: a subtype inherits tp_richcompare and tp_hash when the subtype’s tp_richcompare and tp_hash are both NULL.

以下常量被定义为用作tp_richcompare和PyObject_RichCompare()的第三个参数：

不变	比较
`Py_LT`	`<`
`Py_LE`	`<=`
`Py_EQ`	`==`
`Py_NE`	`!=`
`Py_GT`	`>`
`Py_GE`	`>=`

Py_ssize_t PyTypeObject.tp_weaklistoffset¶

如果此类型的实例是弱引用的，则此字段大于零，并且包含弱引用列表头的实例结构中的偏移量（忽略GC标题（如果存在））；此偏移由PyObject_ClearWeakRefs()和PyWeakref_*()函数使用。实例结构需要包括PyObject*类型的字段，该字段初始化为NULL。

不要将此字段与tp_weaklist相混淆；这是对类型对象本身的弱引用的列表头。

此字段由子类型继承，但请参阅下面列出的规则。子类型可以覆盖此偏移；这意味着子类型使用与基本类型不同的弱引用列表头。由于列表头总是通过tp_weaklistoffset找到，这不应该是一个问题。

当由类语句定义的类型没有__slots__声明，并且它的基类型都不是弱引用时，通过在实例布局中添加一个弱引用列表头部空格，该时隙偏移的tp_weaklistoffset。

当类型的__slots__声明包含名为__weakref__的插槽时，该插槽将成为类型实例的弱引用列表头，插槽的偏移存储在类型的tp_weaklistoffset。

当类型的__slots__声明不包含名为__weakref__的插槽时，类型从其基本类型继承其tp_weaklistoffset。

getiterfunc PyTypeObject.tp_iter¶

指向返回对象的迭代器的函数的可选指针。它的存在通常表示这种类型的实例是可迭代的（尽管在没有这个函数的情况下序列可以是可迭代的）。

此函数具有与PyObject_GetIter()相同的声明。

此字段由子类继承。

iternextfunc PyTypeObject.tp_iternext¶

指向一个函数的可选指针，该函数返回迭代器中的下一个项。当迭代器耗尽时，它必须返回NULL；可以或可以不设置StopIteration异常。当发生另一个错误时，它也必须返回NULL。它的存在表示这种类型的实例是迭代器。

迭代器类型也应该定义tp_iter函数，该函数应该返回迭代器实例本身（不是一个新的迭代器实例）。

此函数具有与PyIter_Next()相同的声明。

此字段由子类继承。

struct PyMethodDef* PyTypeObject.tp_methods¶

指向PyMethodDef结构的静态NULL终止数组的可选指针，声明此类型的常规方法。

对于数组中的每个条目，将一个条目添加到类型的字典（参见下面的tp_dict），其中包含方法描述器。

此字段不由子类继承（方法通过不同的机制继承）。

struct PyMemberDef* PyTypeObject.tp_members¶

指向PyMemberDef结构的静态NULL终止数组的可选指针，声明此类型实例的常规数据成员（字段或槽）。

对于数组中的每个条目，会在类型的字典（见下面的tp_dict）中添加一个条目，其中包含一个成员描述器。

此字段不由子类继承（成员通过不同的机制继承）。

struct PyGetSetDef* PyTypeObject.tp_getset¶

指向PyGetSetDef结构的静态NULL终止数组的可选指针，声明此类型实例的计算属性。

对于数组中的每个条目，将一个条目添加到类型的字典（参见下面的tp_dict），其中包含getset描述器。

此字段不由子类继承（计算的属性通过不同的机制继承）。

PyGetSetDef的文档：

typedef PyObject *(*getter)(PyObject *, void *);
typedef int (*setter)(PyObject *, PyObject *, void *);

typedef struct PyGetSetDef {
    char *name;    /* attribute name */
    getter get;    /* C function to get the attribute */
    setter set;    /* C function to set or delete the attribute */
    char *doc;     /* optional doc string */
    void *closure; /* optional additional data for getter and setter */
} PyGetSetDef;

PyTypeObject* PyTypeObject.tp_base¶

指向继承类型属性的基本类型的可选指针。在这个级别，只支持单继承；多重继承需要通过调用元类型动态创建一个类型对象。

该字段不是子类型继承的（显然），但默认为&PyBaseObject_Type（对于Python程序员来说，它被称为类型object）。

PyObject* PyTypeObject.tp_dict¶

类型的字典存储在PyType_Ready()。

在调用PyType_Ready之前，该字段通常应该初始化为NULL；它也可以被初始化为包含该类型的初始属性的字典。一旦PyType_Ready()初始化了类型，只有当类型的额外属性不对应于重载操作（例如__add__()时）。

此字段不是由子类型继承的（虽然此处定义的属性是通过不同的机制继承的）。

警告

使用字典C-API不能安全地使用PyDict_SetItem()或修改tp_dict。

descrgetfunc PyTypeObject.tp_descr_get¶

指向“描述器获取”函数的可选指针。

声明的功能是

PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);

此字段由子类继承。

descrsetfunc PyTypeObject.tp_descr_set¶

用于设置和删除描述器值的函数的可选指针。

声明的功能是

int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);

值参数设置为NULL以删除该值。此字段由子类继承。

Py_ssize_t PyTypeObject.tp_dictoffset¶

如果此类型的实例具有包含实例变量的字典，则此字段为非零，并且包含实例变量字典类型实例中的偏移量；此偏移由PyObject_GenericGetAttr()使用。

不要将此字段与tp_dict相混淆；这是类型对象本身的属性的字典。

如果此字段的值大于零，它指定从实例结构开始的偏移量。如果值小于零，它指定与实例结构的end的偏移量。负偏移使用起来更昂贵，并且应该只在实例结构包含可变长度部分时使用。这用于例如将实例变量字典添加到str或tuple的子类型。请注意，即使字典未包含在基本对象布局中，tp_basicsize字段也应考虑在该情况下添加到字典末尾的字典。在指针大小为4字节的系统上，应将tp_dictoffset设置为-4，以指示字典位于结构的最末端。

实例中的实际字典偏移可以从负的tp_dictoffset计算如下：

dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset
if dictoffset is not aligned on sizeof(void*):
    round up to sizeof(void*)

其中tp_basicsize，tp_itemsize和tp_dictoffset取自类型对象，ob_size取自实例。采用绝对值是因为int使用ob_size的符号来存储数字的符号。（从来不需要自己做这个计算；它是由_PyObject_GetDictPtr()来完成的。）

此字段由子类型继承，但请参阅下面列出的规则。子类型可以覆盖此偏移；这意味着子类型实例以与基本类型的差异偏移存储字典。因为字典总是通过tp_dictoffset找到，这不应该是一个问题。

当由类语句定义的类型没有__slots__声明，并且它的基本类型都没有实例变量字典时，字典槽添加到实例布局和tp_dictoffset

当由类语句定义的类型具有__slots__声明时，类型从其基类型继承其tp_dictoffset。

（在__slots__声明中添加名为__dict__的插槽没有预期的效果，只会导致混乱。也许这应该添加为一个功能，就像__weakref__虽然。）

initproc PyTypeObject.tp_init¶

一个指向实例初始化函数的可选指针。

此函数对应于类的__init__()方法。像__init__()，可以创建一个实例而不调用__init__()，并且可以通过调用__init__()

声明的功能是

int tp_init(PyObject *self, PyObject *args, PyObject *kwds)

自变量是要初始化的实例； args和kwds参数表示对__init__()的调用的位置和关键字参数。

在类型的tp_new函数返回之后，通过调用其类型正常创建实例时，会调用tp_init函数（如果不是NULL实例的类型。如果tp_new函数返回不是原始类型的子类型的某个其他类型的实例，则不调用tp_init函数；如果tp_new返回原始类型的子类型的实例，则调用子类型的tp_init。

此字段由子类继承。

allocfunc PyTypeObject.tp_alloc¶

指向实例分配函数的可选指针。

声明的功能是

PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems)

此函数的目的是将内存分配与内存初始化分离。它应该返回一个指向实例适当长度的存储器的指针，适当对齐并初始化为零，但ob_refcnt设置为1和ob_type设置为类型参数。If the type’s tp_itemsize is non-zero, the object’s ob_size field should be initialized to nitems and the length of the allocated memory block should be tp_basicsize + nitems*tp_itemsize, rounded up to a multiple of sizeof(void*); otherwise, nitems is not used and the length of the block should be tp_basicsize.

不要使用此函数做任何其他实例初始化，甚至不分配额外的内存；这应该由tp_new来完成。

此字段由静态子类型继承，但不由动态子类型（由类语句创建的子类型）继承；在后者中，该字段总是设置为PyType_GenericAlloc()，以强制执行标准堆分配策略。这也是静态定义类型的建议值。

newfunc PyTypeObject.tp_new¶

指向实例创建函数的可选指针。

如果对于特定类型，此函数为NULL，则不能调用该类型来创建新实例；可能有一些其他方法来创建实例，如工厂函数。

声明的功能是

PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds)

subtype参数是正在创建的对象的类型； args和kwds参数表示对类型的调用的位置和关键字参数。注意，子类型不必等于调用tp_new函数的类型；它可以是该类型的子类型（但不是无关类型）。

tp_new函数应调用subtype-> tp_alloc（subtype， nitems）然后只做绝对必要的进一步初始化。可以安全忽略或重复的初始化应放置在tp_init处理程序中。一个好的经验法则是，对于不可变类型，所有初始化应该发生在tp_new，而对于可变类型，大多数初始化应该延迟到tp_init。

此字段由子类继承，但它不是由tp_base为NULL或&PyBaseObject_Type的静态类型继承的字段。

destructor PyTypeObject.tp_free¶

指向实例释放功能的可选指针。其声明为freefunc：

void tp_free(void *)

与此声明兼容的初始化程序为PyObject_Free()。

此字段由静态子类型继承，但不由动态子类型（由类语句创建的子类型）继承；在后者中，该字段被设置为适于匹配PyType_GenericAlloc()和Py_TPFLAGS_HAVE_GC标志位的值的解除分配器。

inquiry PyTypeObject.tp_is_gc¶

指向由垃圾回收器调用的函数的可选指针。

垃圾收集器需要知道特定对象是否是可收集的。通常，查看对象类型的tp_flags字段并检查Py_TPFLAGS_HAVE_GC标志位就足够了。但是一些类型具有静态和动态分配的实例的混合，并且静态分配的实例是不可收集的。这种类型应该定义这个函数；对于不可收回的实例，应返回1，对于不可收回的实例，应返回0。声明是

int tp_is_gc(PyObject *self)

（唯一的例子是类型本身。元类型PyType_Type定义了此函数以区分静态和动态分配的类型。）

此字段由子类继承。

PyObject* PyTypeObject.tp_bases¶

基本类型的元组。

这是为由类语句创建的类型设置的。对于静态定义的类型，应为NULL。

此字段不会继承。

PyObject* PyTypeObject.tp_mro¶

Tuple包含扩展的基本类型集，以类型本身开始，以方法解析顺序中的object结尾。

此字段不是继承的；它由PyType_Ready()新鲜计算。

destructor PyTypeObject.tp_finalize¶

指向实例最终化函数的可选指针。其声明为destructor：

void tp_finalize(PyObject *)

如果设置tp_finalize，解释器在最终确定实例时调用它一次。它从垃圾收集器（如果实例是一个孤立的引用循环的一部分）或在对象被释放之前调用。无论哪种方式，它都保证在尝试中断引用循环之前被调用，确保它找到处于正常状态的对象。

tp_finalize不应突变当前异常状态；因此，编写一个非平凡终结器的推荐方法是：

static void
local_finalize(PyObject *self)
{
    PyObject *error_type, *error_value, *error_traceback;

    /* Save the current exception, if any. */
    PyErr_Fetch(&error_type, &error_value, &error_traceback);

    /* ... */

    /* Restore the saved exception. */
    PyErr_Restore(error_type, error_value, error_traceback);
}

要考虑此字段（即使通过继承），还必须设置Py_TPFLAGS_HAVE_FINALIZE标志位。

此字段由子类继承。

版本3.4中的新功能。

也可以看看

“安全对象完成”（ PEP 442）

PyObject* PyTypeObject.tp_cache¶: 没用过。不继承。仅供内部使用。

PyObject* PyTypeObject.tp_subclasses¶: 弱引用子类列表。不继承。仅供内部使用。

PyObject* PyTypeObject.tp_weaklist¶: 弱引用列表头，用于弱引用此类型对象。不继承。仅供内部使用。

其余字段仅在定义了功能测试宏COUNT_ALLOCS时才定义，仅供内部使用。为了完整性，这里记录它们。这些字段都不会被子类型继承。

Py_ssize_t PyTypeObject.tp_allocs¶: 分配数。

Py_ssize_t PyTypeObject.tp_frees¶: 释放次数。

Py_ssize_t PyTypeObject.tp_maxalloc¶: 最大同时分配的对象。

PyTypeObject* PyTypeObject.tp_next¶: 指向具有非零tp_allocs字段的下一个类型对象的指针。

另外，注意，在垃圾收集的Python中，tp_dealloc可以从任何Python线程调用，而不仅仅是创建对象的线程（如果对象成为refcount循环的一部分，那么该循环可能被任何一个垃圾容器收集线）。这不是Python API调用的问题，因为调用tp_dealloc的线程将拥有全局解释器锁（GIL）。但是，如果被销毁的对象又会销毁一些其他C或C ++库中的对象，则应注意确保销毁那些调用tp_dealloc的线程上的对象不会违反库的任何假设。

Number Object Structures¶

PyNumberMethods¶

这个结构保存了对象用来实现数字协议的函数的指针。每个函数由Number Protocol部分中记录的类似名称的函数使用。

这里是结构定义：

typedef struct {
     binaryfunc nb_add;
     binaryfunc nb_subtract;
     binaryfunc nb_multiply;
     binaryfunc nb_remainder;
     binaryfunc nb_divmod;
     ternaryfunc nb_power;
     unaryfunc nb_negative;
     unaryfunc nb_positive;
     unaryfunc nb_absolute;
     inquiry nb_bool;
     unaryfunc nb_invert;
     binaryfunc nb_lshift;
     binaryfunc nb_rshift;
     binaryfunc nb_and;
     binaryfunc nb_xor;
     binaryfunc nb_or;
     unaryfunc nb_int;
     void *nb_reserved;
     unaryfunc nb_float;

     binaryfunc nb_inplace_add;
     binaryfunc nb_inplace_subtract;
     binaryfunc nb_inplace_multiply;
     binaryfunc nb_inplace_remainder;
     ternaryfunc nb_inplace_power;
     binaryfunc nb_inplace_lshift;
     binaryfunc nb_inplace_rshift;
     binaryfunc nb_inplace_and;
     binaryfunc nb_inplace_xor;
     binaryfunc nb_inplace_or;

     binaryfunc nb_floor_divide;
     binaryfunc nb_true_divide;
     binaryfunc nb_inplace_floor_divide;
     binaryfunc nb_inplace_true_divide;

     unaryfunc nb_index;

     binaryfunc nb_matrix_multiply;
     binaryfunc nb_inplace_matrix_multiply;
} PyNumberMethods;

注意

二进制和三进制函数必须检查所有操作数的类型，并实现必要的转换（至少一个操作数是定义类型的实例）。如果没有为给定的操作数定义操作，则二进制和三元函数必须返回Py_NotImplemented，如果发生另一个错误，则必须返回NULL并设置异常。

注意

nb_reserved字段应始终为NULL。它以前称为nb_long，并在Python 3.0.1中重命名。

Mapping Object Structures¶

PyMappingMethods¶: 这个结构保存了对象用来实现映射协议的函数的指针。它有三个成员：

lenfunc PyMappingMethods.mp_length¶: 此函数由PyMapping_Length()和PyObject_Size()使用，并具有相同的声明。如果对象没有定义的长度，则此槽可以设置为NULL。

binaryfunc PyMappingMethods.mp_subscript¶: 此函数由PyObject_GetItem()使用，并具有相同的声明。此槽必须填充PyMapping_Check()函数以返回1，否则可以为NULL。

objobjargproc PyMappingMethods.mp_ass_subscript¶: 此函数由PyObject_SetItem()和PyObject_DelItem()使用。它具有与PyObject_SetItem()相同的声明，但是v也可以设置为NULL以删除项目。如果此槽NULL，则该对象不支持项分配和删除。

Sequence Object Structures¶

PySequenceMethods¶: 此结构保存指向对象用于实现序列协议的函数的指针。

lenfunc PySequenceMethods.sq_length¶: 此函数由PySequence_Size()和PyObject_Size()使用，并具有相同的声明。

binaryfunc PySequenceMethods.sq_concat¶: 此函数由PySequence_Concat()使用，并具有相同的声明。在通过nb_add插槽尝试数字加法之后，它也由+操作符使用。

ssizeargfunc PySequenceMethods.sq_repeat¶: 此函数由PySequence_Repeat()使用，并具有相同的声明。在通过nb_multiply插槽尝试数值乘法之后，它还可以由*操作符使用。

ssizeargfunc PySequenceMethods.sq_item¶

此函数由PySequence_GetItem()使用，并具有相同的声明。此槽必须填充PySequence_Check()函数以返回1，否则可以为NULL。

负索引处理如下：如果sq_length槽被填充，则它被调用，并且序列长度用于计算传递到sq_item的正索引。如果sq_length为NULL，则索引将按原样传递到函数。

ssizeobjargproc PySequenceMethods.sq_ass_item¶: 此函数由PySequence_SetItem()使用，并具有相同的声明。如果对象不支持项分配和删除，则此插槽可以保留为NULL。

objobjproc PySequenceMethods.sq_contains¶: 此函数可由PySequence_Contains()使用，并具有相同的声明。这个槽可以留给NULL，在这种情况下，PySequence_Contains()只是遍历该序列直到找到匹配。

binaryfunc PySequenceMethods.sq_inplace_concat¶: 此函数由PySequence_InPlaceConcat()使用，并具有相同的声明。它应该修改其第一个操作数，并返回它。

ssizeargfunc PySequenceMethods.sq_inplace_repeat¶: 此函数由PySequence_InPlaceRepeat()使用，并具有相同的声明。它应该修改其第一个操作数，并返回它。

Buffer Object Structures¶

PyBufferProcs¶: 此结构保存指向Buffer protocol所需的函数的指针。协议定义导出器对象如何将其内部数据暴露给消费者对象。

getbufferproc PyBufferProcs.bf_getbuffer¶

此函数的声明是：

int (PyObject *exporter, Py_buffer *view, int flags);

处理对导出器的请求以填充标志指定的视图。除了点（3），此函数的实现必须采取以下步骤：

检查是否可以满足请求。如果没有，引发PyExc_BufferError，将view->obj设置为NULL，并返回-1。
填写请求的字段。
增加出口数的内部计数器。
将view->obj设置为导出器并增加view->obj。
返回0。

如果exporter是缓冲区提供程序的链或树的一部分，则可以使用两个主要方案：

重新导出：树的每个成员作为导出对象，并将view->obj设置为对其自身的新引用。
重定向：缓冲区请求被重定向到树的根对象。这里，view->obj将是对根对象的新引用。

Buffer structure中描述了视图的各个字段，出口商必须对特定请求作出反应的规则在Buffer request types中。

在Py_buffer结构中指向的所有内存都属于导出器，并且必须保持有效，直到没有消费者留下。format，shape，strides，suboffsets和internal消费者。

PyBuffer_FillInfo()提供了一种简单的方式暴露一个简单的字节缓冲区，同时正确处理所有请求类型。

PyObject_GetBuffer()是包装此函数的消费者的接口。

releasebufferproc PyBufferProcs.bf_releasebuffer¶

此函数的声明是：

void (PyObject *exporter, Py_buffer *view);

处理释放缓冲区资源的请求。如果没有资源需要释放，PyBufferProcs.bf_releasebuffer可以是NULL。否则，此函数的标准实现将采取以下可选步骤：

减少出口数的内部计数器。
如果计数器为0，释放与视图相关的所有内存。

输出器必须使用internal字段来跟踪缓冲区特定资源。该字段保证保持不变，而消费者可以将原始缓冲区的副本作为视图参数传递。

此函数不能减少view->obj，因为它在PyBuffer_Release()中自动完成（此方案对于中断参考周期很有用）。

PyBuffer_Release()是包装此函数的消费者的接口。

Async Object Structures¶

版本3.5中的新功能。

PyAsyncMethods¶

此结构保存指向实现awaitable和asynchronous iterator对象所需的函数的指针。

这里是结构定义：

typedef struct {
    unaryfunc am_await;
    unaryfunc am_aiter;
    unaryfunc am_anext;
} PyAsyncMethods;

unaryfunc PyAsyncMethods.am_await¶

此函数的声明是：

PyObject *am_await(PyObject *self)

返回的对象必须是迭代器，即PyIter_Check()必须返回1。

如果对象不是awaitable，则此插槽可以设置为NULL。

unaryfunc PyAsyncMethods.am_aiter¶

此函数的声明是：

PyObject *am_aiter(PyObject *self)

必须返回awaitable对象。有关详细信息，请参见__anext__()。

如果对象不实现异步迭代协议，则此插槽可以设置为NULL。

unaryfunc PyAsyncMethods.am_anext¶

此函数的声明是：

PyObject *am_anext(PyObject *self)

必须返回awaitable对象。有关详细信息，请参见__anext__()。此时隙可以设置为NULL。

Type Objects¶

Number Object Structures¶

Mapping Object Structures¶

Sequence Object Structures¶

Buffer Object Structures¶

Async Object Structures¶

目录

上一主题

下一主题

这一页