10.2 Common Object Structures

PyObject, PyVarObject

PyObject_HEAD, PyObject_HEAD_INIT, PyObject_VAR_HEAD

Typedefs: unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc, intintargfunc, intobjargproc, intintobjargproc, objobjargproc, destructor, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc, cmpfunc, reprfunc, hashfunc

PyCFunction: Type of the functions used to implement most Python callables in C.

PyMethodDef

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

Field C Type Meaning

ml_name char * name of the method
ml_meth PyCFunction pointer to the C implementation
ml_flags int flag bits indicating how the call should be constructed
ml_doc char * points to the contents of the docstring

The ml_meth is a C function pointer. The functions may be of different types, but they always return PyObject*. If the function is not of the PyCFunction, the compiler will require a cast in the method table. Even though PyCFunction defines the first parameter as PyObject*, it is common that the method implementation uses a the specific C type of the self object.

The flags can have the following values. Only METH_VARARGS and METH_KEYWORDS can be combined; the others can't.

METH_VARARGS: This is the typical calling convention, where the methods have the type PyMethodDef. The function expects two PyObject* values. The first one is the self object for methods; for module functions, it has the value given to Py_InitModule4() (or NULL if Py_InitModule() was used). The second parameter (often called args) is a tuple object representing all arguments. This parameter is typically processed using PyArg_ParseTuple().

METH_KEYWORDS: Methods with these flags must be of type PyCFunctionWithKeywords. The function expects three parameters: self, args, and a dictionary of all the keyword arguments. The flag is typically combined with METH_VARARGS, and the parameters are typically processed using PyArg_ParseTupleAndKeywords().

METH_NOARGS: Methods without parameters don't need to check whether arguments are given if they are listed with the METH_NOARGS flag. They need to be of type PyNoArgsFunction: they expect a single single PyObject* as a parameter. When used with object methods, this parameter is typically named self and will hold a reference to the object instance.

METH_O: Methods with a single object argument can be listed with the METH_O flag, instead of invoking PyArg_ParseTuple() with a "O" argument. They have the type PyCFunction, with the self parameter, and a PyObject* parameter representing the single argument.

METH_OLDARGS: This calling convention is deprecated. The method must be of type PyCFunction. The second argument is NULL if no arguments are given, a single object if exactly one argument is given, and a tuple of objects if more than one argument is given. There is no way for a function using this convention to distinguish between a call with multiple arguments and a call with a tuple as the only argument.

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. This can be useful in the implementation of a tp_getattro or tp_getattr handler that does not use the PyObject_GenericGetAttr() function.

See About this document... for information on suggesting changes.