Type Objects¶

typePyTypeObject¶

Part of theLimited API (as an opaque struct).

The C structure of the objects used to describe built-in types.

PyTypeObjectPyType_Type¶

Part of theStable ABI.

This is the type object for type objects; it is the same object astype in the Python layer.

intPyType_Check(PyObject*o)¶

Return non-zero if the objecto is a type object, including instances oftypes derived from the standard type object. Return 0 in all other cases.This function always succeeds.

intPyType_CheckExact(PyObject*o)¶

Return non-zero if the objecto is a type object, but not a subtype ofthe standard type object. Return 0 in all other cases. This functionalways succeeds.

unsignedintPyType_ClearCache()¶

Part of theStable ABI.

Clear the internal lookup cache. Return the current version tag.

unsignedlongPyType_GetFlags(PyTypeObject*type)¶

Part of theStable ABI.

Return thetp_flags member oftype. This function is primarilymeant for use withPy_LIMITED_API; the individual flag bits areguaranteed to be stable across Python releases, but access totp_flags itself is not part of thelimited API.

Added in version 3.2.

Changed in version 3.4:The return type is nowunsignedlong rather thanlong.

PyObject*PyType_GetDict(PyTypeObject*type)¶

Return the type object’s internal namespace, which is otherwise onlyexposed via a read-only proxy (cls.__dict__).This is areplacement for accessingtp_dict directly.The returned dictionary must be treated as read-only.

This function is meant for specific embedding and language-binding cases,where direct access to the dict is necessary and indirect access(e.g. via the proxy orPyObject_GetAttr()) isn’t adequate.

Extension modules should continue to usetp_dict,directly or indirectly, when setting up their own types.

Added in version 3.12.

voidPyType_Modified(PyTypeObject*type)¶

Part of theStable ABI.

Invalidate the internal lookup cache for the type and all of itssubtypes. This function must be called after any manualmodification of the attributes or base classes of the type.

intPyType_AddWatcher(PyType_WatchCallbackcallback)¶

Registercallback as a type watcher. Return a non-negative integer IDwhich must be passed to future calls toPyType_Watch(). In case oferror (e.g. no more watcher IDs available), return-1 and set anexception.

In free-threaded builds,PyType_AddWatcher() is not thread-safe,so it must be called at start up (before spawning the first thread).

Added in version 3.12.

intPyType_ClearWatcher(intwatcher_id)¶

Clear watcher identified bywatcher_id (previously returned fromPyType_AddWatcher()). Return0 on success,-1 on error (e.g.ifwatcher_id was never registered.)

An extension should never callPyType_ClearWatcher with awatcher_idthat was not returned to it by a previous call toPyType_AddWatcher().

Added in version 3.12.

intPyType_Watch(intwatcher_id,PyObject*type)¶

Marktype as watched. The callback grantedwatcher_id byPyType_AddWatcher() will be called wheneverPyType_Modified() reports a change totype. (The callback may becalled only once for a series of consecutive modifications totype, if_PyType_Lookup() is not called ontype between the modifications;this is an implementation detail and subject to change.)

An extension should never callPyType_Watch with awatcher_id that wasnot returned to it by a previous call toPyType_AddWatcher().

Added in version 3.12.

typedefint(*PyType_WatchCallback)(PyObject*type)¶

Type of a type-watcher callback function.

The callback must not modifytype or causePyType_Modified() to becalled ontype or any type in its MRO; violating this rule could causeinfinite recursion.

Added in version 3.12.

intPyType_HasFeature(PyTypeObject*o,intfeature)¶

Return non-zero if the type objecto sets the featurefeature.Type features are denoted by single bit flags.

intPyType_IS_GC(PyTypeObject*o)¶

Return true if the type object includes support for the cycle detector; thistests the type flagPy_TPFLAGS_HAVE_GC.

intPyType_IsSubtype(PyTypeObject*a,PyTypeObject*b)¶

Part of theStable ABI.

Return true ifa is a subtype ofb.

This function only checks for actual subtypes, which means that__subclasscheck__() is not called onb. CallPyObject_IsSubclass() to do the same check thatissubclass()would do.

PyObject*PyType_GenericAlloc(PyTypeObject*type,Py_ssize_tnitems)¶

Return value: New reference. Part of theStable ABI.

Generic handler for thetp_alloc slot of a typeobject. Uses Python’s default memory allocation mechanism to allocate memoryfor a new instance, zeros the memory, then initializes the memory as if bycallingPyObject_Init() orPyObject_InitVar().

Do not call this directly to allocate memory for an object; call the type’stp_alloc slot instead.

For types that support garbage collection (i.e., thePy_TPFLAGS_HAVE_GC flag is set), this function behaves likePyObject_GC_New orPyObject_GC_NewVar (except thememory is guaranteed to be zeroed before initialization), and should bepaired withPyObject_GC_Del() intp_free.Otherwise, it behaves likePyObject_New orPyObject_NewVar (except the memory is guaranteed to be zeroedbefore initialization) and should be paired withPyObject_Free() intp_free.

