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