Quick Reference¶

X - PyType_Ready sets this value if it is NULL~ - PyType_Ready always sets this value (it should be NULL)? - PyType_Ready may set this value depending on other slotsAlso see the inheritance column ("I").

X - type slot is inherited via *PyType_Ready* if defined with a *NULL* value% - the slots of the sub-struct are inherited individuallyG - inherited, but only in combination with other slots; see the slot's description? - it's complicated; see the slot's description

PyTypeObject Definition¶

The structure definition forPyTypeObject can be found inInclude/cpython/object.h. For convenience of reference, this repeats thedefinition found there:

typedefstruct_typeobject{PyObject_VAR_HEADconstchar*tp_name;/* For printing, in format "<module>.<name>" */Py_ssize_ttp_basicsize,tp_itemsize;/* For allocation *//* Methods to implement standard operations */destructortp_dealloc;Py_ssize_ttp_vectorcall_offset;getattrfunctp_getattr;setattrfunctp_setattr;PyAsyncMethods*tp_as_async;/* formerly known as tp_compare (Python 2)                                    or tp_reserved (Python 3) */reprfunctp_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) */hashfunctp_hash;ternaryfunctp_call;reprfunctp_str;getattrofunctp_getattro;setattrofunctp_setattro;/* Functions to access object as input/output buffer */PyBufferProcs*tp_as_buffer;/* Flags to define presence of optional/expanded features */unsignedlongtp_flags;constchar*tp_doc;/* Documentation string *//* Assigned meaning in release 2.0 *//* call function for all accessible objects */traverseproctp_traverse;/* delete references to contained objects */inquirytp_clear;/* Assigned meaning in release 2.1 *//* rich comparisons */richcmpfunctp_richcompare;/* weak reference enabler */Py_ssize_ttp_weaklistoffset;/* Iterators */getiterfunctp_iter;iternextfunctp_iternext;/* Attribute descriptor and subclassing stuff */structPyMethodDef*tp_methods;structPyMemberDef*tp_members;structPyGetSetDef*tp_getset;// Strong reference on a heap type, borrowed reference on a static typestruct_typeobject*tp_base;PyObject*tp_dict;descrgetfunctp_descr_get;descrsetfunctp_descr_set;Py_ssize_ttp_dictoffset;initproctp_init;allocfunctp_alloc;newfunctp_new;freefunctp_free;/* Low-level free-memory routine */inquirytp_is_gc;/* For PyObject_IS_GC */PyObject*tp_bases;PyObject*tp_mro;/* method resolution order */PyObject*tp_cache;PyObject*tp_subclasses;PyObject*tp_weaklist;destructortp_del;/* Type attribute cache version tag. Added in version 2.6 */unsignedinttp_version_tag;destructortp_finalize;vectorcallfunctp_vectorcall;/* bitset of which type-watchers care about this type */unsignedchartp_watched;}PyTypeObject;

PyObject Slots¶

The type object structure extends thePyVarObject structure. Theob_size field is used for dynamic types (created bytype_new(),usually called from a class statement). Note thatPyType_Type (themetatype) initializestp_itemsize, which means that its instances (i.e.type objects)must have theob_size field.

Py_ssize_tPyObject.ob_refcnt¶

Part of theStable ABI.

This is the type object’s reference count, initialized to1 by thePyObject_HEAD_INIT macro. Note that forstatically allocated typeobjects, the type’s instances (objects whoseob_typepoints back to the type) donot count as references. But fordynamically allocated type objects, the instancesdocount as references.

Inheritance:

This field is not inherited by subtypes.

PyTypeObject*PyObject.ob_type¶

Part of theStable ABI.

This is the type’s type, in other words its metatype. It is initialized by theargument to thePyObject_HEAD_INIT macro, and its value should normally be&PyType_Type. However, for dynamically loadable extension modules that mustbe usable on Windows (at least), the compiler complains that this is not a validinitializer. Therefore, the convention is to passNULL to thePyObject_HEAD_INIT macro and to initialize this field explicitly at thestart of the module’s initialization function, before doing anything else. Thisis typically done like this:

Foo_Type.ob_type=&PyType_Type;

This should be done before any instances of the type are created.PyType_Ready() checks ifob_type isNULL, and if so,initializes it to theob_type field of the base class.PyType_Ready() will not change this field if it is non-zero.

Inheritance:

This field is inherited by subtypes.

PyVarObject Slots¶

Py_ssize_tPyVarObject.ob_size¶

Part of theStable ABI.

Forstatically allocated type objects, this should beinitialized to zero. Fordynamically allocated type objects, this field has a special internal meaning.

This field should be accessed using thePy_SIZE() andPy_SET_SIZE() macros.

Inheritance:

This field is not inherited by subtypes.

PyTypeObject Slots¶

Each slot has a section describing inheritance. IfPyType_Ready()may set a value when the field is set toNULL then there will also bea “Default” section. (Note that many fields set onPyBaseObject_TypeandPyType_Type effectively act as defaults.)

constchar*PyTypeObject.tp_name¶

Pointer to a NUL-terminated string containing the name of the type. For typesthat are accessible as module globals, the string should be the full modulename, followed by a dot, followed by the type name; for built-in types, itshould be just the type name. If the module is a submodule of a package, thefull package name is part of the full module name. For example, a type namedT defined in moduleM in subpackageQ in packagePshould have thetp_name initializer"P.Q.M.T".

Fordynamically allocated type objects,this should just be the type name, andthe module name explicitly stored in the type dict as the value for key'__module__'.

Forstatically allocated type objects,thetp_name field should contain a dot.Everything before the last dot is made accessible as the__module__attribute, and everything after the last dot is made accessible as the__name__ attribute.

If no dot is present, the entiretp_name field is made accessible as the__name__ attribute, and the__module__ attribute is undefined(unless explicitly set in the dictionary, as explained above). This means yourtype will be impossible to pickle. Additionally, it will not be listed inmodule documentations created with pydoc.

This field must not beNULL. It is the only required fieldinPyTypeObject() (other than potentiallytp_itemsize).

Inheritance:

This field is not inherited by subtypes.

Py_ssize_tPyTypeObject.tp_basicsize¶

Py_ssize_tPyTypeObject.tp_itemsize¶

These fields allow calculating the size in bytes of instances of the type.

There are two kinds of types: types with fixed-length instances have a zerotp_itemsize field, types with variable-length instances have a non-zerotp_itemsize field. For a type with fixed-length instances, allinstances have the same size, given intp_basicsize.(Exceptions to this rule can be made usingPyUnstable_Object_GC_NewWithExtraData().)

For a type with variable-length instances, the instances must have anob_size field, and the instance size istp_basicsize plus N timestp_itemsize,where N is the “length” of the object.

Functions likePyObject_NewVar() will take the value of N as anargument, and store in the instance’sob_size field.Note that theob_size field may later be used forother purposes. For example,int instances use the bits ofob_size in an implementation-definedway; the underlying storage and its size should be accessed usingPyLong_Export().

Note

Theob_size field should be accessed usingthePy_SIZE() andPy_SET_SIZE() macros.

Also, the presence of anob_size field in theinstance layout doesn’t mean that the instance structure is variable-length.For example, thelist type has fixed-length instances, yet thoseinstances have aob_size field.(As withint, avoid reading lists’ob_size directly.CallPyList_Size() instead.)

Thetp_basicsize includes size needed for data of the type’stp_base, plus any extra data neededby each instance.

