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. 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 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. 149 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. Any of the calling convention flags 154 can 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 193 These two constants are not used to indicate the calling convention but the 194 binding when use with methods of classes. These may not be used for functions 195 defined for modules. At most one of these flags may be set for any given 196 method. 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 217 One other constant controls whether a method is loaded in place of another 218 definition 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