PyObject*PyType_GenericNew(PyTypeObject*type,PyObject*args,PyObject*kwds)¶

Return value: New reference. Part of theStable ABI.

Generic handler for thetp_new slot of a typeobject. Creates a new instance using the type’stp_alloc slot and returns the resulting object.

intPyType_Ready(PyTypeObject*type)¶

Part of theStable ABI.

Finalize a type object. This should be called on all type objects to finishtheir initialization. This function is responsible for adding inherited slotsfrom a type’s base class. Return0 on success, or return-1 and sets anexception on error.

Note

If some of the base classes implements the GC protocol and the providedtype does not include thePy_TPFLAGS_HAVE_GC in its flags, thenthe GC protocol will be automatically implemented from its parents. Onthe contrary, if the type being created does includePy_TPFLAGS_HAVE_GC in its flags then itmust implement theGC protocol itself by at least implementing thetp_traverse handle.

PyObject*PyType_GetName(PyTypeObject*type)¶

Return value: New reference. Part of theStable ABI since version 3.11.

Return the type’s name. Equivalent to getting the type’s__name__ attribute.

Added in version 3.11.

PyObject*PyType_GetQualName(PyTypeObject*type)¶

Return value: New reference. Part of theStable ABI since version 3.11.

Return the type’s qualified name. Equivalent to getting thetype’s__qualname__ attribute.

Added in version 3.11.

PyObject*PyType_GetFullyQualifiedName(PyTypeObject*type)¶

Part of theStable ABI since version 3.13.

Return the type’s fully qualified name. Equivalent tof"{type.__module__}.{type.__qualname__}", ortype.__qualname__iftype.__module__ is not a string or is equal to"builtins".

Added in version 3.13.

PyObject*PyType_GetModuleName(PyTypeObject*type)¶

Part of theStable ABI since version 3.13.

Return the type’s module name. Equivalent to getting thetype.__module__ attribute.

Added in version 3.13.

void*PyType_GetSlot(PyTypeObject*type,intslot)¶

Part of theStable ABI since version 3.4.

Return the function pointer stored in the given slot. If theresult isNULL, this indicates that either the slot isNULL,or that the function was called with invalid parameters.Callers will typically cast the result pointer into the appropriatefunction type.

SeePyType_Slot.slot for possible values of theslot argument.

Added in version 3.4.

Changed in version 3.10:PyType_GetSlot() can now accept all types.Previously, it was limited toheap types.

PyObject*PyType_GetModule(PyTypeObject*type)¶

Part of theStable ABI since version 3.10.

Return the module object associated with the given type when the type wascreated usingPyType_FromModuleAndSpec().

If no module is associated with the given type, setsTypeErrorand returnsNULL.

This function is usually used to get the module in which a method is defined.Note that in such a method,PyType_GetModule(Py_TYPE(self))may not return the intended result.Py_TYPE(self) may be asubclass of the intended class, and subclassesare not necessarily defined in the same module as their superclass.SeePyCMethod to get the class that defines the method.SeePyType_GetModuleByDef() for cases whenPyCMethod cannotbe used.

Added in version 3.9.

void*PyType_GetModuleState(PyTypeObject*type)¶

Part of theStable ABI since version 3.10.

Return the state of the module object associated with the given type.This is a shortcut for callingPyModule_GetState() on the resultofPyType_GetModule().

If no module is associated with the given type, setsTypeErrorand returnsNULL.

If thetype has an associated module but its state isNULL,returnsNULL without setting an exception.

Added in version 3.9.

PyObject*PyType_GetModuleByDef(PyTypeObject*type,structPyModuleDef*def)¶

Return value: Borrowed reference. Part of theStable ABI since version 3.13.

Find the first superclass whose module was created fromthe givenPyModuleDefdef, and return that module.

If no module is found, raises aTypeError and returnsNULL.

This function is intended to be used together withPyModule_GetState() to get module state from slot methods (such astp_init ornb_add)and other places where a method’s defining class cannot be passed using thePyCMethod calling convention.

The returned reference isborrowed fromtype,and will be valid as long as you hold a reference totype.Do not release it withPy_DECREF() or similar.

Added in version 3.11.

intPyType_GetBaseByToken(PyTypeObject*type,void*token,PyTypeObject**result)¶

Part of theStable ABI since version 3.14.

Find the first superclass intype’smethod resolution order whosePy_tp_token token is equal to the given one.

• If found, set*result to a newstrong referenceto it and return1.

• If not found, set*result toNULL and return0.

• On error, set*result toNULL and return-1 with anexception set.

Theresult argument may beNULL, in which case*result is not set.Use this if you need only the return value.

Thetoken argument may not beNULL.

Added in version 3.14.

intPyUnstable_Type_AssignVersionTag(PyTypeObject*type)¶

This isUnstable API. It may change without warning in minor releases.

Attempt to assign a version tag to the given type.

Returns 1 if the type already had a valid version tag or a new one wasassigned, or 0 if a new tag could not be assigned.

Added in version 3.12.