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)¶

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);

type_PyCFunctionFast¶

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);

type_PyCFunctionFastWithKeywords¶

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 type_PyCFunctionFast. 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 type_PyCFunctionFastWithKeywords. 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.

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.

Common Object Structures¶

Base object types and macros¶

Implementing functions and methods¶

Accessing attributes of extension types¶

Member flags¶

Member types¶

Defining Getters and Setters¶

Table of Contents

Previous topic

Next topic

This Page