5
Common Object Structures
6
========================
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
12
All Python objects ultimately share a small number of fields at the beginning
13
of 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,
15
by the expansions of some macros also used, whether directly or indirectly, in
16
the definition of all other Python objects.
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
31
.. c:type:: PyVarObject
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`.
40
.. c:macro:: PyObject_HEAD
42
This is a macro used when declaring new types which represent objects
43
without a varying length. The PyObject_HEAD macro expands to::
47
See documentation of :c:type:`PyObject` above.
50
.. c:macro:: PyObject_VAR_HEAD
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::
58
See documentation of :c:type:`PyVarObject` above.
61
.. c:macro:: Py_TYPE(o)
63
This macro is used to access the :attr:`ob_type` member of a Python object.
66
(((PyObject*)(o))->ob_type)
69
.. c:macro:: Py_REFCNT(o)
71
This macro is used to access the :attr:`ob_refcnt` member of a Python
75
(((PyObject*)(o))->ob_refcnt)
78
.. c:macro:: Py_SIZE(o)
80
This macro is used to access the :attr:`ob_size` member of a Python object.
83
(((PyVarObject*)(o))->ob_size)
86
.. c:macro:: PyObject_HEAD_INIT(type)
88
This is a macro which expands to initialization values for a new
89
:c:type:`PyObject` type. This macro expands to::
95
.. c:macro:: PyVarObject_HEAD_INIT(type, size)
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::
105
.. c:type:: PyCFunction
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
115
.. c:type:: PyCFunctionWithKeywords
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
123
.. c:type:: PyMethodDef
125
Structure used to describe a method of an extension type. This structure has
128
+------------------+-------------+-------------------------------+
129
| Field | C Type | Meaning |
130
+==================+=============+===============================+
131
| :attr:`ml_name` | 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` | char \* | points to the contents of the |
141
+------------------+-------------+-------------------------------+
143
The :attr:`ml_meth` is a C function pointer. The functions may be of different
144
types, but they always return :c:type:`PyObject\*`. If the function is not of
145
the :c:type:`PyCFunction`, the compiler will require a cast in the method table.
146
Even though :c:type:`PyCFunction` defines the first parameter as
147
:c:type:`PyObject\*`, it is common that the method implementation uses the
148
specific C type of the *self* object.
150
The :attr:`ml_flags` field is a bitfield which can include the following flags.
151
The individual flags indicate either a calling convention or a binding
152
convention. Of the calling convention flags, only :const:`METH_VARARGS` and
153
:const:`METH_KEYWORDS` can be combined (but note that :const:`METH_KEYWORDS`
154
alone is equivalent to ``METH_VARARGS | METH_KEYWORDS``). Any of the calling
155
convention flags can be combined with a binding flag.
158
.. data:: METH_VARARGS
160
This is the typical calling convention, where the methods have the type
161
:c:type:`PyCFunction`. The function expects two :c:type:`PyObject\*` values.
162
The first one is the *self* object for methods; for module functions, it is
163
the module object. The second parameter (often called *args*) is a tuple
164
object representing all arguments. This parameter is typically processed
165
using :c:func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`.
168
.. data:: METH_KEYWORDS
170
Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`.
171
The function expects three parameters: *self*, *args*, and a dictionary of
172
all the keyword arguments. The flag is typically combined with
173
:const:`METH_VARARGS`, and the parameters are typically processed using
174
:c:func:`PyArg_ParseTupleAndKeywords`.
177
.. data:: METH_NOARGS
179
Methods without parameters don't need to check whether arguments are given if
180
they are listed with the :const:`METH_NOARGS` flag. They need to be of type
181
:c:type:`PyCFunction`. The first parameter is typically named *self* and will
182
hold a reference to the module or object instance. In all cases the second
183
parameter will be *NULL*.
188
Methods with a single object argument can be listed with the :const:`METH_O`
189
flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument.
190
They have the type :c:type:`PyCFunction`, with the *self* parameter, and a
191
:c:type:`PyObject\*` parameter representing the single argument.
194
These two constants are not used to indicate the calling convention but the
195
binding when use with methods of classes. These may not be used for functions
196
defined for modules. At most one of these flags may be set for any given
202
.. index:: builtin: classmethod
204
The method will be passed the type object as the first parameter rather
205
than an instance of the type. This is used to create *class methods*,
206
similar to what is created when using the :func:`classmethod` built-in
210
.. data:: METH_STATIC
212
.. index:: builtin: staticmethod
214
The method will be passed *NULL* as the first parameter rather than an
215
instance of the type. This is used to create *static methods*, similar to
216
what is created when using the :func:`staticmethod` built-in function.
218
One other constant controls whether a method is loaded in place of another
219
definition with the same method name.
222
.. data:: METH_COEXIST
224
The method will be loaded in place of existing definitions. Without
225
*METH_COEXIST*, the default is to skip repeated definitions. Since slot
226
wrappers are loaded before the method table, the existence of a
227
*sq_contains* slot, for example, would generate a wrapped method named
228
:meth:`__contains__` and preclude the loading of a corresponding
229
PyCFunction with the same name. With the flag defined, the PyCFunction
230
will be loaded in place of the wrapper object and will co-exist with the
231
slot. This is helpful because calls to PyCFunctions are optimized more
232
than wrapper object calls.
235
.. c:type:: PyMemberDef
237
Structure which describes an attribute of a type which corresponds to a C
238
struct member. Its fields are:
240
+------------------+-------------+-------------------------------+
241
| Field | C Type | Meaning |
242
+==================+=============+===============================+
243
| :attr:`name` | char \* | name of the member |
244
+------------------+-------------+-------------------------------+
245
| :attr:`type` | int | the type of the member in the |
247
+------------------+-------------+-------------------------------+
248
| :attr:`offset` | Py_ssize_t | the offset in bytes that the |
249
| | | member is located on the |
250
| | | type's object struct |
251
+------------------+-------------+-------------------------------+
252
| :attr:`flags` | int | flag bits indicating if the |
253
| | | field should be read-only or |
255
+------------------+-------------+-------------------------------+
256
| :attr:`doc` | char \* | points to the contents of the |
258
+------------------+-------------+-------------------------------+
260
:attr:`type` can be one of many ``T_`` macros corresponding to various C
261
types. When the member is accessed in Python, it will be converted to the
262
equivalent Python type.
264
=============== ==================
266
=============== ==================
274
T_OBJECT_EX PyObject \*
277
T_UBYTE unsigned char
279
T_USHORT unsigned short
280
T_ULONG unsigned long
283
T_ULONGLONG unsigned long long
284
T_PYSSIZET Py_ssize_t
285
=============== ==================
287
:c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` differ in that
288
:c:macro:`T_OBJECT` returns ``None`` if the member is *NULL* and
289
:c:macro:`T_OBJECT_EX` raises an :exc:`AttributeError`. Try to use
290
:c:macro:`T_OBJECT_EX` over :c:macro:`T_OBJECT` because :c:macro:`T_OBJECT_EX`
291
handles use of the :keyword:`del` statement on that attribute more correctly
292
than :c:macro:`T_OBJECT`.
294
:attr:`flags` can be 0 for write and read access or :c:macro:`READONLY` for
295
read-only access. Using :c:macro:`T_STRING` for :attr:`type` implies
296
:c:macro:`READONLY`. Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX`
297
members can be deleted. (They are set to *NULL*).
added
removed
python-3.5.1-docs-html/_sources/c-api/structures.txt