The correct way to settp_basicsize is to use thesizeof operator on the struct used to declare the instance layout.This struct must include the struct used to declare the base type.In other words,tp_basicsize must be greater than or equalto the base’stp_basicsize.

Since every type is a subtype ofobject, this struct mustincludePyObject orPyVarObject (depending onwhetherob_size should be included). These areusually defined by the macroPyObject_HEAD orPyObject_VAR_HEAD, respectively.

The basic size does not include the GC header size, as that header is notpart ofPyObject_HEAD.

For cases where struct used to declare the base type is unknown,seePyType_Spec.basicsize andPyType_FromMetaclass().

Notes about alignment:

• tp_basicsize must be a multiple of_Alignof(PyObject).When usingsizeof on astruct that includesPyObject_HEAD, as recommended, the compiler ensures this.When not using a Cstruct, or when using compilerextensions like__attribute__((packed)), it is up to you.

• If the variable items require a particular alignment,tp_basicsize andtp_itemsize must each be amultiple of that alignment.For example, if a type’s variable part stores adouble, it isyour responsibility that both fields are a multiple of_Alignof(double).

Inheritance:

These fields are inherited separately by subtypes.(That is, if the field is set to zero,PyType_Ready() will copythe value from the base type, indicating that the instances do notneed additional storage.)

If the base type has a non-zerotp_itemsize, it is generally not safe to settp_itemsize to a different non-zero value in a subtype (though thisdepends on the implementation of the base type).

destructorPyTypeObject.tp_dealloc¶

A pointer to the instance destructor function. This function must be definedunless the type guarantees that its instances will never be deallocated (as isthe case for the singletonsNone andEllipsis). The function signature is:

voidtp_dealloc(PyObject*self);

The destructor function is called by thePy_DECREF() andPy_XDECREF() macros when the new reference count is zero. At this point,the instance is still in existence, but there are no references to it. Thedestructor function should free all references which the instance owns, free allmemory buffers owned by the instance (using the freeing function correspondingto the allocation function used to allocate the buffer), and call the type’stp_free function. If the type is not subtypable(doesn’t have thePy_TPFLAGS_BASETYPE flag bit set), it ispermissible to call the object deallocator directly instead of viatp_free. The object deallocator should be the one used to allocate theinstance; this is normallyPyObject_Del() if the instance was allocatedusingPyObject_New orPyObject_NewVar, orPyObject_GC_Del() if the instance was allocated usingPyObject_GC_New orPyObject_GC_NewVar.

If the type supports garbage collection (has thePy_TPFLAGS_HAVE_GCflag bit set), the destructor should callPyObject_GC_UnTrack()before clearing any member fields.

staticvoidfoo_dealloc(foo_object*self){PyObject_GC_UnTrack(self);Py_CLEAR(self->ref);Py_TYPE(self)->tp_free((PyObject*)self);}

Finally, if the type is heap allocated (Py_TPFLAGS_HEAPTYPE), thedeallocator should release the owned reference to its type object(viaPy_DECREF()) aftercalling the type deallocator. In order to avoid dangling pointers, therecommended way to achieve this is:

