← Back to branch summary

~ubuntu-branches/ubuntu/maverick/python3.1/maverick

« back to all changes in this revision

Viewing changes to Doc/c-api/structures.rst

  • Committer: Bazaar Package Importer
  • Author(s): Matthias Klose
  • Date: 2009-03-23 00:01:27 UTC
  • Revision ID: james.westby@ubuntu.com-20090323000127-5fstfxju4ufrhthq
Tags: upstream-3.1~a1+20090322
Import upstream version 3.1~a1+20090322

Show diffs side-by-side

added added

removed removed

Lines of Context:
Doc/c-api/structures.rst
 
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
.. XXX need to document PEP 3123 changes here
 
39
 
 
40
.. cmacro:: PyObject_HEAD
 
41
 
 
42
   This is a macro which expands to the declarations of the fields of the
 
43
   :ctype:`PyObject` type; it is used when declaring new types which represent
 
44
   objects without a varying length.  The specific fields it expands to depend on
 
45
   the definition of :cmacro:`Py_TRACE_REFS`.  By default, that macro is not
 
46
   defined, and :cmacro:`PyObject_HEAD` expands to::
 
47
 
 
48
      Py_ssize_t ob_refcnt;
 
49
      PyTypeObject *ob_type;
 
50
 
 
51
   When :cmacro:`Py_TRACE_REFS` is defined, it expands to::
 
52
 
 
53
      PyObject *_ob_next, *_ob_prev;
 
54
      Py_ssize_t ob_refcnt;
 
55
      PyTypeObject *ob_type;
 
56
 
 
57
 
 
58
.. cmacro:: PyObject_VAR_HEAD
 
59
 
 
60
   This is a macro which expands to the declarations of the fields of the
 
61
   :ctype:`PyVarObject` type; it is used when declaring new types which represent
 
62
   objects with a length that varies from instance to instance.  This macro always
 
63
   expands to::
 
64
 
 
65
      PyObject_HEAD
 
66
      Py_ssize_t ob_size;
 
67
 
 
68
   Note that :cmacro:`PyObject_HEAD` is part of the expansion, and that its own
 
69
   expansion varies depending on the definition of :cmacro:`Py_TRACE_REFS`.
 
70
 
 
71
.. cmacro:: PyObject_HEAD_INIT
 
72
 
 
73
 
 
74
.. ctype:: PyCFunction
 
75
 
 
76
   Type of the functions used to implement most Python callables in C. Functions of
 
77
   this type take two :ctype:`PyObject\*` parameters and return one such value.  If
 
78
   the return value is *NULL*, an exception shall have been set.  If not *NULL*,
 
79
   the return value is interpreted as the return value of the function as exposed
 
80
   in Python.  The function must return a new reference.
 
81
 
 
82
 
 
83
.. ctype:: PyCFunctionWithKeywords
 
84
 
 
85
   Type of the functions used to implement Python callables in C that take
 
86
   keyword arguments: they take three :ctype:`PyObject\*` parameters and return
 
87
   one such value.  See :ctype:`PyCFunction` above for the meaning of the return
 
88
   value.
 
89
 
 
90
 
 
91
.. ctype:: PyMethodDef
 
92
 
 
93
   Structure used to describe a method of an extension type.  This structure has
 
94
   four fields:
 
95
 
 
96
   +------------------+-------------+-------------------------------+
 
97
   | Field            | C Type      | Meaning                       |
 
98
   +==================+=============+===============================+
 
99
   | :attr:`ml_name`  | char \*     | name of the method            |
 
100
   +------------------+-------------+-------------------------------+
 
101
   | :attr:`ml_meth`  | PyCFunction | pointer to the C              |
 
102
   |                  |             | implementation                |
 
103
   +------------------+-------------+-------------------------------+
 
104
   | :attr:`ml_flags` | int         | flag bits indicating how the  |
 
105
   |                  |             | call should be constructed    |
 
106
   +------------------+-------------+-------------------------------+
 
107
   | :attr:`ml_doc`   | char \*     | points to the contents of the |
 
108
   |                  |             | docstring                     |
 
109
   +------------------+-------------+-------------------------------+
 
110
 
 
111
The :attr:`ml_meth` is a C function pointer.  The functions may be of different
 
112
types, but they always return :ctype:`PyObject\*`.  If the function is not of
 
113
the :ctype:`PyCFunction`, the compiler will require a cast in the method table.
 
114
Even though :ctype:`PyCFunction` defines the first parameter as
 
115
:ctype:`PyObject\*`, it is common that the method implementation uses a the
 
116
specific C type of the *self* object.
 
117
 
 
118
The :attr:`ml_flags` field is a bitfield which can include the following flags.
 
119
The individual flags indicate either a calling convention or a binding
 
120
convention.  Of the calling convention flags, only :const:`METH_VARARGS` and
 
121
:const:`METH_KEYWORDS` can be combined (but note that :const:`METH_KEYWORDS`
 
122
alone is equivalent to ``METH_VARARGS | METH_KEYWORDS``). Any of the calling
 
123
convention flags can be combined with a binding flag.
 
124
 
 
125
 
 
126
.. data:: METH_VARARGS
 
127
 
 
128
   This is the typical calling convention, where the methods have the type
 
129
   :ctype:`PyCFunction`. The function expects two :ctype:`PyObject\*` values.  The
 
130
   first one is the *self* object for methods; for module functions, it has the
 
131
   value given to :cfunc:`Py_InitModule4` (or *NULL* if :cfunc:`Py_InitModule` was
 
132
   used).  The second parameter (often called *args*) is a tuple object
 
133
   representing all arguments. This parameter is typically processed using
 
134
   :cfunc:`PyArg_ParseTuple` or :cfunc:`PyArg_UnpackTuple`.
 
