Skip to main content

类型对象

也许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,这意味着其实例(即类型对象) must 具有 ob_size 字段。

PyObject* PyObject._ob_next
PyObject* PyObject._ob_prev

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

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

Py_ssize_t PyObject.ob_refcnt

这是类型对象的引用计数,由 PyObject_HEAD_INIT 宏初始化为 1。请注意,对于静态分配的类型对象,类型的实例(ob_type 指向类型的对象)会将 not 计为引用。但对于动态分配的类型对象,实例 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终止字符串。对于可作为模块全局变量访问的类型,字符串应该是完整的模块名称,后跟一个点,后跟类型名称;对于内置类型,它应该只是类型名称。如果模块是包的子模块,则完整包名称是完整模块名称的一部分。例如,在包 P 中的子包 Q 中的模块 M 中定义的名为 T 的类型应当具有 tp_name 初始化器 "P.Q.M.T"

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

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

如果不存在点,则使整个 tp_name 字段作为 __name__ 属性可访问,并且 __module__ 属性是未定义的(除非在字典中明确设置,如上所述)。这意味着你的类型不可能泡菜。此外,它不会列在使用pydoc创建的模块文档中。

此字段不由子类型继承。

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_HEADPyObject_VAR_HEAD (无论用于声明实例结构)声明的实例中的字段,如果它们存在,则这又包括 _ob_prev_ob_next 字段。这意味着,获取 tp_basicsize 的初始化器的唯一正确的方法是在用于声明实例布局的结构上使用 sizeof 运算符。基本大小不包括GC标头大小。

这些字段由子类型单独继承。如果基类型具有非零的 tp_itemsize,则通常不安全地将 tp_itemsize 设置为子类型中的不同的非零值(尽管这取决于基本类型的实现)。

关于对齐的注释:如果变量项需要特定的对齐,这应该由 tp_basicsize 的值来处理。示例:假设某个类型实现了 double 数组。 tp_itemsizesizeof(double)。程序员的责任是 tp_basicsizesizeof(double) 的倍数(假设这是 double 的对齐要求)。

destructor PyTypeObject.tp_dealloc

指向实例析构函数的指针。必须定义此函数,除非类型保证其实例永远不会被释放(如单例 NoneEllipsis 的情况)。

当新的引用计数为零时,析构函数由 Py_DECREF()Py_XDECREF() 宏调用。此时,实例仍然存在,但没有对它的引用。析构函数应释放实例拥有的所有引用,释放实例拥有的所有内存缓冲区(使用与用于分配缓冲区的分配函数相对应的释放函数),最后(作为其最后一个动作)调用类型的 tp_free 函数。如果类型不是子类型(没有设置 Py_TPFLAGS_BASETYPE 标志位),则允许直接调用对象释放器,而不是通过 tp_free。对象deallocator应该是用于分配实例的;如果使用 PyObject_New()PyObject_VarNew() 分配实例,这通常是 PyObject_Del(),如果使用 PyObject_GC_New()PyObject_GC_NewVar() 分配实例,则通常是 PyObject_GC_Del()

此字段由子类继承。

printfunc PyTypeObject.tp_print

保留槽,以前用于Python 2.x中的打印格式。

getattrfunc PyTypeObject.tp_getattr

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

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

该字段由子类型与 tp_getattro 一起继承:当子类型 tp_getattrtp_getattro 都是 NULL 时,子类型从其基本类型继承 tp_getattrtp_getattro

setattrfunc PyTypeObject.tp_setattr

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

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

该字段由子类型与 tp_setattro 一起继承:当子类型 tp_setattrtp_setattro 都是 NULL 时,子类型从其基本类型继承 tp_setattrtp_setattro

PyAsyncMethods* tp_as_async

指向包含仅与在C级执行 awaitableasynchronous iterator 协议的对象相关的字段的附加结构的指针。有关详细信息,请参阅 异步对象结构

3.5 新版功能: 以前称为 tp_comparetp_reserved

reprfunc PyTypeObject.tp_repr

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

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

