Base object types and macros¶

All Python objects ultimately share a small number of fields at the beginningof the object’s representation in memory. These are represented by thePyObject andPyVarObject types, which are defined, in turn,by the expansions of some macros also used, whether directly or indirectly, inthe definition of all other Python objects. Additional macros can be foundunderreference counting.

typePyObject¶

Part of theLimited API. (Only some members are part of the stable ABI.)

All object types are extensions of this type. This is a type whichcontains the information Python needs to treat a pointer to an object as anobject. In a normal “release” build, it contains only the object’sreference count and a pointer to the corresponding type object.Nothing is actually declared to be aPyObject, but every pointerto a Python object can be cast to aPyObject*.

The members must not be accessed directly; instead use macros such asPy_REFCNT andPy_TYPE.

Py_ssize_tob_refcnt¶

Part of theStable ABI.

The object’s reference count, as returned byPy_REFCNT.Do not use this field directly; instead use functions and macros such asPy_REFCNT,Py_INCREF() andPy_DecRef().

The field type may be different fromPy_ssize_t, depending onbuild configuration and platform.

PyTypeObject*ob_type¶

Part of theStable ABI.

The object’s type.Do not use this field directly; usePy_TYPE andPy_SET_TYPE() instead.

typePyVarObject¶

Part of theLimited API. (Only some members are part of the stable ABI.)

An extension ofPyObject that adds theob_size field.This is intended for objects that have some notion oflength.

As withPyObject, the members must not be accessed directly;instead use macros such asPy_SIZE,Py_REFCNT andPy_TYPE.

Py_ssize_tob_size¶

Part of theStable ABI.

A size field, whose contents should be considered an object’s internalimplementation detail.

Do not use this field directly; usePy_SIZE instead.

Object creation functions such asPyObject_NewVar() willgenerally set this field to the requested size (number of items).After creation, arbitrary values can be stored inob_sizeusingPy_SET_SIZE.

To get an object’s publicly exposed length, as returned bythe Python functionlen(), usePyObject_Length()instead.

PyObject_HEAD¶

This is a macro used when declaring new types which represent objectswithout a varying length. The PyObject_HEAD macro expands to:

PyObjectob_base;

See documentation ofPyObject above.

PyObject_VAR_HEAD¶

This is a macro used when declaring new types which represent objectswith a length that varies from instance to instance.The PyObject_VAR_HEAD macro expands to:

PyVarObjectob_base;

See documentation ofPyVarObject above.

PyTypeObjectPyBaseObject_Type¶

Part of theStable ABI.

The base class of all other objects, the same asobject in Python.

intPy_Is(PyObject*x,PyObject*y)¶

Part of theStable ABI since version 3.10.

Test if thex object is they object, the same asxisy in Python.

Added in version 3.10.

intPy_IsNone(PyObject*x)¶

Part of theStable ABI since version 3.10.

Test if an object is theNone singleton,the same asxisNone in Python.

Added in version 3.10.

intPy_IsTrue(PyObject*x)¶

Part of theStable ABI since version 3.10.

Test if an object is theTrue singleton,the same asxisTrue in Python.

Added in version 3.10.

intPy_IsFalse(PyObject*x)¶

Part of theStable ABI since version 3.10.

Test if an object is theFalse singleton,the same asxisFalse in Python.

Added in version 3.10.

PyTypeObject*Py_TYPE(PyObject*o)¶

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

Get the type of the Python objecto.

The returned reference isborrowed fromo.Do not release it withPy_DECREF() or similar.

Changed in version 3.11:Py_TYPE() is changed to an inline static function.The parameter type is no longerconstPyObject*.

intPy_IS_TYPE(PyObject*o,PyTypeObject*type)¶

Return non-zero if the objecto type istype. Return zero otherwise.Equivalent to:Py_TYPE(o)==type.

Added in version 3.9.

voidPy_SET_TYPE(PyObject*o,PyTypeObject*type)¶

