10.2 Common Object Structures
Keywords: api

#
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.