1.. highlight:: c 2 3.. _common-structs: 4 5Common Object Structures 6======================== 7 8There are a large number of structures which are used in the definition of 9object types for Python. This section describes these structures and how they 10are used. 11 12 13Base object types and macros 14---------------------------- 15 16All Python objects ultimately share a small number of fields at the beginning 17of the object's representation in memory. These are represented by the 18:c:type:`PyObject` and :c:type:`PyVarObject` types, which are defined, in turn, 19by the expansions of some macros also used, whether directly or indirectly, in 20the definition of all other Python objects. 21 22 23.. c:type:: PyObject 24 25 All object types are extensions of this type. This is a type which 26 contains the information Python needs to treat a pointer to an object as an 27 object. In a normal "release" build, it contains only the object's 28 reference count and a pointer to the corresponding type object. 29 Nothing is actually declared to be a :c:type:`PyObject`, but every pointer 30 to a Python object can be cast to a :c:type:`PyObject*`. Access to the 31 members must be done by using the macros :c:macro:`Py_REFCNT` and 32 :c:macro:`Py_TYPE`. 33 34 35.. c:type:: PyVarObject 36 37 This is an extension of :c:type:`PyObject` that adds the :attr:`ob_size` 38 field. This is only used for objects that have some notion of *length*. 39 This type does not often appear in the Python/C API. 40 Access to the members must be done by using the macros 41 :c:macro:`Py_REFCNT`, :c:macro:`Py_TYPE`, and :c:macro:`Py_SIZE`. 42 43 44.. c:macro:: PyObject_HEAD 45 46 This is a macro used when declaring new types which represent objects 47 without a varying length. The PyObject_HEAD macro expands to:: 48 49 PyObject ob_base; 50 51 See documentation of :c:type:`PyObject` above. 52 53 54.. c:macro:: PyObject_VAR_HEAD 55 56 This is a macro used when declaring new types which represent objects 57 with a length that varies from instance to instance. 58 The PyObject_VAR_HEAD macro expands to:: 59 60 PyVarObject ob_base; 61 62 See documentation of :c:type:`PyVarObject` above. 63 64 65.. c:function:: int Py_Is(const PyObject *x, const PyObject *y) 66 67 Test if the *x* object is the *y* object, the same as ``x is y`` in Python. 68 69 .. versionadded:: 3.10 70 71 72.. c:function:: int Py_IsNone(const PyObject *x) 73 74 Test if an object is the ``None`` singleton, 75 the same as ``x is None`` in Python. 76 77 .. versionadded:: 3.10 78 79 80.. c:function:: int Py_IsTrue(const PyObject *x) 81 82 Test if an object is the ``True`` singleton, 83 the same as ``x is True`` in Python. 84 85 .. versionadded:: 3.10 86 87 88.. c:function:: int Py_IsFalse(const PyObject *x) 89 90 Test if an object is the ``False`` singleton, 91 the same as ``x is False`` in Python. 92 93 .. versionadded:: 3.10 94 95 96.. c:function:: PyTypeObject* Py_TYPE(const PyObject *o) 97 98 Get the type of the Python object *o*. 99 100 Return a :term:`borrowed reference`. 101 102 The :c:func:`Py_SET_TYPE` function must be used to set an object type. 103 104 105.. c:function:: int Py_IS_TYPE(PyObject *o, PyTypeObject *type) 106 107 Return non-zero if the object *o* type is *type*. Return zero otherwise. 108 Equivalent to: ``Py_TYPE(o) == type``. 109 110 .. versionadded:: 3.9 111 112 113.. c:function:: void Py_SET_TYPE(PyObject *o, PyTypeObject *type) 114 115 Set the object *o* type to *type*. 116 117 .. versionadded:: 3.9 118 119 120.. c:function:: Py_ssize_t Py_REFCNT(const PyObject *o) 121 122 Get the reference count of the Python object *o*. 123 124 .. versionchanged:: 3.10 125 :c:func:`Py_REFCNT()` is changed to the inline static function. 126 Use :c:func:`Py_SET_REFCNT()` to set an object reference count. 127 128 129.. c:function:: void Py_SET_REFCNT(PyObject *o, Py_ssize_t refcnt) 130 131 Set the object *o* reference counter to *refcnt*. 132 133 .. versionadded:: 3.9 134 135 136.. c:function:: Py_ssize_t Py_SIZE(const PyVarObject *o) 137 138 Get the size of the Python object *o*. 139 140 The :c:func:`Py_SET_SIZE` function must be used to set an object size. 141 142 143.. c:function:: void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size) 144 145 Set the object *o* size to *size*. 146 147 .. versionadded:: 3.9 148 149 150.. c:macro:: PyObject_HEAD_INIT(type) 151 152 This is a macro which expands to initialization values for a new 153 :c:type:`PyObject` type. This macro expands to:: 154 155 _PyObject_EXTRA_INIT 156 1, type, 157 158 159.. c:macro:: PyVarObject_HEAD_INIT(type, size) 160 161 This is a macro which expands to initialization values for a new 162 :c:type:`PyVarObject` type, including the :attr:`ob_size` field. 163 This macro expands to:: 164 165 _PyObject_EXTRA_INIT 166 1, type, size, 167 168 169Implementing functions and methods 170---------------------------------- 171 172.. c:type:: PyCFunction 173 174 Type of the functions used to implement most Python callables in C. 175 Functions of this type take two :c:type:`PyObject*` parameters and return 176 one such value. If the return value is ``NULL``, an exception shall have 177 been set. If not ``NULL``, the return value is interpreted as the return 178 value of the function as exposed in Python. The function must return a new 179 reference. 180 181 The function signature is:: 182 183 PyObject *PyCFunction(PyObject *self, 184 PyObject *args); 185 186.. c:type:: PyCFunctionWithKeywords 187 188 Type of the functions used to implement Python callables in C 189 with signature :const:`METH_VARARGS | METH_KEYWORDS`. 190 The function signature is:: 191 192 PyObject *PyCFunctionWithKeywords(PyObject *self, 193 PyObject *args, 194 PyObject *kwargs); 195 196 197.. c:type:: _PyCFunctionFast 198 199 Type of the functions used to implement Python callables in C 200 with signature :const:`METH_FASTCALL`. 201 The function signature is:: 202 203 PyObject *_PyCFunctionFast(PyObject *self, 204 PyObject *const *args, 205 Py_ssize_t nargs); 206 207.. c:type:: _PyCFunctionFastWithKeywords 208 209 Type of the functions used to implement Python callables in C 210 with signature :const:`METH_FASTCALL | METH_KEYWORDS`. 211 The function signature is:: 212 213 PyObject *_PyCFunctionFastWithKeywords(PyObject *self, 214 PyObject *const *args, 215 Py_ssize_t nargs, 216 PyObject *kwnames); 217 218.. c:type:: PyCMethod 219 220 Type of the functions used to implement Python callables in C 221 with signature :const:`METH_METHOD | METH_FASTCALL | METH_KEYWORDS`. 222 The function signature is:: 223 224 PyObject *PyCMethod(PyObject *self, 225 PyTypeObject *defining_class, 226 PyObject *const *args, 227 Py_ssize_t nargs, 228 PyObject *kwnames) 229 230 .. versionadded:: 3.9 231 232 233.. c:type:: PyMethodDef 234 235 Structure used to describe a method of an extension type. This structure has 236 four fields: 237 238 +------------------+---------------+-------------------------------+ 239 | Field | C Type | Meaning | 240 +==================+===============+===============================+ 241 | :attr:`ml_name` | const char \* | name of the method | 242 +------------------+---------------+-------------------------------+ 243 | :attr:`ml_meth` | PyCFunction | pointer to the C | 244 | | | implementation | 245 +------------------+---------------+-------------------------------+ 246 | :attr:`ml_flags` | int | flag bits indicating how the | 247 | | | call should be constructed | 248 +------------------+---------------+-------------------------------+ 249 | :attr:`ml_doc` | const char \* | points to the contents of the | 250 | | | docstring | 251 +------------------+---------------+-------------------------------+ 252 253The :attr:`ml_meth` is a C function pointer. The functions may be of different 254types, but they always return :c:type:`PyObject*`. If the function is not of 255the :c:type:`PyCFunction`, the compiler will require a cast in the method table. 256Even though :c:type:`PyCFunction` defines the first parameter as 257:c:type:`PyObject*`, it is common that the method implementation uses the 258specific C type of the *self* object. 259 260The :attr:`ml_flags` field is a bitfield which can include the following flags. 261The individual flags indicate either a calling convention or a binding 262convention. 263 264There are these calling conventions: 265 266.. data:: METH_VARARGS 267 268 This is the typical calling convention, where the methods have the type 269 :c:type:`PyCFunction`. The function expects two :c:type:`PyObject*` values. 270 The first one is the *self* object for methods; for module functions, it is 271 the module object. The second parameter (often called *args*) is a tuple 272 object representing all arguments. This parameter is typically processed 273 using :c:func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`. 274 275 276.. data:: METH_VARARGS | METH_KEYWORDS 277 278 Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`. 279 The function expects three parameters: *self*, *args*, *kwargs* where 280 *kwargs* is a dictionary of all the keyword arguments or possibly ``NULL`` 281 if there are no keyword arguments. The parameters are typically processed 282 using :c:func:`PyArg_ParseTupleAndKeywords`. 283 284 285.. data:: METH_FASTCALL 286 287 Fast calling convention supporting only positional arguments. 288 The methods have the type :c:type:`_PyCFunctionFast`. 289 The first parameter is *self*, the second parameter is a C array 290 of :c:type:`PyObject*` values indicating the arguments and the third 291 parameter is the number of arguments (the length of the array). 292 293 .. versionadded:: 3.7 294 295 .. versionchanged:: 3.10 296 297 ``METH_FASTCALL`` is now part of the stable ABI. 298 299 300.. data:: METH_FASTCALL | METH_KEYWORDS 301 302 Extension of :const:`METH_FASTCALL` supporting also keyword arguments, 303 with methods of type :c:type:`_PyCFunctionFastWithKeywords`. 304 Keyword arguments are passed the same way as in the 305 :ref:`vectorcall protocol <vectorcall>`: 306 there is an additional fourth :c:type:`PyObject*` parameter 307 which is a tuple representing the names of the keyword arguments 308 (which are guaranteed to be strings) 309 or possibly ``NULL`` if there are no keywords. The values of the keyword 310 arguments are stored in the *args* array, after the positional arguments. 311 312 This is not part of the :ref:`limited API <stable>`. 313 314 .. versionadded:: 3.7 315 316 317.. data:: METH_METHOD | METH_FASTCALL | METH_KEYWORDS 318 319 Extension of :const:`METH_FASTCALL | METH_KEYWORDS` supporting the *defining 320 class*, that is, the class that contains the method in question. 321 The defining class might be a superclass of ``Py_TYPE(self)``. 322 323 The method needs to be of type :c:type:`PyCMethod`, the same as for 324 ``METH_FASTCALL | METH_KEYWORDS`` with ``defining_class`` argument added after 325 ``self``. 326 327 .. versionadded:: 3.9 328 329 330.. data:: METH_NOARGS 331 332 Methods without parameters don't need to check whether arguments are given if 333 they are listed with the :const:`METH_NOARGS` flag. They need to be of type 334 :c:type:`PyCFunction`. The first parameter is typically named *self* and will 335 hold a reference to the module or object instance. In all cases the second 336 parameter will be ``NULL``. 337 338 339.. data:: METH_O 340 341 Methods with a single object argument can be listed with the :const:`METH_O` 342 flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument. 343 They have the type :c:type:`PyCFunction`, with the *self* parameter, and a 344 :c:type:`PyObject*` parameter representing the single argument. 345 346 347These two constants are not used to indicate the calling convention but the 348binding when use with methods of classes. These may not be used for functions 349defined for modules. At most one of these flags may be set for any given 350method. 351 352 353.. data:: METH_CLASS 354 355 .. index:: builtin: classmethod 356 357 The method will be passed the type object as the first parameter rather 358 than an instance of the type. This is used to create *class methods*, 359 similar to what is created when using the :func:`classmethod` built-in 360 function. 361 362 363.. data:: METH_STATIC 364 365 .. index:: builtin: staticmethod 366 367 The method will be passed ``NULL`` as the first parameter rather than an 368 instance of the type. This is used to create *static methods*, similar to 369 what is created when using the :func:`staticmethod` built-in function. 370 371One other constant controls whether a method is loaded in place of another 372definition with the same method name. 373 374 375.. data:: METH_COEXIST 376 377 The method will be loaded in place of existing definitions. Without 378 *METH_COEXIST*, the default is to skip repeated definitions. Since slot 379 wrappers are loaded before the method table, the existence of a 380 *sq_contains* slot, for example, would generate a wrapped method named 381 :meth:`__contains__` and preclude the loading of a corresponding 382 PyCFunction with the same name. With the flag defined, the PyCFunction 383 will be loaded in place of the wrapper object and will co-exist with the 384 slot. This is helpful because calls to PyCFunctions are optimized more 385 than wrapper object calls. 386 387 388Accessing attributes of extension types 389--------------------------------------- 390 391.. c:type:: PyMemberDef 392 393 Structure which describes an attribute of a type which corresponds to a C 394 struct member. Its fields are: 395 396 +------------------+---------------+-------------------------------+ 397 | Field | C Type | Meaning | 398 +==================+===============+===============================+ 399 | :attr:`name` | const char \* | name of the member | 400 +------------------+---------------+-------------------------------+ 401 | :attr:`!type` | int | the type of the member in the | 402 | | | C struct | 403 +------------------+---------------+-------------------------------+ 404 | :attr:`offset` | Py_ssize_t | the offset in bytes that the | 405 | | | member is located on the | 406 | | | type's object struct | 407 +------------------+---------------+-------------------------------+ 408 | :attr:`flags` | int | flag bits indicating if the | 409 | | | field should be read-only or | 410 | | | writable | 411 +------------------+---------------+-------------------------------+ 412 | :attr:`doc` | const char \* | points to the contents of the | 413 | | | docstring | 414 +------------------+---------------+-------------------------------+ 415 416 :attr:`!type` can be one of many ``T_`` macros corresponding to various C 417 types. When the member is accessed in Python, it will be converted to the 418 equivalent Python type. 419 420 =============== ================== 421 Macro name C type 422 =============== ================== 423 T_SHORT short 424 T_INT int 425 T_LONG long 426 T_FLOAT float 427 T_DOUBLE double 428 T_STRING const char \* 429 T_OBJECT PyObject \* 430 T_OBJECT_EX PyObject \* 431 T_CHAR char 432 T_BYTE char 433 T_UBYTE unsigned char 434 T_UINT unsigned int 435 T_USHORT unsigned short 436 T_ULONG unsigned long 437 T_BOOL char 438 T_LONGLONG long long 439 T_ULONGLONG unsigned long long 440 T_PYSSIZET Py_ssize_t 441 =============== ================== 442 443 :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` differ in that 444 :c:macro:`T_OBJECT` returns ``None`` if the member is ``NULL`` and 445 :c:macro:`T_OBJECT_EX` raises an :exc:`AttributeError`. Try to use 446 :c:macro:`T_OBJECT_EX` over :c:macro:`T_OBJECT` because :c:macro:`T_OBJECT_EX` 447 handles use of the :keyword:`del` statement on that attribute more correctly 448 than :c:macro:`T_OBJECT`. 449 450 :attr:`flags` can be ``0`` for write and read access or :c:macro:`READONLY` for 451 read-only access. Using :c:macro:`T_STRING` for :attr:`type` implies 452 :c:macro:`READONLY`. :c:macro:`T_STRING` data is interpreted as UTF-8. 453 Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` 454 members can be deleted. (They are set to ``NULL``). 455 456 .. _pymemberdef-offsets: 457 458 Heap allocated types (created using :c:func:`PyType_FromSpec` or similar), 459 ``PyMemberDef`` may contain definitions for the special members 460 ``__dictoffset__``, ``__weaklistoffset__`` and ``__vectorcalloffset__``, 461 corresponding to 462 :c:member:`~PyTypeObject.tp_dictoffset`, 463 :c:member:`~PyTypeObject.tp_weaklistoffset` and 464 :c:member:`~PyTypeObject.tp_vectorcall_offset` in type objects. 465 These must be defined with ``T_PYSSIZET`` and ``READONLY``, for example:: 466 467 static PyMemberDef spam_type_members[] = { 468 {"__dictoffset__", T_PYSSIZET, offsetof(Spam_object, dict), READONLY}, 469 {NULL} /* Sentinel */ 470 }; 471 472 473.. c:function:: PyObject* PyMember_GetOne(const char *obj_addr, struct PyMemberDef *m) 474 475 Get an attribute belonging to the object at address *obj_addr*. The 476 attribute is described by ``PyMemberDef`` *m*. Returns ``NULL`` 477 on error. 478 479 480.. c:function:: int PyMember_SetOne(char *obj_addr, struct PyMemberDef *m, PyObject *o) 481 482 Set an attribute belonging to the object at address *obj_addr* to object *o*. 483 The attribute to set is described by ``PyMemberDef`` *m*. Returns ``0`` 484 if successful and a negative value on failure. 485 486 487.. c:type:: PyGetSetDef 488 489 Structure to define property-like access for a type. See also description of 490 the :c:member:`PyTypeObject.tp_getset` slot. 491 492 +-------------+------------------+-----------------------------------+ 493 | Field | C Type | Meaning | 494 +=============+==================+===================================+ 495 | name | const char \* | attribute name | 496 +-------------+------------------+-----------------------------------+ 497 | get | getter | C Function to get the attribute | 498 +-------------+------------------+-----------------------------------+ 499 | set | setter | optional C function to set or | 500 | | | delete the attribute, if omitted | 501 | | | the attribute is readonly | 502 +-------------+------------------+-----------------------------------+ 503 | doc | const char \* | optional docstring | 504 +-------------+------------------+-----------------------------------+ 505 | closure | void \* | optional function pointer, | 506 | | | providing additional data for | 507 | | | getter and setter | 508 +-------------+------------------+-----------------------------------+ 509 510 The ``get`` function takes one :c:type:`PyObject*` parameter (the 511 instance) and a function pointer (the associated ``closure``):: 512 513 typedef PyObject *(*getter)(PyObject *, void *); 514 515 It should return a new reference on success or ``NULL`` with a set exception 516 on failure. 517 518 ``set`` functions take two :c:type:`PyObject*` parameters (the instance and 519 the value to be set) and a function pointer (the associated ``closure``):: 520 521 typedef int (*setter)(PyObject *, PyObject *, void *); 522 523 In case the attribute should be deleted the second parameter is ``NULL``. 524 Should return ``0`` on success or ``-1`` with a set exception on failure. 525