Common Object Structures

There are a large number of structures which are used in the definition of object types for Python. This section describes these structures and how they are used.

Base object types and macros

All Python objects ultimately share a small number of fields at the beginning of the object’s representation in memory. These are represented by the PyObjectandPyVarObjecttypes, which are defined, in turn, by the expansions of some macros also used, whether directly or indirectly, in the definition of all other Python objects. Additional macros can be found underreference 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 which contains the information Python needs to treat a pointer to an object as an object. In a normal “release” build, it contains only the object’s reference count and a pointer to the corresponding type object. Nothing is actually declared to be aPyObject,but every pointer to a Python object can be cast to aPyObject*.Access to the members must be done by using the macrosPy_REFCNTand Py_TYPE.

typePyVarObject

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

This is an extension ofPyObjectthat adds theob_size field. This is only used for objects that have some notion oflength. This type does not often appear in the Python/C API. Access to the members must be done by using the macros Py_REFCNT,Py_TYPE,andPy_SIZE.

PyObject_HEAD

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

PyObjectob_base;

See documentation ofPyObjectabove.

PyObject_VAR_HEAD

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

PyVarObjectob_base;

See documentation ofPyVarObjectabove.

intPy_Is(PyObject*x,PyObject*y)

Part of theStable ABIsince version 3.10.

Test if thexobject is theyobject, the same asxisyin Python.

Added in version 3.10.

intPy_IsNone(PyObject*x)

Part of theStable ABIsince version 3.10.

Test if an object is theNonesingleton, the same asxisNonein Python.

Added in version 3.10.

intPy_IsTrue(PyObject*x)

Part of theStable ABIsince version 3.10.

Test if an object is theTruesingleton, the same asxisTruein Python.

Added in version 3.10.

intPy_IsFalse(PyObject*x)

Part of theStable ABIsince version 3.10.

Test if an object is theFalsesingleton, the same asxisFalsein Python.

Added in version 3.10.

PyTypeObject*Py_TYPE(PyObject*o)

Return value: Borrowed reference.

Get the type of the Python objecto.

Return aborrowed reference.

Use thePy_SET_TYPE()function to set an object type.

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 objectotype istype.Return zero otherwise. Equivalent to:Py_TYPE(o)==type.

Added in version 3.9.

voidPy_SET_TYPE(PyObject*o,PyTypeObject*type)

Set the objectotype totype.

Added in version 3.9.

Py_ssize_tPy_SIZE(PyVarObject*o)

Get the size of the Python objecto.

Use thePy_SET_SIZE()function to set an object size.

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 the objectosize tosize.

Added in version 3.9.

PyObject_HEAD_INIT(type)

This is a macro which expands to initialization values for a new PyObjecttype. This macro expands to:

_PyObject_EXTRA_INIT
1,type,

PyVarObject_HEAD_INIT(type,size)

This is a macro which expands to initialization values for a new PyVarObjecttype, including theob_sizefield. This macro expands to:

_PyObject_EXTRA_INIT
1,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 return one such value. If the return value isNULL,an exception shall have been set. If notNULL,the return value is interpreted as the return value of the function as exposed in Python. The function must return a new reference.

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 C with signatureMETH_VARARGS | METH_KEYWORDS. The function signature is:

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

typePyCFunctionFast

Part of theStable ABIsince version 3.13.

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

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

typePyCFunctionFastWithKeywords

Part of theStable ABIsince version 3.13.

Type of the functions used to implement Python callables in C with 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 C with 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 has four 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_methis a C function pointer. The functions may be of different types, but they always returnPyObject*.If the function is not of thePyCFunction,the compiler will require a cast in the method table. Even thoughPyCFunctiondefines the first parameter as PyObject*,it is common that the method implementation uses the specific C type of theselfobject.

Theml_flagsfield is a bitfield which can include the following flags. The individual flags indicate either a calling convention or a binding convention.

There are these calling conventions:

METH_VARARGS

This is the typical calling convention, where the methods have the type PyCFunction.The function expects twoPyObject*values. The first one is theselfobject for methods; for module functions, it is the module object. The second parameter (often calledargs) is a tuple object representing all arguments. This parameter is typically processed usingPyArg_ParseTuple()orPyArg_UnpackTuple().

METH_KEYWORDS

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