当未设置此字段时,将返回一个格式为 <%s object at %p> 的字符串,其中 %s 由类型名称替换,%p 由对象的内存地址替换。

此字段由子类继承。

PyNumberMethods* tp_as_number

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

tp_as_number 字段不是继承的,而是包含的字段单独继承。

PySequenceMethods* tp_as_sequence

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

tp_as_sequence 字段不是继承的,而是包含的字段单独继承。

PyMappingMethods* tp_as_mapping

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

tp_as_mapping 字段不是继承的,而是包含的字段单独继承。

hashfunc PyTypeObject.tp_hash

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

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

此字段可以明确设置为 PyObject_HashNotImplemented(),以阻止散列方法从父类型继承。这被解释为在Python级别的 __hash__ = None 的等效,导致 isinstance(o, collections.Hashable) 正确返回 False。注意,反之亦然 - 在Python级别的类上设置 __hash__ = None 将导致 tp_hash 槽被设置为 PyObject_HashNotImplemented()

当未设置此字段时,尝试获取对象的散列会提高 TypeError

此字段由子类型与 tp_richcompare 一起继承:当子类型 tp_richcomparetp_hash 都是 NULL 时,子类型继承 tp_richcomparetp_hash

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(),这实现了查找对象属性的常规方法。

该字段由子类型与 tp_getattr 一起继承:当子类型 tp_getattrtp_getattro 都是 NULL 时,子类型从其基本类型继承 tp_getattrtp_getattro

setattrofunc PyTypeObject.tp_setattro

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

签名与 PyObject_SetAttr() 相同,但必须支持将 v 设置为 NULL 以删除属性。通常方便的是将此字段设置为 PyObject_GenericSetAttr(),这实现了设置对象属性的常规方式。

该字段由子类型与 tp_setattr 一起继承:当子类型 tp_setattrtp_setattro 都是 NULL 时,子类型从其基本类型继承 tp_setattrtp_setattro

PyBufferProcs* PyTypeObject.tp_as_buffer

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

tp_as_buffer 字段不是继承的,而是包含的字段单独继承。

unsigned long PyTypeObject.tp_flags

该字段是各种标志的位掩码。一些标志表示某些情况下的变量语义;其他用于指示历史上不总是存在的类型对象(或通过 tp_as_numbertp_as_sequencetp_as_mappingtp_as_buffer 引用的扩展结构)中的某些字段有效;如果这样的标志位是清楚的,则其保护的类型字段不能被访问,并且必须被认为具有零或 NULL 值。

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

以下位掩码当前已定义;这些可以使用 | 运算符一起进行OR运算以形成 tp_flags 字段的值。宏 PyType_HasFeature() 取类型和标志值 tpf,并检查 tp->tp_flags & f 是否非零。

Py_TPFLAGS_HEAPTYPE

当类型对象本身在堆上分配时,该位置位。在这种情况下,它的实例的 ob_type 字段被认为是对类型的引用,并且当创建新实例时,类型对象被INCREF’ed,并且当实例被销毁时被DECREF’ed(这不适用于实例子类型;只有实例的ob_type引用的类型被INCREF’ed或DECREF’ed)。

Py_TPFLAGS_BASETYPE

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

Py_TPFLAGS_READY

PyType_Ready() 完全初始化类型对象时,该位置位。

Py_TPFLAGS_READYING

PyType_Ready() 处于初始化类型对象的过程中时,该位被置位。

Py_TPFLAGS_HAVE_GC

当对象支持垃圾回收时,该位置位。如果设置此位,则必须使用 PyObject_GC_New() 创建实例,并使用 PyObject_GC_Del() 销毁。更多信息在 支持循环垃圾收集 部分。该位还意味着GC相关字段 tp_traversetp_clear 存在于类型对象中。

Py_TPFLAGS_DEFAULT

这是与类型对象及其扩展结构中某些字段的存在相关的所有位的位掩码。目前,它包括以下位:Py_TPFLAGS_HAVE_STACKLESS_EXTENSIONPy_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 时隙存在于类型结构中时,该位置位。

3.4 新版功能.

const char* PyTypeObject.tp_doc

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

