Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1 | .. highlightlang:: c |
| 2 | |
| 3 | .. _type-structs: |
| 4 | |
| 5 | Type Objects |
| 6 | ============ |
| 7 | |
| 8 | Perhaps one of the most important structures of the Python object system is the |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 9 | structure that defines a new type: the :c:type:`PyTypeObject` structure. Type |
| 10 | objects can be handled using any of the :c:func:`PyObject_\*` or |
| 11 | :c:func:`PyType_\*` functions, but do not offer much that's interesting to most |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 12 | Python applications. These objects are fundamental to how objects behave, so |
| 13 | they are very important to the interpreter itself and to any extension module |
| 14 | that implements new types. |
| 15 | |
| 16 | Type objects are fairly large compared to most of the standard types. The reason |
| 17 | for the size is that each type object stores a large number of values, mostly C |
| 18 | function pointers, each of which implements a small part of the type's |
| 19 | functionality. The fields of the type object are examined in detail in this |
| 20 | section. The fields will be described in the order in which they occur in the |
| 21 | structure. |
| 22 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 23 | In addition to the following quick reference, the :ref:`examples` |
| 24 | section provides at-a-glance insight into the meaning and use of |
| 25 | :c:type:`PyTypeObject`. |
| 26 | |
| 27 | |
| 28 | Quick Reference |
| 29 | --------------- |
| 30 | |
| 31 | .. _tp-slots-table: |
| 32 | |
| 33 | "tp slots" |
| 34 | ^^^^^^^^^^ |
| 35 | |
| 36 | .. table:: |
| 37 | :widths: 18,18,18,1,1,1,1 |
| 38 | |
| 39 | +---------------------------------------------+-----------------------------------+-------------------+---------------+ |
| 40 | | PyTypeObject Slot [#slots]_ | :ref:`Type <slot-typedefs-table>` | special | Info [#cols]_ | |
| 41 | | | | methods/attrs +---+---+---+---+ |
| 42 | | | | | O | T | D | I | |
| 43 | +=============================================+===================================+===================+===+===+===+===+ |
| 44 | | <R> :c:member:`~PyTypeObject.tp_name` | const char * | __name__ | X | X | | | |
| 45 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 46 | | :c:member:`~PyTypeObject.tp_basicsize` | Py_ssize_t | | X | X | | X | |
| 47 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 48 | | :c:member:`~PyTypeObject.tp_itemsize` | Py_ssize_t | | | X | | X | |
| 49 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 50 | | :c:member:`~PyTypeObject.tp_dealloc` | :c:type:`destructor` | | X | X | | X | |
| 51 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 52 | | (:c:member:`~PyTypeObject.tp_print`) | | |
| 53 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 54 | | (:c:member:`~PyTypeObject.tp_getattr`) | :c:type:`getattrfunc` | __getattribute__, | | | | G | |
| 55 | | | | __getattr__ | | | | | |
| 56 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 57 | | (:c:member:`~PyTypeObject.tp_setattr`) | :c:type:`setattrfunc` | __setattr__, | | | | G | |
| 58 | | | | __delattr__ | | | | | |
| 59 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 60 | | :c:member:`~PyTypeObject.tp_as_async` | :c:type:`PyAsyncMethods` * | :ref:`sub-slots` | | | | % | |
| 61 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 62 | | :c:member:`~PyTypeObject.tp_repr` | :c:type:`reprfunc` | __repr__ | X | X | | X | |
| 63 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 64 | | :c:member:`~PyTypeObject.tp_as_number` | :c:type:`PyNumberMethods` * | :ref:`sub-slots` | | | | % | |
| 65 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 66 | | :c:member:`~PyTypeObject.tp_as_sequence` | :c:type:`PySequenceMethods` * | :ref:`sub-slots` | | | | % | |
| 67 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 68 | | :c:member:`~PyTypeObject.tp_as_mapping` | :c:type:`PyMappingMethods` * | :ref:`sub-slots` | | | | % | |
| 69 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 70 | | :c:member:`~PyTypeObject.tp_hash` | :c:type:`hashfunc` | __hash__ | X | | | G | |
| 71 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 72 | | :c:member:`~PyTypeObject.tp_call` | :c:type:`ternaryfunc` | __call__ | | X | | X | |
| 73 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 74 | | :c:member:`~PyTypeObject.tp_str` | :c:type:`reprfunc` | __str__ | X | | | X | |
| 75 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 76 | | :c:member:`~PyTypeObject.tp_getattro` | :c:type:`getattrofunc` | __getattribute__, | X | X | | G | |
| 77 | | | | __getattr__ | | | | | |
| 78 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 79 | | :c:member:`~PyTypeObject.tp_setattro` | :c:type:`setattrofunc` | __setattr__, | X | X | | G | |
| 80 | | | | __delattr__ | | | | | |
| 81 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 82 | | :c:member:`~PyTypeObject.tp_as_buffer` | :c:type:`PyBufferProcs` * | | | | | % | |
| 83 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 84 | | :c:member:`~PyTypeObject.tp_flags` | unsigned long | | X | X | | ? | |
| 85 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 86 | | :c:member:`~PyTypeObject.tp_doc` | const char * | __doc__ | X | X | | | |
| 87 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 88 | | :c:member:`~PyTypeObject.tp_traverse` | :c:type:`traverseproc` | | | X | | G | |
| 89 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 90 | | :c:member:`~PyTypeObject.tp_clear` | :c:type:`inquiry` | | | X | | G | |
| 91 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 92 | | :c:member:`~PyTypeObject.tp_richcompare` | :c:type:`richcmpfunc` | __lt__, | X | | | G | |
| 93 | | | | __le__, | | | | | |
| 94 | | | | __eq__, | | | | | |
| 95 | | | | __ne__, | | | | | |
| 96 | | | | __gt__, | | | | | |
| 97 | | | | __ge__ | | | | | |
| 98 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 99 | | :c:member:`~PyTypeObject.tp_weaklistoffset` | Py_ssize_t | | | X | | ? | |
| 100 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 101 | | :c:member:`~PyTypeObject.tp_iter` | :c:type:`getiterfunc` | __iter__ | | | | X | |
| 102 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 103 | | :c:member:`~PyTypeObject.tp_iternext` | :c:type:`iternextfunc` | __next__ | | | | X | |
| 104 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 105 | | :c:member:`~PyTypeObject.tp_methods` | :c:type:`PyMethodDef` [] | | X | X | | | |
| 106 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 107 | | :c:member:`~PyTypeObject.tp_members` | :c:type:`PyMemberDef` [] | | | X | | | |
| 108 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 109 | | :c:member:`~PyTypeObject.tp_getset` | :c:type:`PyGetSetDef` [] | | X | X | | | |
| 110 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 111 | | :c:member:`~PyTypeObject.tp_base` | :c:type:`PyTypeObject` * | __base__ | | | X | | |
| 112 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 113 | | :c:member:`~PyTypeObject.tp_dict` | :c:type:`PyObject` * | __dict__ | | | ? | | |
| 114 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 115 | | :c:member:`~PyTypeObject.tp_descr_get` | :c:type:`descrgetfunc` | __get__ | | | | X | |
| 116 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 117 | | :c:member:`~PyTypeObject.tp_descr_set` | :c:type:`descrsetfunc` | __set__, | | | | X | |
| 118 | | | | __delete__ | | | | | |
| 119 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 120 | | :c:member:`~PyTypeObject.tp_dictoffset` | Py_ssize_t | | | X | | ? | |
| 121 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 122 | | :c:member:`~PyTypeObject.tp_init` | :c:type:`initproc` | __init__ | X | X | | X | |
| 123 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 124 | | :c:member:`~PyTypeObject.tp_alloc` | :c:type:`allocfunc` | | X | | ? | ? | |
| 125 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 126 | | :c:member:`~PyTypeObject.tp_new` | :c:type:`newfunc` | __new__ | X | X | ? | ? | |
| 127 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 128 | | :c:member:`~PyTypeObject.tp_free` | :c:type:`freefunc` | | X | X | ? | ? | |
| 129 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 130 | | :c:member:`~PyTypeObject.tp_is_gc` | :c:type:`inquiry` | | | X | | X | |
| 131 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 132 | | <:c:member:`~PyTypeObject.tp_bases`> | :c:type:`PyObject` * | __bases__ | | | ~ | | |
| 133 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 134 | | <:c:member:`~PyTypeObject.tp_mro`> | :c:type:`PyObject` * | __mro__ | | | ~ | | |
| 135 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 136 | | [:c:member:`~PyTypeObject.tp_cache`] | :c:type:`PyObject` * | | | | | |
| 137 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 138 | | [:c:member:`~PyTypeObject.tp_subclasses`] | :c:type:`PyObject` * | __subclasses__ | | | | |
| 139 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 140 | | [:c:member:`~PyTypeObject.tp_weaklist`] | :c:type:`PyObject` * | | | | | |
| 141 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 142 | | (:c:member:`~PyTypeObject.tp_del`) | :c:type:`destructor` | | | | | | |
| 143 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 144 | | [:c:member:`~PyTypeObject.tp_version_tag`] | unsigned int | | | | | |
| 145 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 146 | | :c:member:`~PyTypeObject.tp_finalize` | :c:type:`destructor` | __del__ | | | | X | |
| 147 | +---------------------------------------------+-----------------------------------+-------------------+---+---+---+---+ |
| 148 | |
| 149 | If :const:`COUNT_ALLOCS` is defined then the following (internal-only) |
| 150 | fields exist as well: |
| 151 | |
| 152 | * :c:member:`~PyTypeObject.tp_allocs` |
| 153 | * :c:member:`~PyTypeObject.tp_frees` |
| 154 | * :c:member:`~PyTypeObject.tp_maxalloc` |
| 155 | * :c:member:`~PyTypeObject.tp_prev` |
| 156 | * :c:member:`~PyTypeObject.tp_next` |
| 157 | |
| 158 | .. [#slots] |
| 159 | A slot name in parentheses indicates it is (effectively) deprecated. |
| 160 | Names in angle brackets should be treated as read-only. |
| 161 | Names in square brackets are for internal use only. |
| 162 | "<R>" (as a prefix) means the field is required (must be non-*NULL*). |
| 163 | .. [#cols] Columns: |
| 164 | |
| 165 | **"O"**: set on :c:type:`PyBaseObject_Type` |
| 166 | |
| 167 | **"T"**: set on :c:type:`PyType_Type` |
| 168 | |
| 169 | **"D"**: default (if slot is set to *NULL*) |
| 170 | |
| 171 | .. code-block:: none |
| 172 | |
| 173 | X - *PyType_Ready* sets this value if it is *NULL* |
| 174 | ~ - *PyType_Ready* always sets this value (it should be *NULL*) |
| 175 | ? - *PyType_Ready* may set this value depending on other slots |
| 176 | |
| 177 | Also see the inheritance column ("I"). |
| 178 | |
| 179 | **"I"**: inheritance |
| 180 | |
| 181 | .. code-block:: none |
| 182 | |
| 183 | X - type slot is inherited via *PyType_Ready* if defined with a *NULL* value |
| 184 | % - the slots of the sub-struct are inherited individually |
| 185 | G - inherited, but only in combination with other slots; see the slot's description |
| 186 | ? - it's complicated; see the slot's description |
| 187 | |
| 188 | Note that some slots are effectively inherited through the normal |
| 189 | attribute lookup chain. |
| 190 | |
| 191 | .. _sub-slots: |
| 192 | |
| 193 | sub-slots |
| 194 | ^^^^^^^^^ |
| 195 | |
| 196 | .. table:: |
| 197 | :widths: 26,17,12 |
| 198 | |
| 199 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 200 | | Slot | :ref:`Type <slot-typedefs-table>` | special | |
| 201 | | | | methods | |
| 202 | +=========================================================+===================================+==============+ |
| 203 | | :c:member:`~PyAsyncMethods.am_await` | :c:type:`unaryfunc` | __await__ | |
| 204 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 205 | | :c:member:`~PyAsyncMethods.am_aiter` | :c:type:`unaryfunc` | __aiter__ | |
| 206 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 207 | | :c:member:`~PyAsyncMethods.am_anext` | :c:type:`unaryfunc` | __anext__ | |
| 208 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 209 | | | |
| 210 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 211 | | :c:member:`~PyNumberMethods.nb_add` | :c:type:`binaryfunc` | __add__ | |
| 212 | | | | __radd__ | |
| 213 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 214 | | :c:member:`~PyNumberMethods.nb_inplace_add` | :c:type:`binaryfunc` | __iadd__ | |
| 215 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 216 | | :c:member:`~PyNumberMethods.nb_subtract` | :c:type:`binaryfunc` | __sub__ | |
| 217 | | | | __rsub__ | |
| 218 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 219 | | :c:member:`~PyNumberMethods.nb_inplace_subtract` | :c:type:`binaryfunc` | __sub__ | |
| 220 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 221 | | :c:member:`~PyNumberMethods.nb_multiply` | :c:type:`binaryfunc` | __mul__ | |
| 222 | | | | __rmul__ | |
| 223 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 224 | | :c:member:`~PyNumberMethods.nb_inplace_multiply` | :c:type:`binaryfunc` | __mul__ | |
| 225 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 226 | | :c:member:`~PyNumberMethods.nb_remainder` | :c:type:`binaryfunc` | __mod__ | |
| 227 | | | | __rmod__ | |
| 228 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 229 | | :c:member:`~PyNumberMethods.nb_inplace_remainder` | :c:type:`binaryfunc` | __mod__ | |
| 230 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 231 | | :c:member:`~PyNumberMethods.nb_divmod` | :c:type:`binaryfunc` | __divmod__ | |
| 232 | | | | __rdivmod__ | |
| 233 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 234 | | :c:member:`~PyNumberMethods.nb_power` | :c:type:`ternaryfunc` | __pow__ | |
| 235 | | | | __rpow__ | |
| 236 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 237 | | :c:member:`~PyNumberMethods.nb_inplace_power` | :c:type:`ternaryfunc` | __pow__ | |
| 238 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 239 | | :c:member:`~PyNumberMethods.nb_negative` | :c:type:`unaryfunc` | __neg__ | |
| 240 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 241 | | :c:member:`~PyNumberMethods.nb_positive` | :c:type:`unaryfunc` | __pos__ | |
| 242 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 243 | | :c:member:`~PyNumberMethods.nb_absolute` | :c:type:`unaryfunc` | __abs__ | |
| 244 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 245 | | :c:member:`~PyNumberMethods.nb_bool` | :c:type:`inquiry` | __bool__ | |
| 246 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 247 | | :c:member:`~PyNumberMethods.nb_invert` | :c:type:`unaryfunc` | __invert__ | |
| 248 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 249 | | :c:member:`~PyNumberMethods.nb_lshift` | :c:type:`binaryfunc` | __lshift__ | |
| 250 | | | | __rlshift__ | |
| 251 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 252 | | :c:member:`~PyNumberMethods.nb_inplace_lshift` | :c:type:`binaryfunc` | __lshift__ | |
| 253 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 254 | | :c:member:`~PyNumberMethods.nb_rshift` | :c:type:`binaryfunc` | __rshift__ | |
| 255 | | | | __rrshift__ | |
| 256 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 257 | | :c:member:`~PyNumberMethods.nb_inplace_rshift` | :c:type:`binaryfunc` | __rshift__ | |
| 258 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 259 | | :c:member:`~PyNumberMethods.nb_and` | :c:type:`binaryfunc` | __and__ | |
| 260 | | | | __rand__ | |
| 261 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 262 | | :c:member:`~PyNumberMethods.nb_inplace_and` | :c:type:`binaryfunc` | __and__ | |
| 263 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 264 | | :c:member:`~PyNumberMethods.nb_xor` | :c:type:`binaryfunc` | __xor__ | |
| 265 | | | | __rxor__ | |
| 266 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 267 | | :c:member:`~PyNumberMethods.nb_inplace_xor` | :c:type:`binaryfunc` | __xor__ | |
| 268 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 269 | | :c:member:`~PyNumberMethods.nb_or` | :c:type:`binaryfunc` | __or__ | |
| 270 | | | | __ror__ | |
| 271 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 272 | | :c:member:`~PyNumberMethods.nb_inplace_or` | :c:type:`binaryfunc` | __or__ | |
| 273 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 274 | | :c:member:`~PyNumberMethods.nb_int` | :c:type:`unaryfunc` | __int__ | |
| 275 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 276 | | :c:member:`~PyNumberMethods.nb_reserved` | void * | | |
| 277 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 278 | | :c:member:`~PyNumberMethods.nb_float` | :c:type:`unaryfunc` | __float__ | |
| 279 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 280 | | :c:member:`~PyNumberMethods.nb_floor_divide` | :c:type:`binaryfunc` | __floordiv__ | |
| 281 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 282 | | :c:member:`~PyNumberMethods.nb_inplace_floor_divide` | :c:type:`binaryfunc` | __floordiv__ | |
| 283 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 284 | | :c:member:`~PyNumberMethods.nb_true_divide` | :c:type:`binaryfunc` | __truediv__ | |
| 285 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 286 | | :c:member:`~PyNumberMethods.nb_inplace_true_divide` | :c:type:`binaryfunc` | __truediv__ | |
| 287 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 288 | | :c:member:`~PyNumberMethods.nb_index` | :c:type:`binaryfunc` | __index__ | |
| 289 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 290 | | :c:member:`~PyNumberMethods.nb_matrix_multiply` | :c:type:`binaryfunc` | __matmul__ | |
| 291 | | | | __rmatmul__ | |
| 292 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 293 | | :c:member:`~PyNumberMethods.nb_inplace_matrix_multiply` | :c:type:`binaryfunc` | __matmul__ | |
| 294 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 295 | | | |
| 296 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 297 | | :c:member:`~PyMappingMethods.mp_length` | :c:type:`lenfunc` | __len__ | |
| 298 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 299 | | :c:member:`~PyMappingMethods.mp_subscript` | :c:type:`binaryfunc` | __getitem__ | |
| 300 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 301 | | :c:member:`~PyMappingMethods.mp_ass_subscript` | :c:type:`objobjargproc` | __setitem__, | |
| 302 | | | | __delitem__ | |
| 303 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 304 | | | |
| 305 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 306 | | :c:member:`~PySequenceMethods.sq_length` | :c:type:`lenfunc` | __len__ | |
| 307 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 308 | | :c:member:`~PySequenceMethods.sq_concat` | :c:type:`binaryfunc` | __add__ | |
| 309 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 310 | | :c:member:`~PySequenceMethods.sq_repeat` | :c:type:`ssizeargfunc` | __mul__ | |
| 311 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 312 | | :c:member:`~PySequenceMethods.sq_item` | :c:type:`ssizeargfunc` | __getitem__ | |
| 313 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 314 | | :c:member:`~PySequenceMethods.sq_ass_item` | :c:type:`ssizeobjargproc` | __setitem__ | |
| 315 | | | | __delitem__ | |
| 316 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 317 | | :c:member:`~PySequenceMethods.sq_contains` | :c:type:`objobjproc` | __contains__ | |
| 318 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 319 | | :c:member:`~PySequenceMethods.sq_inplace_concat` | :c:type:`binaryfunc` | __iadd__ | |
| 320 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 321 | | :c:member:`~PySequenceMethods.sq_inplace_repeat` | :c:type:`ssizeargfunc` | __imul__ | |
| 322 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 323 | | | |
| 324 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 325 | | :c:member:`~PyBufferProcs.bf_getbuffer` | :c:func:`getbufferproc` | | |
| 326 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 327 | | :c:member:`~PyBufferProcs.bf_releasebuffer` | :c:func:`releasebufferproc` | | |
| 328 | +---------------------------------------------------------+-----------------------------------+--------------+ |
| 329 | |
| 330 | .. _slot-typedefs-table: |
| 331 | |
| 332 | slot typedefs |
| 333 | ^^^^^^^^^^^^^ |
| 334 | |
| 335 | +-----------------------------+-----------------------------+----------------------+ |
| 336 | | typedef | Parameter Types | Return Type | |
| 337 | +=============================+=============================+======================+ |
| 338 | | :c:type:`allocfunc` | .. line-block:: | :c:type:`PyObject` * | |
| 339 | | | | | |
| 340 | | | :c:type:`PyTypeObject` * | | |
| 341 | | | Py_ssize_t | | |
| 342 | +-----------------------------+-----------------------------+----------------------+ |
| 343 | | :c:type:`destructor` | void * | void | |
| 344 | +-----------------------------+-----------------------------+----------------------+ |
| 345 | | :c:type:`freefunc` | void * | void | |
| 346 | +-----------------------------+-----------------------------+----------------------+ |
| 347 | | :c:type:`traverseproc` | .. line-block:: | int | |
| 348 | | | | | |
| 349 | | | void * | | |
| 350 | | | :c:type:`visitproc` | | |
| 351 | | | void * | | |
| 352 | +-----------------------------+-----------------------------+----------------------+ |
| 353 | | :c:type:`newfunc` | .. line-block:: | :c:type:`PyObject` * | |
| 354 | | | | | |
| 355 | | | :c:type:`PyObject` * | | |
| 356 | | | :c:type:`PyObject` * | | |
| 357 | | | :c:type:`PyObject` * | | |
| 358 | +-----------------------------+-----------------------------+----------------------+ |
| 359 | | :c:type:`initproc` | .. line-block:: | int | |
| 360 | | | | | |
| 361 | | | :c:type:`PyObject` * | | |
| 362 | | | :c:type:`PyObject` * | | |
| 363 | | | :c:type:`PyObject` * | | |
| 364 | +-----------------------------+-----------------------------+----------------------+ |
| 365 | | :c:type:`reprfunc` | :c:type:`PyObject` * | :c:type:`PyObject` * | |
| 366 | +-----------------------------+-----------------------------+----------------------+ |
| 367 | | :c:type:`printfunc` | .. line-block:: | int | |
| 368 | | | | | |
| 369 | | | :c:type:`PyObject` * | | |
| 370 | | | FILE * | | |
| 371 | | | int | | |
| 372 | +-----------------------------+-----------------------------+----------------------+ |
| 373 | | :c:type:`getattrfunc` | .. line-block:: | :c:type:`PyObject` * | |
| 374 | | | | | |
| 375 | | | :c:type:`PyObject` * | | |
| 376 | | | const char * | | |
| 377 | +-----------------------------+-----------------------------+----------------------+ |
| 378 | | :c:type:`setattrfunc` | .. line-block:: | int | |
| 379 | | | | | |
| 380 | | | :c:type:`PyObject` * | | |
| 381 | | | const char * | | |
| 382 | | | :c:type:`PyObject` * | | |
| 383 | +-----------------------------+-----------------------------+----------------------+ |
| 384 | | :c:type:`getattrofunc` | .. line-block:: | :c:type:`PyObject` * | |
| 385 | | | | | |
| 386 | | | :c:type:`PyObject` * | | |
| 387 | | | :c:type:`PyObject` * | | |
| 388 | +-----------------------------+-----------------------------+----------------------+ |
| 389 | | :c:type:`setattrofunc` | .. line-block:: | int | |
| 390 | | | | | |
| 391 | | | :c:type:`PyObject` * | | |
| 392 | | | :c:type:`PyObject` * | | |
| 393 | | | :c:type:`PyObject` * | | |
| 394 | +-----------------------------+-----------------------------+----------------------+ |
| 395 | | :c:type:`descrgetfunc` | .. line-block:: | :c:type:`PyObject` * | |
| 396 | | | | | |
| 397 | | | :c:type:`PyObject` * | | |
| 398 | | | :c:type:`PyObject` * | | |
| 399 | | | :c:type:`PyObject` * | | |
| 400 | +-----------------------------+-----------------------------+----------------------+ |
| 401 | | :c:type:`descrsetfunc` | .. line-block:: | int | |
| 402 | | | | | |
| 403 | | | :c:type:`PyObject` * | | |
| 404 | | | :c:type:`PyObject` * | | |
| 405 | | | :c:type:`PyObject` * | | |
| 406 | +-----------------------------+-----------------------------+----------------------+ |
| 407 | | :c:type:`hashfunc` | :c:type:`PyObject` * | Py_hash_t | |
| 408 | +-----------------------------+-----------------------------+----------------------+ |
| 409 | | :c:type:`richcmpfunc` | .. line-block:: | :c:type:`PyObject` * | |
| 410 | | | | | |
| 411 | | | :c:type:`PyObject` * | | |
| 412 | | | :c:type:`PyObject` * | | |
| 413 | | | int | | |
| 414 | +-----------------------------+-----------------------------+----------------------+ |
| 415 | | :c:type:`getiterfunc` | :c:type:`PyObject` * | :c:type:`PyObject` * | |
| 416 | +-----------------------------+-----------------------------+----------------------+ |
| 417 | | :c:type:`iternextfunc` | :c:type:`PyObject` * | :c:type:`PyObject` * | |
| 418 | +-----------------------------+-----------------------------+----------------------+ |
| 419 | | :c:type:`lenfunc` | :c:type:`PyObject` * | Py_ssize_t | |
| 420 | +-----------------------------+-----------------------------+----------------------+ |
| 421 | | :c:type:`getbufferproc` | .. line-block:: | int | |
| 422 | | | | | |
| 423 | | | :c:type:`PyObject` * | | |
| 424 | | | :c:type:`Py_buffer` * | | |
| 425 | | | int | | |
| 426 | +-----------------------------+-----------------------------+----------------------+ |
| 427 | | :c:type:`releasebufferproc` | .. line-block:: | void | |
| 428 | | | | | |
| 429 | | | :c:type:`PyObject` * | | |
| 430 | | | :c:type:`Py_buffer` * | | |
| 431 | +-----------------------------+-----------------------------+----------------------+ |
| 432 | | :c:type:`inquiry` | void * | int | |
| 433 | +-----------------------------+-----------------------------+----------------------+ |
| 434 | | :c:type:`unaryfunc` | .. line-block:: | :c:type:`PyObject` * | |
| 435 | | | | | |
| 436 | | | :c:type:`PyObject` * | | |
| 437 | +-----------------------------+-----------------------------+----------------------+ |
| 438 | | :c:type:`binaryfunc` | .. line-block:: | :c:type:`PyObject` * | |
| 439 | | | | | |
| 440 | | | :c:type:`PyObject` * | | |
| 441 | | | :c:type:`PyObject` * | | |
| 442 | +-----------------------------+-----------------------------+----------------------+ |
| 443 | | :c:type:`ternaryfunc` | .. line-block:: | :c:type:`PyObject` * | |
| 444 | | | | | |
| 445 | | | :c:type:`PyObject` * | | |
| 446 | | | :c:type:`PyObject` * | | |
| 447 | | | :c:type:`PyObject` * | | |
| 448 | +-----------------------------+-----------------------------+----------------------+ |
| 449 | | :c:type:`ssizeargfunc` | .. line-block:: | :c:type:`PyObject` * | |
| 450 | | | | | |
| 451 | | | :c:type:`PyObject` * | | |
| 452 | | | Py_ssize_t | | |
| 453 | +-----------------------------+-----------------------------+----------------------+ |
| 454 | | :c:type:`ssizeobjargproc` | .. line-block:: | int | |
| 455 | | | | | |
| 456 | | | :c:type:`PyObject` * | | |
| 457 | | | Py_ssize_t | | |
| 458 | +-----------------------------+-----------------------------+----------------------+ |
| 459 | | :c:type:`objobjproc` | .. line-block:: | int | |
| 460 | | | | | |
| 461 | | | :c:type:`PyObject` * | | |
| 462 | | | :c:type:`PyObject` * | | |
| 463 | +-----------------------------+-----------------------------+----------------------+ |
| 464 | | :c:type:`objobjargproc` | .. line-block:: | int | |
| 465 | | | | | |
| 466 | | | :c:type:`PyObject` * | | |
| 467 | | | :c:type:`PyObject` * | | |
| 468 | | | :c:type:`PyObject` * | | |
| 469 | +-----------------------------+-----------------------------+----------------------+ |
| 470 | |
| 471 | See :ref:`slot-typedefs` below for more detail. |
| 472 | |
| 473 | |
| 474 | PyTypeObject Definition |
| 475 | ----------------------- |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 476 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 477 | The structure definition for :c:type:`PyTypeObject` can be found in |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 478 | :file:`Include/object.h`. For convenience of reference, this repeats the |
| 479 | definition found there: |
| 480 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 481 | .. XXX Drop this? |
| 482 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 483 | .. literalinclude:: ../includes/typestruct.h |
| 484 | |
| 485 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 486 | PyObject Slots |
| 487 | -------------- |
| 488 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 489 | The type object structure extends the :c:type:`PyVarObject` structure. The |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 490 | :attr:`ob_size` field is used for dynamic types (created by :func:`type_new`, |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 491 | usually called from a class statement). Note that :c:data:`PyType_Type` (the |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 492 | metatype) initializes :c:member:`~PyTypeObject.tp_itemsize`, which means that its instances (i.e. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 493 | type objects) *must* have the :attr:`ob_size` field. |
| 494 | |
| 495 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 496 | .. c:member:: PyObject* PyObject._ob_next |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 497 | PyObject* PyObject._ob_prev |
| 498 | |
| 499 | These fields are only present when the macro ``Py_TRACE_REFS`` is defined. |
| 500 | Their initialization to *NULL* is taken care of by the ``PyObject_HEAD_INIT`` |
| 501 | macro. For statically allocated objects, these fields always remain *NULL*. |
| 502 | For dynamically allocated objects, these two fields are used to link the object |
| 503 | into a doubly-linked list of *all* live objects on the heap. This could be used |
| 504 | for various debugging purposes; currently the only use is to print the objects |
| 505 | that are still alive at the end of a run when the environment variable |
| 506 | :envvar:`PYTHONDUMPREFS` is set. |
| 507 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 508 | **Inheritance:** |
| 509 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 510 | These fields are not inherited by subtypes. |
| 511 | |
| 512 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 513 | .. c:member:: Py_ssize_t PyObject.ob_refcnt |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 514 | |
| 515 | This is the type object's reference count, initialized to ``1`` by the |
| 516 | ``PyObject_HEAD_INIT`` macro. Note that for statically allocated type objects, |
| 517 | the type's instances (objects whose :attr:`ob_type` points back to the type) do |
| 518 | *not* count as references. But for dynamically allocated type objects, the |
| 519 | instances *do* count as references. |
| 520 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 521 | **Inheritance:** |
| 522 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 523 | This field is not inherited by subtypes. |
| 524 | |
| 525 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 526 | .. c:member:: PyTypeObject* PyObject.ob_type |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 527 | |
| 528 | This is the type's type, in other words its metatype. It is initialized by the |
| 529 | argument to the ``PyObject_HEAD_INIT`` macro, and its value should normally be |
| 530 | ``&PyType_Type``. However, for dynamically loadable extension modules that must |
| 531 | be usable on Windows (at least), the compiler complains that this is not a valid |
| 532 | initializer. Therefore, the convention is to pass *NULL* to the |
| 533 | ``PyObject_HEAD_INIT`` macro and to initialize this field explicitly at the |
| 534 | start of the module's initialization function, before doing anything else. This |
| 535 | is typically done like this:: |
| 536 | |
| 537 | Foo_Type.ob_type = &PyType_Type; |
| 538 | |
| 539 | This should be done before any instances of the type are created. |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 540 | :c:func:`PyType_Ready` checks if :attr:`ob_type` is *NULL*, and if so, |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 541 | initializes it to the :attr:`ob_type` field of the base class. |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 542 | :c:func:`PyType_Ready` will not change this field if it is non-zero. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 543 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 544 | **Inheritance:** |
| 545 | |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 546 | This field is inherited by subtypes. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 547 | |
| 548 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 549 | PyVarObject Slots |
| 550 | ----------------- |
| 551 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 552 | .. c:member:: Py_ssize_t PyVarObject.ob_size |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 553 | |
| 554 | For statically allocated type objects, this should be initialized to zero. For |
| 555 | dynamically allocated type objects, this field has a special internal meaning. |
| 556 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 557 | **Inheritance:** |
| 558 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 559 | This field is not inherited by subtypes. |
| 560 | |
| 561 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 562 | PyTypeObject Slots |
| 563 | ------------------ |
| 564 | |
| 565 | Each slot has a section describing inheritance. If :c:func:`PyType_Ready` |
| 566 | may set a value when the field is set to *NULL* then there will also be |
| 567 | a "Default" section. (Note that many fields set on :c:type:`PyBaseObject_Type` |
| 568 | and :c:type:`PyType_Type` effectively act as defaults.) |
| 569 | |
Martin Panter | 78d5033 | 2015-08-25 05:06:39 +0000 | [diff] [blame] | 570 | .. c:member:: const char* PyTypeObject.tp_name |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 571 | |
| 572 | Pointer to a NUL-terminated string containing the name of the type. For types |
| 573 | that are accessible as module globals, the string should be the full module |
| 574 | name, followed by a dot, followed by the type name; for built-in types, it |
| 575 | should be just the type name. If the module is a submodule of a package, the |
| 576 | full package name is part of the full module name. For example, a type named |
| 577 | :class:`T` defined in module :mod:`M` in subpackage :mod:`Q` in package :mod:`P` |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 578 | should have the :c:member:`~PyTypeObject.tp_name` initializer ``"P.Q.M.T"``. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 579 | |
| 580 | For dynamically allocated type objects, this should just be the type name, and |
| 581 | the module name explicitly stored in the type dict as the value for key |
| 582 | ``'__module__'``. |
| 583 | |
| 584 | For statically allocated type objects, the tp_name field should contain a dot. |
| 585 | Everything before the last dot is made accessible as the :attr:`__module__` |
| 586 | attribute, and everything after the last dot is made accessible as the |
Martin Panter | bae5d81 | 2016-06-18 03:57:31 +0000 | [diff] [blame] | 587 | :attr:`~definition.__name__` attribute. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 588 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 589 | If no dot is present, the entire :c:member:`~PyTypeObject.tp_name` field is made accessible as the |
Martin Panter | bae5d81 | 2016-06-18 03:57:31 +0000 | [diff] [blame] | 590 | :attr:`~definition.__name__` attribute, and the :attr:`__module__` attribute is undefined |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 591 | (unless explicitly set in the dictionary, as explained above). This means your |
Serhiy Storchaka | de0574b | 2016-10-07 23:24:35 +0300 | [diff] [blame] | 592 | type will be impossible to pickle. Additionally, it will not be listed in |
| 593 | module documentations created with pydoc. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 594 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 595 | This field must not be *NULL*. It is the only required field |
| 596 | in :c:func:`PyTypeObject` (other than potentially |
| 597 | :c:member:`~PyTypeObject.tp_itemsize`). |
| 598 | |
| 599 | **Inheritance:** |
| 600 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 601 | This field is not inherited by subtypes. |
| 602 | |
| 603 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 604 | .. c:member:: Py_ssize_t PyTypeObject.tp_basicsize |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 605 | Py_ssize_t PyTypeObject.tp_itemsize |
| 606 | |
| 607 | These fields allow calculating the size in bytes of instances of the type. |
| 608 | |
| 609 | There are two kinds of types: types with fixed-length instances have a zero |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 610 | :c:member:`~PyTypeObject.tp_itemsize` field, types with variable-length instances have a non-zero |
| 611 | :c:member:`~PyTypeObject.tp_itemsize` field. For a type with fixed-length instances, all |
| 612 | instances have the same size, given in :c:member:`~PyTypeObject.tp_basicsize`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 613 | |
| 614 | For a type with variable-length instances, the instances must have an |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 615 | :attr:`ob_size` field, and the instance size is :c:member:`~PyTypeObject.tp_basicsize` plus N |
| 616 | times :c:member:`~PyTypeObject.tp_itemsize`, where N is the "length" of the object. The value of |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 617 | N is typically stored in the instance's :attr:`ob_size` field. There are |
Mark Dickinson | bf5c6a9 | 2009-01-17 10:21:23 +0000 | [diff] [blame] | 618 | exceptions: for example, ints use a negative :attr:`ob_size` to indicate a |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 619 | negative number, and N is ``abs(ob_size)`` there. Also, the presence of an |
| 620 | :attr:`ob_size` field in the instance layout doesn't mean that the instance |
| 621 | structure is variable-length (for example, the structure for the list type has |
| 622 | fixed-length instances, yet those instances have a meaningful :attr:`ob_size` |
| 623 | field). |
| 624 | |
| 625 | The basic size includes the fields in the instance declared by the macro |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 626 | :c:macro:`PyObject_HEAD` or :c:macro:`PyObject_VAR_HEAD` (whichever is used to |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 627 | declare the instance struct) and this in turn includes the :attr:`_ob_prev` and |
| 628 | :attr:`_ob_next` fields if they are present. This means that the only correct |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 629 | way to get an initializer for the :c:member:`~PyTypeObject.tp_basicsize` is to use the |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 630 | ``sizeof`` operator on the struct used to declare the instance layout. |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 631 | The basic size does not include the GC header size. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 632 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 633 | A note about alignment: if the variable items require a particular alignment, |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 634 | this should be taken care of by the value of :c:member:`~PyTypeObject.tp_basicsize`. Example: |
| 635 | suppose a type implements an array of ``double``. :c:member:`~PyTypeObject.tp_itemsize` is |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 636 | ``sizeof(double)``. It is the programmer's responsibility that |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 637 | :c:member:`~PyTypeObject.tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 638 | alignment requirement for ``double``). |
| 639 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 640 | For any type with variable-length instances, this field must not be *NULL*. |
| 641 | |
| 642 | **Inheritance:** |
| 643 | |
| 644 | These fields are inherited separately by subtypes. If the base type has a |
| 645 | non-zero :c:member:`~PyTypeObject.tp_itemsize`, it is generally not safe to set |
| 646 | :c:member:`~PyTypeObject.tp_itemsize` to a different non-zero value in a subtype (though this |
| 647 | depends on the implementation of the base type). |
| 648 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 649 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 650 | .. c:member:: destructor PyTypeObject.tp_dealloc |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 651 | |
| 652 | A pointer to the instance destructor function. This function must be defined |
| 653 | unless the type guarantees that its instances will never be deallocated (as is |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 654 | the case for the singletons ``None`` and ``Ellipsis``). The function signature is:: |
| 655 | |
| 656 | void tp_dealloc(PyObject *self); |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 657 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 658 | The destructor function is called by the :c:func:`Py_DECREF` and |
| 659 | :c:func:`Py_XDECREF` macros when the new reference count is zero. At this point, |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 660 | the instance is still in existence, but there are no references to it. The |
| 661 | destructor function should free all references which the instance owns, free all |
| 662 | memory buffers owned by the instance (using the freeing function corresponding |
| 663 | to the allocation function used to allocate the buffer), and finally (as its |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 664 | last action) call the type's :c:member:`~PyTypeObject.tp_free` function. If the type is not |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 665 | subtypable (doesn't have the :const:`Py_TPFLAGS_BASETYPE` flag bit set), it is |
| 666 | permissible to call the object deallocator directly instead of via |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 667 | :c:member:`~PyTypeObject.tp_free`. The object deallocator should be the one used to allocate the |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 668 | instance; this is normally :c:func:`PyObject_Del` if the instance was allocated |
| 669 | using :c:func:`PyObject_New` or :c:func:`PyObject_VarNew`, or |
| 670 | :c:func:`PyObject_GC_Del` if the instance was allocated using |
| 671 | :c:func:`PyObject_GC_New` or :c:func:`PyObject_GC_NewVar`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 672 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 673 | **Inheritance:** |
| 674 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 675 | This field is inherited by subtypes. |
| 676 | |
| 677 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 678 | .. c:member:: printfunc PyTypeObject.tp_print |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 679 | |
Georg Brandl | 340c749 | 2014-10-05 16:38:02 +0200 | [diff] [blame] | 680 | Reserved slot, formerly used for print formatting in Python 2.x. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 681 | |
| 682 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 683 | .. c:member:: getattrfunc PyTypeObject.tp_getattr |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 684 | |
| 685 | An optional pointer to the get-attribute-string function. |
| 686 | |
| 687 | This field is deprecated. When it is defined, it should point to a function |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 688 | that acts the same as the :c:member:`~PyTypeObject.tp_getattro` function, but taking a C string |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 689 | instead of a Python string object to give the attribute name. |
Martin Panter | 7a44783 | 2016-12-10 05:56:13 +0000 | [diff] [blame] | 690 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 691 | **Inheritance:** |
| 692 | |
| 693 | Group: :attr:`tp_getattr`, :attr:`tp_getattro` |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 694 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 695 | This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattro`: a subtype |
| 696 | inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when |
| 697 | the subtype's :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` are both *NULL*. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 698 | |
| 699 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 700 | .. c:member:: setattrfunc PyTypeObject.tp_setattr |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 701 | |
Martin Panter | 45be8d6 | 2015-12-08 00:03:20 +0000 | [diff] [blame] | 702 | An optional pointer to the function for setting and deleting attributes. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 703 | |
| 704 | This field is deprecated. When it is defined, it should point to a function |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 705 | that acts the same as the :c:member:`~PyTypeObject.tp_setattro` function, but taking a C string |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 706 | instead of a Python string object to give the attribute name. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 707 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 708 | **Inheritance:** |
Martin Panter | 7a44783 | 2016-12-10 05:56:13 +0000 | [diff] [blame] | 709 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 710 | Group: :attr:`tp_setattr`, :attr:`tp_setattro` |
| 711 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 712 | This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattro`: a subtype |
| 713 | inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when |
| 714 | the subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` are both *NULL*. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 715 | |
| 716 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 717 | .. c:member:: PyAsyncMethods* PyTypeObject.tp_as_async |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 718 | |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 719 | Pointer to an additional structure that contains fields relevant only to |
| 720 | objects which implement :term:`awaitable` and :term:`asynchronous iterator` |
| 721 | protocols at the C-level. See :ref:`async-structs` for details. |
| 722 | |
| 723 | .. versionadded:: 3.5 |
Yury Selivanov | a18cad5 | 2015-05-21 17:02:31 -0400 | [diff] [blame] | 724 | Formerly known as ``tp_compare`` and ``tp_reserved``. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 725 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 726 | **Inheritance:** |
| 727 | |
| 728 | The :c:member:`~PyTypeObject.tp_as_async` field is not inherited, |
| 729 | but the contained fields are inherited individually. |
| 730 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 731 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 732 | .. c:member:: reprfunc PyTypeObject.tp_repr |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 733 | |
| 734 | .. index:: builtin: repr |
| 735 | |
| 736 | An optional pointer to a function that implements the built-in function |
| 737 | :func:`repr`. |
| 738 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 739 | The signature is the same as for :c:func:`PyObject_Repr`:: |
| 740 | |
| 741 | PyObject *tp_repr(PyObject *self); |
| 742 | |
| 743 | The function must return a string or a Unicode object. Ideally, |
| 744 | this function should return a string that, when passed to |
| 745 | :func:`eval`, given a suitable environment, returns an object with the |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 746 | same value. If this is not feasible, it should return a string starting with |
| 747 | ``'<'`` and ending with ``'>'`` from which both the type and the value of the |
| 748 | object can be deduced. |
| 749 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 750 | **Inheritance:** |
| 751 | |
| 752 | This field is inherited by subtypes. |
| 753 | |
| 754 | **Default:** |
| 755 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 756 | When this field is not set, a string of the form ``<%s object at %p>`` is |
| 757 | returned, where ``%s`` is replaced by the type name, and ``%p`` by the object's |
| 758 | memory address. |
| 759 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 760 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 761 | .. c:member:: PyNumberMethods* PyTypeObject.tp_as_number |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 762 | |
| 763 | Pointer to an additional structure that contains fields relevant only to |
| 764 | objects which implement the number protocol. These fields are documented in |
| 765 | :ref:`number-structs`. |
| 766 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 767 | **Inheritance:** |
| 768 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 769 | The :c:member:`~PyTypeObject.tp_as_number` field is not inherited, but the contained fields are |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 770 | inherited individually. |
| 771 | |
| 772 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 773 | .. c:member:: PySequenceMethods* PyTypeObject.tp_as_sequence |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 774 | |
| 775 | Pointer to an additional structure that contains fields relevant only to |
| 776 | objects which implement the sequence protocol. These fields are documented |
| 777 | in :ref:`sequence-structs`. |
| 778 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 779 | **Inheritance:** |
| 780 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 781 | The :c:member:`~PyTypeObject.tp_as_sequence` field is not inherited, but the contained fields |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 782 | are inherited individually. |
| 783 | |
| 784 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 785 | .. c:member:: PyMappingMethods* PyTypeObject.tp_as_mapping |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 786 | |
| 787 | Pointer to an additional structure that contains fields relevant only to |
| 788 | objects which implement the mapping protocol. These fields are documented in |
| 789 | :ref:`mapping-structs`. |
| 790 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 791 | **Inheritance:** |
| 792 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 793 | The :c:member:`~PyTypeObject.tp_as_mapping` field is not inherited, but the contained fields |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 794 | are inherited individually. |
| 795 | |
| 796 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 797 | .. c:member:: hashfunc PyTypeObject.tp_hash |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 798 | |
| 799 | .. index:: builtin: hash |
| 800 | |
| 801 | An optional pointer to a function that implements the built-in function |
| 802 | :func:`hash`. |
| 803 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 804 | The signature is the same as for :c:func:`PyObject_Hash`:: |
| 805 | |
| 806 | Py_hash_t tp_hash(PyObject *); |
| 807 | |
| 808 | The value ``-1`` should not be returned as a |
Benjamin Peterson | 8f67d08 | 2010-10-17 20:54:53 +0000 | [diff] [blame] | 809 | normal return value; when an error occurs during the computation of the hash |
| 810 | value, the function should set an exception and return ``-1``. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 811 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 812 | When this field is not set (*and* :attr:`tp_richcompare` is not set), |
| 813 | an attempt to take the hash of the object raises :exc:`TypeError`. |
| 814 | This is the same as setting it to :c:func:`PyObject_HashNotImplemented`. |
| 815 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 816 | This field can be set explicitly to :c:func:`PyObject_HashNotImplemented` to |
Nick Coghlan | 7a70a3a | 2008-08-18 13:18:16 +0000 | [diff] [blame] | 817 | block inheritance of the hash method from a parent type. This is interpreted |
| 818 | as the equivalent of ``__hash__ = None`` at the Python level, causing |
| 819 | ``isinstance(o, collections.Hashable)`` to correctly return ``False``. Note |
| 820 | that the converse is also true - setting ``__hash__ = None`` on a class at |
| 821 | the Python level will result in the ``tp_hash`` slot being set to |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 822 | :c:func:`PyObject_HashNotImplemented`. |
Nick Coghlan | 7a70a3a | 2008-08-18 13:18:16 +0000 | [diff] [blame] | 823 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 824 | **Inheritance:** |
| 825 | |
| 826 | Group: :attr:`tp_hash`, :attr:`tp_richcompare` |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 827 | |
Mark Dickinson | 9f98926 | 2009-02-02 21:29:40 +0000 | [diff] [blame] | 828 | This field is inherited by subtypes together with |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 829 | :c:member:`~PyTypeObject.tp_richcompare`: a subtype inherits both of |
| 830 | :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash`, when the subtype's |
| 831 | :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` are both *NULL*. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 832 | |
| 833 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 834 | .. c:member:: ternaryfunc PyTypeObject.tp_call |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 835 | |
| 836 | An optional pointer to a function that implements calling the object. This |
| 837 | should be *NULL* if the object is not callable. The signature is the same as |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 838 | for :c:func:`PyObject_Call`:: |
| 839 | |
| 840 | PyObject *tp_call(PyObject *self, PyObject *args, PyObject *kwargs); |
| 841 | |
| 842 | **Inheritance:** |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 843 | |
| 844 | This field is inherited by subtypes. |
| 845 | |
| 846 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 847 | .. c:member:: reprfunc PyTypeObject.tp_str |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 848 | |
| 849 | An optional pointer to a function that implements the built-in operation |
| 850 | :func:`str`. (Note that :class:`str` is a type now, and :func:`str` calls the |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 851 | constructor for that type. This constructor calls :c:func:`PyObject_Str` to do |
| 852 | the actual work, and :c:func:`PyObject_Str` will call this handler.) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 853 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 854 | The signature is the same as for :c:func:`PyObject_Str`:: |
| 855 | |
| 856 | PyObject *tp_str(PyObject *self); |
| 857 | |
| 858 | The function must return a string or a Unicode object. It should be a "friendly" string |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 859 | representation of the object, as this is the representation that will be used, |
| 860 | among other things, by the :func:`print` function. |
| 861 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 862 | **Inheritance:** |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 863 | |
| 864 | This field is inherited by subtypes. |
| 865 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 866 | **Default:** |
| 867 | |
| 868 | When this field is not set, :c:func:`PyObject_Repr` is called to return a string |
| 869 | representation. |
| 870 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 871 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 872 | .. c:member:: getattrofunc PyTypeObject.tp_getattro |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 873 | |
| 874 | An optional pointer to the get-attribute function. |
| 875 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 876 | The signature is the same as for :c:func:`PyObject_GetAttr`:: |
| 877 | |
| 878 | PyObject *tp_getattro(PyObject *self, PyObject *attr); |
| 879 | |
| 880 | It is usually convenient to set this field to :c:func:`PyObject_GenericGetAttr`, |
| 881 | which implements the normal way of looking for object attributes. |
| 882 | |
| 883 | **Inheritance:** |
| 884 | |
| 885 | Group: :attr:`tp_getattr`, :attr:`tp_getattro` |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 886 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 887 | This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattr`: a subtype |
| 888 | inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when |
| 889 | the subtype's :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` are both *NULL*. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 890 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 891 | **Default:** |
| 892 | |
| 893 | :c:type:`PyBaseObject_Type` uses :c:func:`PyObject_GenericGetAttr`. |
| 894 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 895 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 896 | .. c:member:: setattrofunc PyTypeObject.tp_setattro |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 897 | |
Martin Panter | 45be8d6 | 2015-12-08 00:03:20 +0000 | [diff] [blame] | 898 | An optional pointer to the function for setting and deleting attributes. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 899 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 900 | The signature is the same as for :c:func:`PyObject_SetAttr`:: |
| 901 | |
| 902 | PyObject *tp_setattro(PyObject *self, PyObject *attr, PyObject *value); |
| 903 | |
| 904 | In addition, setting *value* to *NULL* to delete an attribute must be |
| 905 | supported. It is usually convenient to set this field to |
| 906 | :c:func:`PyObject_GenericSetAttr`, which implements the normal |
| 907 | way of setting object attributes. |
| 908 | |
| 909 | **Inheritance:** |
| 910 | |
| 911 | Group: :attr:`tp_setattr`, :attr:`tp_setattro` |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 912 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 913 | This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattr`: a subtype |
| 914 | inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when |
| 915 | the subtype's :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` are both *NULL*. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 916 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 917 | **Default:** |
| 918 | |
| 919 | :c:type:`PyBaseObject_Type` uses :c:func:`PyObject_GenericSetAttr`. |
| 920 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 921 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 922 | .. c:member:: PyBufferProcs* PyTypeObject.tp_as_buffer |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 923 | |
| 924 | Pointer to an additional structure that contains fields relevant only to objects |
| 925 | which implement the buffer interface. These fields are documented in |
| 926 | :ref:`buffer-structs`. |
| 927 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 928 | **Inheritance:** |
| 929 | |
| 930 | The :c:member:`~PyTypeObject.tp_as_buffer` field is not inherited, |
| 931 | but the contained fields are inherited individually. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 932 | |
| 933 | |
Martin Panter | 78d5033 | 2015-08-25 05:06:39 +0000 | [diff] [blame] | 934 | .. c:member:: unsigned long PyTypeObject.tp_flags |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 935 | |
| 936 | This field is a bit mask of various flags. Some flags indicate variant |
| 937 | semantics for certain situations; others are used to indicate that certain |
| 938 | fields in the type object (or in the extension structures referenced via |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 939 | :c:member:`~PyTypeObject.tp_as_number`, :c:member:`~PyTypeObject.tp_as_sequence`, :c:member:`~PyTypeObject.tp_as_mapping`, and |
| 940 | :c:member:`~PyTypeObject.tp_as_buffer`) that were historically not always present are valid; if |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 941 | such a flag bit is clear, the type fields it guards must not be accessed and |
| 942 | must be considered to have a zero or *NULL* value instead. |
| 943 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 944 | **Inheritance:** |
| 945 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 946 | Inheritance of this field is complicated. Most flag bits are inherited |
| 947 | individually, i.e. if the base type has a flag bit set, the subtype inherits |
| 948 | this flag bit. The flag bits that pertain to extension structures are strictly |
| 949 | inherited if the extension structure is inherited, i.e. the base type's value of |
| 950 | the flag bit is copied into the subtype together with a pointer to the extension |
| 951 | structure. The :const:`Py_TPFLAGS_HAVE_GC` flag bit is inherited together with |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 952 | the :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields, i.e. if the |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 953 | :const:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 954 | :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` fields in the subtype exist and have |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 955 | *NULL* values. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 956 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 957 | .. XXX are most flag bits *really* inherited individually? |
| 958 | |
| 959 | **Default:** |
| 960 | |
| 961 | :c:type:`PyBaseObject_Type` uses |
| 962 | ``Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE``. |
| 963 | |
| 964 | **Bit Masks:** |
| 965 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 966 | The following bit masks are currently defined; these can be ORed together using |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 967 | the ``|`` operator to form the value of the :c:member:`~PyTypeObject.tp_flags` field. The macro |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 968 | :c:func:`PyType_HasFeature` takes a type and a flags value, *tp* and *f*, and |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 969 | checks whether ``tp->tp_flags & f`` is non-zero. |
| 970 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 971 | .. data:: Py_TPFLAGS_HEAPTYPE |
| 972 | |
| 973 | This bit is set when the type object itself is allocated on the heap. In this |
| 974 | case, the :attr:`ob_type` field of its instances is considered a reference to |
| 975 | the type, and the type object is INCREF'ed when a new instance is created, and |
| 976 | DECREF'ed when an instance is destroyed (this does not apply to instances of |
| 977 | subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or |
| 978 | DECREF'ed). |
| 979 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 980 | **Inheritance:** |
| 981 | |
| 982 | ??? |
| 983 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 984 | |
| 985 | .. data:: Py_TPFLAGS_BASETYPE |
| 986 | |
| 987 | This bit is set when the type can be used as the base type of another type. If |
| 988 | this bit is clear, the type cannot be subtyped (similar to a "final" class in |
| 989 | Java). |
| 990 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 991 | **Inheritance:** |
| 992 | |
| 993 | ??? |
| 994 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 995 | |
| 996 | .. data:: Py_TPFLAGS_READY |
| 997 | |
| 998 | This bit is set when the type object has been fully initialized by |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 999 | :c:func:`PyType_Ready`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1000 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1001 | **Inheritance:** |
| 1002 | |
| 1003 | ??? |
| 1004 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1005 | |
| 1006 | .. data:: Py_TPFLAGS_READYING |
| 1007 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1008 | This bit is set while :c:func:`PyType_Ready` is in the process of initializing |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1009 | the type object. |
| 1010 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1011 | **Inheritance:** |
| 1012 | |
| 1013 | ??? |
| 1014 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1015 | |
| 1016 | .. data:: Py_TPFLAGS_HAVE_GC |
| 1017 | |
| 1018 | This bit is set when the object supports garbage collection. If this bit |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1019 | is set, instances must be created using :c:func:`PyObject_GC_New` and |
| 1020 | destroyed using :c:func:`PyObject_GC_Del`. More information in section |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1021 | :ref:`supporting-cycle-detection`. This bit also implies that the |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1022 | GC-related fields :c:member:`~PyTypeObject.tp_traverse` and :c:member:`~PyTypeObject.tp_clear` are present in |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 1023 | the type object. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1024 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1025 | **Inheritance:** |
| 1026 | |
| 1027 | Group: :const:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear` |
| 1028 | |
| 1029 | The :const:`Py_TPFLAGS_HAVE_GC` flag bit is inherited |
| 1030 | together with the :attr:`tp_traverse` and :attr:`tp_clear` |
| 1031 | fields, i.e. if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is |
| 1032 | clear in the subtype and the :attr:`tp_traverse` and |
| 1033 | :attr:`tp_clear` fields in the subtype exist and have *NULL* |
| 1034 | values. |
| 1035 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1036 | |
| 1037 | .. data:: Py_TPFLAGS_DEFAULT |
| 1038 | |
| 1039 | This is a bitmask of all the bits that pertain to the existence of certain |
| 1040 | fields in the type object and its extension structures. Currently, it includes |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 1041 | the following bits: :const:`Py_TPFLAGS_HAVE_STACKLESS_EXTENSION`, |
| 1042 | :const:`Py_TPFLAGS_HAVE_VERSION_TAG`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1043 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1044 | **Inheritance:** |
| 1045 | |
| 1046 | ??? |
| 1047 | |
| 1048 | .. XXX Document more flags here? |
| 1049 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1050 | |
Antoine Pitrou | f9f54a2 | 2014-04-29 01:39:03 +0200 | [diff] [blame] | 1051 | .. data:: Py_TPFLAGS_LONG_SUBCLASS |
| 1052 | .. data:: Py_TPFLAGS_LIST_SUBCLASS |
| 1053 | .. data:: Py_TPFLAGS_TUPLE_SUBCLASS |
| 1054 | .. data:: Py_TPFLAGS_BYTES_SUBCLASS |
| 1055 | .. data:: Py_TPFLAGS_UNICODE_SUBCLASS |
| 1056 | .. data:: Py_TPFLAGS_DICT_SUBCLASS |
| 1057 | .. data:: Py_TPFLAGS_BASE_EXC_SUBCLASS |
| 1058 | .. data:: Py_TPFLAGS_TYPE_SUBCLASS |
| 1059 | |
| 1060 | These flags are used by functions such as |
| 1061 | :c:func:`PyLong_Check` to quickly determine if a type is a subclass |
| 1062 | of a built-in type; such specific checks are faster than a generic |
| 1063 | check, like :c:func:`PyObject_IsInstance`. Custom types that inherit |
| 1064 | from built-ins should have their :c:member:`~PyTypeObject.tp_flags` |
| 1065 | set appropriately, or the code that interacts with such types |
| 1066 | will behave differently depending on what kind of check is used. |
| 1067 | |
| 1068 | |
Antoine Pitrou | 796564c | 2013-07-30 19:59:21 +0200 | [diff] [blame] | 1069 | .. data:: Py_TPFLAGS_HAVE_FINALIZE |
| 1070 | |
Antoine Pitrou | a68cbfa | 2013-08-01 21:14:43 +0200 | [diff] [blame] | 1071 | This bit is set when the :c:member:`~PyTypeObject.tp_finalize` slot is present in the |
Antoine Pitrou | 796564c | 2013-07-30 19:59:21 +0200 | [diff] [blame] | 1072 | type structure. |
| 1073 | |
| 1074 | .. versionadded:: 3.4 |
| 1075 | |
| 1076 | |
Martin Panter | 78d5033 | 2015-08-25 05:06:39 +0000 | [diff] [blame] | 1077 | .. c:member:: const char* PyTypeObject.tp_doc |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1078 | |
| 1079 | An optional pointer to a NUL-terminated C string giving the docstring for this |
| 1080 | type object. This is exposed as the :attr:`__doc__` attribute on the type and |
| 1081 | instances of the type. |
| 1082 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1083 | **Inheritance:** |
| 1084 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1085 | This field is *not* inherited by subtypes. |
| 1086 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1087 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1088 | .. c:member:: traverseproc PyTypeObject.tp_traverse |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1089 | |
| 1090 | An optional pointer to a traversal function for the garbage collector. This is |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1091 | only used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. The signature is:: |
| 1092 | |
| 1093 | int tp_traverse(PyObject *self, visitproc visit, void *arg); |
| 1094 | |
| 1095 | More information about Python's garbage collection scheme can be found |
| 1096 | in section :ref:`supporting-cycle-detection`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1097 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1098 | The :c:member:`~PyTypeObject.tp_traverse` pointer is used by the garbage collector to detect |
| 1099 | reference cycles. A typical implementation of a :c:member:`~PyTypeObject.tp_traverse` function |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1100 | simply calls :c:func:`Py_VISIT` on each of the instance's members that are Python |
| 1101 | objects. For example, this is function :c:func:`local_traverse` from the |
Georg Brandl | 2067bfd | 2008-05-25 13:05:15 +0000 | [diff] [blame] | 1102 | :mod:`_thread` extension module:: |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1103 | |
| 1104 | static int |
| 1105 | local_traverse(localobject *self, visitproc visit, void *arg) |
| 1106 | { |
| 1107 | Py_VISIT(self->args); |
| 1108 | Py_VISIT(self->kw); |
| 1109 | Py_VISIT(self->dict); |
| 1110 | return 0; |
| 1111 | } |
| 1112 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1113 | Note that :c:func:`Py_VISIT` is called only on those members that can participate |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1114 | in reference cycles. Although there is also a ``self->key`` member, it can only |
| 1115 | be *NULL* or a Python string and therefore cannot be part of a reference cycle. |
| 1116 | |
| 1117 | On the other hand, even if you know a member can never be part of a cycle, as a |
| 1118 | debugging aid you may want to visit it anyway just so the :mod:`gc` module's |
Serhiy Storchaka | 0b68a2d | 2013-10-09 13:26:17 +0300 | [diff] [blame] | 1119 | :func:`~gc.get_referents` function will include it. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1120 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1121 | Note that :c:func:`Py_VISIT` requires the *visit* and *arg* parameters to |
| 1122 | :c:func:`local_traverse` to have these specific names; don't name them just |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1123 | anything. |
| 1124 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1125 | **Inheritance:** |
| 1126 | |
| 1127 | Group: :const:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear` |
| 1128 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1129 | This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_clear` and the |
| 1130 | :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and |
| 1131 | :c:member:`~PyTypeObject.tp_clear` are all inherited from the base type if they are all zero in |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 1132 | the subtype. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1133 | |
| 1134 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1135 | .. c:member:: inquiry PyTypeObject.tp_clear |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1136 | |
| 1137 | An optional pointer to a clear function for the garbage collector. This is only |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1138 | used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. The signature is:: |
| 1139 | |
| 1140 | int tp_clear(PyObject *); |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1141 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1142 | The :c:member:`~PyTypeObject.tp_clear` member function is used to break reference cycles in cyclic |
| 1143 | garbage detected by the garbage collector. Taken together, all :c:member:`~PyTypeObject.tp_clear` |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1144 | functions in the system must combine to break all reference cycles. This is |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1145 | subtle, and if in any doubt supply a :c:member:`~PyTypeObject.tp_clear` function. For example, |
| 1146 | the tuple type does not implement a :c:member:`~PyTypeObject.tp_clear` function, because it's |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1147 | possible to prove that no reference cycle can be composed entirely of tuples. |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1148 | Therefore the :c:member:`~PyTypeObject.tp_clear` functions of other types must be sufficient to |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1149 | break any cycle containing a tuple. This isn't immediately obvious, and there's |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1150 | rarely a good reason to avoid implementing :c:member:`~PyTypeObject.tp_clear`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1151 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1152 | Implementations of :c:member:`~PyTypeObject.tp_clear` should drop the instance's references to |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1153 | those of its members that may be Python objects, and set its pointers to those |
| 1154 | members to *NULL*, as in the following example:: |
| 1155 | |
| 1156 | static int |
| 1157 | local_clear(localobject *self) |
| 1158 | { |
| 1159 | Py_CLEAR(self->key); |
| 1160 | Py_CLEAR(self->args); |
| 1161 | Py_CLEAR(self->kw); |
| 1162 | Py_CLEAR(self->dict); |
| 1163 | return 0; |
| 1164 | } |
| 1165 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1166 | The :c:func:`Py_CLEAR` macro should be used, because clearing references is |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1167 | delicate: the reference to the contained object must not be decremented until |
| 1168 | after the pointer to the contained object is set to *NULL*. This is because |
| 1169 | decrementing the reference count may cause the contained object to become trash, |
| 1170 | triggering a chain of reclamation activity that may include invoking arbitrary |
| 1171 | Python code (due to finalizers, or weakref callbacks, associated with the |
| 1172 | contained object). If it's possible for such code to reference *self* again, |
| 1173 | it's important that the pointer to the contained object be *NULL* at that time, |
| 1174 | so that *self* knows the contained object can no longer be used. The |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1175 | :c:func:`Py_CLEAR` macro performs the operations in a safe order. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1176 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1177 | Because the goal of :c:member:`~PyTypeObject.tp_clear` functions is to break reference cycles, |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1178 | it's not necessary to clear contained objects like Python strings or Python |
| 1179 | integers, which can't participate in reference cycles. On the other hand, it may |
| 1180 | be convenient to clear all contained Python objects, and write the type's |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1181 | :c:member:`~PyTypeObject.tp_dealloc` function to invoke :c:member:`~PyTypeObject.tp_clear`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1182 | |
| 1183 | More information about Python's garbage collection scheme can be found in |
| 1184 | section :ref:`supporting-cycle-detection`. |
| 1185 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1186 | **Inheritance:** |
| 1187 | |
| 1188 | Group: :const:`Py_TPFLAGS_HAVE_GC`, :attr:`tp_traverse`, :attr:`tp_clear` |
| 1189 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1190 | This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_traverse` and the |
| 1191 | :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and |
| 1192 | :c:member:`~PyTypeObject.tp_clear` are all inherited from the base type if they are all zero in |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 1193 | the subtype. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1194 | |
| 1195 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1196 | .. c:member:: richcmpfunc PyTypeObject.tp_richcompare |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1197 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1198 | An optional pointer to the rich comparison function, whose signature is:: |
| 1199 | |
| 1200 | PyObject *tp_richcompare(PyObject *self, PyObject *other, int op); |
| 1201 | |
| 1202 | The first parameter is guaranteed to be an instance of the type |
| 1203 | that is defined by :c:type:`PyTypeObject`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1204 | |
Christian Heimes | e1c9811 | 2008-01-21 11:20:28 +0000 | [diff] [blame] | 1205 | The function should return the result of the comparison (usually ``Py_True`` |
| 1206 | or ``Py_False``). If the comparison is undefined, it must return |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1207 | ``Py_NotImplemented``, if another error occurred it must return *NULL* and |
Christian Heimes | e1c9811 | 2008-01-21 11:20:28 +0000 | [diff] [blame] | 1208 | set an exception condition. |
| 1209 | |
| 1210 | .. note:: |
| 1211 | |
| 1212 | If you want to implement a type for which only a limited set of |
| 1213 | comparisons makes sense (e.g. ``==`` and ``!=``, but not ``<`` and |
| 1214 | friends), directly raise :exc:`TypeError` in the rich comparison function. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1215 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1216 | The following constants are defined to be used as the third argument for |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1217 | :c:member:`~PyTypeObject.tp_richcompare` and for :c:func:`PyObject_RichCompare`: |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1218 | |
| 1219 | +----------------+------------+ |
| 1220 | | Constant | Comparison | |
| 1221 | +================+============+ |
| 1222 | | :const:`Py_LT` | ``<`` | |
| 1223 | +----------------+------------+ |
| 1224 | | :const:`Py_LE` | ``<=`` | |
| 1225 | +----------------+------------+ |
| 1226 | | :const:`Py_EQ` | ``==`` | |
| 1227 | +----------------+------------+ |
| 1228 | | :const:`Py_NE` | ``!=`` | |
| 1229 | +----------------+------------+ |
| 1230 | | :const:`Py_GT` | ``>`` | |
| 1231 | +----------------+------------+ |
| 1232 | | :const:`Py_GE` | ``>=`` | |
| 1233 | +----------------+------------+ |
| 1234 | |
stratakis | e8b1965 | 2017-11-02 11:32:54 +0100 | [diff] [blame] | 1235 | The following macro is defined to ease writing rich comparison functions: |
| 1236 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1237 | .. c:function:: PyObject \*Py_RETURN_RICHCOMPARE(VAL_A, VAL_B, int op) |
stratakis | e8b1965 | 2017-11-02 11:32:54 +0100 | [diff] [blame] | 1238 | |
| 1239 | Return ``Py_True`` or ``Py_False`` from the function, depending on the |
| 1240 | result of a comparison. |
| 1241 | VAL_A and VAL_B must be orderable by C comparison operators (for example, |
| 1242 | they may be C ints or floats). The third argument specifies the requested |
| 1243 | operation, as for :c:func:`PyObject_RichCompare`. |
| 1244 | |
| 1245 | The return value's reference count is properly incremented. |
| 1246 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1247 | On error, sets an exception and returns *NULL* from the function. |
stratakis | e8b1965 | 2017-11-02 11:32:54 +0100 | [diff] [blame] | 1248 | |
| 1249 | .. versionadded:: 3.7 |
| 1250 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1251 | **Inheritance:** |
| 1252 | |
| 1253 | Group: :attr:`tp_hash`, :attr:`tp_richcompare` |
| 1254 | |
| 1255 | This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_hash`: |
| 1256 | a subtype inherits :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` when |
| 1257 | the subtype's :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` are both |
| 1258 | *NULL*. |
| 1259 | |
| 1260 | **Default:** |
| 1261 | |
| 1262 | :c:type:`PyBaseObject_Type` provides a :attr:`tp_richcompare` |
| 1263 | implementation, which may be inherited. However, if only |
| 1264 | :attr:`tp_hash` is defined, not even the inherited function is used |
| 1265 | and instances of the type will not be able to participate in any |
| 1266 | comparisons. |
| 1267 | |
Christian Heimes | e1c9811 | 2008-01-21 11:20:28 +0000 | [diff] [blame] | 1268 | |
Martin Panter | 78d5033 | 2015-08-25 05:06:39 +0000 | [diff] [blame] | 1269 | .. c:member:: Py_ssize_t PyTypeObject.tp_weaklistoffset |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1270 | |
| 1271 | If the instances of this type are weakly referenceable, this field is greater |
| 1272 | than zero and contains the offset in the instance structure of the weak |
| 1273 | reference list head (ignoring the GC header, if present); this offset is used by |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1274 | :c:func:`PyObject_ClearWeakRefs` and the :c:func:`PyWeakref_\*` functions. The |
| 1275 | instance structure needs to include a field of type :c:type:`PyObject\*` which is |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1276 | initialized to *NULL*. |
| 1277 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1278 | Do not confuse this field with :c:member:`~PyTypeObject.tp_weaklist`; that is the list head for |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1279 | weak references to the type object itself. |
| 1280 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1281 | **Inheritance:** |
| 1282 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1283 | This field is inherited by subtypes, but see the rules listed below. A subtype |
| 1284 | may override this offset; this means that the subtype uses a different weak |
| 1285 | reference list head than the base type. Since the list head is always found via |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1286 | :c:member:`~PyTypeObject.tp_weaklistoffset`, this should not be a problem. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1287 | |
Serhiy Storchaka | 0b68a2d | 2013-10-09 13:26:17 +0300 | [diff] [blame] | 1288 | When a type defined by a class statement has no :attr:`~object.__slots__` declaration, |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1289 | and none of its base types are weakly referenceable, the type is made weakly |
| 1290 | referenceable by adding a weak reference list head slot to the instance layout |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1291 | and setting the :c:member:`~PyTypeObject.tp_weaklistoffset` of that slot's offset. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1292 | |
| 1293 | When a type's :attr:`__slots__` declaration contains a slot named |
| 1294 | :attr:`__weakref__`, that slot becomes the weak reference list head for |
| 1295 | instances of the type, and the slot's offset is stored in the type's |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1296 | :c:member:`~PyTypeObject.tp_weaklistoffset`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1297 | |
| 1298 | When a type's :attr:`__slots__` declaration does not contain a slot named |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1299 | :attr:`__weakref__`, the type inherits its :c:member:`~PyTypeObject.tp_weaklistoffset` from its |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1300 | base type. |
| 1301 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1302 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1303 | .. c:member:: getiterfunc PyTypeObject.tp_iter |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1304 | |
| 1305 | An optional pointer to a function that returns an iterator for the object. Its |
| 1306 | presence normally signals that the instances of this type are iterable (although |
Georg Brandl | 23e8db5 | 2008-04-07 19:17:06 +0000 | [diff] [blame] | 1307 | sequences may be iterable without this function). |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1308 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1309 | This function has the same signature as :c:func:`PyObject_GetIter`:: |
| 1310 | |
| 1311 | PyObject *tp_iter(PyObject *self); |
| 1312 | |
| 1313 | **Inheritance:** |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1314 | |
| 1315 | This field is inherited by subtypes. |
| 1316 | |
| 1317 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1318 | .. c:member:: iternextfunc PyTypeObject.tp_iternext |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1319 | |
Georg Brandl | f392057 | 2008-04-30 20:06:53 +0000 | [diff] [blame] | 1320 | An optional pointer to a function that returns the next item in an iterator. |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1321 | The signature is:: |
| 1322 | |
| 1323 | PyObject *tp_iternext(PyObject *self); |
| 1324 | |
Georg Brandl | f392057 | 2008-04-30 20:06:53 +0000 | [diff] [blame] | 1325 | When the iterator is exhausted, it must return *NULL*; a :exc:`StopIteration` |
| 1326 | exception may or may not be set. When another error occurs, it must return |
| 1327 | *NULL* too. Its presence signals that the instances of this type are |
| 1328 | iterators. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1329 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1330 | Iterator types should also define the :c:member:`~PyTypeObject.tp_iter` function, and that |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1331 | function should return the iterator instance itself (not a new iterator |
| 1332 | instance). |
| 1333 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1334 | This function has the same signature as :c:func:`PyIter_Next`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1335 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1336 | **Inheritance:** |
| 1337 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1338 | This field is inherited by subtypes. |
| 1339 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1340 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1341 | .. c:member:: struct PyMethodDef* PyTypeObject.tp_methods |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1342 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1343 | An optional pointer to a static *NULL*-terminated array of :c:type:`PyMethodDef` |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1344 | structures, declaring regular methods of this type. |
| 1345 | |
| 1346 | For each entry in the array, an entry is added to the type's dictionary (see |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1347 | :c:member:`~PyTypeObject.tp_dict` below) containing a method descriptor. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1348 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1349 | **Inheritance:** |
| 1350 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1351 | This field is not inherited by subtypes (methods are inherited through a |
| 1352 | different mechanism). |
| 1353 | |
| 1354 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1355 | .. c:member:: struct PyMemberDef* PyTypeObject.tp_members |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1356 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1357 | An optional pointer to a static *NULL*-terminated array of :c:type:`PyMemberDef` |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1358 | structures, declaring regular data members (fields or slots) of instances of |
| 1359 | this type. |
| 1360 | |
| 1361 | For each entry in the array, an entry is added to the type's dictionary (see |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1362 | :c:member:`~PyTypeObject.tp_dict` below) containing a member descriptor. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1363 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1364 | **Inheritance:** |
| 1365 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1366 | This field is not inherited by subtypes (members are inherited through a |
| 1367 | different mechanism). |
| 1368 | |
| 1369 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1370 | .. c:member:: struct PyGetSetDef* PyTypeObject.tp_getset |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1371 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1372 | An optional pointer to a static *NULL*-terminated array of :c:type:`PyGetSetDef` |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1373 | structures, declaring computed attributes of instances of this type. |
| 1374 | |
| 1375 | For each entry in the array, an entry is added to the type's dictionary (see |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1376 | :c:member:`~PyTypeObject.tp_dict` below) containing a getset descriptor. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1377 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1378 | **Inheritance:** |
| 1379 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1380 | This field is not inherited by subtypes (computed attributes are inherited |
| 1381 | through a different mechanism). |
| 1382 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1383 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1384 | .. c:member:: PyTypeObject* PyTypeObject.tp_base |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1385 | |
| 1386 | An optional pointer to a base type from which type properties are inherited. At |
| 1387 | this level, only single inheritance is supported; multiple inheritance require |
| 1388 | dynamically creating a type object by calling the metatype. |
| 1389 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1390 | .. note:: |
| 1391 | |
| 1392 | .. from Modules/xxmodule.c |
| 1393 | |
| 1394 | Slot initialization is subject to the rules of initializing globals. |
| 1395 | C99 requires the initializers to be "address constants". Function |
| 1396 | designators like :c:func:`PyType_GenericNew`, with implicit conversion |
| 1397 | to a pointer, are valid C99 address constants. |
| 1398 | |
| 1399 | However, the unary '&' operator applied to a non-static variable |
| 1400 | like :c:func:`PyBaseObject_Type` is not required to produce an address |
| 1401 | constant. Compilers may support this (gcc does), MSVC does not. |
| 1402 | Both compilers are strictly standard conforming in this particular |
| 1403 | behavior. |
| 1404 | |
| 1405 | Consequently, :c:member:`~PyTypeObject.tp_base` should be set in |
| 1406 | the extension module's init function. |
| 1407 | |
| 1408 | **Inheritance:** |
| 1409 | |
| 1410 | This field is not inherited by subtypes (obviously). |
| 1411 | |
| 1412 | **Default:** |
| 1413 | |
| 1414 | This field defaults to ``&PyBaseObject_Type`` (which to Python |
| 1415 | programmers is known as the type :class:`object`). |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1416 | |
| 1417 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1418 | .. c:member:: PyObject* PyTypeObject.tp_dict |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1419 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1420 | The type's dictionary is stored here by :c:func:`PyType_Ready`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1421 | |
| 1422 | This field should normally be initialized to *NULL* before PyType_Ready is |
| 1423 | called; it may also be initialized to a dictionary containing initial attributes |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1424 | for the type. Once :c:func:`PyType_Ready` has initialized the type, extra |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1425 | attributes for the type may be added to this dictionary only if they don't |
| 1426 | correspond to overloaded operations (like :meth:`__add__`). |
| 1427 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1428 | **Inheritance:** |
| 1429 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1430 | This field is not inherited by subtypes (though the attributes defined in here |
| 1431 | are inherited through a different mechanism). |
| 1432 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1433 | **Default:** |
| 1434 | |
| 1435 | If this field is *NULL*, :c:func:`PyType_Ready` will assign a new |
| 1436 | dictionary to it. |
| 1437 | |
Benjamin Peterson | 77c4fd0 | 2011-08-09 16:07:01 -0500 | [diff] [blame] | 1438 | .. warning:: |
| 1439 | |
| 1440 | It is not safe to use :c:func:`PyDict_SetItem` on or otherwise modify |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1441 | :c:member:`~PyTypeObject.tp_dict` with the dictionary C-API. |
Benjamin Peterson | 77c4fd0 | 2011-08-09 16:07:01 -0500 | [diff] [blame] | 1442 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1443 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1444 | .. c:member:: descrgetfunc PyTypeObject.tp_descr_get |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1445 | |
| 1446 | An optional pointer to a "descriptor get" function. |
| 1447 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1448 | The function signature is:: |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1449 | |
| 1450 | PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type); |
| 1451 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1452 | .. XXX explain more? |
| 1453 | |
| 1454 | **Inheritance:** |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1455 | |
| 1456 | This field is inherited by subtypes. |
| 1457 | |
| 1458 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1459 | .. c:member:: descrsetfunc PyTypeObject.tp_descr_set |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1460 | |
Martin Panter | 45be8d6 | 2015-12-08 00:03:20 +0000 | [diff] [blame] | 1461 | An optional pointer to a function for setting and deleting |
| 1462 | a descriptor's value. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1463 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1464 | The function signature is:: |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1465 | |
| 1466 | int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value); |
| 1467 | |
Martin Panter | 45be8d6 | 2015-12-08 00:03:20 +0000 | [diff] [blame] | 1468 | The *value* argument is set to *NULL* to delete the value. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1469 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1470 | .. XXX explain more? |
| 1471 | |
| 1472 | **Inheritance:** |
| 1473 | |
| 1474 | This field is inherited by subtypes. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1475 | |
| 1476 | |
Martin Panter | 78d5033 | 2015-08-25 05:06:39 +0000 | [diff] [blame] | 1477 | .. c:member:: Py_ssize_t PyTypeObject.tp_dictoffset |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1478 | |
| 1479 | If the instances of this type have a dictionary containing instance variables, |
| 1480 | this field is non-zero and contains the offset in the instances of the type of |
| 1481 | the instance variable dictionary; this offset is used by |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1482 | :c:func:`PyObject_GenericGetAttr`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1483 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1484 | Do not confuse this field with :c:member:`~PyTypeObject.tp_dict`; that is the dictionary for |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1485 | attributes of the type object itself. |
| 1486 | |
| 1487 | If the value of this field is greater than zero, it specifies the offset from |
| 1488 | the start of the instance structure. If the value is less than zero, it |
| 1489 | specifies the offset from the *end* of the instance structure. A negative |
| 1490 | offset is more expensive to use, and should only be used when the instance |
| 1491 | structure contains a variable-length part. This is used for example to add an |
| 1492 | instance variable dictionary to subtypes of :class:`str` or :class:`tuple`. Note |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1493 | that the :c:member:`~PyTypeObject.tp_basicsize` field should account for the dictionary added to |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1494 | the end in that case, even though the dictionary is not included in the basic |
| 1495 | object layout. On a system with a pointer size of 4 bytes, |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1496 | :c:member:`~PyTypeObject.tp_dictoffset` should be set to ``-4`` to indicate that the dictionary is |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1497 | at the very end of the structure. |
| 1498 | |
| 1499 | The real dictionary offset in an instance can be computed from a negative |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1500 | :c:member:`~PyTypeObject.tp_dictoffset` as follows:: |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1501 | |
| 1502 | dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset |
| 1503 | if dictoffset is not aligned on sizeof(void*): |
| 1504 | round up to sizeof(void*) |
| 1505 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1506 | where :c:member:`~PyTypeObject.tp_basicsize`, :c:member:`~PyTypeObject.tp_itemsize` and :c:member:`~PyTypeObject.tp_dictoffset` are |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1507 | taken from the type object, and :attr:`ob_size` is taken from the instance. The |
Mark Dickinson | bf5c6a9 | 2009-01-17 10:21:23 +0000 | [diff] [blame] | 1508 | absolute value is taken because ints use the sign of :attr:`ob_size` to |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1509 | store the sign of the number. (There's never a need to do this calculation |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1510 | yourself; it is done for you by :c:func:`_PyObject_GetDictPtr`.) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1511 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1512 | **Inheritance:** |
| 1513 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1514 | This field is inherited by subtypes, but see the rules listed below. A subtype |
| 1515 | may override this offset; this means that the subtype instances store the |
| 1516 | dictionary at a difference offset than the base type. Since the dictionary is |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1517 | always found via :c:member:`~PyTypeObject.tp_dictoffset`, this should not be a problem. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1518 | |
Serhiy Storchaka | 0b68a2d | 2013-10-09 13:26:17 +0300 | [diff] [blame] | 1519 | When a type defined by a class statement has no :attr:`~object.__slots__` declaration, |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1520 | and none of its base types has an instance variable dictionary, a dictionary |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1521 | slot is added to the instance layout and the :c:member:`~PyTypeObject.tp_dictoffset` is set to |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1522 | that slot's offset. |
| 1523 | |
| 1524 | When a type defined by a class statement has a :attr:`__slots__` declaration, |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1525 | the type inherits its :c:member:`~PyTypeObject.tp_dictoffset` from its base type. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1526 | |
Serhiy Storchaka | 0b68a2d | 2013-10-09 13:26:17 +0300 | [diff] [blame] | 1527 | (Adding a slot named :attr:`~object.__dict__` to the :attr:`__slots__` declaration does |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1528 | not have the expected effect, it just causes confusion. Maybe this should be |
| 1529 | added as a feature just like :attr:`__weakref__` though.) |
| 1530 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1531 | **Default:** |
| 1532 | |
| 1533 | This slot has no default. For static types, if the field is |
| 1534 | *NULL* then no :attr:`__dict__` gets created for instances. |
| 1535 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1536 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1537 | .. c:member:: initproc PyTypeObject.tp_init |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1538 | |
| 1539 | An optional pointer to an instance initialization function. |
| 1540 | |
| 1541 | This function corresponds to the :meth:`__init__` method of classes. Like |
| 1542 | :meth:`__init__`, it is possible to create an instance without calling |
| 1543 | :meth:`__init__`, and it is possible to reinitialize an instance by calling its |
| 1544 | :meth:`__init__` method again. |
| 1545 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1546 | The function signature is:: |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1547 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1548 | int tp_init(PyObject *self, PyObject *args, PyObject *kwds); |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1549 | |
| 1550 | The self argument is the instance to be initialized; the *args* and *kwds* |
| 1551 | arguments represent positional and keyword arguments of the call to |
| 1552 | :meth:`__init__`. |
| 1553 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1554 | The :c:member:`~PyTypeObject.tp_init` function, if not *NULL*, is called when an instance is |
| 1555 | created normally by calling its type, after the type's :c:member:`~PyTypeObject.tp_new` function |
| 1556 | has returned an instance of the type. If the :c:member:`~PyTypeObject.tp_new` function returns an |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1557 | instance of some other type that is not a subtype of the original type, no |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1558 | :c:member:`~PyTypeObject.tp_init` function is called; if :c:member:`~PyTypeObject.tp_new` returns an instance of a |
| 1559 | subtype of the original type, the subtype's :c:member:`~PyTypeObject.tp_init` is called. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1560 | |
Stéphane Wirtel | 7c4fcb6 | 2019-03-15 16:18:36 +0000 | [diff] [blame] | 1561 | Returns ``0`` on success, ``-1`` and sets an exception on error. |
| 1562 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1563 | **Inheritance:** |
| 1564 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1565 | This field is inherited by subtypes. |
| 1566 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1567 | **Default:** |
| 1568 | |
| 1569 | For static types this field does not have a default. |
| 1570 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1571 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1572 | .. c:member:: allocfunc PyTypeObject.tp_alloc |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1573 | |
| 1574 | An optional pointer to an instance allocation function. |
| 1575 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1576 | The function signature is:: |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1577 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1578 | PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems); |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1579 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1580 | **Inheritance:** |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1581 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1582 | This field is inherited by static subtypes, but not by dynamic |
| 1583 | subtypes (subtypes created by a class statement). |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1584 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1585 | **Default:** |
| 1586 | |
| 1587 | For dynamic subtypes, this field is always set to |
| 1588 | :c:func:`PyType_GenericAlloc`, to force a standard heap |
| 1589 | allocation strategy. |
| 1590 | |
| 1591 | For static subtypes, :c:type:`PyBaseObject_Type` uses |
| 1592 | :c:func:`PyType_GenericAlloc`. That is the recommended value |
| 1593 | for all statically defined types. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1594 | |
| 1595 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1596 | .. c:member:: newfunc PyTypeObject.tp_new |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1597 | |
| 1598 | An optional pointer to an instance creation function. |
| 1599 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1600 | The function signature is:: |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1601 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1602 | PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds); |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1603 | |
| 1604 | The subtype argument is the type of the object being created; the *args* and |
| 1605 | *kwds* arguments represent positional and keyword arguments of the call to the |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1606 | type. Note that subtype doesn't have to equal the type whose :c:member:`~PyTypeObject.tp_new` |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1607 | function is called; it may be a subtype of that type (but not an unrelated |
| 1608 | type). |
| 1609 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1610 | The :c:member:`~PyTypeObject.tp_new` function should call ``subtype->tp_alloc(subtype, nitems)`` |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1611 | to allocate space for the object, and then do only as much further |
| 1612 | initialization as is absolutely necessary. Initialization that can safely be |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1613 | ignored or repeated should be placed in the :c:member:`~PyTypeObject.tp_init` handler. A good |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1614 | rule of thumb is that for immutable types, all initialization should take place |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1615 | in :c:member:`~PyTypeObject.tp_new`, while for mutable types, most initialization should be |
| 1616 | deferred to :c:member:`~PyTypeObject.tp_init`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1617 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1618 | **Inheritance:** |
| 1619 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1620 | This field is inherited by subtypes, except it is not inherited by static types |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1621 | whose :c:member:`~PyTypeObject.tp_base` is *NULL* or ``&PyBaseObject_Type``. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1622 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1623 | **Default:** |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1624 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1625 | For static types this field has no default. This means if the |
| 1626 | slot is defined as *NULL*, the type cannot be called to create new |
| 1627 | instances; presumably there is some other way to create |
| 1628 | instances, like a factory function. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1629 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1630 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1631 | .. c:member:: freefunc PyTypeObject.tp_free |
| 1632 | |
| 1633 | An optional pointer to an instance deallocation function. Its signature is:: |
| 1634 | |
| 1635 | void tp_free(void *self); |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1636 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1637 | An initializer that is compatible with this signature is :c:func:`PyObject_Free`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1638 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1639 | **Inheritance:** |
| 1640 | |
| 1641 | This field is inherited by static subtypes, but not by dynamic |
| 1642 | subtypes (subtypes created by a class statement) |
| 1643 | |
| 1644 | **Default:** |
| 1645 | |
| 1646 | In dynamic subtypes, this field is set to a deallocator suitable to |
| 1647 | match :c:func:`PyType_GenericAlloc` and the value of the |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1648 | :const:`Py_TPFLAGS_HAVE_GC` flag bit. |
| 1649 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1650 | For static subtypes, :c:type:`PyBaseObject_Type` uses PyObject_Del. |
| 1651 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1652 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1653 | .. c:member:: inquiry PyTypeObject.tp_is_gc |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1654 | |
| 1655 | An optional pointer to a function called by the garbage collector. |
| 1656 | |
| 1657 | The garbage collector needs to know whether a particular object is collectible |
| 1658 | or not. Normally, it is sufficient to look at the object's type's |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1659 | :c:member:`~PyTypeObject.tp_flags` field, and check the :const:`Py_TPFLAGS_HAVE_GC` flag bit. But |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1660 | some types have a mixture of statically and dynamically allocated instances, and |
| 1661 | the statically allocated instances are not collectible. Such types should |
| 1662 | define this function; it should return ``1`` for a collectible instance, and |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1663 | ``0`` for a non-collectible instance. The signature is:: |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1664 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1665 | int tp_is_gc(PyObject *self); |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1666 | |
| 1667 | (The only example of this are types themselves. The metatype, |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1668 | :c:data:`PyType_Type`, defines this function to distinguish between statically |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1669 | and dynamically allocated types.) |
| 1670 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1671 | **Inheritance:** |
| 1672 | |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 1673 | This field is inherited by subtypes. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1674 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1675 | **Default:** |
| 1676 | |
| 1677 | This slot has no default. If this field is *NULL*, |
| 1678 | :const:`Py_TPFLAGS_HAVE_GC` is used as the functional equivalent. |
| 1679 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1680 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1681 | .. c:member:: PyObject* PyTypeObject.tp_bases |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1682 | |
| 1683 | Tuple of base types. |
| 1684 | |
| 1685 | This is set for types created by a class statement. It should be *NULL* for |
| 1686 | statically defined types. |
| 1687 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1688 | **Inheritance:** |
| 1689 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1690 | This field is not inherited. |
| 1691 | |
| 1692 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1693 | .. c:member:: PyObject* PyTypeObject.tp_mro |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1694 | |
| 1695 | Tuple containing the expanded set of base types, starting with the type itself |
| 1696 | and ending with :class:`object`, in Method Resolution Order. |
| 1697 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1698 | |
| 1699 | **Inheritance:** |
| 1700 | |
| 1701 | This field is not inherited; it is calculated fresh by |
| 1702 | :c:func:`PyType_Ready`. |
| 1703 | |
| 1704 | |
| 1705 | .. c:member:: PyObject* PyTypeObject.tp_cache |
| 1706 | |
| 1707 | Unused. Internal use only. |
| 1708 | |
| 1709 | **Inheritance:** |
| 1710 | |
| 1711 | This field is not inherited. |
| 1712 | |
| 1713 | |
| 1714 | .. c:member:: PyObject* PyTypeObject.tp_subclasses |
| 1715 | |
| 1716 | List of weak references to subclasses. Internal use only. |
| 1717 | |
| 1718 | **Inheritance:** |
| 1719 | |
| 1720 | This field is not inherited. |
| 1721 | |
| 1722 | |
| 1723 | .. c:member:: PyObject* PyTypeObject.tp_weaklist |
| 1724 | |
| 1725 | Weak reference list head, for weak references to this type object. Not |
| 1726 | inherited. Internal use only. |
| 1727 | |
| 1728 | **Inheritance:** |
| 1729 | |
| 1730 | This field is not inherited. |
| 1731 | |
| 1732 | |
| 1733 | .. c:member:: destructor PyTypeObject.tp_del |
| 1734 | |
| 1735 | This field is deprecated. Use :c:member:`~PyTypeObject.tp_finalize` instead. |
| 1736 | |
| 1737 | |
| 1738 | .. c:member:: unsigned int PyTypeObject.tp_version_tag |
| 1739 | |
| 1740 | Used to index into the method cache. Internal use only. |
| 1741 | |
| 1742 | **Inheritance:** |
| 1743 | |
| 1744 | This field is not inherited. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1745 | |
| 1746 | |
Antoine Pitrou | 796564c | 2013-07-30 19:59:21 +0200 | [diff] [blame] | 1747 | .. c:member:: destructor PyTypeObject.tp_finalize |
| 1748 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1749 | An optional pointer to an instance finalization function. Its signature is:: |
Antoine Pitrou | 796564c | 2013-07-30 19:59:21 +0200 | [diff] [blame] | 1750 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1751 | void tp_finalize(PyObject *self); |
Antoine Pitrou | 796564c | 2013-07-30 19:59:21 +0200 | [diff] [blame] | 1752 | |
Antoine Pitrou | a68cbfa | 2013-08-01 21:14:43 +0200 | [diff] [blame] | 1753 | If :c:member:`~PyTypeObject.tp_finalize` is set, the interpreter calls it once when |
Antoine Pitrou | 796564c | 2013-07-30 19:59:21 +0200 | [diff] [blame] | 1754 | finalizing an instance. It is called either from the garbage |
| 1755 | collector (if the instance is part of an isolated reference cycle) or |
| 1756 | just before the object is deallocated. Either way, it is guaranteed |
| 1757 | to be called before attempting to break reference cycles, ensuring |
| 1758 | that it finds the object in a sane state. |
| 1759 | |
Antoine Pitrou | a68cbfa | 2013-08-01 21:14:43 +0200 | [diff] [blame] | 1760 | :c:member:`~PyTypeObject.tp_finalize` should not mutate the current exception status; |
Antoine Pitrou | 796564c | 2013-07-30 19:59:21 +0200 | [diff] [blame] | 1761 | therefore, a recommended way to write a non-trivial finalizer is:: |
| 1762 | |
| 1763 | static void |
| 1764 | local_finalize(PyObject *self) |
| 1765 | { |
| 1766 | PyObject *error_type, *error_value, *error_traceback; |
| 1767 | |
| 1768 | /* Save the current exception, if any. */ |
| 1769 | PyErr_Fetch(&error_type, &error_value, &error_traceback); |
| 1770 | |
| 1771 | /* ... */ |
| 1772 | |
| 1773 | /* Restore the saved exception. */ |
| 1774 | PyErr_Restore(error_type, error_value, error_traceback); |
| 1775 | } |
| 1776 | |
| 1777 | For this field to be taken into account (even through inheritance), |
| 1778 | you must also set the :const:`Py_TPFLAGS_HAVE_FINALIZE` flags bit. |
| 1779 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1780 | **Inheritance:** |
| 1781 | |
Antoine Pitrou | 796564c | 2013-07-30 19:59:21 +0200 | [diff] [blame] | 1782 | This field is inherited by subtypes. |
| 1783 | |
| 1784 | .. versionadded:: 3.4 |
| 1785 | |
| 1786 | .. seealso:: "Safe object finalization" (:pep:`442`) |
| 1787 | |
| 1788 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1789 | The remaining fields are only defined if the feature test macro |
| 1790 | :const:`COUNT_ALLOCS` is defined, and are for internal use only. They are |
| 1791 | documented here for completeness. None of these fields are inherited by |
| 1792 | subtypes. |
| 1793 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1794 | .. c:member:: Py_ssize_t PyTypeObject.tp_allocs |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1795 | |
| 1796 | Number of allocations. |
| 1797 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1798 | .. c:member:: Py_ssize_t PyTypeObject.tp_frees |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1799 | |
| 1800 | Number of frees. |
| 1801 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1802 | .. c:member:: Py_ssize_t PyTypeObject.tp_maxalloc |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1803 | |
| 1804 | Maximum simultaneously allocated objects. |
| 1805 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1806 | .. c:member:: PyTypeObject* PyTypeObject.tp_prev |
| 1807 | |
| 1808 | Pointer to the previous type object with a non-zero :c:member:`~PyTypeObject.tp_allocs` field. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1809 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1810 | .. c:member:: PyTypeObject* PyTypeObject.tp_next |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1811 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1812 | Pointer to the next type object with a non-zero :c:member:`~PyTypeObject.tp_allocs` field. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1813 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1814 | Also, note that, in a garbage collected Python, :c:member:`~PyTypeObject.tp_dealloc` may be called from |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1815 | any Python thread, not just the thread which created the object (if the object |
| 1816 | becomes part of a refcount cycle, that cycle might be collected by a garbage |
| 1817 | collection on any thread). This is not a problem for Python API calls, since |
| 1818 | the thread on which tp_dealloc is called will own the Global Interpreter Lock |
| 1819 | (GIL). However, if the object being destroyed in turn destroys objects from some |
| 1820 | other C or C++ library, care should be taken to ensure that destroying those |
| 1821 | objects on the thread which called tp_dealloc will not violate any assumptions |
| 1822 | of the library. |
| 1823 | |
| 1824 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1825 | Heap Types |
| 1826 | ---------- |
| 1827 | |
| 1828 | In addition to defining Python types statically, you can define them |
| 1829 | dynamically (i.e. to the heap) using :c:func:`PyType_FromSpec` and |
| 1830 | :c:func:`PyType_FromSpecWithBases`. |
| 1831 | |
| 1832 | .. XXX Explain how to use PyType_FromSpec(). |
| 1833 | |
| 1834 | .. XXX Document PyType_Spec. |
| 1835 | |
| 1836 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1837 | .. _number-structs: |
| 1838 | |
| 1839 | Number Object Structures |
| 1840 | ======================== |
| 1841 | |
| 1842 | .. sectionauthor:: Amaury Forgeot d'Arc |
| 1843 | |
| 1844 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1845 | .. c:type:: PyNumberMethods |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1846 | |
| 1847 | This structure holds pointers to the functions which an object uses to |
| 1848 | implement the number protocol. Each function is used by the function of |
| 1849 | similar name documented in the :ref:`number` section. |
| 1850 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1851 | .. XXX Drop the definition? |
| 1852 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1853 | Here is the structure definition:: |
| 1854 | |
| 1855 | typedef struct { |
| 1856 | binaryfunc nb_add; |
| 1857 | binaryfunc nb_subtract; |
| 1858 | binaryfunc nb_multiply; |
| 1859 | binaryfunc nb_remainder; |
| 1860 | binaryfunc nb_divmod; |
| 1861 | ternaryfunc nb_power; |
| 1862 | unaryfunc nb_negative; |
| 1863 | unaryfunc nb_positive; |
| 1864 | unaryfunc nb_absolute; |
| 1865 | inquiry nb_bool; |
| 1866 | unaryfunc nb_invert; |
| 1867 | binaryfunc nb_lshift; |
| 1868 | binaryfunc nb_rshift; |
| 1869 | binaryfunc nb_and; |
| 1870 | binaryfunc nb_xor; |
| 1871 | binaryfunc nb_or; |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1872 | unaryfunc nb_int; |
Mark Dickinson | 8055afd | 2009-01-17 10:04:45 +0000 | [diff] [blame] | 1873 | void *nb_reserved; |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1874 | unaryfunc nb_float; |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1875 | |
| 1876 | binaryfunc nb_inplace_add; |
| 1877 | binaryfunc nb_inplace_subtract; |
| 1878 | binaryfunc nb_inplace_multiply; |
| 1879 | binaryfunc nb_inplace_remainder; |
| 1880 | ternaryfunc nb_inplace_power; |
| 1881 | binaryfunc nb_inplace_lshift; |
| 1882 | binaryfunc nb_inplace_rshift; |
| 1883 | binaryfunc nb_inplace_and; |
| 1884 | binaryfunc nb_inplace_xor; |
| 1885 | binaryfunc nb_inplace_or; |
| 1886 | |
| 1887 | binaryfunc nb_floor_divide; |
| 1888 | binaryfunc nb_true_divide; |
| 1889 | binaryfunc nb_inplace_floor_divide; |
| 1890 | binaryfunc nb_inplace_true_divide; |
| 1891 | |
| 1892 | unaryfunc nb_index; |
Benjamin Peterson | d51374e | 2014-04-09 23:55:56 -0400 | [diff] [blame] | 1893 | |
| 1894 | binaryfunc nb_matrix_multiply; |
| 1895 | binaryfunc nb_inplace_matrix_multiply; |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1896 | } PyNumberMethods; |
| 1897 | |
| 1898 | .. note:: |
| 1899 | |
| 1900 | Binary and ternary functions must check the type of all their operands, |
| 1901 | and implement the necessary conversions (at least one of the operands is |
| 1902 | an instance of the defined type). If the operation is not defined for the |
| 1903 | given operands, binary and ternary functions must return |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1904 | ``Py_NotImplemented``, if another error occurred they must return *NULL* |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1905 | and set an exception. |
| 1906 | |
Mark Dickinson | 8055afd | 2009-01-17 10:04:45 +0000 | [diff] [blame] | 1907 | .. note:: |
| 1908 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1909 | The :c:data:`nb_reserved` field should always be *NULL*. It |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1910 | was previously called :c:data:`nb_long`, and was renamed in |
Mark Dickinson | 8055afd | 2009-01-17 10:04:45 +0000 | [diff] [blame] | 1911 | Python 3.0.1. |
| 1912 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 1913 | .. c:member:: binaryfunc PyNumberMethods.nb_add |
| 1914 | .. c:member:: binaryfunc PyNumberMethods.nb_subtract |
| 1915 | .. c:member:: binaryfunc PyNumberMethods.nb_multiply |
| 1916 | .. c:member:: binaryfunc PyNumberMethods.nb_remainder |
| 1917 | .. c:member:: binaryfunc PyNumberMethods.nb_divmod |
| 1918 | .. c:member:: ternaryfunc PyNumberMethods.nb_power |
| 1919 | .. c:member:: unaryfunc PyNumberMethods.nb_negative |
| 1920 | .. c:member:: unaryfunc PyNumberMethods.nb_positive |
| 1921 | .. c:member:: unaryfunc PyNumberMethods.nb_absolute |
| 1922 | .. c:member:: inquiry PyNumberMethods.nb_bool |
| 1923 | .. c:member:: unaryfunc PyNumberMethods.nb_invert |
| 1924 | .. c:member:: binaryfunc PyNumberMethods.nb_lshift |
| 1925 | .. c:member:: binaryfunc PyNumberMethods.nb_rshift |
| 1926 | .. c:member:: binaryfunc PyNumberMethods.nb_and |
| 1927 | .. c:member:: binaryfunc PyNumberMethods.nb_xor |
| 1928 | .. c:member:: binaryfunc PyNumberMethods.nb_or |
| 1929 | .. c:member:: unaryfunc PyNumberMethods.nb_int |
| 1930 | .. c:member:: void *PyNumberMethods.nb_reserved |
| 1931 | .. c:member:: unaryfunc PyNumberMethods.nb_float |
| 1932 | .. c:member:: binaryfunc PyNumberMethods.nb_inplace_add |
| 1933 | .. c:member:: binaryfunc PyNumberMethods.nb_inplace_subtract |
| 1934 | .. c:member:: binaryfunc PyNumberMethods.nb_inplace_multiply |
| 1935 | .. c:member:: binaryfunc PyNumberMethods.nb_inplace_remainder |
| 1936 | .. c:member:: ternaryfunc PyNumberMethods.nb_inplace_power |
| 1937 | .. c:member:: binaryfunc PyNumberMethods.nb_inplace_lshift |
| 1938 | .. c:member:: binaryfunc PyNumberMethods.nb_inplace_rshift |
| 1939 | .. c:member:: binaryfunc PyNumberMethods.nb_inplace_and |
| 1940 | .. c:member:: binaryfunc PyNumberMethods.nb_inplace_xor |
| 1941 | .. c:member:: binaryfunc PyNumberMethods.nb_inplace_or |
| 1942 | .. c:member:: binaryfunc PyNumberMethods.nb_floor_divide |
| 1943 | .. c:member:: binaryfunc PyNumberMethods.nb_true_divide |
| 1944 | .. c:member:: binaryfunc PyNumberMethods.nb_inplace_floor_divide |
| 1945 | .. c:member:: binaryfunc PyNumberMethods.nb_inplace_true_divide |
| 1946 | .. c:member:: unaryfunc PyNumberMethods.nb_index |
| 1947 | .. c:member:: binaryfunc PyNumberMethods.nb_matrix_multiply |
| 1948 | .. c:member:: binaryfunc PyNumberMethods.nb_inplace_matrix_multiply |
| 1949 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1950 | |
| 1951 | .. _mapping-structs: |
| 1952 | |
| 1953 | Mapping Object Structures |
| 1954 | ========================= |
| 1955 | |
| 1956 | .. sectionauthor:: Amaury Forgeot d'Arc |
| 1957 | |
| 1958 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1959 | .. c:type:: PyMappingMethods |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1960 | |
| 1961 | This structure holds pointers to the functions which an object uses to |
| 1962 | implement the mapping protocol. It has three members: |
| 1963 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1964 | .. c:member:: lenfunc PyMappingMethods.mp_length |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1965 | |
Serhiy Storchaka | f5b1183 | 2018-05-22 11:02:44 +0300 | [diff] [blame] | 1966 | This function is used by :c:func:`PyMapping_Size` and |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1967 | :c:func:`PyObject_Size`, and has the same signature. This slot may be set to |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1968 | *NULL* if the object has no defined length. |
| 1969 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1970 | .. c:member:: binaryfunc PyMappingMethods.mp_subscript |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1971 | |
Serhiy Storchaka | f5b1183 | 2018-05-22 11:02:44 +0300 | [diff] [blame] | 1972 | This function is used by :c:func:`PyObject_GetItem` and |
| 1973 | :c:func:`PySequence_GetSlice`, and has the same signature as |
| 1974 | :c:func:`!PyObject_GetItem`. This slot must be filled for the |
| 1975 | :c:func:`PyMapping_Check` function to return ``1``, it can be *NULL* |
| 1976 | otherwise. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1977 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1978 | .. c:member:: objobjargproc PyMappingMethods.mp_ass_subscript |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1979 | |
Serhiy Storchaka | f5b1183 | 2018-05-22 11:02:44 +0300 | [diff] [blame] | 1980 | This function is used by :c:func:`PyObject_SetItem`, |
| 1981 | :c:func:`PyObject_DelItem`, :c:func:`PyObject_SetSlice` and |
| 1982 | :c:func:`PyObject_DelSlice`. It has the same signature as |
| 1983 | :c:func:`!PyObject_SetItem`, but *v* can also be set to *NULL* to delete |
Martin Panter | 45be8d6 | 2015-12-08 00:03:20 +0000 | [diff] [blame] | 1984 | an item. If this slot is *NULL*, the object does not support item |
| 1985 | assignment and deletion. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1986 | |
| 1987 | |
| 1988 | .. _sequence-structs: |
| 1989 | |
| 1990 | Sequence Object Structures |
| 1991 | ========================== |
| 1992 | |
| 1993 | .. sectionauthor:: Amaury Forgeot d'Arc |
| 1994 | |
| 1995 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1996 | .. c:type:: PySequenceMethods |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1997 | |
| 1998 | This structure holds pointers to the functions which an object uses to |
| 1999 | implement the sequence protocol. |
| 2000 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 2001 | .. c:member:: lenfunc PySequenceMethods.sq_length |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2002 | |
Serhiy Storchaka | f5b1183 | 2018-05-22 11:02:44 +0300 | [diff] [blame] | 2003 | This function is used by :c:func:`PySequence_Size` and |
| 2004 | :c:func:`PyObject_Size`, and has the same signature. It is also used for |
| 2005 | handling negative indices via the :c:member:`~PySequenceMethods.sq_item` |
| 2006 | and the :c:member:`~PySequenceMethods.sq_ass_item` slots. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2007 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 2008 | .. c:member:: binaryfunc PySequenceMethods.sq_concat |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2009 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 2010 | This function is used by :c:func:`PySequence_Concat` and has the same |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2011 | signature. It is also used by the ``+`` operator, after trying the numeric |
Serhiy Storchaka | f5b1183 | 2018-05-22 11:02:44 +0300 | [diff] [blame] | 2012 | addition via the :c:member:`~PyNumberMethods.nb_add` slot. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2013 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 2014 | .. c:member:: ssizeargfunc PySequenceMethods.sq_repeat |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2015 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 2016 | This function is used by :c:func:`PySequence_Repeat` and has the same |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2017 | signature. It is also used by the ``*`` operator, after trying numeric |
Serhiy Storchaka | f5b1183 | 2018-05-22 11:02:44 +0300 | [diff] [blame] | 2018 | multiplication via the :c:member:`~PyNumberMethods.nb_multiply` slot. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2019 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 2020 | .. c:member:: ssizeargfunc PySequenceMethods.sq_item |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2021 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 2022 | This function is used by :c:func:`PySequence_GetItem` and has the same |
Serhiy Storchaka | f5b1183 | 2018-05-22 11:02:44 +0300 | [diff] [blame] | 2023 | signature. It is also used by :c:func:`PyObject_GetItem`, after trying |
| 2024 | the subscription via the :c:member:`~PyMappingMethods.mp_subscript` slot. |
| 2025 | This slot must be filled for the :c:func:`PySequence_Check` |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2026 | function to return ``1``, it can be *NULL* otherwise. |
| 2027 | |
| 2028 | Negative indexes are handled as follows: if the :attr:`sq_length` slot is |
| 2029 | filled, it is called and the sequence length is used to compute a positive |
| 2030 | index which is passed to :attr:`sq_item`. If :attr:`sq_length` is *NULL*, |
| 2031 | the index is passed as is to the function. |
| 2032 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 2033 | .. c:member:: ssizeobjargproc PySequenceMethods.sq_ass_item |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2034 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 2035 | This function is used by :c:func:`PySequence_SetItem` and has the same |
Serhiy Storchaka | f5b1183 | 2018-05-22 11:02:44 +0300 | [diff] [blame] | 2036 | signature. It is also used by :c:func:`PyObject_SetItem` and |
| 2037 | :c:func:`PyObject_DelItem`, after trying the item assignment and deletion |
| 2038 | via the :c:member:`~PyMappingMethods.mp_ass_subscript` slot. |
| 2039 | This slot may be left to *NULL* if the object does not support |
Martin Panter | 45be8d6 | 2015-12-08 00:03:20 +0000 | [diff] [blame] | 2040 | item assignment and deletion. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2041 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 2042 | .. c:member:: objobjproc PySequenceMethods.sq_contains |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2043 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 2044 | This function may be used by :c:func:`PySequence_Contains` and has the same |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2045 | signature. This slot may be left to *NULL*, in this case |
Serhiy Storchaka | f5b1183 | 2018-05-22 11:02:44 +0300 | [diff] [blame] | 2046 | :c:func:`!PySequence_Contains` simply traverses the sequence until it |
| 2047 | finds a match. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2048 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 2049 | .. c:member:: binaryfunc PySequenceMethods.sq_inplace_concat |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2050 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 2051 | This function is used by :c:func:`PySequence_InPlaceConcat` and has the same |
Serhiy Storchaka | f5b1183 | 2018-05-22 11:02:44 +0300 | [diff] [blame] | 2052 | signature. It should modify its first operand, and return it. This slot |
| 2053 | may be left to *NULL*, in this case :c:func:`!PySequence_InPlaceConcat` |
| 2054 | will fall back to :c:func:`PySequence_Concat`. It is also used by the |
Andre Delfino | f4efa31 | 2019-04-08 06:14:43 -0300 | [diff] [blame^] | 2055 | augmented assignment ``+=``, after trying numeric in-place addition |
Serhiy Storchaka | f5b1183 | 2018-05-22 11:02:44 +0300 | [diff] [blame] | 2056 | via the :c:member:`~PyNumberMethods.nb_inplace_add` slot. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2057 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 2058 | .. c:member:: ssizeargfunc PySequenceMethods.sq_inplace_repeat |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2059 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 2060 | This function is used by :c:func:`PySequence_InPlaceRepeat` and has the same |
Serhiy Storchaka | f5b1183 | 2018-05-22 11:02:44 +0300 | [diff] [blame] | 2061 | signature. It should modify its first operand, and return it. This slot |
| 2062 | may be left to *NULL*, in this case :c:func:`!PySequence_InPlaceRepeat` |
| 2063 | will fall back to :c:func:`PySequence_Repeat`. It is also used by the |
Andre Delfino | f4efa31 | 2019-04-08 06:14:43 -0300 | [diff] [blame^] | 2064 | augmented assignment ``*=``, after trying numeric in-place multiplication |
Serhiy Storchaka | f5b1183 | 2018-05-22 11:02:44 +0300 | [diff] [blame] | 2065 | via the :c:member:`~PyNumberMethods.nb_inplace_multiply` slot. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2066 | |
| 2067 | |
| 2068 | .. _buffer-structs: |
| 2069 | |
| 2070 | Buffer Object Structures |
| 2071 | ======================== |
| 2072 | |
| 2073 | .. sectionauthor:: Greg J. Stein <greg@lyra.org> |
Benjamin Peterson | 9d0ced3 | 2008-09-16 02:24:31 +0000 | [diff] [blame] | 2074 | .. sectionauthor:: Benjamin Peterson |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 2075 | .. sectionauthor:: Stefan Krah |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2076 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 2077 | .. c:type:: PyBufferProcs |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2078 | |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 2079 | This structure holds pointers to the functions required by the |
| 2080 | :ref:`Buffer protocol <bufferobjects>`. The protocol defines how |
| 2081 | an exporter object can expose its internal data to consumer objects. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2082 | |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 2083 | .. c:member:: getbufferproc PyBufferProcs.bf_getbuffer |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2084 | |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 2085 | The signature of this function is:: |
| 2086 | |
| 2087 | int (PyObject *exporter, Py_buffer *view, int flags); |
| 2088 | |
| 2089 | Handle a request to *exporter* to fill in *view* as specified by *flags*. |
Stefan Krah | abd887d | 2012-03-06 14:55:06 +0100 | [diff] [blame] | 2090 | Except for point (3), an implementation of this function MUST take these |
| 2091 | steps: |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 2092 | |
Stefan Krah | abd887d | 2012-03-06 14:55:06 +0100 | [diff] [blame] | 2093 | (1) Check if the request can be met. If not, raise :c:data:`PyExc_BufferError`, |
Serhiy Storchaka | 1ecf7d2 | 2016-10-27 21:41:19 +0300 | [diff] [blame] | 2094 | set :c:data:`view->obj` to *NULL* and return ``-1``. |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 2095 | |
Stefan Krah | abd887d | 2012-03-06 14:55:06 +0100 | [diff] [blame] | 2096 | (2) Fill in the requested fields. |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 2097 | |
Stefan Krah | abd887d | 2012-03-06 14:55:06 +0100 | [diff] [blame] | 2098 | (3) Increment an internal counter for the number of exports. |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 2099 | |
Stefan Krah | abd887d | 2012-03-06 14:55:06 +0100 | [diff] [blame] | 2100 | (4) Set :c:data:`view->obj` to *exporter* and increment :c:data:`view->obj`. |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 2101 | |
Serhiy Storchaka | 1ecf7d2 | 2016-10-27 21:41:19 +0300 | [diff] [blame] | 2102 | (5) Return ``0``. |
Stefan Krah | abd887d | 2012-03-06 14:55:06 +0100 | [diff] [blame] | 2103 | |
| 2104 | If *exporter* is part of a chain or tree of buffer providers, two main |
| 2105 | schemes can be used: |
| 2106 | |
| 2107 | * Re-export: Each member of the tree acts as the exporting object and |
| 2108 | sets :c:data:`view->obj` to a new reference to itself. |
| 2109 | |
| 2110 | * Redirect: The buffer request is redirected to the root object of the |
| 2111 | tree. Here, :c:data:`view->obj` will be a new reference to the root |
| 2112 | object. |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 2113 | |
| 2114 | The individual fields of *view* are described in section |
| 2115 | :ref:`Buffer structure <buffer-structure>`, the rules how an exporter |
| 2116 | must react to specific requests are in section |
| 2117 | :ref:`Buffer request types <buffer-request-types>`. |
| 2118 | |
| 2119 | All memory pointed to in the :c:type:`Py_buffer` structure belongs to |
| 2120 | the exporter and must remain valid until there are no consumers left. |
Stefan Krah | abd887d | 2012-03-06 14:55:06 +0100 | [diff] [blame] | 2121 | :c:member:`~Py_buffer.format`, :c:member:`~Py_buffer.shape`, |
| 2122 | :c:member:`~Py_buffer.strides`, :c:member:`~Py_buffer.suboffsets` |
| 2123 | and :c:member:`~Py_buffer.internal` |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 2124 | are read-only for the consumer. |
| 2125 | |
| 2126 | :c:func:`PyBuffer_FillInfo` provides an easy way of exposing a simple |
| 2127 | bytes buffer while dealing correctly with all request types. |
| 2128 | |
| 2129 | :c:func:`PyObject_GetBuffer` is the interface for the consumer that |
| 2130 | wraps this function. |
| 2131 | |
| 2132 | .. c:member:: releasebufferproc PyBufferProcs.bf_releasebuffer |
| 2133 | |
| 2134 | The signature of this function is:: |
| 2135 | |
| 2136 | void (PyObject *exporter, Py_buffer *view); |
| 2137 | |
| 2138 | Handle a request to release the resources of the buffer. If no resources |
Stefan Krah | abd887d | 2012-03-06 14:55:06 +0100 | [diff] [blame] | 2139 | need to be released, :c:member:`PyBufferProcs.bf_releasebuffer` may be |
| 2140 | *NULL*. Otherwise, a standard implementation of this function will take |
| 2141 | these optional steps: |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 2142 | |
Stefan Krah | abd887d | 2012-03-06 14:55:06 +0100 | [diff] [blame] | 2143 | (1) Decrement an internal counter for the number of exports. |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 2144 | |
Serhiy Storchaka | 1ecf7d2 | 2016-10-27 21:41:19 +0300 | [diff] [blame] | 2145 | (2) If the counter is ``0``, free all memory associated with *view*. |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 2146 | |
| 2147 | The exporter MUST use the :c:member:`~Py_buffer.internal` field to keep |
Stefan Krah | abd887d | 2012-03-06 14:55:06 +0100 | [diff] [blame] | 2148 | track of buffer-specific resources. This field is guaranteed to remain |
| 2149 | constant, while a consumer MAY pass a copy of the original buffer as the |
| 2150 | *view* argument. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2151 | |
| 2152 | |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 2153 | This function MUST NOT decrement :c:data:`view->obj`, since that is |
Stefan Krah | abd887d | 2012-03-06 14:55:06 +0100 | [diff] [blame] | 2154 | done automatically in :c:func:`PyBuffer_Release` (this scheme is |
| 2155 | useful for breaking reference cycles). |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2156 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 2157 | |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 2158 | :c:func:`PyBuffer_Release` is the interface for the consumer that |
| 2159 | wraps this function. |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 2160 | |
| 2161 | |
| 2162 | .. _async-structs: |
| 2163 | |
| 2164 | |
| 2165 | Async Object Structures |
| 2166 | ======================= |
| 2167 | |
| 2168 | .. sectionauthor:: Yury Selivanov <yselivanov@sprymix.com> |
| 2169 | |
Yury Selivanov | a18cad5 | 2015-05-21 17:02:31 -0400 | [diff] [blame] | 2170 | .. versionadded:: 3.5 |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 2171 | |
| 2172 | .. c:type:: PyAsyncMethods |
| 2173 | |
| 2174 | This structure holds pointers to the functions required to implement |
| 2175 | :term:`awaitable` and :term:`asynchronous iterator` objects. |
| 2176 | |
| 2177 | Here is the structure definition:: |
| 2178 | |
| 2179 | typedef struct { |
Yury Selivanov | 6ef0590 | 2015-05-28 11:21:31 -0400 | [diff] [blame] | 2180 | unaryfunc am_await; |
| 2181 | unaryfunc am_aiter; |
| 2182 | unaryfunc am_anext; |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 2183 | } PyAsyncMethods; |
| 2184 | |
Yury Selivanov | 6ef0590 | 2015-05-28 11:21:31 -0400 | [diff] [blame] | 2185 | .. c:member:: unaryfunc PyAsyncMethods.am_await |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 2186 | |
| 2187 | The signature of this function is:: |
| 2188 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 2189 | PyObject *am_await(PyObject *self); |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 2190 | |
| 2191 | The returned object must be an iterator, i.e. :c:func:`PyIter_Check` must |
| 2192 | return ``1`` for it. |
| 2193 | |
| 2194 | This slot may be set to *NULL* if an object is not an :term:`awaitable`. |
| 2195 | |
Yury Selivanov | 6ef0590 | 2015-05-28 11:21:31 -0400 | [diff] [blame] | 2196 | .. c:member:: unaryfunc PyAsyncMethods.am_aiter |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 2197 | |
| 2198 | The signature of this function is:: |
| 2199 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 2200 | PyObject *am_aiter(PyObject *self); |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 2201 | |
| 2202 | Must return an :term:`awaitable` object. See :meth:`__anext__` for details. |
| 2203 | |
| 2204 | This slot may be set to *NULL* if an object does not implement |
| 2205 | asynchronous iteration protocol. |
| 2206 | |
Yury Selivanov | 6ef0590 | 2015-05-28 11:21:31 -0400 | [diff] [blame] | 2207 | .. c:member:: unaryfunc PyAsyncMethods.am_anext |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 2208 | |
| 2209 | The signature of this function is:: |
| 2210 | |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 2211 | PyObject *am_anext(PyObject *self); |
Yury Selivanov | f3e40fa | 2015-05-21 11:50:30 -0400 | [diff] [blame] | 2212 | |
| 2213 | Must return an :term:`awaitable` object. See :meth:`__anext__` for details. |
| 2214 | This slot may be set to *NULL*. |
Eric Snow | 9e7c921 | 2018-06-14 15:46:35 -0600 | [diff] [blame] | 2215 | |
| 2216 | |
| 2217 | .. _slot-typedefs: |
| 2218 | |
| 2219 | Slot Type typedefs |
| 2220 | ================== |
| 2221 | |
| 2222 | .. c:type:: PyObject *(*allocfunc)(PyTypeObject *cls, Py_ssize_t nitems) |
| 2223 | |
| 2224 | The purpose of this function is to separate memory allocation from memory |
| 2225 | initialization. It should return a pointer to a block of memory of adequate |
| 2226 | length for the instance, suitably aligned, and initialized to zeros, but with |
| 2227 | :attr:`ob_refcnt` set to ``1`` and :attr:`ob_type` set to the type argument. If |
| 2228 | the type's :c:member:`~PyTypeObject.tp_itemsize` is non-zero, the object's :attr:`ob_size` field |
| 2229 | should be initialized to *nitems* and the length of the allocated memory block |
| 2230 | should be ``tp_basicsize + nitems*tp_itemsize``, rounded up to a multiple of |
| 2231 | ``sizeof(void*)``; otherwise, *nitems* is not used and the length of the block |
| 2232 | should be :c:member:`~PyTypeObject.tp_basicsize`. |
| 2233 | |
| 2234 | This function should not do any other instance initialization, not even to |
| 2235 | allocate additional memory; that should be done by :c:member:`~PyTypeObject.tp_new`. |
| 2236 | |
| 2237 | .. c:type:: void (*destructor)(PyObject *) |
| 2238 | |
| 2239 | .. c:type:: void (*freefunc)(void *) |
| 2240 | |
| 2241 | See :c:member:`~PyTypeObject.tp_free`. |
| 2242 | |
| 2243 | .. c:type:: PyObject *(*newfunc)(PyObject *, PyObject *, PyObject *) |
| 2244 | |
| 2245 | See :c:member:`~PyTypeObject.tp_new`. |
| 2246 | |
| 2247 | .. c:type:: int (*initproc)(PyObject *, PyObject *, PyObject *) |
| 2248 | |
| 2249 | See :c:member:`~PyTypeObject.tp_init`. |
| 2250 | |
| 2251 | .. c:type:: PyObject *(*reprfunc)(PyObject *) |
| 2252 | |
| 2253 | See :c:member:`~PyTypeObject.tp_repr`. |
| 2254 | |
| 2255 | .. c:type:: int (*printfunc)(PyObject *, FILE *, int) |
| 2256 | |
| 2257 | This is hidden if :const:`PY_LIMITED_API` is set. |
| 2258 | |
| 2259 | .. c:type:: PyObject *(*getattrfunc)(PyObject *self, char *attr) |
| 2260 | |
| 2261 | Return the value of the named attribute for the object. |
| 2262 | |
| 2263 | .. c:type:: int (*setattrfunc)(PyObject *self, char *attr, PyObject *value) |
| 2264 | |
| 2265 | Set the value of the named attribute for the object. |
| 2266 | The value argument is set to *NULL* to delete the attribute. |
| 2267 | |
| 2268 | .. c:type:: PyObject *(*getattrofunc)(PyObject *self, PyObject *attr) |
| 2269 | |
| 2270 | Return the value of the named attribute for the object. |
| 2271 | |
| 2272 | See :c:member:`~PyTypeObject.tp_getattro`. |
| 2273 | |
| 2274 | .. c:type:: int (*setattrofunc)(PyObject *self, PyObject *attr, PyObject *value) |
| 2275 | |
| 2276 | Set the value of the named attribute for the object. |
| 2277 | The value argument is set to *NULL* to delete the attribute. |
| 2278 | |
| 2279 | See :c:member:`~PyTypeObject.tp_setattro`. |
| 2280 | |
| 2281 | .. c:type:: PyObject *(*descrgetfunc)(PyObject *, PyObject *, PyObject *) |
| 2282 | |
| 2283 | See :c:member:`~PyTypeObject.tp_descrget`. |
| 2284 | |
| 2285 | .. c:type:: int (*descrsetfunc)(PyObject *, PyObject *, PyObject *) |
| 2286 | |
| 2287 | See :c:member:`~PyTypeObject.tp_descrset`. |
| 2288 | |
| 2289 | .. c:type:: Py_hash_t (*hashfunc)(PyObject *) |
| 2290 | |
| 2291 | See :c:member:`~PyTypeObject.tp_hash`. |
| 2292 | |
| 2293 | .. c:type:: PyObject *(*richcmpfunc)(PyObject *, PyObject *, int) |
| 2294 | |
| 2295 | See :c:member:`~PyTypeObject.tp_richcompare`. |
| 2296 | |
| 2297 | .. c:type:: PyObject *(*getiterfunc)(PyObject *) |
| 2298 | |
| 2299 | See :c:member:`~PyTypeObject.tp_iter`. |
| 2300 | |
| 2301 | .. c:type:: PyObject *(*iternextfunc)(PyObject *) |
| 2302 | |
| 2303 | See :c:member:`~PyTypeObject.tp_iternext`. |
| 2304 | |
| 2305 | .. c:type:: Py_ssize_t (*lenfunc)(PyObject *) |
| 2306 | |
| 2307 | .. c:type:: int (*getbufferproc)(PyObject *, Py_buffer *, int) |
| 2308 | |
| 2309 | .. c:type:: void (*releasebufferproc)(PyObject *, Py_buffer *) |
| 2310 | |
| 2311 | .. c:type:: PyObject *(*unaryfunc)(PyObject *) |
| 2312 | |
| 2313 | .. c:type:: PyObject *(*binaryfunc)(PyObject *, PyObject *) |
| 2314 | |
| 2315 | .. c:type:: PyObject *(*ternaryfunc)(PyObject *, PyObject *, PyObject *) |
| 2316 | |
| 2317 | .. c:type:: PyObject *(*ssizeargfunc)(PyObject *, Py_ssize_t) |
| 2318 | |
| 2319 | .. c:type:: int (*ssizeobjargproc)(PyObject *, Py_ssize_t) |
| 2320 | |
| 2321 | .. c:type:: int (*objobjproc)(PyObject *, PyObject *) |
| 2322 | |
| 2323 | .. c:type:: int (*objobjargproc)(PyObject *, PyObject *, PyObject *) |
| 2324 | |
| 2325 | |
| 2326 | .. _examples: |
| 2327 | |
| 2328 | Examples |
| 2329 | ======== |
| 2330 | |
| 2331 | The following are simple examples of Python type definitions. They |
| 2332 | include common usage you may encounter. Some demonstrate tricky corner |
| 2333 | cases. For more examples, practical info, and a tutorial, see |
| 2334 | :ref:`defining-new-types` and :ref:`new-types-topics`. |
| 2335 | |
| 2336 | A basic static type:: |
| 2337 | |
| 2338 | typedef struct { |
| 2339 | PyObject_HEAD |
| 2340 | const char *data; |
| 2341 | } MyObject; |
| 2342 | |
| 2343 | static PyTypeObject MyObject_Type = { |
| 2344 | PyVarObject_HEAD_INIT(NULL, 0) |
| 2345 | .tp_name = "mymod.MyObject", |
| 2346 | .tp_basicsize = sizeof(MyObject), |
| 2347 | .tp_doc = "My objects", |
| 2348 | .tp_new = myobj_new, |
| 2349 | .tp_dealloc = (destructor)myobj_dealloc, |
| 2350 | .tp_repr = (reprfunc)myobj_repr, |
| 2351 | }; |
| 2352 | |
| 2353 | You may also find older code (especially in the CPython code base) |
| 2354 | with a more verbose initializer:: |
| 2355 | |
| 2356 | static PyTypeObject MyObject_Type = { |
| 2357 | PyVarObject_HEAD_INIT(NULL, 0) |
| 2358 | "mymod.MyObject", /* tp_name */ |
| 2359 | sizeof(MyObject), /* tp_basicsize */ |
| 2360 | 0, /* tp_itemsize */ |
| 2361 | (destructor)myobj_dealloc, /* tp_dealloc */ |
| 2362 | 0, /* tp_print */ |
| 2363 | 0, /* tp_getattr */ |
| 2364 | 0, /* tp_setattr */ |
| 2365 | 0, /* tp_as_async */ |
| 2366 | (reprfunc)myobj_repr, /* tp_repr */ |
| 2367 | 0, /* tp_as_number */ |
| 2368 | 0, /* tp_as_sequence */ |
| 2369 | 0, /* tp_as_mapping */ |
| 2370 | 0, /* tp_hash */ |
| 2371 | 0, /* tp_call */ |
| 2372 | 0, /* tp_str */ |
| 2373 | 0, /* tp_getattro */ |
| 2374 | 0, /* tp_setattro */ |
| 2375 | 0, /* tp_as_buffer */ |
| 2376 | 0, /* tp_flags */ |
| 2377 | "My objects", /* tp_doc */ |
| 2378 | 0, /* tp_traverse */ |
| 2379 | 0, /* tp_clear */ |
| 2380 | 0, /* tp_richcompare */ |
| 2381 | 0, /* tp_weaklistoffset */ |
| 2382 | 0, /* tp_iter */ |
| 2383 | 0, /* tp_iternext */ |
| 2384 | 0, /* tp_methods */ |
| 2385 | 0, /* tp_members */ |
| 2386 | 0, /* tp_getset */ |
| 2387 | 0, /* tp_base */ |
| 2388 | 0, /* tp_dict */ |
| 2389 | 0, /* tp_descr_get */ |
| 2390 | 0, /* tp_descr_set */ |
| 2391 | 0, /* tp_dictoffset */ |
| 2392 | 0, /* tp_init */ |
| 2393 | 0, /* tp_alloc */ |
| 2394 | myobj_new, /* tp_new */ |
| 2395 | }; |
| 2396 | |
| 2397 | A type that supports weakrefs, instance dicts, and hashing:: |
| 2398 | |
| 2399 | typedef struct { |
| 2400 | PyObject_HEAD |
| 2401 | const char *data; |
| 2402 | PyObject *inst_dict; |
| 2403 | PyObject *weakreflist; |
| 2404 | } MyObject; |
| 2405 | |
| 2406 | static PyTypeObject MyObject_Type = { |
| 2407 | PyVarObject_HEAD_INIT(NULL, 0) |
| 2408 | .tp_name = "mymod.MyObject", |
| 2409 | .tp_basicsize = sizeof(MyObject), |
| 2410 | .tp_doc = "My objects", |
| 2411 | .tp_weaklistoffset = offsetof(MyObject, weakreflist), |
| 2412 | .tp_dictoffset = offsetof(MyObject, inst_dict), |
| 2413 | .tp_flags = Py_TPFLAGS_DEFAULT | Py_TPFLAGS_BASETYPE | Py_TPFLAGS_HAVE_GC, |
| 2414 | .tp_new = myobj_new, |
| 2415 | .tp_traverse = (traverseproc)myobj_traverse, |
| 2416 | .tp_clear = (inquiry)myobj_clear, |
| 2417 | .tp_alloc = PyType_GenericNew, |
| 2418 | .tp_dealloc = (destructor)myobj_dealloc, |
| 2419 | .tp_repr = (reprfunc)myobj_repr, |
| 2420 | .tp_hash = (hashfunc)myobj_hash, |
| 2421 | .tp_richcompare = PyBaseObject_Type.tp_richcompare, |
| 2422 | }; |
| 2423 | |
| 2424 | A str subclass that cannot be subclassed and cannot be called |
| 2425 | to create instances (e.g. uses a separate factory func):: |
| 2426 | |
| 2427 | typedef struct { |
| 2428 | PyUnicodeObject raw; |
| 2429 | char *extra; |
| 2430 | } MyStr; |
| 2431 | |
| 2432 | static PyTypeObject MyStr_Type = { |
| 2433 | PyVarObject_HEAD_INIT(NULL, 0) |
| 2434 | .tp_name = "mymod.MyStr", |
| 2435 | .tp_basicsize = sizeof(MyStr), |
| 2436 | .tp_base = NULL, // set to &PyUnicode_Type in module init |
| 2437 | .tp_doc = "my custom str", |
| 2438 | .tp_flags = Py_TPFLAGS_DEFAULT, |
| 2439 | .tp_new = NULL, |
| 2440 | .tp_repr = (reprfunc)myobj_repr, |
| 2441 | }; |
| 2442 | |
| 2443 | The simplest static type (with fixed-length instances):: |
| 2444 | |
| 2445 | typedef struct { |
| 2446 | PyObject_HEAD |
| 2447 | } MyObject; |
| 2448 | |
| 2449 | static PyTypeObject MyObject_Type = { |
| 2450 | PyVarObject_HEAD_INIT(NULL, 0) |
| 2451 | .tp_name = "mymod.MyObject", |
| 2452 | }; |
| 2453 | |
| 2454 | The simplest static type (with variable-length instances):: |
| 2455 | |
| 2456 | typedef struct { |
| 2457 | PyObject_VAR_HEAD |
| 2458 | const char *data[1]; |
| 2459 | } MyObject; |
| 2460 | |
| 2461 | static PyTypeObject MyObject_Type = { |
| 2462 | PyVarObject_HEAD_INIT(NULL, 0) |
| 2463 | .tp_name = "mymod.MyObject", |
| 2464 | .tp_basicsize = sizeof(MyObject) - sizeof(char *), |
| 2465 | .tp_itemsize = sizeof(char *), |
| 2466 | }; |