METH_VARARGS|METH_KEYWORDS

Methods with these flags must be of typePyCFunctionWithKeywords. The function expects three parameters:self,args,kwargswhere kwargsis a dictionary of all the keyword arguments or possiblyNULL if there are no keyword arguments. The parameters are typically processed usingPyArg_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 array ofPyObject*values indicating the arguments and the third parameter is the number of arguments (the length of the array).

Added in version 3.7.

Changed in version 3.10:METH_FASTCALLis now part of thestable ABI.

METH_FASTCALL|METH_KEYWORDS

Extension ofMETH_FASTCALLsupporting also keyword arguments, with methods of typePyCFunctionFastWithKeywords. Keyword arguments are passed the same way as in the vectorcall protocol: there is an additional fourthPyObject*parameter which is a tuple representing the names of the keyword arguments (which are guaranteed to be strings) or possiblyNULLif there are no keywords. The values of the keyword arguments are stored in theargsarray, 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_KEYWORDS supporting 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 for METH_FASTCALL|METH_KEYWORDSwithdefining_classargument added after self.

Added in version 3.9.

METH_NOARGS

Methods without parameters don’t need to check whether arguments are given if they are listed with theMETH_NOARGSflag. They need to be of type PyCFunction.The first parameter is typically namedselfand will hold a reference to the module or object instance. In all cases the second parameter will beNULL.

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

METH_O

Methods with a single object argument can be listed with theMETH_O flag, instead of invokingPyArg_ParseTuple()with a"O"argument. They have the typePyCFunction,with theselfparameter, and a PyObject*parameter representing the single argument.

These two constants are not used to indicate the calling convention but the binding when use with methods of classes. These may not be used for functions defined for modules. At most one of these flags may be set for any given method.

METH_CLASS

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

METH_STATIC

The method will be passedNULLas the first parameter rather than an instance of the type. This is used to createstatic methods,similar to what is created when using thestaticmethod()built-in function.

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

METH_COEXIST

The method will be loaded in place of existing definitions. Without METH_COEXIST,the default is to skip repeated definitions. Since slot wrappers are loaded before the method table, the existence of a sq_containsslot, for example, would generate a wrapped method named __contains__()and preclude the loading of a corresponding PyCFunction with the same name. With the flag defined, the PyCFunction will be loaded in place of the wrapper object and will co-exist with the slot. This is helpful because calls to PyCFunctions are optimized more than wrapper object calls.

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

Return value: New reference.Part of theStable ABIsince version 3.9.

Turnmlinto a Pythoncallableobject. The caller must ensure thatmloutlives thecallable. Typically,mlis defined as a static variable.

Theselfparameter will be passed as theselfargument to the C function inml->ml_methwhen invoked. selfcan beNULL.

Thecallableobject’s__module__attribute can be set from the givenmoduleargument. moduleshould be a Python string, which will be used as name of the module the function is defined in. If unavailable, it can be set toNoneorNULL.

See also

function.__module__

Theclsparameter will be passed as thedefining_class argument to the C function. Must be set ifMETH_METHODis 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 ABIsince 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 C struct member. When defining a class, put a NULL-terminated array of these structures in thetp_membersslot.

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 typesfor 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 (whenflagsis0), members allow both read and write access. Use thePy_READONLYflag for read-only access. Certain types, likePy_T_STRING,implyPy_READONLY. OnlyPy_T_OBJECT_EX(and legacyT_OBJECT) members can be deleted.

For heap-allocated types (created usingPyType_FromSpec()or similar), PyMemberDefmay contain a definition for the special member "__vectorcalloffset__",corresponding to tp_vectorcall_offsetin type objects. These must be defined withPy_T_PYSSIZETandPy_READONLY,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_dictoffsetand tp_weaklistoffsetcan be defined similarly using "__dictoffset__"and"__weaklistoffset__"members, but extensions are strongly encouraged to usePy_TPFLAGS_MANAGED_DICTand Py_TPFLAGS_MANAGED_WEAKREFinstead.

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

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

Part of theStable ABI.

Get an attribute belonging to the object at addressobj_addr.The attribute is described byPyMemberDefm.ReturnsNULL on error.

Changed in version 3.12:PyMember_GetOneis 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_addrto objecto. The attribute to set is described byPyMemberDefm.Returns0 if successful and a negative value on failure.

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

