1.. highlightlang:: c
2
3.. _common-structs:
4
5Common Object Structures
6========================
7
8There are a large number of structures which are used in the definition of
9object types for Python.  This section describes these structures and how they
10are used.
11
12All Python objects ultimately share a small number of fields at the beginning
13of the object's representation in memory.  These are represented by the
14:c:type:`PyObject` and :c:type:`PyVarObject` types, which are defined, in turn,
15by the expansions of some macros also used, whether directly or indirectly, in
16the definition of all other Python objects.
17
18
19.. c:type:: PyObject
20
21   All object types are extensions of this type.  This is a type which
22   contains the information Python needs to treat a pointer to an object as an
23   object.  In a normal "release" build, it contains only the object's
24   reference count and a pointer to the corresponding type object.
25   Nothing is actually declared to be a :c:type:`PyObject`, but every pointer
26   to a Python object can be cast to a :c:type:`PyObject*`.  Access to the
27   members must be done by using the macros :c:macro:`Py_REFCNT` and
28   :c:macro:`Py_TYPE`.
29
30
31.. c:type:: PyVarObject
32
33   This is an extension of :c:type:`PyObject` that adds the :attr:`ob_size`
34   field.  This is only used for objects that have some notion of *length*.
35   This type does not often appear in the Python/C API.
36   Access to the members must be done by using the macros
37   :c:macro:`Py_REFCNT`, :c:macro:`Py_TYPE`, and :c:macro:`Py_SIZE`.
38
39
40.. c:macro:: PyObject_HEAD
41
42   This is a macro used when declaring new types which represent objects
43   without a varying length.  The PyObject_HEAD macro expands to::
44
45      PyObject ob_base;
46
47   See documentation of :c:type:`PyObject` above.
48
49
50.. c:macro:: PyObject_VAR_HEAD
51
52   This is a macro used when declaring new types which represent objects
53   with a length that varies from instance to instance.
54   The PyObject_VAR_HEAD macro expands to::
55
56      PyVarObject ob_base;
57
58   See documentation of :c:type:`PyVarObject` above.
59
60
61.. c:macro:: Py_TYPE(o)
62
63   This macro is used to access the :attr:`ob_type` member of a Python object.
64   It expands to::
65
66      (((PyObject*)(o))->ob_type)
67
68
69.. c:macro:: Py_REFCNT(o)
70
71   This macro is used to access the :attr:`ob_refcnt` member of a Python
72   object.
73   It expands to::
74
75      (((PyObject*)(o))->ob_refcnt)
76
77
78.. c:macro:: Py_SIZE(o)
79
80   This macro is used to access the :attr:`ob_size` member of a Python object.
81   It expands to::
82
83      (((PyVarObject*)(o))->ob_size)
84
85
86.. c:macro:: PyObject_HEAD_INIT(type)
87
88   This is a macro which expands to initialization values for a new
89   :c:type:`PyObject` type.  This macro expands to::
90
91      _PyObject_EXTRA_INIT
92      1, type,
93
94
95.. c:macro:: PyVarObject_HEAD_INIT(type, size)
96
97   This is a macro which expands to initialization values for a new
98   :c:type:`PyVarObject` type, including the :attr:`ob_size` field.
99   This macro expands to::
100
101      _PyObject_EXTRA_INIT
102      1, type, size,
103
104
105.. c:type:: PyCFunction
106
107   Type of the functions used to implement most Python callables in C.
108   Functions of this type take two :c:type:`PyObject\*` parameters and return
109   one such value.  If the return value is *NULL*, an exception shall have
110   been set.  If not *NULL*, the return value is interpreted as the return
111   value of the function as exposed in Python.  The function must return a new
112   reference.
113
114
115.. c:type:: PyCFunctionWithKeywords
116
117   Type of the functions used to implement Python callables in C that take
118   keyword arguments: they take three :c:type:`PyObject\*` parameters and return
119   one such value.  See :c:type:`PyCFunction` above for the meaning of the return
120   value.
121
122
123.. c:type:: PyMethodDef
124
125   Structure used to describe a method of an extension type.  This structure has
126   four fields:
127
128   +------------------+---------------+-------------------------------+
129   | Field            | C Type        | Meaning                       |
130   +==================+===============+===============================+
131   | :attr:`ml_name`  | const char \* | name of the method            |
132   +------------------+---------------+-------------------------------+
133   | :attr:`ml_meth`  | PyCFunction   | pointer to the C              |
134   |                  |               | implementation                |
135   +------------------+---------------+-------------------------------+
136   | :attr:`ml_flags` | int           | flag bits indicating how the  |
137   |                  |               | call should be constructed    |
138   +------------------+---------------+-------------------------------+
139   | :attr:`ml_doc`   | const char \* | points to the contents of the |
140   |                  |               | docstring                     |
141   +------------------+---------------+-------------------------------+
142
143The :attr:`ml_meth` is a C function pointer.  The functions may be of different
144types, but they always return :c:type:`PyObject\*`.  If the function is not of
145the :c:type:`PyCFunction`, the compiler will require a cast in the method table.
146Even though :c:type:`PyCFunction` defines the first parameter as
147:c:type:`PyObject\*`, it is common that the method implementation uses the
148specific C type of the *self* object.
149
150The :attr:`ml_flags` field is a bitfield which can include the following flags.
151The individual flags indicate either a calling convention or a binding
152convention.  Of the calling convention flags, only :const:`METH_VARARGS` and
153:const:`METH_KEYWORDS` can be combined. Any of the calling convention flags
154can be combined with a binding flag.
155
156
157.. data:: METH_VARARGS
158
159   This is the typical calling convention, where the methods have the type
160   :c:type:`PyCFunction`. The function expects two :c:type:`PyObject\*` values.
161   The first one is the *self* object for methods; for module functions, it is
162   the module object.  The second parameter (often called *args*) is a tuple
163   object representing all arguments. This parameter is typically processed
164   using :c:func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`.
165
166
167.. data:: METH_KEYWORDS
168
169   Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`.
170   The function expects three parameters: *self*, *args*, and a dictionary of
171   all the keyword arguments.  The flag must be combined with
172   :const:`METH_VARARGS`, and the parameters are typically processed using
173   :c:func:`PyArg_ParseTupleAndKeywords`.
174
175
176.. data:: METH_NOARGS
177
178   Methods without parameters don't need to check whether arguments are given if
179   they are listed with the :const:`METH_NOARGS` flag.  They need to be of type
180   :c:type:`PyCFunction`.  The first parameter is typically named *self* and will
181   hold a reference to the module or object instance.  In all cases the second
182   parameter will be *NULL*.
183
184
185.. data:: METH_O
186
187   Methods with a single object argument can be listed with the :const:`METH_O`
188   flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument.
189   They have the type :c:type:`PyCFunction`, with the *self* parameter, and a
190   :c:type:`PyObject\*` parameter representing the single argument.
191
192
193These two constants are not used to indicate the calling convention but the
194binding when use with methods of classes.  These may not be used for functions
195defined for modules.  At most one of these flags may be set for any given
196method.
197
198
199.. data:: METH_CLASS
200
201   .. index:: builtin: classmethod
202
203   The method will be passed the type object as the first parameter rather
204   than an instance of the type.  This is used to create *class methods*,
205   similar to what is created when using the :func:`classmethod` built-in
206   function.
207
208
209.. data:: METH_STATIC
210
211   .. index:: builtin: staticmethod
212
213   The method will be passed *NULL* as the first parameter rather than an
214   instance of the type.  This is used to create *static methods*, similar to
215   what is created when using the :func:`staticmethod` built-in function.
216
217One other constant controls whether a method is loaded in place of another
218definition with the same method name.
219
220
221.. data:: METH_COEXIST
222
223   The method will be loaded in place of existing definitions.  Without
224   *METH_COEXIST*, the default is to skip repeated definitions.  Since slot
225   wrappers are loaded before the method table, the existence of a
226   *sq_contains* slot, for example, would generate a wrapped method named
227   :meth:`__contains__` and preclude the loading of a corresponding
228   PyCFunction with the same name.  With the flag defined, the PyCFunction
229   will be loaded in place of the wrapper object and will co-exist with the
230   slot.  This is helpful because calls to PyCFunctions are optimized more
231   than wrapper object calls.
232
233
234.. c:type:: PyMemberDef
235
236   Structure which describes an attribute of a type which corresponds to a C
237   struct member.  Its fields are:
238
239   +------------------+---------------+-------------------------------+
240   | Field            | C Type        | Meaning                       |
241   +==================+===============+===============================+
242   | :attr:`name`     | const char \* | name of the member            |
243   +------------------+---------------+-------------------------------+
244   | :attr:`!type`    | int           | the type of the member in the |
245   |                  |               | C struct                      |
246   +------------------+---------------+-------------------------------+
247   | :attr:`offset`   | Py_ssize_t    | the offset in bytes that the  |
248   |                  |               | member is located on the      |
249   |                  |               | type's object struct          |
250   +------------------+---------------+-------------------------------+
251   | :attr:`flags`    | int           | flag bits indicating if the   |
252   |                  |               | field should be read-only or  |
253   |                  |               | writable                      |
254   +------------------+---------------+-------------------------------+
255   | :attr:`doc`      | const char \* | points to the contents of the |
256   |                  |               | docstring                     |
257   +------------------+---------------+-------------------------------+
258
259   :attr:`!type` can be one of many ``T_`` macros corresponding to various C
260   types.  When the member is accessed in Python, it will be converted to the
261   equivalent Python type.
262
263   =============== ==================
264   Macro name      C type
265   =============== ==================
266   T_SHORT         short
267   T_INT           int
268   T_LONG          long
269   T_FLOAT         float
270   T_DOUBLE        double
271   T_STRING        const char \*
272   T_OBJECT        PyObject \*
273   T_OBJECT_EX     PyObject \*
274   T_CHAR          char
275   T_BYTE          char
276   T_UBYTE         unsigned char
277   T_UINT          unsigned int
278   T_USHORT        unsigned short
279   T_ULONG         unsigned long
280   T_BOOL          char
281   T_LONGLONG      long long
282   T_ULONGLONG     unsigned long long
283   T_PYSSIZET      Py_ssize_t
284   =============== ==================
285
286   :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` differ in that
287   :c:macro:`T_OBJECT` returns ``None`` if the member is *NULL* and
288   :c:macro:`T_OBJECT_EX` raises an :exc:`AttributeError`.  Try to use
289   :c:macro:`T_OBJECT_EX` over :c:macro:`T_OBJECT` because :c:macro:`T_OBJECT_EX`
290   handles use of the :keyword:`del` statement on that attribute more correctly
291   than :c:macro:`T_OBJECT`.
292
293   :attr:`flags` can be ``0`` for write and read access or :c:macro:`READONLY` for
294   read-only access.  Using :c:macro:`T_STRING` for :attr:`type` implies
295   :c:macro:`READONLY`.  :c:macro:`T_STRING` data is interpreted as UTF-8.
296   Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX`
297   members can be deleted.  (They are set to *NULL*).
298
299
300.. c:type:: PyGetSetDef
301
302   Structure to define property-like access for a type. See also description of
303   the :c:member:`PyTypeObject.tp_getset` slot.
304
305   +-------------+------------------+-----------------------------------+
306   | Field       | C Type           | Meaning                           |
307   +=============+==================+===================================+
308   | name        | const char \*    | attribute name                    |
309   +-------------+------------------+-----------------------------------+
310   | get         | getter           | C Function to get the attribute   |
311   +-------------+------------------+-----------------------------------+
312   | set         | setter           | optional C function to set or     |
313   |             |                  | delete the attribute, if omitted  |
314   |             |                  | the attribute is readonly         |
315   +-------------+------------------+-----------------------------------+
316   | doc         | const char \*    | optional docstring                |
317   +-------------+------------------+-----------------------------------+
318   | closure     | void \*          | optional function pointer,        |
319   |             |                  | providing additional data for     |
320   |             |                  | getter and setter                 |
321   +-------------+------------------+-----------------------------------+
322
323   The ``get`` function takes one :c:type:`PyObject\*` parameter (the
324   instance) and a function pointer (the associated ``closure``)::
325
326      typedef PyObject *(*getter)(PyObject *, void *);
327
328   It should return a new reference on success or *NULL* with a set exception
329   on failure.
330
331   ``set`` functions take two :c:type:`PyObject\*` parameters (the instance and
332   the value to be set) and a function pointer (the associated ``closure``)::
333
334      typedef int (*setter)(PyObject *, PyObject *, void *);
335
336   In case the attribute should be deleted the second parameter is *NULL*.
337   Should return ``0`` on success or ``-1`` with a set exception on failure.
338