Set the type of objecto totype, without any checking or referencecounting.

This is a very low-level operation.Consider instead setting the Python attribute__class__usingPyObject_SetAttrString() or similar.

Note that assigning an incompatible type can lead to undefined behavior.

Iftype is aheap type, the caller must create anew reference to it.Similarly, if the old type ofo is a heap type, the caller must releasea reference to that type.

Added in version 3.9.

Py_ssize_tPy_SIZE(PyVarObject*o)¶

Get theob_size field ofo.

Changed in version 3.11:Py_SIZE() is changed to an inline static function.The parameter type is no longerconstPyVarObject*.

voidPy_SET_SIZE(PyVarObject*o,Py_ssize_tsize)¶

Set theob_size field ofo tosize.

Added in version 3.9.

PyObject_HEAD_INIT(type)¶

This is a macro which expands to initialization values for a newPyObject type. This macro expands to:

_PyObject_EXTRA_INIT1,type,

PyVarObject_HEAD_INIT(type,size)¶

This is a macro which expands to initialization values for a newPyVarObject type, including theob_size field.This macro expands to:

_PyObject_EXTRA_INIT1,type,size,

Implementing functions and methods¶

typePyCFunction¶

Part of theStable ABI.

Type of the functions used to implement most Python callables in C.Functions of this type take twoPyObject* parameters and returnone such value. If the return value isNULL, an exception shall havebeen set. If notNULL, the return value is interpreted as the returnvalue of the function as exposed in Python. The function must return a newreference.

The function signature is:

PyObject*PyCFunction(PyObject*self,PyObject*args);

typePyCFunctionWithKeywords¶

Part of theStable ABI.

Type of the functions used to implement Python callables in Cwith signatureMETH_VARARGS | METH_KEYWORDS.The function signature is:

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

typePyCFunctionFast¶

Part of theStable ABI since version 3.13.

Type of the functions used to implement Python callables in Cwith signatureMETH_FASTCALL.The function signature is:

PyObject*PyCFunctionFast(PyObject*self,PyObject*const*args,Py_ssize_tnargs);

typePyCFunctionFastWithKeywords¶

Part of theStable ABI since version 3.13.

Type of the functions used to implement Python callables in Cwith signatureMETH_FASTCALL | METH_KEYWORDS.The function signature is:

PyObject*PyCFunctionFastWithKeywords(PyObject*self,PyObject*const*args,Py_ssize_tnargs,PyObject*kwnames);

typePyCMethod¶

Type of the functions used to implement Python callables in Cwith signatureMETH_METHOD | METH_FASTCALL | METH_KEYWORDS.The function signature is:

PyObject*PyCMethod(PyObject*self,PyTypeObject*defining_class,PyObject*const*args,Py_ssize_tnargs,PyObject*kwnames)

Added in version 3.9.

typePyMethodDef¶

Part of theStable ABI (including all members).

Structure used to describe a method of an extension type. This structure hasfour fields:

constchar*ml_name¶

Name of the method.

PyCFunctionml_meth¶

Pointer to the C implementation.

intml_flags¶

Flags bits indicating how the call should be constructed.

constchar*ml_doc¶

Points to the contents of the docstring.

Theml_meth is a C function pointer.The functions may be of differenttypes, but they always returnPyObject*. If the function is not ofthePyCFunction, the compiler will require a cast in the method table.Even thoughPyCFunction defines the first parameter asPyObject*, it is common that the method implementation uses thespecific C type of theself object.

Theml_flags field is a bitfield which can includethe following flags.The individual flags indicate either a calling convention or a bindingconvention.

There are these calling conventions:

METH_VARARGS¶

This is the typical calling convention, where the methods have the typePyCFunction. The function expects twoPyObject* values.The first one is theself object for methods; for module functions, it isthe module object. The second parameter (often calledargs) is a tupleobject representing all arguments. This parameter is typically processedusingPyArg_ParseTuple() orPyArg_UnpackTuple().