135
 
 
136
 
 
137
.. data:: METH_KEYWORDS
 
138
 
 
139
   Methods with these flags must be of type :ctype:`PyCFunctionWithKeywords`.  The
 
140
   function expects three parameters: *self*, *args*, and a dictionary of all the
 
141
   keyword arguments.  The flag is typically combined with :const:`METH_VARARGS`,
 
142
   and the parameters are typically processed using
 
143
   :cfunc:`PyArg_ParseTupleAndKeywords`.
 
144
 
 
145
 
 
146
.. data:: METH_NOARGS
 
147
 
 
148
   Methods without parameters don't need to check whether arguments are given if
 
149
   they are listed with the :const:`METH_NOARGS` flag.  They need to be of type
 
150
   :ctype:`PyCFunction`.  When used with object methods, the first parameter is
 
151
   typically named ``self`` and will hold a reference to the object instance.  In
 
152
   all cases the second parameter will be *NULL*.
 
153
 
 
154
 
 
155
.. data:: METH_O
 
156
 
 
157
   Methods with a single object argument can be listed with the :const:`METH_O`
 
158
   flag, instead of invoking :cfunc:`PyArg_ParseTuple` with a ``"O"`` argument.
 
159
   They have the type :ctype:`PyCFunction`, with the *self* parameter, and a
 
160
   :ctype:`PyObject\*` parameter representing the single argument.
 
161
 
 
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
 
 
178
.. data:: METH_STATIC
 
179
 
 
180
   .. index:: builtin: staticmethod
 
181
 
 
182
   The method will be passed *NULL* as the first parameter rather than an instance
 
183
   of the type.  This is used to create *static methods*, similar to what is
 
184
   created when using the :func:`staticmethod` built-in function.
 
185
 
 
186
One other constant controls whether a method is loaded in place of another
 
187
definition with the same method name.
 
188
 
 
189
 
 
190
.. data:: METH_COEXIST
 
191
 
 
192
   The method will be loaded in place of existing definitions.  Without
 
193
   *METH_COEXIST*, the default is to skip repeated definitions.  Since slot
 
194
   wrappers are loaded before the method table, the existence of a *sq_contains*
 
195
   slot, for example, would generate a wrapped method named :meth:`__contains__`
 
196
   and preclude the loading of a corresponding PyCFunction with the same name.
 
197
   With the flag defined, the PyCFunction will be loaded in place of the wrapper
 
198
   object and will co-exist with the slot.  This is helpful because calls to
 
199
   PyCFunctions are optimized more than wrapper object calls.
 
200
 
 
201
 
 
202
.. ctype:: PyMemberDef
 
203
 
 
204
   Structure which describes an attribute of a type which corresponds to a C
 
205
   struct member.  Its fields are:
 
206
 
 
207
   +------------------+-------------+-------------------------------+
 
208
   | Field            | C Type      | Meaning                       |
 
209
   +==================+=============+===============================+
 
210
   | :attr:`name`     | char \*     | name of the member            |
 
211
   +------------------+-------------+-------------------------------+
 
212
   | :attr:`type`     | int         | the type of the member in the |
 
213
   |                  |             | C struct                      |
 
214
   +------------------+-------------+-------------------------------+
 
215
   | :attr:`offset`   | Py_ssize_t  | the offset in bytes that the  |
 
216
   |                  |             | member is located on the      |
 
217
   |                  |             | type's object struct          |
 
218
   +------------------+-------------+-------------------------------+
 
219
   | :attr:`flags`    | int         | flag bits indicating if the   |
 
220
   |                  |             | field should be read-only or  |
 
221
   |                  |             | writable                      |
 
222
   +------------------+-------------+-------------------------------+
 
223
   | :attr:`doc`      | char \*     | points to the contents of the |
 
224
   |                  |             | docstring                     |
 
225
   +------------------+-------------+-------------------------------+
 
226
 
 
227
   :attr:`type` can be one of many ``T_`` macros corresponding to various C
 
228
   types.  When the member is accessed in Python, it will be converted to the
 
229
   equivalent Python type.
 
230
 
 
231
   =============== ==================
 
232
   Macro name      C type
 
233
   =============== ==================
 
234
   T_SHORT         short
 
235
   T_INT           int
 
236
   T_LONG          long
 
237
   T_FLOAT         float
 
238
   T_DOUBLE        double
 
239
   T_STRING        char \*
 
240
   T_OBJECT        PyObject \*
 
241
   T_OBJECT_EX     PyObject \*
 
242
   T_CHAR          char
 
243
   T_BYTE          char
 
244
   T_UNBYTE        unsigned char
 
245
   T_UINT          unsigned int
 
246
   T_USHORT        unsigned short
 
247
   T_ULONG         unsigned long
 
248
   T_BOOL          char
 
249
   T_LONGLONG      long long
 
250
   T_ULONGLONG     unsigned long long
 
251
   T_PYSSIZET      Py_ssize_t
 
252
   =============== ==================
 
253
 
 
254
   :cmacro:`T_OBJECT` and :cmacro:`T_OBJECT_EX` differ in that
 
255
   :cmacro:`T_OBJECT` returns ``None`` if the member is *NULL* and
 
256
   :cmacro:`T_OBJECT_EX` raises an :exc:`AttributeError`.
 
257
 
 
258
   :attr:`flags` can be 0 for write and read access or :cmacro:`READONLY` for
 
259
   read-only access.  Using :cmacro:`T_STRING` for :attr:`type` implies
 
260
   :cmacro:`READONLY`.  Only :cmacro:`T_OBJECT` and :cmacro:`T_OBJECT_EX`
 
261
   members can be deleted.  (They are set to *NULL*).