Common Object Structures¶

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

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.

PyObject¶

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. Itcorresponds to the fields defined by the expansion of thePyObject_HEADmacro.

PyVarObject¶

This is an extension ofPyObject that adds theob_sizefield. This is only used for objects that have some notion oflength.This type does not often appear in the Python/C API. It corresponds to thefields defined by the expansion of thePyObject_VAR_HEAD macro.

These macros are used in the definition ofPyObject andPyVarObject:

PyObject_HEAD¶

This is a macro which expands to the declarations of the fields of thePyObject type; it is used when declaring new types which representobjects without a varying length. The specific fields it expands to dependon the definition ofPy_TRACE_REFS. By default, that macro isnot defined, andPyObject_HEAD expands to:

Py_ssize_tob_refcnt;PyTypeObject*ob_type;

WhenPy_TRACE_REFS is defined, it expands to:

PyObject*_ob_next,*_ob_prev;Py_ssize_tob_refcnt;PyTypeObject*ob_type;

PyObject_VAR_HEAD¶

This is a macro which expands to the declarations of the fields of thePyVarObject type; it is used when declaring new types whichrepresent objects with a length that varies from instance to instance.This macro always expands to:

PyObject_HEADPy_ssize_tob_size;

Note thatPyObject_HEAD is part of the expansion, and that its ownexpansion varies depending on the definition ofPy_TRACE_REFS.

Py_TYPE(o)¶

This macro is used to access theob_type member of a Python object.It expands to:

(((PyObject*)(o))->ob_type)

New in version 2.6.

Py_REFCNT(o)¶

This macro is used to access theob_refcnt member of a Pythonobject.It expands to:

(((PyObject*)(o))->ob_refcnt)

New in version 2.6.

Py_SIZE(o)¶

This macro is used to access theob_size member of a Python object.It expands to:

(((PyVarObject*)(o))->ob_size)

New in version 2.6.

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,

PyCFunction¶

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.

PyMethodDef¶

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

Field	C Type	Meaning
ml_name	char *	name of the method
ml_meth	PyCFunction	pointer to the Cimplementation
ml_flags	int	flag bits indicating how thecall should be constructed
ml_doc	char *	points to the contents of thedocstring

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 include the following flags.The individual flags indicate either a calling convention or a bindingconvention. Of the calling convention flags, onlyMETH_VARARGS andMETH_KEYWORDS can be combined. Any of the calling convention flagscan be combined with a binding flag.

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¶

Methods with these flags must be of typePyCFunctionWithKeywords.The function expects three parameters:self,args, and a dictionary ofall the keyword arguments. The flag is typically combined withMETH_VARARGS, and the parameters are typically processed usingPyArg_ParseTupleAndKeywords().

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 andwill hold a reference to the module or object instance. In all cases thesecond parameter will beNULL.

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.

METH_OLDARGS¶

This calling convention is deprecated. The method must be of typePyCFunction. The second argument isNULL if no arguments aregiven, a single object if exactly one argument is given, and a tuple ofobjects if more than one argument is given. There is no way for a functionusing this convention to distinguish between a call with multiple argumentsand a call with a tuple as the only 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.

New in version 2.3.

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.

New in version 2.3.

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.

New in version 2.4.

PyMemberDef¶

Structure which describes an attribute of a type which corresponds to a Cstruct member. Its fields are:

Field	C Type	Meaning
name	char *	name of the member
type	int	the type of the member in theC struct
offset	Py_ssize_t	the offset in bytes that themember is located on thetype’s object struct
flags	int	flag bits indicating if thefield should be read-only orwritable
doc	char *	points to the contents of thedocstring

type can be one of manyT_ macros corresponding to various Ctypes. When the member is accessed in Python, it will be converted to theequivalent Python type.

Macro name	C type
T_SHORT	short
T_INT	int
T_LONG	long
T_FLOAT	float
T_DOUBLE	double
T_STRING	char *
T_OBJECT	PyObject *
T_OBJECT_EX	PyObject *
T_CHAR	char
T_BYTE	char
T_UBYTE	unsigned char
T_UINT	unsigned int
T_USHORT	unsigned short
T_ULONG	unsigned long
T_BOOL	char
T_LONGLONG	long long
T_ULONGLONG	unsigned long long
T_PYSSIZET	Py_ssize_t

T_OBJECT andT_OBJECT_EX differ in thatT_OBJECT returnsNone if the member isNULL andT_OBJECT_EX raises anAttributeError. Try to useT_OBJECT_EX overT_OBJECT becauseT_OBJECT_EXhandles use of thedel statement on that attribute more correctlythanT_OBJECT.

flags can be0 for write and read access orREADONLY forread-only access. UsingT_STRING fortype impliesREADONLY. OnlyT_OBJECT andT_OBJECT_EXmembers can be deleted. (They are set toNULL).

PyGetSetDef¶

Structure to define property-like access for a type. See also description ofthePyTypeObject.tp_getset slot.

Field	C Type	Meaning
name	char *	attribute name
get	getter	C Function to get the attribute
set	setter	optional C function to set ordelete the attribute, if omittedthe attribute is readonly
doc	char *	optional docstring
closure	void *	optional function pointer,providing additional data forgetter and setter

Theget function takes onePyObject* parameter (theinstance) and a function pointer (the associatedclosure):

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

It should return a new reference on success orNULL with a set exceptionon failure.

set functions take twoPyObject* parameters (the instance andthe value to be set) and a function pointer (the associatedclosure):

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

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

PyObject*Py_FindMethod(PyMethodDef table[],PyObject *ob, char *name)¶

Return value: New reference.

Return a bound method object for an extension type implemented in C. Thiscan be useful in the implementation of atp_getattro ortp_getattr handler that does not use thePyObject_GenericGetAttr() function.