METH_KEYWORDS¶

Can only be used in certain combinations with other flags:METH_VARARGS | METH_KEYWORDS,METH_FASTCALL | METH_KEYWORDS andMETH_METHOD | METH_FASTCALL | METH_KEYWORDS.

METH_VARARGS|METH_KEYWORDS

Methods with these flags must be of typePyCFunctionWithKeywords.The function expects three parameters:self,args,kwargs wherekwargs is a dictionary of all the keyword arguments or possiblyNULLif there are no keyword arguments. The parameters are typically processedusingPyArg_ParseTupleAndKeywords().

METH_FASTCALL¶

Fast calling convention supporting only positional arguments.The methods have the typePyCFunctionFast.The first parameter isself, the second parameter is a C arrayofPyObject* values indicating the arguments and the thirdparameter is the number of arguments (the length of the array).

Added in version 3.7.

Changed in version 3.10:METH_FASTCALL is now part of thestable ABI.

METH_FASTCALL|METH_KEYWORDS

Extension ofMETH_FASTCALL supporting also keyword arguments,with methods of typePyCFunctionFastWithKeywords.Keyword arguments are passed the same way as in thevectorcall protocol:there is an additional fourthPyObject* parameterwhich is a tuple representing the names of the keyword arguments(which are guaranteed to be strings)or possiblyNULL if there are no keywords. The values of the keywordarguments are stored in theargs array, after the positional arguments.

Added in version 3.7.

METH_METHOD¶

Can only be used in the combination with other flags:METH_METHOD | METH_FASTCALL | METH_KEYWORDS.

METH_METHOD|METH_FASTCALL|METH_KEYWORDS

Extension ofMETH_FASTCALL | METH_KEYWORDSsupporting thedefining class, that is,the class that contains the method in question.The defining class might be a superclass ofPy_TYPE(self).

The method needs to be of typePyCMethod, the same as forMETH_FASTCALL|METH_KEYWORDS withdefining_class argument added afterself.

Added in version 3.9.

METH_NOARGS¶

Methods without parameters don’t need to check whether arguments are given ifthey are listed with theMETH_NOARGS flag. They need to be of typePyCFunction. The first parameter is typically namedself and willhold a reference to the module or object instance. In all cases the secondparameter will beNULL.

The function must have 2 parameters. Since the second parameter is unused,Py_UNUSED can be used to prevent a compiler warning.

METH_O¶

Methods with a single object argument can be listed with theMETH_Oflag, instead of invokingPyArg_ParseTuple() with a"O" argument.They have the typePyCFunction, with theself parameter, and aPyObject* parameter representing the single argument.

These two constants are not used to indicate the calling convention but thebinding when use with methods of classes. These may not be used for functionsdefined for modules. At most one of these flags may be set for any givenmethod.

METH_CLASS¶

The method will be passed the type object as the first parameter ratherthan an instance of the type. This is used to createclass methods,similar to what is created when using theclassmethod() built-infunction.

METH_STATIC¶

The method will be passedNULL as the first parameter rather than aninstance of the type. This is used to createstatic methods, similar towhat is created when using thestaticmethod() built-in function.

One other constant controls whether a method is loaded in place of anotherdefinition with the same method name.

METH_COEXIST¶

The method will be loaded in place of existing definitions. WithoutMETH_COEXIST, the default is to skip repeated definitions. Since slotwrappers are loaded before the method table, the existence of asq_contains slot, for example, would generate a wrapped method named__contains__() and preclude the loading of a correspondingPyCFunction with the same name. With the flag defined, the PyCFunctionwill be loaded in place of the wrapper object and will co-exist with theslot. This is helpful because calls to PyCFunctions are optimized morethan wrapper object calls.

PyObject*PyCMethod_New(PyMethodDef*ml,PyObject*self,PyObject*module,PyTypeObject*cls)¶

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

