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