此字段是由子类继承的 not

traverseproc PyTypeObject.tp_traverse

指向垃圾回收器的遍历函数的可选指针。这仅在 Py_TPFLAGS_HAVE_GC 标志位置1时使用。有关Python的垃圾收集方案的更多信息,请参见 支持循环垃圾收集 部分。

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() 要求 local_traverse()visitarg 参数具有这些特定名称;不要命名他们什么。

此字段由子类型与 tp_clearPy_TPFLAGS_HAVE_GC 标志位一起继承:如果它们在子类型中都为零,则标志位,tp_traversetp_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。这是因为减少引用计数可能导致包含的对象变成垃圾,触发一系列回收活动,可能包括调用任意Python代码(由于finalizers或weakref回调,与包含的对象相关联)。如果这样的代码可能再次引用 self,那么重要的是,包含的对象的指针在那时是 NULL,所以 self 知道包含的对象不能再被使用。 Py_CLEAR() 宏以安全顺序执行操作。

因为 tp_clear 函数的目标是打破参考循环,所以不必清除包含的对象,如Python字符串或Python整数,它们不能参与参考循环。另一方面,可以方便地清除所有包含的Python对象,并写入类型的 tp_dealloc 函数来调用 tp_clear

有关Python垃圾收集方案的更多信息,请参见 支持循环垃圾收集 部分。

此字段由子类型与 tp_traversePy_TPFLAGS_HAVE_GC 标志位一起继承:如果它们在子类型中都为零,则标志位,tp_traversetp_clear 都从基本类型继承。

richcmpfunc PyTypeObject.tp_richcompare

指向丰富比较函数的可选指针,其签名为 PyObject *tp_richcompare(PyObject *a, PyObject *b, int op)。第一个参数被保证为由 PyTypeObject 定义的类型的实例。

函数应返回比较结果(通常为 Py_TruePy_False)。如果比较未定义,它必须返回 Py_NotImplemented,如果发生另一个错误,它必须返回 NULL 并设置一个异常条件。

注解

如果你想实现一个类型,只有有限的比较有意义(例如 ==!=,但不是 < 和朋友),直接提出 TypeError 在丰富的比较函数。

该字段由子类型与 tp_hash 一起继承:当子类型 tp_richcomparetp_hash 都是 NULL 时,子类型继承 tp_richcomparetp_hash

以下常量被定义为用作 tp_richcomparePyObject_RichCompare() 的第三个参数:

不变

比较

Py_LT

<

Py_LE

<=

Py_EQ

==

Py_NE

!=

Py_GT

>

Py_GE

>=

Py_ssize_t PyTypeObject.tp_weaklistoffset

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

不要将此字段与 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

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

对于数组中的每个条目,将一个条目添加到包含方法描述符的类型的字典(请参阅下面的 tp_dict)。

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

struct PyMemberDef* PyTypeObject.tp_members

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

对于数组中的每个条目,将一个条目添加到包含成员描述符的类型的字典(请参阅下面的 tp_dict)。

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

struct PyGetSetDef* PyTypeObject.tp_getset

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

对于数组中的每个条目,将一个条目添加到包含getset描述符的类型的字典(请参阅下面的 tp_dict)。

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

文档的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);

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

Py_ssize_t PyTypeObject.tp_dictoffset

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

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

如果此字段的值大于零,它指定从实例结构的开始的偏移量。如果值小于零,它指定与实例结构的 end 的偏移量。负偏移使用起来更昂贵,并且只应在实例结构包含可变长度部分时使用。这用于例如将实例变量字典添加到 strtuple 的子类型。请注意,即使字典不包括在基本对象布局中,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_basicsizetp_itemsizetp_dictoffset 取自类型对象,ob_size 取自实例。取绝对值,因为int使用 ob_size 的符号存储数字的符号。 (从来没有必要自己做这个计算;它是由 _PyObject_GetDictPtr() 为你完成的。)

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

当由类语句定义的类型没有 __slots__ 声明,并且其基类型没有一个实例变量字典时,字典槽添加到实例布局中,tp_dictoffset 被设置为该槽的偏移量。

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