Turnml into a Pythoncallable object.The caller must ensure thatml outlives thecallable.Typically,ml is defined as a static variable.

Theself parameter will be passed as theself argumentto the C function inml->ml_meth when invoked.self can beNULL.

Thecallable object’s__module__ attributecan be set from the givenmodule argument.module should be a Python string,which will be used as name of the module the function is defined in.If unavailable, it can be set toNone orNULL.

See also

function.__module__

Thecls parameter will be passed as thedefining_classargument to the C function.Must be set ifMETH_METHOD is set onml->ml_flags.

Added in version 3.9.

PyObject*PyCFunction_NewEx(PyMethodDef*ml,PyObject*self,PyObject*module)¶

Return value: New reference. Part of theStable ABI.

Equivalent toPyCMethod_New(ml,self,module,NULL).

PyObject*PyCFunction_New(PyMethodDef*ml,PyObject*self)¶

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

Equivalent toPyCMethod_New(ml,self,NULL,NULL).

Accessing attributes of extension types¶

typePyMemberDef¶

Part of theStable ABI (including all members).

Structure which describes an attribute of a type which corresponds to a Cstruct member.When defining a class, put a NULL-terminated array of thesestructures in thetp_members slot.

Its fields are, in order:

constchar*name¶

Name of the member.A NULL value marks the end of aPyMemberDef[] array.

The string should be static, no copy is made of it.

inttype¶

The type of the member in the C struct.SeeMember types for the possible values.

Py_ssize_toffset¶

The offset in bytes that the member is located on the type’s object struct.

intflags¶

Zero or more of theMember flags, combined using bitwise OR.

constchar*doc¶

The docstring, or NULL.The string should be static, no copy is made of it.Typically, it is defined usingPyDoc_STR.

By default (whenflags is0), members allowboth read and write access.Use thePy_READONLY flag for read-only access.Certain types, likePy_T_STRING, implyPy_READONLY.OnlyPy_T_OBJECT_EX (and legacyT_OBJECT) members canbe deleted.

For heap-allocated types (created usingPyType_FromSpec() or similar),PyMemberDef may contain a definition for the special member"__vectorcalloffset__", corresponding totp_vectorcall_offset in type objects.This member must be defined withPy_T_PYSSIZET, and eitherPy_READONLY orPy_READONLY|Py_RELATIVE_OFFSET. For example:

staticPyMemberDefspam_type_members[]={{"__vectorcalloffset__",Py_T_PYSSIZET,offsetof(Spam_object,vectorcall),Py_READONLY},{NULL}/* Sentinel */};

(You may need to#include<stddef.h> foroffsetof().)

The legacy offsetstp_dictoffset andtp_weaklistoffset can be defined similarly using"__dictoffset__" and"__weaklistoffset__" members, but extensionsare strongly encouraged to usePy_TPFLAGS_MANAGED_DICT andPy_TPFLAGS_MANAGED_WEAKREF instead.

Changed in version 3.12:PyMemberDef is always available.Previously, it required including"structmember.h".

Changed in version 3.14:Py_RELATIVE_OFFSET is now allowed for"__vectorcalloffset__","__dictoffset__" and"__weaklistoffset__".

PyObject*PyMember_GetOne(constchar*obj_addr,structPyMemberDef*m)¶

Part of theStable ABI.

Get an attribute belonging to the object at addressobj_addr. Theattribute is described byPyMemberDefm. ReturnsNULLon error.

Changed in version 3.12:PyMember_GetOne is always available.Previously, it required including"structmember.h".

intPyMember_SetOne(char*obj_addr,structPyMemberDef*m,PyObject*o)¶

Part of theStable ABI.

Set an attribute belonging to the object at addressobj_addr to objecto.The attribute to set is described byPyMemberDefm. Returns0if successful and a negative value on failure.

Changed in version 3.12:PyMember_SetOne is always available.Previously, it required including"structmember.h".