Member flags

The following flags can be used withPyMemberDef.flags:

Py_READONLY

Not writable.

Py_AUDIT_READ

Emit anobject.__getattr__audit event before reading.

Py_RELATIVE_OFFSET

Indicates that theoffsetof thisPyMemberDef entry indicates an offset from the subclass-specific data, rather than fromPyObject.

Can only be used as part ofPy_tp_members slotwhen creating a class using negative basicsize. It is mandatory in that case.

This flag is only used inPyType_Slot. When settingtp_membersduring class creation, Python clears it and sets PyMemberDef.offsetto the offset from thePyObjectstruct.

Changed in version 3.10:TheRESTRICTED,READ_RESTRICTEDand WRITE_RESTRICTEDmacros available with #include"structmember.h"are deprecated. READ_RESTRICTEDandRESTRICTEDare equivalent to Py_AUDIT_READ;WRITE_RESTRICTEDdoes nothing.

Changed in version 3.12:TheREADONLYmacro was renamed toPy_READONLY. ThePY_AUDIT_READmacro was renamed with thePy_prefix. The new names are now always available. Previously, these required#include"structmember.h". The header is still available and it provides the old names.

Member types

PyMemberDef.typecan be one of the following macros corresponding to various C types. When the member is accessed in Python, it will be converted to the equivalent Python type. When it is set from Python, it will be converted back to the C type. If that is not possible, an exception such asTypeErroror ValueErroris raised.

Unless marked (D), attributes defined this way cannot be deleted using e.g.delordelattr().

Macro name	C type	Python type
Py_T_BYTE	char	int
Py_T_SHORT	short	int
Py_T_INT	int	int
Py_T_LONG	long	int
Py_T_LONGLONG	longlong	int
Py_T_UBYTE	unsignedchar	int
Py_T_UINT	unsignedint	int
Py_T_USHORT	unsignedshort	int
Py_T_ULONG	unsignedlong	int
Py_T_ULONGLONG	unsignedlonglong	int
Py_T_PYSSIZET	Py_ssize_t	int
Py_T_FLOAT	float	float
Py_T_DOUBLE	double	float
Py_T_BOOL	char (written as 0 or 1)	bool
Py_T_STRING	constchar*(*)	str(RO)
Py_T_STRING_INPLACE	constchar[](*)	str(RO)
Py_T_CHAR	char(0-127)	str(**)
Py_T_OBJECT_EX	PyObject*	object(D)

(*): Zero-terminated, UTF8-encoded C string. WithPy_T_STRINGthe C representation is a pointer; withPy_T_STRING_INPLACEthe string is stored directly in the structure.

(**): String of length 1. Only ASCII is accepted.

(RO): ImpliesPy_READONLY.

(D): Can be deleted, in which case the pointer is set toNULL. Reading aNULLpointer raisesAttributeError.

Added in version 3.12:In previous versions, the macros were only available with #include"structmember.h"and were named without thePy_prefix (e.g. asT_INT). The header is still available and contains the old names, along with the following deprecated types:

T_OBJECT

LikePy_T_OBJECT_EX,butNULLis converted toNone. This results in surprising behavior in Python: deleting the attribute effectively sets it toNone.

T_NONE

AlwaysNone.Must be used withPy_READONLY.

Defining Getters and Setters

typePyGetSetDef

Part of theStable ABI(including all members).

Structure to define property-like access for a type. See also description of thePyTypeObject.tp_getsetslot.

constchar*name

attribute name

getterget

C function to get the attribute.

setterset

Optional C function to set or delete the attribute. IfNULL,the attribute is read-only.

constchar*doc

optional docstring

void*closure

Optional user data pointer, providing additional data for getter and setter.

typedefPyObject*(*getter)(PyObject*,void*)

Part of theStable ABI.

Thegetfunction takes onePyObject*parameter (the instance) and a user data pointer (the associatedclosure):

It should return a new reference on success orNULLwith a set exception on failure.

typedefint(*setter)(PyObject*,PyObject*,void*)

Part of theStable ABI.

setfunctions take twoPyObject*parameters (the instance and the value to be set) and a user data pointer (the associatedclosure):

In case the attribute should be deleted the second parameter isNULL. Should return0on success or-1with a set exception on failure.