1 .. highlightlang:: c

     2 

     3 .. _common-structs:

     4 

     5 Common Object Structures

     6 ========================

     7 

     8 There are a large number of structures which are used in the definition of

     9 object types for Python.  This section describes these structures and how they

    10 are used.

    11 

    12 All Python objects ultimately share a small number of fields at the beginning of

    13 the object's representation in memory.  These are represented by the

    14 :ctype:`PyObject` and :ctype:`PyVarObject` types, which are defined, in turn, by

    15 the expansions of some macros also used, whether directly or indirectly, in the

    16 definition of all other Python objects.

    17 

    18 

    19 .. ctype:: PyObject

    20 

    21    All object types are extensions of this type.  This is a type which contains the

    22    information Python needs to treat a pointer to an object as an object.  In a

    23    normal "release" build, it contains only the object's reference count and a

    24    pointer to the corresponding type object.  It corresponds to the fields defined

    25    by the expansion of the ``PyObject_HEAD`` macro.

    26 

    27 

    28 .. ctype:: PyVarObject

    29 

    30    This is an extension of :ctype:`PyObject` that adds the :attr:`ob_size` field.

    31    This is only used for objects that have some notion of *length*.  This type does

    32    not often appear in the Python/C API.  It corresponds to the fields defined by

    33    the expansion of the ``PyObject_VAR_HEAD`` macro.

    34 

    35 These macros are used in the definition of :ctype:`PyObject` and

    36 :ctype:`PyVarObject`:

    37 

    38 

    39 .. cmacro:: PyObject_HEAD

    40 

    41    This is a macro which expands to the declarations of the fields of the

    42    :ctype:`PyObject` type; it is used when declaring new types which represent

    43    objects without a varying length.  The specific fields it expands to depend on

    44    the definition of :cmacro:`Py_TRACE_REFS`.  By default, that macro is not

    45    defined, and :cmacro:`PyObject_HEAD` expands to::

    46 

    47       Py_ssize_t ob_refcnt;

    48       PyTypeObject *ob_type;

    49 

    50    When :cmacro:`Py_TRACE_REFS` is defined, it expands to::

    51 

    52       PyObject *_ob_next, *_ob_prev;

    53       Py_ssize_t ob_refcnt;

    54       PyTypeObject *ob_type;

    55 

    56 

    57 .. cmacro:: PyObject_VAR_HEAD

    58 

    59    This is a macro which expands to the declarations of the fields of the

    60    :ctype:`PyVarObject` type; it is used when declaring new types which represent

    61    objects with a length that varies from instance to instance.  This macro always

    62    expands to::

    63 

    64       PyObject_HEAD

    65       Py_ssize_t ob_size;

    66 

    67    Note that :cmacro:`PyObject_HEAD` is part of the expansion, and that its own

    68    expansion varies depending on the definition of :cmacro:`Py_TRACE_REFS`.

    69 

    70 PyObject_HEAD_INIT

    71 

    72 

    73 .. ctype:: PyCFunction

    74 

    75    Type of the functions used to implement most Python callables in C. Functions of

    76    this type take two :ctype:`PyObject\*` parameters and return one such value.  If

    77    the return value is *NULL*, an exception shall have been set.  If not *NULL*,

    78    the return value is interpreted as the return value of the function as exposed

    79    in Python.  The function must return a new reference.

    80 

    81 

    82 .. ctype:: PyMethodDef

    83 

    84    Structure used to describe a method of an extension type.  This structure has

    85    four fields:

    86 

    87    +------------------+-------------+-------------------------------+

    88    | Field            | C Type      | Meaning                       |

    89    +==================+=============+===============================+

    90    | :attr:`ml_name`  | char \*     | name of the method            |

    91    +------------------+-------------+-------------------------------+

    92    | :attr:`ml_meth`  | PyCFunction | pointer to the C              |

    93    |                  |             | implementation                |

    94    +------------------+-------------+-------------------------------+

    95    | :attr:`ml_flags` | int         | flag bits indicating how the  |

    96    |                  |             | call should be constructed    |

    97    +------------------+-------------+-------------------------------+

    98    | :attr:`ml_doc`   | char \*     | points to the contents of the |

    99    |                  |             | docstring                     |

   100    +------------------+-------------+-------------------------------+

   101 

   102 The :attr:`ml_meth` is a C function pointer.  The functions may be of different

   103 types, but they always return :ctype:`PyObject\*`.  If the function is not of

   104 the :ctype:`PyCFunction`, the compiler will require a cast in the method table.

   105 Even though :ctype:`PyCFunction` defines the first parameter as

   106 :ctype:`PyObject\*`, it is common that the method implementation uses a the

   107 specific C type of the *self* object.

   108 

   109 The :attr:`ml_flags` field is a bitfield which can include the following flags.

   110 The individual flags indicate either a calling convention or a binding

   111 convention.  Of the calling convention flags, only :const:`METH_VARARGS` and

   112 :const:`METH_KEYWORDS` can be combined (but note that :const:`METH_KEYWORDS`

   113 alone is equivalent to ``METH_VARARGS | METH_KEYWORDS``). Any of the calling

   114 convention flags can be combined with a binding flag.

   115 

   116 

   117 .. data:: METH_VARARGS

   118 

   119    This is the typical calling convention, where the methods have the type

   120    :ctype:`PyCFunction`. The function expects two :ctype:`PyObject\*` values.  The

   121    first one is the *self* object for methods; for module functions, it has the

   122    value given to :cfunc:`Py_InitModule4` (or *NULL* if :cfunc:`Py_InitModule` was

   123    used).  The second parameter (often called *args*) is a tuple object

   124    representing all arguments. This parameter is typically processed using

   125    :cfunc:`PyArg_ParseTuple` or :cfunc:`PyArg_UnpackTuple`.

   126 

   127 

   128 .. data:: METH_KEYWORDS

   129 

   130    Methods with these flags must be of type :ctype:`PyCFunctionWithKeywords`.  The

   131    function expects three parameters: *self*, *args*, and a dictionary of all the

   132    keyword arguments.  The flag is typically combined with :const:`METH_VARARGS`,

   133    and the parameters are typically processed using

   134    :cfunc:`PyArg_ParseTupleAndKeywords`.

   135 

   136 

   137 .. data:: METH_NOARGS

   138 

   139    Methods without parameters don't need to check whether arguments are given if

   140    they are listed with the :const:`METH_NOARGS` flag.  They need to be of type

   141    :ctype:`PyCFunction`.  When used with object methods, the first parameter is

   142    typically named ``self`` and will hold a reference to the object instance.  In

   143    all cases the second parameter will be *NULL*.

   144 

   145 

   146 .. data:: METH_O

   147 

   148    Methods with a single object argument can be listed with the :const:`METH_O`

   149    flag, instead of invoking :cfunc:`PyArg_ParseTuple` with a ``"O"`` argument.

   150    They have the type :ctype:`PyCFunction`, with the *self* parameter, and a

   151    :ctype:`PyObject\*` parameter representing the single argument.

   152 

   153 

   154 .. data:: METH_OLDARGS

   155 

   156    This calling convention is deprecated.  The method must be of type

   157    :ctype:`PyCFunction`.  The second argument is *NULL* if no arguments are given,

   158    a single object if exactly one argument is given, and a tuple of objects if more

   159    than one argument is given.  There is no way for a function using this

   160    convention to distinguish between a call with multiple arguments and a call with

   161    a tuple as the only argument.

   162 

   163 These two constants are not used to indicate the calling convention but the

   164 binding when use with methods of classes.  These may not be used for functions

   165 defined for modules.  At most one of these flags may be set for any given

   166 method.

   167 

   168 

   169 .. data:: METH_CLASS

   170 

   171    .. index:: builtin: classmethod

   172 

   173    The method will be passed the type object as the first parameter rather than an

   174    instance of the type.  This is used to create *class methods*, similar to what

   175    is created when using the :func:`classmethod` built-in function.

   176 

   177    .. versionadded:: 2.3

   178 

   179 

   180 .. data:: METH_STATIC

   181 

   182    .. index:: builtin: staticmethod

   183 

   184    The method will be passed *NULL* as the first parameter rather than an instance

   185    of the type.  This is used to create *static methods*, similar to what is

   186    created when using the :func:`staticmethod` built-in function.

   187 

   188    .. versionadded:: 2.3

   189 

   190 One other constant controls whether a method is loaded in place of another

   191 definition with the same method name.

   192 

   193 

   194 .. data:: METH_COEXIST

   195 

   196    The method will be loaded in place of existing definitions.  Without

   197    *METH_COEXIST*, the default is to skip repeated definitions.  Since slot

   198    wrappers are loaded before the method table, the existence of a *sq_contains*

   199    slot, for example, would generate a wrapped method named :meth:`__contains__`

   200    and preclude the loading of a corresponding PyCFunction with the same name.

   201    With the flag defined, the PyCFunction will be loaded in place of the wrapper

   202    object and will co-exist with the slot.  This is helpful because calls to

   203    PyCFunctions are optimized more than wrapper object calls.

   204 

   205    .. versionadded:: 2.4

   206 

   207 

   208 .. cfunction:: PyObject* Py_FindMethod(PyMethodDef table[], PyObject *ob, char *name)

   209 

   210    Return a bound method object for an extension type implemented in C.  This can

   211    be useful in the implementation of a :attr:`tp_getattro` or :attr:`tp_getattr`

   212    handler that does not use the :cfunc:`PyObject_GenericGetAttr` function.