(添加一个名为 __dict__ 的槽到 __slots__ 声明没有预期的效果,它只是引起混乱,也许这应该像 __weakref__ 一样添加)。

initproc PyTypeObject.tp_init

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

此函数对应于类的 __init__() 方法。像 __init__() 一样,可以创建一个实例而不调用 __init__(),并且可以通过再次调用它的 __init__() 方法来重新初始化实例。

函数签名是

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

self参数是要初始化的实例; argskwds 参数表示对 __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 设置为 1ob_type 设置为类型参数。如果类型的 tp_itemsize 不为零,则对象的 ob_size 字段应被初始化为 nitems,并且所分配的存储器块的长度应当为 tp_basicsize + nitems*tp_itemsize,舍入为 sizeof(void*) 的倍数;否则,不使用 nitems,块的长度应为 tp_basicsize

不要使用此函数做任何其他实例初始化,甚至不分配额外的内存;应由 tp_new 做。

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

newfunc PyTypeObject.tp_new

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

如果这个函数是一个特定类型的 NULL,则不能调用该类型来创建新实例;可能有一些其他方式来创建实例,如工厂函数。

函数签名是

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

subtype参数是正在创建的对象的类型; argskwds 参数表示对类型的调用的位置和关键字参数。注意,子类型不必等于调用 tp_new 函数的类型;它可以是该类型的子类型(但不是无关类型)。

tp_new 函数应该调用 subtype->tp_alloc(subtype, nitems) 为对象分配空间,然后只做绝对必要的进一步初始化。可以安全地忽略或重复的初始化应该放在 tp_init 处理程序中。一个好的经验法则是,对于不可变类型,所有初始化应该在 tp_new 中进行,而对于可变类型,大多数初始化应该推迟到 tp_init

此字段由子类继承,但它不是由 tp_baseNULL&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的那些对象不会违反库的任何假设。

数字对象结构

PyNumberMethods

该结构保存了对象用于实现号码协议的函数的指针。每个函数由 号码协议 部分中记录的类似名称的函数使用。

这里是结构定义:

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中重命名。

映射对象结构

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,则对象不支持项分配和删除。

序列对象结构

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_lengthNULL,则索引按原样传递到函数。

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() 使用并具有相同的签名。它应该修改其第一个操作数,并返回它。

缓冲区对象结构

PyBufferProcs

此结构保存指向 缓冲协议 所需功能的指针。协议定义导出器对象如何将其内部数据暴露给使用者对象。

getbufferproc PyBufferProcs.bf_getbuffer

这个函数的签名是:

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

处理 exporter 请求以填写 flags 指定的 view。除了点(3),该函数的实现必须采取以下步骤:

  1. 检查是否可以满足请求。如果没有,提出 PyExc_BufferError,将 view->obj 设置为 NULL 并返回 -1

  2. 填写请求的字段。

  3. 为导出数增加内部计数器。

  4. view->obj 设置为 exporter 并增加 view->obj

  5. 返回 0

如果 exporter 是缓冲器提供者的链或树的一部分,则可以使用两个主要方案:

  • 重新导出:树的每个成员作为导出对象,并将 view->obj 设置为对其自身的新引用。

  • 重定向:缓冲区请求被重定向到树的根对象。这里,view->obj 将是对根对象的新引用。

view 的各个字段在 缓冲结构 部分中描述,出口商必须对具体请求做出反应的规则在 缓冲区请求类型 部分。

Py_buffer 结构中指向的所有内存都属于导出器,并且必须保持有效,直到没有消费者离开。 formatshapestridessuboffsetsinternal 对于消费者是只读的。

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

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

releasebufferproc PyBufferProcs.bf_releasebuffer

这个函数的签名是:

void (PyObject *exporter, Py_buffer *view);

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

  1. 减少出口数的内部计数器。

  2. 如果计数器是 0,则释放与 view 相关联的所有内存。

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

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

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

异步对象结构

3.5 新版功能.

PyAsyncMethods

此结构保存指向实现 awaitableasynchronous 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