staticvoidfoo_dealloc(foo_object*self){PyTypeObject*tp=Py_TYPE(self);// free references and buffers heretp->tp_free(self);Py_DECREF(tp);}

Warning

In a garbage collected Python,tp_dealloc may be called fromany Python thread, not just the thread which created the object (if theobject becomes part of a refcount cycle, that cycle might be collected bya garbage collection on any thread). This is not a problem for PythonAPI calls, since the thread on whichtp_dealloc is calledwill own the Global Interpreter Lock (GIL). However, if the object beingdestroyed in turn destroys objects from some other C or C++ library, careshould be taken to ensure that destroying those objects on the threadwhich calledtp_dealloc will not violate any assumptions ofthe library.

Inheritance:

This field is inherited by subtypes.

Py_ssize_tPyTypeObject.tp_vectorcall_offset¶

An optional offset to a per-instance function that implements callingthe object using thevectorcall protocol,a more efficient alternativeof the simplertp_call.

This field is only used if the flagPy_TPFLAGS_HAVE_VECTORCALLis set. If so, this must be a positive integer containing the offset in theinstance of avectorcallfunc pointer.

Thevectorcallfunc pointer may beNULL, in which case the instance behavesas ifPy_TPFLAGS_HAVE_VECTORCALL was not set: calling the instancefalls back totp_call.

Any class that setsPy_TPFLAGS_HAVE_VECTORCALL must also settp_call and make sure its behaviour is consistentwith thevectorcallfunc function.This can be done by settingtp_call toPyVectorcall_Call().

Changed in version 3.8:Before version 3.8, this slot was namedtp_print.In Python 2.x, it was used for printing to a file.In Python 3.0 to 3.7, it was unused.

Changed in version 3.12:Before version 3.12, it was not recommended formutable heap types to implement the vectorcallprotocol.When a user sets__call__ in Python code, onlytp_call isupdated, likely making it inconsistent with the vectorcall function.Since 3.12, setting__call__ will disable vectorcall optimizationby clearing thePy_TPFLAGS_HAVE_VECTORCALL flag.

Inheritance:

This field is always inherited.However, thePy_TPFLAGS_HAVE_VECTORCALL flag is notalways inherited. If it’s not set, then the subclass won’t usevectorcall, except whenPyVectorcall_Call() is explicitly called.

getattrfuncPyTypeObject.tp_getattr¶

An optional pointer to the get-attribute-string function.

This field is deprecated. When it is defined, it should point to a functionthat acts the same as thetp_getattro function, but taking a C stringinstead of a Python string object to give the attribute name.

Inheritance:

Group:tp_getattr,tp_getattro

This field is inherited by subtypes together withtp_getattro: a subtypeinherits bothtp_getattr andtp_getattro from its base type whenthe subtype’stp_getattr andtp_getattro are bothNULL.

setattrfuncPyTypeObject.tp_setattr¶

An optional pointer to the function for setting and deleting attributes.

This field is deprecated. When it is defined, it should point to a functionthat acts the same as thetp_setattro function, but taking a C stringinstead of a Python string object to give the attribute name.

Inheritance:

Group:tp_setattr,tp_setattro

This field is inherited by subtypes together withtp_setattro: a subtypeinherits bothtp_setattr andtp_setattro from its base type whenthe subtype’stp_setattr andtp_setattro are bothNULL.

PyAsyncMethods*PyTypeObject.tp_as_async¶

Pointer to an additional structure that contains fields relevant only toobjects which implementawaitable andasynchronous iteratorprotocols at the C-level. SeeAsync Object Structures for details.

Added in version 3.5:Formerly known astp_compare andtp_reserved.

Inheritance:

Thetp_as_async field is not inherited,but the contained fields are inherited individually.

reprfuncPyTypeObject.tp_repr¶

An optional pointer to a function that implements the built-in functionrepr().

The signature is the same as forPyObject_Repr():

PyObject*tp_repr(PyObject*self);

The function must return a string or a Unicode object. Ideally,this function should return a string that, when passed toeval(), given a suitable environment, returns an object with thesame value. If this is not feasible, it should return a string starting with'<' and ending with'>' from which both the type and the value of theobject can be deduced.

Inheritance:

This field is inherited by subtypes.

Default:

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

PyNumberMethods*PyTypeObject.tp_as_number¶

Pointer to an additional structure that contains fields relevant only toobjects which implement the number protocol. These fields are documented inNumber Object Structures.

Inheritance:

Thetp_as_number field is not inherited, but the contained fields areinherited individually.

PySequenceMethods*PyTypeObject.tp_as_sequence¶

Pointer to an additional structure that contains fields relevant only toobjects which implement the sequence protocol. These fields are documentedinSequence Object Structures.

Inheritance:

Thetp_as_sequence field is not inherited, but the contained fieldsare inherited individually.

PyMappingMethods*PyTypeObject.tp_as_mapping¶

Pointer to an additional structure that contains fields relevant only toobjects which implement the mapping protocol. These fields are documented inMapping Object Structures.

Inheritance:

Thetp_as_mapping field is not inherited, but the contained fieldsare inherited individually.

hashfuncPyTypeObject.tp_hash¶

An optional pointer to a function that implements the built-in functionhash().

The signature is the same as forPyObject_Hash():

Py_hash_ttp_hash(PyObject*);

The value-1 should not be returned as anormal return value; when an error occurs during the computation of the hashvalue, the function should set an exception and return-1.

When this field is not set (andtp_richcompare is not set),an attempt to take the hash of the object raisesTypeError.This is the same as setting it toPyObject_HashNotImplemented().

This field can be set explicitly toPyObject_HashNotImplemented() toblock inheritance of the hash method from a parent type. This is interpretedas the equivalent of__hash__=None at the Python level, causingisinstance(o,collections.Hashable) to correctly returnFalse. Notethat the converse is also true - setting__hash__=None on a class atthe Python level will result in thetp_hash slot being set toPyObject_HashNotImplemented().

Inheritance:

Group:tp_hash,tp_richcompare

This field is inherited by subtypes together withtp_richcompare: a subtype inherits both oftp_richcompare andtp_hash, when the subtype’stp_richcompare andtp_hash are bothNULL.

Default:

PyBaseObject_Type usesPyObject_GenericHash().

ternaryfuncPyTypeObject.tp_call¶

An optional pointer to a function that implements calling the object. Thisshould beNULL if the object is not callable. The signature is the same asforPyObject_Call():

PyObject*tp_call(PyObject*self,PyObject*args,PyObject*kwargs);

Inheritance:

This field is inherited by subtypes.

reprfuncPyTypeObject.tp_str¶

An optional pointer to a function that implements the built-in operationstr(). (Note thatstr is a type now, andstr() calls theconstructor for that type. This constructor callsPyObject_Str() to dothe actual work, andPyObject_Str() will call this handler.)

The signature is the same as forPyObject_Str():

PyObject*tp_str(PyObject*self);

The function must return a string or a Unicode object. It should be a “friendly” stringrepresentation of the object, as this is the representation that will be used,among other things, by theprint() function.

Inheritance:

This field is inherited by subtypes.

Default:

When this field is not set,PyObject_Repr() is called to return a stringrepresentation.

getattrofuncPyTypeObject.tp_getattro¶

An optional pointer to the get-attribute function.

The signature is the same as forPyObject_GetAttr():

PyObject*tp_getattro(PyObject*self,PyObject*attr);

It is usually convenient to set this field toPyObject_GenericGetAttr(),which implements the normal way of looking for object attributes.

Inheritance:

Group:tp_getattr,tp_getattro

This field is inherited by subtypes together withtp_getattr: a subtypeinherits bothtp_getattr andtp_getattro from its base type whenthe subtype’stp_getattr andtp_getattro are bothNULL.

Default:

PyBaseObject_Type usesPyObject_GenericGetAttr().

setattrofuncPyTypeObject.tp_setattro¶

An optional pointer to the function for setting and deleting attributes.

The signature is the same as forPyObject_SetAttr():

inttp_setattro(PyObject*self,PyObject*attr,PyObject*value);

In addition, settingvalue toNULL to delete an attribute must besupported. It is usually convenient to set this field toPyObject_GenericSetAttr(), which implements the normalway of setting object attributes.

Inheritance:

Group:tp_setattr,tp_setattro

This field is inherited by subtypes together withtp_setattr: a subtypeinherits bothtp_setattr andtp_setattro from its base type whenthe subtype’stp_setattr andtp_setattro are bothNULL.

Default:

PyBaseObject_Type usesPyObject_GenericSetAttr().

PyBufferProcs*PyTypeObject.tp_as_buffer¶

Pointer to an additional structure that contains fields relevant only to objectswhich implement the buffer interface. These fields are documented inBuffer Object Structures.

Inheritance:

Thetp_as_buffer field is not inherited,but the contained fields are inherited individually.

unsignedlongPyTypeObject.tp_flags¶

This field is a bit mask of various flags. Some flags indicate variantsemantics for certain situations; others are used to indicate that certainfields in the type object (or in the extension structures referenced viatp_as_number,tp_as_sequence,tp_as_mapping, andtp_as_buffer) that were historically not always present are valid; ifsuch a flag bit is clear, the type fields it guards must not be accessed andmust be considered to have a zero orNULL value instead.

Inheritance:

Inheritance of this field is complicated. Most flag bits are inheritedindividually, i.e. if the base type has a flag bit set, the subtype inheritsthis flag bit. The flag bits that pertain to extension structures are strictlyinherited if the extension structure is inherited, i.e. the base type’s value ofthe flag bit is copied into the subtype together with a pointer to the extensionstructure. ThePy_TPFLAGS_HAVE_GC flag bit is inherited together withthetp_traverse andtp_clear fields, i.e. if thePy_TPFLAGS_HAVE_GC flag bit is clear in the subtype and thetp_traverse andtp_clear fields in the subtype exist and haveNULL values... XXX are most flag bitsreally inherited individually?

Default:

PyBaseObject_Type usesPy_TPFLAGS_DEFAULT|Py_TPFLAGS_BASETYPE.

Bit Masks:

The following bit masks are currently defined; these can be ORed together usingthe| operator to form the value of thetp_flags field. The macroPyType_HasFeature() takes a type and a flags value,tp andf, andchecks whethertp->tp_flags&f is non-zero.

Py_TPFLAGS_HEAPTYPE¶

This bit is set when the type object itself is allocated on the heap, forexample, types created dynamically usingPyType_FromSpec(). In thiscase, theob_type field of its instances is considered a reference tothe type, and the type object is INCREF’ed when a new instance is created, andDECREF’ed when an instance is destroyed (this does not apply to instances ofsubtypes; only the type referenced by the instance’s ob_type gets INCREF’ed orDECREF’ed). Heap types should alsosupport garbage collectionas they can form a reference cycle with their own module object.

Inheritance:

???

Py_TPFLAGS_BASETYPE¶

This bit is set when the type can be used as the base type of another type. Ifthis bit is clear, the type cannot be subtyped (similar to a “final” class inJava).

Inheritance:

???

Py_TPFLAGS_READY¶

This bit is set when the type object has been fully initialized byPyType_Ready().

Inheritance:

???

Py_TPFLAGS_READYING¶

This bit is set whilePyType_Ready() is in the process of initializingthe type object.

Inheritance:

???

Py_TPFLAGS_HAVE_GC¶

This bit is set when the object supports garbage collection. If this bitis set, instances must be created usingPyObject_GC_New anddestroyed usingPyObject_GC_Del(). More information in sectionSupporting Cyclic Garbage Collection. This bit also implies that theGC-related fieldstp_traverse andtp_clear are present inthe type object.

Inheritance:

Group:Py_TPFLAGS_HAVE_GC,tp_traverse,tp_clear

ThePy_TPFLAGS_HAVE_GC flag bit is inheritedtogether with thetp_traverse andtp_clearfields, i.e. if thePy_TPFLAGS_HAVE_GC flag bit isclear in the subtype and thetp_traverse andtp_clear fields in the subtype exist and haveNULLvalues.

Py_TPFLAGS_DEFAULT¶

This is a bitmask of all the bits that pertain to the existence of certainfields in the type object and its extension structures. Currently, it includesthe following bits:Py_TPFLAGS_HAVE_STACKLESS_EXTENSION.

Inheritance:

???

Py_TPFLAGS_METHOD_DESCRIPTOR¶

This bit indicates that objects behave like unbound methods.

If this flag is set fortype(meth), then:

• meth.__get__(obj,cls)(*args,**kwds) (withobj not None)must be equivalent tometh(obj,*args,**kwds).

• meth.__get__(None,cls)(*args,**kwds)must be equivalent tometh(*args,**kwds).

This flag enables an optimization for typical method calls likeobj.meth(): it avoids creating a temporary “bound method” object forobj.meth.

Added in version 3.8.

Inheritance:

This flag is never inherited by types without thePy_TPFLAGS_IMMUTABLETYPE flag set. For extension types, it isinherited whenevertp_descr_get is inherited.

Py_TPFLAGS_MANAGED_DICT¶

This bit indicates that instances of the class have a~object.__dict__attribute, and that the space for the dictionary is managed by the VM.

If this flag is set,Py_TPFLAGS_HAVE_GC should also be set.

The type traverse function must callPyObject_VisitManagedDict()and its clear function must callPyObject_ClearManagedDict().

Added in version 3.12.

Inheritance:

This flag is inherited unless thetp_dictoffset field is set in a superclass.

Py_TPFLAGS_MANAGED_WEAKREF¶

This bit indicates that instances of the class should be weaklyreferenceable.

Added in version 3.12.

Inheritance:

This flag is inherited unless thetp_weaklistoffset field is set in a superclass.

Py_TPFLAGS_ITEMS_AT_END¶

Only usable with variable-size types, i.e. ones with non-zerotp_itemsize.

Indicates that the variable-sized portion of an instance of this type isat the end of the instance’s memory area, at an offset ofPy_TYPE(obj)->tp_basicsize (which may be different in eachsubclass).

When setting this flag, be sure that all superclasses eitheruse this memory layout, or are not variable-sized.Python does not check this.

Added in version 3.12.

Inheritance:

This flag is inherited.

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¶

These flags are used by functions such asPyLong_Check() to quickly determine if a type is a subclassof a built-in type; such specific checks are faster than a genericcheck, likePyObject_IsInstance(). Custom types that inheritfrom built-ins should have theirtp_flagsset appropriately, or the code that interacts with such typeswill behave differently depending on what kind of check is used.

Py_TPFLAGS_HAVE_FINALIZE¶

This bit is set when thetp_finalize slot is present in thetype structure.

Added in version 3.4.

Deprecated since version 3.8:This flag isn’t necessary anymore, as the interpreter assumes thetp_finalize slot is always present in thetype structure.

Py_TPFLAGS_HAVE_VECTORCALL¶

This bit is set when the class implementsthevectorcall protocol.Seetp_vectorcall_offset for details.

Inheritance:

This bit is inherited iftp_call is alsoinherited.

Added in version 3.9.

Changed in version 3.12:This flag is now removed from a class when the class’s__call__() method is reassigned.

This flag can now be inherited by mutable classes.

Py_TPFLAGS_IMMUTABLETYPE¶

This bit is set for type objects that are immutable: type attributes cannot be set nor deleted.

PyType_Ready() automatically applies this flag tostatic types.

Inheritance:

This flag is not inherited.

Added in version 3.10.

Py_TPFLAGS_DISALLOW_INSTANTIATION¶

Disallow creating instances of the type: settp_new to NULL and don’t create the__new__key in the type dictionary.

The flag must be set before creating the type, not after. For example, itmust be set beforePyType_Ready() is called on the type.

The flag is set automatically onstatic types iftp_base is NULL or&PyBaseObject_Type andtp_new is NULL.

Inheritance:

This flag is not inherited.However, subclasses will not be instantiable unless they provide anon-NULLtp_new (which is only possiblevia the C API).

Note

To disallow instantiating a class directly but allow instantiatingits subclasses (e.g. for anabstract base class),do not use this flag.Instead, maketp_new only succeed forsubclasses.

Added in version 3.10.

Py_TPFLAGS_MAPPING¶

This bit indicates that instances of the class may match mapping patternswhen used as the subject of amatch block. It is automaticallyset when registering or subclassingcollections.abc.Mapping, andunset when registeringcollections.abc.Sequence.

Note

Py_TPFLAGS_MAPPING andPy_TPFLAGS_SEQUENCE aremutually exclusive; it is an error to enable both flags simultaneously.

Inheritance:

This flag is inherited by types that do not already setPy_TPFLAGS_SEQUENCE.

See also

PEP 634 – Structural Pattern Matching: Specification

Added in version 3.10.

Py_TPFLAGS_SEQUENCE¶

This bit indicates that instances of the class may match sequence patternswhen used as the subject of amatch block. It is automaticallyset when registering or subclassingcollections.abc.Sequence, andunset when registeringcollections.abc.Mapping.

Note

Py_TPFLAGS_MAPPING andPy_TPFLAGS_SEQUENCE aremutually exclusive; it is an error to enable both flags simultaneously.

Inheritance:

This flag is inherited by types that do not already setPy_TPFLAGS_MAPPING.

See also

PEP 634 – Structural Pattern Matching: Specification

Added in version 3.10.

Py_TPFLAGS_VALID_VERSION_TAG¶

Internal. Do not set or unset this flag.To indicate that a class has changed callPyType_Modified()

Warning

This flag is present in header files, but is not be used.It will be removed in a future version of CPython

constchar*PyTypeObject.tp_doc¶

An optional pointer to a NUL-terminated C string giving the docstring for thistype object. This is exposed as the__doc__ attribute on thetype and instances of the type.

Inheritance:

This field isnot inherited by subtypes.

traverseprocPyTypeObject.tp_traverse¶

An optional pointer to a traversal function for the garbage collector. This isonly used if thePy_TPFLAGS_HAVE_GC flag bit is set. The signature is:

inttp_traverse(PyObject*self,visitprocvisit,void*arg);

More information about Python’s garbage collection scheme can be foundin sectionSupporting Cyclic Garbage Collection.

Thetp_traverse pointer is used by the garbage collector to detectreference cycles. A typical implementation of atp_traverse functionsimply callsPy_VISIT() on each of the instance’s members that are Pythonobjects that the instance owns. For example, this is functionlocal_traverse() from the_thread extension module:

staticintlocal_traverse(localobject*self,visitprocvisit,void*arg){Py_VISIT(self->args);Py_VISIT(self->kw);Py_VISIT(self->dict);return0;}

Note thatPy_VISIT() is called only on those members that can participatein reference cycles. Although there is also aself->key member, it can onlybeNULL or a Python string and therefore cannot be part of a reference cycle.

On the other hand, even if you know a member can never be part of a cycle, as adebugging aid you may want to visit it anyway just so thegc module’sget_referents() function will include it.

Heap types (Py_TPFLAGS_HEAPTYPE) must visit their type with:

Py_VISIT(Py_TYPE(self));

It is only needed since Python 3.9. To support Python 3.8 and older, thisline must be conditional:

#if PY_VERSION_HEX >= 0x03090000Py_VISIT(Py_TYPE(self));#endif

If thePy_TPFLAGS_MANAGED_DICT bit is set in thetp_flags field, the traverse function must callPyObject_VisitManagedDict() like this:

PyObject_VisitManagedDict((PyObject*)self,visit,arg);

Warning

When implementingtp_traverse, only themembers that the instanceowns (by havingstrong references to them) must bevisited. For instance, if an object supports weak references via thetp_weaklist slot, the pointer supportingthe linked list (whattp_weaklist points to) mustnot bevisited as the instance does not directly own the weak references to itself(the weakreference list is there to support the weak reference machinery,but the instance has no strong reference to the elements inside it, as theyare allowed to be removed even if the instance is still alive).

Note thatPy_VISIT() requires thevisit andarg parameters tolocal_traverse() to have these specific names; don’t name them justanything.

Instances ofheap-allocated types hold a reference totheir type. Their traversal function must therefore either visitPy_TYPE(self), or delegate this responsibility bycallingtp_traverse of another heap-allocated type (such as aheap-allocated superclass).If they do not, the type object may not be garbage-collected.

Changed in version 3.9:Heap-allocated types are expected to visitPy_TYPE(self) intp_traverse. In earlier versions of Python, due tobug 40217, doing thismay lead to crashes in subclasses.

Inheritance:

Group:Py_TPFLAGS_HAVE_GC,tp_traverse,tp_clear

This field is inherited by subtypes together withtp_clear and thePy_TPFLAGS_HAVE_GC flag bit: the flag bit,tp_traverse, andtp_clear are all inherited from the base type if they are all zero inthe subtype.

inquiryPyTypeObject.tp_clear¶

An optional pointer to a clear function for the garbage collector. This is onlyused if thePy_TPFLAGS_HAVE_GC flag bit is set. The signature is:

inttp_clear(PyObject*);

Thetp_clear member function is used to break reference cycles in cyclicgarbage detected by the garbage collector. Taken together, alltp_clearfunctions in the system must combine to break all reference cycles. This issubtle, and if in any doubt supply atp_clear function. For example,the tuple type does not implement atp_clear function, because it’spossible to prove that no reference cycle can be composed entirely of tuples.Therefore thetp_clear functions of other types must be sufficient tobreak any cycle containing a tuple. This isn’t immediately obvious, and there’srarely a good reason to avoid implementingtp_clear.

Implementations oftp_clear should drop the instance’s references tothose of its members that may be Python objects, and set its pointers to thosemembers toNULL, as in the following example:

staticintlocal_clear(localobject*self){Py_CLEAR(self->key);Py_CLEAR(self->args);Py_CLEAR(self->kw);Py_CLEAR(self->dict);return0;}

ThePy_CLEAR() macro should be used, because clearing references isdelicate: the reference to the contained object must not be released(viaPy_DECREF()) untilafter the pointer to the contained object is set toNULL. This is becausereleasing the reference may cause the contained object to become trash,triggering a chain of reclamation activity that may include invoking arbitraryPython code (due to finalizers, or weakref callbacks, associated with thecontained object). If it’s possible for such code to referenceself again,it’s important that the pointer to the contained object beNULL at that time,so thatself knows the contained object can no longer be used. ThePy_CLEAR() macro performs the operations in a safe order.

If thePy_TPFLAGS_MANAGED_DICT bit is set in thetp_flags field, the traverse function must callPyObject_ClearManagedDict() like this:

PyObject_ClearManagedDict((PyObject*)self);

Note thattp_clear is notalways calledbefore an instance is deallocated. For example, when reference countingis enough to determine that an object is no longer used, the cyclic garbagecollector is not involved andtp_dealloc iscalled directly.

Because the goal oftp_clear functions is to break reference cycles,it’s not necessary to clear contained objects like Python strings or Pythonintegers, which can’t participate in reference cycles. On the other hand, it maybe convenient to clear all contained Python objects, and write the type’stp_dealloc function to invoketp_clear.

More information about Python’s garbage collection scheme can be found insectionSupporting Cyclic Garbage Collection.

Inheritance:

Group:Py_TPFLAGS_HAVE_GC,tp_traverse,tp_clear

This field is inherited by subtypes together withtp_traverse and thePy_TPFLAGS_HAVE_GC flag bit: the flag bit,tp_traverse, andtp_clear are all inherited from the base type if they are all zero inthe subtype.

richcmpfuncPyTypeObject.tp_richcompare¶

An optional pointer to the rich comparison function, whose signature is:

PyObject*tp_richcompare(PyObject*self,PyObject*other,intop);

The first parameter is guaranteed to be an instance of the typethat is defined byPyTypeObject.

The function should return the result of the comparison (usuallyPy_TrueorPy_False). If the comparison is undefined, it must returnPy_NotImplemented, if another error occurred it must returnNULL andset an exception condition.

The following constants are defined to be used as the third argument fortp_richcompare and forPyObject_RichCompare():

Constant	Comparison
Py_LT¶	<
Py_LE¶	<=
Py_EQ¶	==
Py_NE¶	!=
Py_GT¶	>
Py_GE¶	>=

The following macro is defined to ease writing rich comparison functions:

Py_RETURN_RICHCOMPARE(VAL_A,VAL_B,op)¶

ReturnPy_True orPy_False from the function, depending on theresult of a comparison.VAL_A and VAL_B must be orderable by C comparison operators (for example,they may be C ints or floats). The third argument specifies the requestedoperation, as forPyObject_RichCompare().

The returned value is a newstrong reference.

On error, sets an exception and returnsNULL from the function.

Added in version 3.7.

Inheritance:

Group:tp_hash,tp_richcompare

This field is inherited by subtypes together withtp_hash:a subtype inheritstp_richcompare andtp_hash whenthe subtype’stp_richcompare andtp_hash are bothNULL.

Default:

PyBaseObject_Type provides atp_richcompareimplementation, which may be inherited. However, if onlytp_hash is defined, not even the inherited function is usedand instances of the type will not be able to participate in anycomparisons.

Py_ssize_tPyTypeObject.tp_weaklistoffset¶

While this field is still supported,Py_TPFLAGS_MANAGED_WEAKREFshould be used instead, if at all possible.

If the instances of this type are weakly referenceable, this field is greaterthan zero and contains the offset in the instance structure of the weakreference list head (ignoring the GC header, if present); this offset is used byPyObject_ClearWeakRefs() and thePyWeakref_* functions. Theinstance structure needs to include a field of typePyObject* which isinitialized toNULL.

Do not confuse this field withtp_weaklist; that is the list head forweak references to the type object itself.

It is an error to set both thePy_TPFLAGS_MANAGED_WEAKREF bit andtp_weaklistoffset.

Inheritance:

This field is inherited by subtypes, but see the rules listed below. A subtypemay override this offset; this means that the subtype uses a different weakreference list head than the base type. Since the list head is always found viatp_weaklistoffset, this should not be a problem.

Default:

If thePy_TPFLAGS_MANAGED_WEAKREF bit is set in thetp_flags field, thentp_weaklistoffset will be set to a negative value,to indicate that it is unsafe to use this field.

getiterfuncPyTypeObject.tp_iter¶

An optional pointer to a function that returns aniterator for theobject. Its presence normally signals that the instances of this type areiterable (although sequences may be iterable without this function).

This function has the same signature asPyObject_GetIter():

PyObject*tp_iter(PyObject*self);

Inheritance:

This field is inherited by subtypes.

iternextfuncPyTypeObject.tp_iternext¶

An optional pointer to a function that returns the next item in aniterator. The signature is:

PyObject*tp_iternext(PyObject*self);

When the iterator is exhausted, it must returnNULL; aStopIterationexception may or may not be set. When another error occurs, it must returnNULL too. Its presence signals that the instances of this type areiterators.

Iterator types should also define thetp_iter function, and thatfunction should return the iterator instance itself (not a new iteratorinstance).

This function has the same signature asPyIter_Next().

Inheritance:

This field is inherited by subtypes.

structPyMethodDef*PyTypeObject.tp_methods¶

An optional pointer to a staticNULL-terminated array ofPyMethodDefstructures, declaring regular methods of this type.

For each entry in the array, an entry is added to the type’s dictionary (seetp_dict below) containing a method descriptor.

Inheritance:

This field is not inherited by subtypes (methods are inherited through adifferent mechanism).

structPyMemberDef*PyTypeObject.tp_members¶

An optional pointer to a staticNULL-terminated array ofPyMemberDefstructures, declaring regular data members (fields or slots) of instances ofthis type.

For each entry in the array, an entry is added to the type’s dictionary (seetp_dict below) containing a member descriptor.

Inheritance:

This field is not inherited by subtypes (members are inherited through adifferent mechanism).

structPyGetSetDef*PyTypeObject.tp_getset¶

An optional pointer to a staticNULL-terminated array ofPyGetSetDefstructures, declaring computed attributes of instances of this type.

For each entry in the array, an entry is added to the type’s dictionary (seetp_dict below) containing a getset descriptor.

Inheritance:

This field is not inherited by subtypes (computed attributes are inheritedthrough a different mechanism).

PyTypeObject*PyTypeObject.tp_base¶

An optional pointer to a base type from which type properties are inherited. Atthis level, only single inheritance is supported; multiple inheritance requiredynamically creating a type object by calling the metatype.

Note

Slot initialization is subject to the rules of initializing globals.C99 requires the initializers to be “address constants”. Functiondesignators likePyType_GenericNew(), with implicit conversionto a pointer, are valid C99 address constants.

However, the unary ‘&’ operator applied to a non-static variablelikePyBaseObject_Type is not required to produce an addressconstant. Compilers may support this (gcc does), MSVC does not.Both compilers are strictly standard conforming in this particularbehavior.

Consequently,tp_base should be set inthe extension module’s init function.

Inheritance:

This field is not inherited by subtypes (obviously).

Default:

This field defaults to&PyBaseObject_Type (which to Pythonprogrammers is known as the typeobject).

PyObject*PyTypeObject.tp_dict¶

The type’s dictionary is stored here byPyType_Ready().

This field should normally be initialized toNULL before PyType_Ready iscalled; it may also be initialized to a dictionary containing initial attributesfor the type. OncePyType_Ready() has initialized the type, extraattributes for the type may be added to this dictionary only if they don’tcorrespond to overloaded operations (like__add__()). Onceinitialization for the type has finished, this field should betreated as read-only.

Some types may not store their dictionary in this slot.UsePyType_GetDict() to retrieve the dictionary for an arbitrarytype.

Changed in version 3.12:Internals detail: For static builtin types, this is alwaysNULL.Instead, the dict for such types is stored onPyInterpreterState.UsePyType_GetDict() to get the dict for an arbitrary type.

Inheritance:

This field is not inherited by subtypes (though the attributes defined in hereare inherited through a different mechanism).

Default:

If this field isNULL,PyType_Ready() will assign a newdictionary to it.

Warning

It is not safe to usePyDict_SetItem() on or otherwise modifytp_dict with the dictionary C-API.

descrgetfuncPyTypeObject.tp_descr_get¶

An optional pointer to a “descriptor get” function.

The function signature is:

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

Inheritance:

This field is inherited by subtypes.

descrsetfuncPyTypeObject.tp_descr_set¶

An optional pointer to a function for setting and deletinga descriptor’s value.

The function signature is:

inttp_descr_set(PyObject*self,PyObject*obj,PyObject*value);

Thevalue argument is set toNULL to delete the value.

Inheritance:

This field is inherited by subtypes.

Py_ssize_tPyTypeObject.tp_dictoffset¶

While this field is still supported,Py_TPFLAGS_MANAGED_DICT should beused instead, if at all possible.

If the instances of this type have a dictionary containing instance variables,this field is non-zero and contains the offset in the instances of the type ofthe instance variable dictionary; this offset is used byPyObject_GenericGetAttr().

Do not confuse this field withtp_dict; that is the dictionary forattributes of the type object itself.

The value specifies the offset of the dictionary from the start of the instance structure.

Thetp_dictoffset should be regarded as write-only.To get the pointer to the dictionary callPyObject_GenericGetDict().CallingPyObject_GenericGetDict() may need to allocate memory for thedictionary, so it is may be more efficient to callPyObject_GetAttr()when accessing an attribute on the object.

It is an error to set both thePy_TPFLAGS_MANAGED_DICT bit andtp_dictoffset.

Inheritance:

This field is inherited by subtypes. A subtype should not override this offset;doing so could be unsafe, if C code tries to access the dictionary at theprevious offset.To properly support inheritance, usePy_TPFLAGS_MANAGED_DICT.

Default:

This slot has no default. Forstatic types, if thefield isNULL then no__dict__ gets created for instances.

If thePy_TPFLAGS_MANAGED_DICT bit is set in thetp_flags field, thentp_dictoffset will be set to-1, to indicatethat it is unsafe to use this field.

initprocPyTypeObject.tp_init¶

An optional pointer to an instance initialization function.

This function corresponds to the__init__() method of classes. Like__init__(), it is possible to create an instance without calling__init__(), and it is possible to reinitialize an instance by calling its__init__() method again.

The function signature is:

inttp_init(PyObject*self,PyObject*args,PyObject*kwds);

The self argument is the instance to be initialized; theargs andkwdsarguments represent positional and keyword arguments of the call to__init__().

Thetp_init function, if notNULL, is called when an instance iscreated normally by calling its type, after the type’stp_new functionhas returned an instance of the type. If thetp_new function returns aninstance of some other type that is not a subtype of the original type, notp_init function is called; iftp_new returns an instance of asubtype of the original type, the subtype’stp_init is called.

Returns0 on success,-1 and sets an exception on error.

Inheritance:

This field is inherited by subtypes.

Default:

Forstatic types this field does not have a default.

allocfuncPyTypeObject.tp_alloc¶

An optional pointer to an instance allocation function.

The function signature is:

PyObject*tp_alloc(PyTypeObject*self,Py_ssize_tnitems);

Inheritance:

This field is inherited by static subtypes, but not by dynamicsubtypes (subtypes created by a class statement).

Default:

For dynamic subtypes, this field is always set toPyType_GenericAlloc(), to force a standard heapallocation strategy.

For static subtypes,PyBaseObject_Type usesPyType_GenericAlloc(). That is the recommended valuefor all statically defined types.

newfuncPyTypeObject.tp_new¶

An optional pointer to an instance creation function.

The function signature is:

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

Thesubtype argument is the type of the object being created; theargs andkwds arguments represent positional and keyword arguments of the call to thetype. Note thatsubtype doesn’t have to equal the type whosetp_newfunction is called; it may be a subtype of that type (but not an unrelatedtype).

Thetp_new function should callsubtype->tp_alloc(subtype,nitems)to allocate space for the object, and then do only as much furtherinitialization as is absolutely necessary. Initialization that can safely beignored or repeated should be placed in thetp_init handler. A goodrule of thumb is that for immutable types, all initialization should take placeintp_new, while for mutable types, most initialization should bedeferred totp_init.

Set thePy_TPFLAGS_DISALLOW_INSTANTIATION flag to disallow creatinginstances of the type in Python.

Inheritance:

This field is inherited by subtypes, except it is not inherited bystatic types whosetp_baseisNULL or&PyBaseObject_Type.

Default:

Forstatic types this field has no default.This means if the slot is defined asNULL, the type cannot be calledto create new instances; presumably there is some other way to createinstances, like a factory function.

freefuncPyTypeObject.tp_free¶

An optional pointer to an instance deallocation function. Its signature is:

voidtp_free(void*self);

An initializer that is compatible with this signature isPyObject_Free().

Inheritance:

This field is inherited by static subtypes, but not by dynamicsubtypes (subtypes created by a class statement)

Default:

In dynamic subtypes, this field is set to a deallocator suitable tomatchPyType_GenericAlloc() and the value of thePy_TPFLAGS_HAVE_GC flag bit.

For static subtypes,PyBaseObject_Type usesPyObject_Del().

inquiryPyTypeObject.tp_is_gc¶

An optional pointer to a function called by the garbage collector.

The garbage collector needs to know whether a particular object is collectibleor not. Normally, it is sufficient to look at the object’s type’stp_flags field, and check thePy_TPFLAGS_HAVE_GC flag bit. Butsome types have a mixture of statically and dynamically allocated instances, andthe statically allocated instances are not collectible. Such types shoulddefine this function; it should return1 for a collectible instance, and0 for a non-collectible instance. The signature is:

inttp_is_gc(PyObject*self);

(The only example of this are types themselves. The metatype,PyType_Type, defines this function to distinguish between staticallyanddynamically allocated types.)

Inheritance:

This field is inherited by subtypes.

Default:

This slot has no default. If this field isNULL,Py_TPFLAGS_HAVE_GC is used as the functional equivalent.

PyObject*PyTypeObject.tp_bases¶

Tuple of base types.

This field should be set toNULL and treated as read-only.Python will fill it in when the type isinitialized.

For dynamically created classes, thePy_tp_basesslot can be used instead of thebases argumentofPyType_FromSpecWithBases().The argument form is preferred.

Warning

Multiple inheritance does not work well for statically defined types.If you settp_bases to a tuple, Python will not raise an error,but some slots will only be inherited from the first base.

Inheritance:

This field is not inherited.

PyObject*PyTypeObject.tp_mro¶

Tuple containing the expanded set of base types, starting with the type itselfand ending withobject, in Method Resolution Order.

This field should be set toNULL and treated as read-only.Python will fill it in when the type isinitialized.

Inheritance:

This field is not inherited; it is calculated fresh byPyType_Ready().

PyObject*PyTypeObject.tp_cache¶

Unused. Internal use only.

Inheritance:

This field is not inherited.

void*PyTypeObject.tp_subclasses¶

A collection of subclasses. Internal use only. May be an invalid pointer.

To get a list of subclasses, call the Python method__subclasses__().

Changed in version 3.12:For some types, this field does not hold a validPyObject*.The type was changed tovoid* to indicate this.

Inheritance:

This field is not inherited.

PyObject*PyTypeObject.tp_weaklist¶

Weak reference list head, for weak references to this type object. Notinherited. Internal use only.

Changed in version 3.12:Internals detail: For the static builtin types this is alwaysNULL,even if weakrefs are added. Instead, the weakrefs for each are storedonPyInterpreterState. Use the public C-API or the internal_PyObject_GET_WEAKREFS_LISTPTR() macro to avoid the distinction.

Inheritance:

This field is not inherited.

destructorPyTypeObject.tp_del¶

This field is deprecated. Usetp_finalize instead.

unsignedintPyTypeObject.tp_version_tag¶

Used to index into the method cache. Internal use only.

Inheritance:

This field is not inherited.

destructorPyTypeObject.tp_finalize¶

An optional pointer to an instance finalization function. Its signature is:

voidtp_finalize(PyObject*self);

Iftp_finalize is set, the interpreter calls it once whenfinalizing an instance. It is called either from the garbagecollector (if the instance is part of an isolated reference cycle) orjust before the object is deallocated. Either way, it is guaranteedto be called before attempting to break reference cycles, ensuringthat it finds the object in a sane state.

tp_finalize should not mutate the current exception status;therefore, a recommended way to write a non-trivial finalizer is:

staticvoidlocal_finalize(PyObject*self){/* Save the current exception, if any. */PyObject*exc=PyErr_GetRaisedException();/* ... *//* Restore the saved exception. */PyErr_SetRaisedException(exc);}

Inheritance:

This field is inherited by subtypes.

Added in version 3.4.

Changed in version 3.8:Before version 3.8 it was necessary to set thePy_TPFLAGS_HAVE_FINALIZE flags bit in order for this field to beused. This is no longer required.

See also

“Safe object finalization” (PEP 442)

vectorcallfuncPyTypeObject.tp_vectorcall¶

Vectorcall function to use for calls of this type object.In other words, it is used to implementvectorcall fortype.__call__.Iftp_vectorcall isNULL, the default call implementationusing__new__() and__init__() is used.

Inheritance:

This field is never inherited.

Added in version 3.9:(the field exists since 3.8 but it’s only used since 3.9)

unsignedcharPyTypeObject.tp_watched¶

Internal. Do not use.

Added in version 3.12.

Static Types¶

Traditionally, types defined in C code arestatic, that is,a staticPyTypeObject structure is defined directly in codeand initialized usingPyType_Ready().

This results in types that are limited relative to types defined in Python:

• Static types are limited to one base, i.e. they cannot use multipleinheritance.

• Static type objects (but not necessarily their instances) are immutable.It is not possible to add or modify the type object’s attributes from Python.

• Static type objects are shared acrosssub-interpreters, so they should notinclude any subinterpreter-specific state.

Also, sincePyTypeObject is only part of theLimited API as an opaque struct, any extension modules using static types must becompiled for a specific Python minor version.

Heap Types¶

An alternative tostatic types isheap-allocated types,orheap types for short, which correspond closely to classes created byPython’sclass statement. Heap types have thePy_TPFLAGS_HEAPTYPEflag set.

This is done by filling aPyType_Spec structure and callingPyType_FromSpec(),PyType_FromSpecWithBases(),PyType_FromModuleAndSpec(), orPyType_FromMetaclass().

Number Object Structures¶

typePyNumberMethods¶

This structure holds pointers to the functions which an object uses toimplement the number protocol. Each function is used by the function ofsimilar name documented in theNumber Protocol section.

Here is the structure definition:

typedefstruct{binaryfuncnb_add;binaryfuncnb_subtract;binaryfuncnb_multiply;binaryfuncnb_remainder;binaryfuncnb_divmod;ternaryfuncnb_power;unaryfuncnb_negative;unaryfuncnb_positive;unaryfuncnb_absolute;inquirynb_bool;unaryfuncnb_invert;binaryfuncnb_lshift;binaryfuncnb_rshift;binaryfuncnb_and;binaryfuncnb_xor;binaryfuncnb_or;unaryfuncnb_int;void*nb_reserved;unaryfuncnb_float;binaryfuncnb_inplace_add;binaryfuncnb_inplace_subtract;binaryfuncnb_inplace_multiply;binaryfuncnb_inplace_remainder;ternaryfuncnb_inplace_power;binaryfuncnb_inplace_lshift;binaryfuncnb_inplace_rshift;binaryfuncnb_inplace_and;binaryfuncnb_inplace_xor;binaryfuncnb_inplace_or;binaryfuncnb_floor_divide;binaryfuncnb_true_divide;binaryfuncnb_inplace_floor_divide;binaryfuncnb_inplace_true_divide;unaryfuncnb_index;binaryfuncnb_matrix_multiply;binaryfuncnb_inplace_matrix_multiply;}PyNumberMethods;

Note

Binary and ternary functions must check the type of all their operands,and implement the necessary conversions (at least one of the operands isan instance of the defined type). If the operation is not defined for thegiven operands, binary and ternary functions must returnPy_NotImplemented, if another error occurred they must returnNULLand set an exception.

Note

Thenb_reserved field should always beNULL. Itwas previously callednb_long, and was renamed inPython 3.0.1.

binaryfuncPyNumberMethods.nb_add¶

binaryfuncPyNumberMethods.nb_subtract¶

binaryfuncPyNumberMethods.nb_multiply¶

binaryfuncPyNumberMethods.nb_remainder¶

binaryfuncPyNumberMethods.nb_divmod¶

ternaryfuncPyNumberMethods.nb_power¶

unaryfuncPyNumberMethods.nb_negative¶

unaryfuncPyNumberMethods.nb_positive¶

unaryfuncPyNumberMethods.nb_absolute¶

inquiryPyNumberMethods.nb_bool¶

unaryfuncPyNumberMethods.nb_invert¶

binaryfuncPyNumberMethods.nb_lshift¶

binaryfuncPyNumberMethods.nb_rshift¶

binaryfuncPyNumberMethods.nb_and¶

binaryfuncPyNumberMethods.nb_xor¶

binaryfuncPyNumberMethods.nb_or¶

unaryfuncPyNumberMethods.nb_int¶

void*PyNumberMethods.nb_reserved¶

unaryfuncPyNumberMethods.nb_float¶

binaryfuncPyNumberMethods.nb_inplace_add¶

binaryfuncPyNumberMethods.nb_inplace_subtract¶

binaryfuncPyNumberMethods.nb_inplace_multiply¶

binaryfuncPyNumberMethods.nb_inplace_remainder¶

ternaryfuncPyNumberMethods.nb_inplace_power¶

binaryfuncPyNumberMethods.nb_inplace_lshift¶

binaryfuncPyNumberMethods.nb_inplace_rshift¶

binaryfuncPyNumberMethods.nb_inplace_and¶

binaryfuncPyNumberMethods.nb_inplace_xor¶

binaryfuncPyNumberMethods.nb_inplace_or¶

binaryfuncPyNumberMethods.nb_floor_divide¶

binaryfuncPyNumberMethods.nb_true_divide¶

binaryfuncPyNumberMethods.nb_inplace_floor_divide¶

binaryfuncPyNumberMethods.nb_inplace_true_divide¶

unaryfuncPyNumberMethods.nb_index¶

binaryfuncPyNumberMethods.nb_matrix_multiply¶

binaryfuncPyNumberMethods.nb_inplace_matrix_multiply¶

Mapping Object Structures¶

typePyMappingMethods¶

This structure holds pointers to the functions which an object uses toimplement the mapping protocol. It has three members:

lenfuncPyMappingMethods.mp_length¶

This function is used byPyMapping_Size() andPyObject_Size(), and has the same signature. This slot may be set toNULL if the object has no defined length.

binaryfuncPyMappingMethods.mp_subscript¶

This function is used byPyObject_GetItem() andPySequence_GetSlice(), and has the same signature asPyObject_GetItem(). This slot must be filled for thePyMapping_Check() function to return1, it can beNULLotherwise.

objobjargprocPyMappingMethods.mp_ass_subscript¶

This function is used byPyObject_SetItem(),PyObject_DelItem(),PySequence_SetSlice() andPySequence_DelSlice(). It has the same signature asPyObject_SetItem(), butv can also be set toNULL to deletean item. If this slot isNULL, the object does not support itemassignment and deletion.

Sequence Object Structures¶

typePySequenceMethods¶

This structure holds pointers to the functions which an object uses toimplement the sequence protocol.

lenfuncPySequenceMethods.sq_length¶

This function is used byPySequence_Size() andPyObject_Size(), and has the same signature. It is also used forhandling negative indices via thesq_itemand thesq_ass_item slots.

binaryfuncPySequenceMethods.sq_concat¶

This function is used byPySequence_Concat() and has the samesignature. It is also used by the+ operator, after trying the numericaddition via thenb_add slot.

ssizeargfuncPySequenceMethods.sq_repeat¶

This function is used byPySequence_Repeat() and has the samesignature. It is also used by the* operator, after trying numericmultiplication via thenb_multiply slot.

ssizeargfuncPySequenceMethods.sq_item¶

This function is used byPySequence_GetItem() and has the samesignature. It is also used byPyObject_GetItem(), after tryingthe subscription via themp_subscript slot.This slot must be filled for thePySequence_Check()function to return1, it can beNULL otherwise.

Negative indexes are handled as follows: if thesq_length slot isfilled, it is called and the sequence length is used to compute a positiveindex which is passed tosq_item. Ifsq_length isNULL,the index is passed as is to the function.

ssizeobjargprocPySequenceMethods.sq_ass_item¶

This function is used byPySequence_SetItem() and has the samesignature. It is also used byPyObject_SetItem() andPyObject_DelItem(), after trying the item assignment and deletionvia themp_ass_subscript slot.This slot may be left toNULL if the object does not supportitem assignment and deletion.

objobjprocPySequenceMethods.sq_contains¶

This function may be used byPySequence_Contains() and has the samesignature. This slot may be left toNULL, in this casePySequence_Contains() simply traverses the sequence until itfinds a match.

binaryfuncPySequenceMethods.sq_inplace_concat¶

This function is used byPySequence_InPlaceConcat() and has the samesignature. It should modify its first operand, and return it. This slotmay be left toNULL, in this casePySequence_InPlaceConcat()will fall back toPySequence_Concat(). It is also used by theaugmented assignment+=, after trying numeric in-place additionvia thenb_inplace_add slot.

ssizeargfuncPySequenceMethods.sq_inplace_repeat¶

This function is used byPySequence_InPlaceRepeat() and has the samesignature. It should modify its first operand, and return it. This slotmay be left toNULL, in this casePySequence_InPlaceRepeat()will fall back toPySequence_Repeat(). It is also used by theaugmented assignment*=, after trying numeric in-place multiplicationvia thenb_inplace_multiply slot.

Buffer Object Structures¶

typePyBufferProcs¶

This structure holds pointers to the functions required by theBuffer protocol. The protocol defines howan exporter object can expose its internal data to consumer objects.