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 | |
| 23 | Typedefs: unaryfunc, binaryfunc, ternaryfunc, inquiry, intargfunc, |
| 24 | intintargfunc, intobjargproc, intintobjargproc, objobjargproc, destructor, |
| 25 | freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc, |
Mark Dickinson | 9f98926 | 2009-02-02 21:29:40 +0000 | [diff] [blame] | 26 | reprfunc, hashfunc |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 27 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 28 | The structure definition for :c:type:`PyTypeObject` can be found in |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 29 | :file:`Include/object.h`. For convenience of reference, this repeats the |
| 30 | definition found there: |
| 31 | |
| 32 | .. literalinclude:: ../includes/typestruct.h |
| 33 | |
| 34 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 35 | The type object structure extends the :c:type:`PyVarObject` structure. The |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 36 | :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] | 37 | 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] | 38 | 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] | 39 | type objects) *must* have the :attr:`ob_size` field. |
| 40 | |
| 41 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 42 | .. c:member:: PyObject* PyObject._ob_next |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 43 | PyObject* PyObject._ob_prev |
| 44 | |
| 45 | These fields are only present when the macro ``Py_TRACE_REFS`` is defined. |
| 46 | Their initialization to *NULL* is taken care of by the ``PyObject_HEAD_INIT`` |
| 47 | macro. For statically allocated objects, these fields always remain *NULL*. |
| 48 | For dynamically allocated objects, these two fields are used to link the object |
| 49 | into a doubly-linked list of *all* live objects on the heap. This could be used |
| 50 | for various debugging purposes; currently the only use is to print the objects |
| 51 | that are still alive at the end of a run when the environment variable |
| 52 | :envvar:`PYTHONDUMPREFS` is set. |
| 53 | |
| 54 | These fields are not inherited by subtypes. |
| 55 | |
| 56 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 57 | .. c:member:: Py_ssize_t PyObject.ob_refcnt |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 58 | |
| 59 | This is the type object's reference count, initialized to ``1`` by the |
| 60 | ``PyObject_HEAD_INIT`` macro. Note that for statically allocated type objects, |
| 61 | the type's instances (objects whose :attr:`ob_type` points back to the type) do |
| 62 | *not* count as references. But for dynamically allocated type objects, the |
| 63 | instances *do* count as references. |
| 64 | |
| 65 | This field is not inherited by subtypes. |
| 66 | |
| 67 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 68 | .. c:member:: PyTypeObject* PyObject.ob_type |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 69 | |
| 70 | This is the type's type, in other words its metatype. It is initialized by the |
| 71 | argument to the ``PyObject_HEAD_INIT`` macro, and its value should normally be |
| 72 | ``&PyType_Type``. However, for dynamically loadable extension modules that must |
| 73 | be usable on Windows (at least), the compiler complains that this is not a valid |
| 74 | initializer. Therefore, the convention is to pass *NULL* to the |
| 75 | ``PyObject_HEAD_INIT`` macro and to initialize this field explicitly at the |
| 76 | start of the module's initialization function, before doing anything else. This |
| 77 | is typically done like this:: |
| 78 | |
| 79 | Foo_Type.ob_type = &PyType_Type; |
| 80 | |
| 81 | This should be done before any instances of the type are created. |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 82 | :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] | 83 | initializes it to the :attr:`ob_type` field of the base class. |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 84 | :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] | 85 | |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 86 | This field is inherited by subtypes. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 87 | |
| 88 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 89 | .. c:member:: Py_ssize_t PyVarObject.ob_size |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 90 | |
| 91 | For statically allocated type objects, this should be initialized to zero. For |
| 92 | dynamically allocated type objects, this field has a special internal meaning. |
| 93 | |
| 94 | This field is not inherited by subtypes. |
| 95 | |
| 96 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 97 | .. c:member:: char* PyTypeObject.tp_name |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 98 | |
| 99 | Pointer to a NUL-terminated string containing the name of the type. For types |
| 100 | that are accessible as module globals, the string should be the full module |
| 101 | name, followed by a dot, followed by the type name; for built-in types, it |
| 102 | should be just the type name. If the module is a submodule of a package, the |
| 103 | full package name is part of the full module name. For example, a type named |
| 104 | :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] | 105 | 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] | 106 | |
| 107 | For dynamically allocated type objects, this should just be the type name, and |
| 108 | the module name explicitly stored in the type dict as the value for key |
| 109 | ``'__module__'``. |
| 110 | |
| 111 | For statically allocated type objects, the tp_name field should contain a dot. |
| 112 | Everything before the last dot is made accessible as the :attr:`__module__` |
| 113 | attribute, and everything after the last dot is made accessible as the |
| 114 | :attr:`__name__` attribute. |
| 115 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 116 | If no dot is present, the entire :c:member:`~PyTypeObject.tp_name` field is made accessible as the |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 117 | :attr:`__name__` attribute, and the :attr:`__module__` attribute is undefined |
| 118 | (unless explicitly set in the dictionary, as explained above). This means your |
| 119 | type will be impossible to pickle. |
| 120 | |
| 121 | This field is not inherited by subtypes. |
| 122 | |
| 123 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 124 | .. c:member:: Py_ssize_t PyTypeObject.tp_basicsize |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 125 | Py_ssize_t PyTypeObject.tp_itemsize |
| 126 | |
| 127 | These fields allow calculating the size in bytes of instances of the type. |
| 128 | |
| 129 | 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] | 130 | :c:member:`~PyTypeObject.tp_itemsize` field, types with variable-length instances have a non-zero |
| 131 | :c:member:`~PyTypeObject.tp_itemsize` field. For a type with fixed-length instances, all |
| 132 | instances have the same size, given in :c:member:`~PyTypeObject.tp_basicsize`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 133 | |
| 134 | For a type with variable-length instances, the instances must have an |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 135 | :attr:`ob_size` field, and the instance size is :c:member:`~PyTypeObject.tp_basicsize` plus N |
| 136 | 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] | 137 | 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] | 138 | 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] | 139 | negative number, and N is ``abs(ob_size)`` there. Also, the presence of an |
| 140 | :attr:`ob_size` field in the instance layout doesn't mean that the instance |
| 141 | structure is variable-length (for example, the structure for the list type has |
| 142 | fixed-length instances, yet those instances have a meaningful :attr:`ob_size` |
| 143 | field). |
| 144 | |
| 145 | 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] | 146 | :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] | 147 | declare the instance struct) and this in turn includes the :attr:`_ob_prev` and |
| 148 | :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] | 149 | 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] | 150 | ``sizeof`` operator on the struct used to declare the instance layout. |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 151 | The basic size does not include the GC header size. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 152 | |
| 153 | These fields are inherited separately by subtypes. If the base type has a |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 154 | non-zero :c:member:`~PyTypeObject.tp_itemsize`, it is generally not safe to set |
| 155 | :c:member:`~PyTypeObject.tp_itemsize` to a different non-zero value in a subtype (though this |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 156 | depends on the implementation of the base type). |
| 157 | |
| 158 | A note about alignment: if the variable items require a particular alignment, |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 159 | this should be taken care of by the value of :c:member:`~PyTypeObject.tp_basicsize`. Example: |
| 160 | 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] | 161 | ``sizeof(double)``. It is the programmer's responsibility that |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 162 | :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] | 163 | alignment requirement for ``double``). |
| 164 | |
| 165 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 166 | .. c:member:: destructor PyTypeObject.tp_dealloc |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 167 | |
| 168 | A pointer to the instance destructor function. This function must be defined |
| 169 | unless the type guarantees that its instances will never be deallocated (as is |
| 170 | the case for the singletons ``None`` and ``Ellipsis``). |
| 171 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 172 | The destructor function is called by the :c:func:`Py_DECREF` and |
| 173 | :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] | 174 | the instance is still in existence, but there are no references to it. The |
| 175 | destructor function should free all references which the instance owns, free all |
| 176 | memory buffers owned by the instance (using the freeing function corresponding |
| 177 | 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] | 178 | 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] | 179 | subtypable (doesn't have the :const:`Py_TPFLAGS_BASETYPE` flag bit set), it is |
| 180 | permissible to call the object deallocator directly instead of via |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 181 | :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] | 182 | instance; this is normally :c:func:`PyObject_Del` if the instance was allocated |
| 183 | using :c:func:`PyObject_New` or :c:func:`PyObject_VarNew`, or |
| 184 | :c:func:`PyObject_GC_Del` if the instance was allocated using |
| 185 | :c:func:`PyObject_GC_New` or :c:func:`PyObject_GC_NewVar`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 186 | |
| 187 | This field is inherited by subtypes. |
| 188 | |
| 189 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 190 | .. c:member:: printfunc PyTypeObject.tp_print |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 191 | |
Georg Brandl | 340c749 | 2014-10-05 16:38:02 +0200 | [diff] [blame] | 192 | Reserved slot, formerly used for print formatting in Python 2.x. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 193 | |
| 194 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 195 | .. c:member:: getattrfunc PyTypeObject.tp_getattr |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 196 | |
| 197 | An optional pointer to the get-attribute-string function. |
| 198 | |
| 199 | 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] | 200 | that acts the same as the :c:member:`~PyTypeObject.tp_getattro` function, but taking a C string |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 201 | instead of a Python string object to give the attribute name. The signature is |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 202 | the same as for :c:func:`PyObject_GetAttrString`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 203 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 204 | This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattro`: a subtype |
| 205 | inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when |
| 206 | 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] | 207 | |
| 208 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 209 | .. c:member:: setattrfunc PyTypeObject.tp_setattr |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 210 | |
| 211 | An optional pointer to the set-attribute-string function. |
| 212 | |
| 213 | 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] | 214 | that acts the same as the :c:member:`~PyTypeObject.tp_setattro` function, but taking a C string |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 215 | instead of a Python string object to give the attribute name. The signature is |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 216 | the same as for :c:func:`PyObject_SetAttrString`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 217 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 218 | This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattro`: a subtype |
| 219 | inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when |
| 220 | 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] | 221 | |
| 222 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 223 | .. c:member:: void* PyTypeObject.tp_reserved |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 224 | |
Mark Dickinson | 9f98926 | 2009-02-02 21:29:40 +0000 | [diff] [blame] | 225 | Reserved slot, formerly known as tp_compare. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 226 | |
| 227 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 228 | .. c:member:: reprfunc PyTypeObject.tp_repr |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 229 | |
| 230 | .. index:: builtin: repr |
| 231 | |
| 232 | An optional pointer to a function that implements the built-in function |
| 233 | :func:`repr`. |
| 234 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 235 | The signature is the same as for :c:func:`PyObject_Repr`; it must return a string |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 236 | or a Unicode object. Ideally, this function should return a string that, when |
| 237 | passed to :func:`eval`, given a suitable environment, returns an object with the |
| 238 | same value. If this is not feasible, it should return a string starting with |
| 239 | ``'<'`` and ending with ``'>'`` from which both the type and the value of the |
| 240 | object can be deduced. |
| 241 | |
| 242 | When this field is not set, a string of the form ``<%s object at %p>`` is |
| 243 | returned, where ``%s`` is replaced by the type name, and ``%p`` by the object's |
| 244 | memory address. |
| 245 | |
| 246 | This field is inherited by subtypes. |
| 247 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 248 | .. c:member:: PyNumberMethods* tp_as_number |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 249 | |
| 250 | Pointer to an additional structure that contains fields relevant only to |
| 251 | objects which implement the number protocol. These fields are documented in |
| 252 | :ref:`number-structs`. |
| 253 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 254 | 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] | 255 | inherited individually. |
| 256 | |
| 257 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 258 | .. c:member:: PySequenceMethods* tp_as_sequence |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 259 | |
| 260 | Pointer to an additional structure that contains fields relevant only to |
| 261 | objects which implement the sequence protocol. These fields are documented |
| 262 | in :ref:`sequence-structs`. |
| 263 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 264 | 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] | 265 | are inherited individually. |
| 266 | |
| 267 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 268 | .. c:member:: PyMappingMethods* tp_as_mapping |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 269 | |
| 270 | Pointer to an additional structure that contains fields relevant only to |
| 271 | objects which implement the mapping protocol. These fields are documented in |
| 272 | :ref:`mapping-structs`. |
| 273 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 274 | 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] | 275 | are inherited individually. |
| 276 | |
| 277 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 278 | .. c:member:: hashfunc PyTypeObject.tp_hash |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 279 | |
| 280 | .. index:: builtin: hash |
| 281 | |
| 282 | An optional pointer to a function that implements the built-in function |
| 283 | :func:`hash`. |
| 284 | |
Benjamin Peterson | 8f67d08 | 2010-10-17 20:54:53 +0000 | [diff] [blame] | 285 | The signature is the same as for :c:func:`PyObject_Hash`; it must return a |
| 286 | value of the type Py_hash_t. The value ``-1`` should not be returned as a |
| 287 | normal return value; when an error occurs during the computation of the hash |
| 288 | value, the function should set an exception and return ``-1``. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 289 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 290 | This field can be set explicitly to :c:func:`PyObject_HashNotImplemented` to |
Nick Coghlan | 7a70a3a | 2008-08-18 13:18:16 +0000 | [diff] [blame] | 291 | block inheritance of the hash method from a parent type. This is interpreted |
| 292 | as the equivalent of ``__hash__ = None`` at the Python level, causing |
| 293 | ``isinstance(o, collections.Hashable)`` to correctly return ``False``. Note |
| 294 | that the converse is also true - setting ``__hash__ = None`` on a class at |
| 295 | 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] | 296 | :c:func:`PyObject_HashNotImplemented`. |
Nick Coghlan | 7a70a3a | 2008-08-18 13:18:16 +0000 | [diff] [blame] | 297 | |
Mark Dickinson | 9f98926 | 2009-02-02 21:29:40 +0000 | [diff] [blame] | 298 | When this field is not set, an attempt to take the hash of the |
| 299 | object raises :exc:`TypeError`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 300 | |
Mark Dickinson | 9f98926 | 2009-02-02 21:29:40 +0000 | [diff] [blame] | 301 | This field is inherited by subtypes together with |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 302 | :c:member:`~PyTypeObject.tp_richcompare`: a subtype inherits both of |
| 303 | :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash`, when the subtype's |
| 304 | :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] | 305 | |
| 306 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 307 | .. c:member:: ternaryfunc PyTypeObject.tp_call |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 308 | |
| 309 | An optional pointer to a function that implements calling the object. This |
| 310 | should be *NULL* if the object is not callable. The signature is the same as |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 311 | for :c:func:`PyObject_Call`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 312 | |
| 313 | This field is inherited by subtypes. |
| 314 | |
| 315 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 316 | .. c:member:: reprfunc PyTypeObject.tp_str |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 317 | |
| 318 | An optional pointer to a function that implements the built-in operation |
| 319 | :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] | 320 | constructor for that type. This constructor calls :c:func:`PyObject_Str` to do |
| 321 | the actual work, and :c:func:`PyObject_Str` will call this handler.) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 322 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 323 | The signature is the same as for :c:func:`PyObject_Str`; it must return a string |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 324 | or a Unicode object. This function should return a "friendly" string |
| 325 | representation of the object, as this is the representation that will be used, |
| 326 | among other things, by the :func:`print` function. |
| 327 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 328 | When this field is not set, :c:func:`PyObject_Repr` is called to return a string |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 329 | representation. |
| 330 | |
| 331 | This field is inherited by subtypes. |
| 332 | |
| 333 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 334 | .. c:member:: getattrofunc PyTypeObject.tp_getattro |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 335 | |
| 336 | An optional pointer to the get-attribute function. |
| 337 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 338 | The signature is the same as for :c:func:`PyObject_GetAttr`. It is usually |
| 339 | convenient to set this field to :c:func:`PyObject_GenericGetAttr`, which |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 340 | implements the normal way of looking for object attributes. |
| 341 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 342 | This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_getattr`: a subtype |
| 343 | inherits both :c:member:`~PyTypeObject.tp_getattr` and :c:member:`~PyTypeObject.tp_getattro` from its base type when |
| 344 | 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] | 345 | |
| 346 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 347 | .. c:member:: setattrofunc PyTypeObject.tp_setattro |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 348 | |
| 349 | An optional pointer to the set-attribute function. |
| 350 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 351 | The signature is the same as for :c:func:`PyObject_SetAttr`. It is usually |
| 352 | convenient to set this field to :c:func:`PyObject_GenericSetAttr`, which |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 353 | implements the normal way of setting object attributes. |
| 354 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 355 | This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_setattr`: a subtype |
| 356 | inherits both :c:member:`~PyTypeObject.tp_setattr` and :c:member:`~PyTypeObject.tp_setattro` from its base type when |
| 357 | 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] | 358 | |
| 359 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 360 | .. c:member:: PyBufferProcs* PyTypeObject.tp_as_buffer |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 361 | |
| 362 | Pointer to an additional structure that contains fields relevant only to objects |
| 363 | which implement the buffer interface. These fields are documented in |
| 364 | :ref:`buffer-structs`. |
| 365 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 366 | The :c:member:`~PyTypeObject.tp_as_buffer` field is not inherited, but the contained fields are |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 367 | inherited individually. |
| 368 | |
| 369 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 370 | .. c:member:: long PyTypeObject.tp_flags |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 371 | |
| 372 | This field is a bit mask of various flags. Some flags indicate variant |
| 373 | semantics for certain situations; others are used to indicate that certain |
| 374 | fields in the type object (or in the extension structures referenced via |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 375 | :c:member:`~PyTypeObject.tp_as_number`, :c:member:`~PyTypeObject.tp_as_sequence`, :c:member:`~PyTypeObject.tp_as_mapping`, and |
| 376 | :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] | 377 | such a flag bit is clear, the type fields it guards must not be accessed and |
| 378 | must be considered to have a zero or *NULL* value instead. |
| 379 | |
| 380 | Inheritance of this field is complicated. Most flag bits are inherited |
| 381 | individually, i.e. if the base type has a flag bit set, the subtype inherits |
| 382 | this flag bit. The flag bits that pertain to extension structures are strictly |
| 383 | inherited if the extension structure is inherited, i.e. the base type's value of |
| 384 | the flag bit is copied into the subtype together with a pointer to the extension |
| 385 | 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] | 386 | 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] | 387 | :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] | 388 | :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] | 389 | *NULL* values. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 390 | |
| 391 | 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] | 392 | 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] | 393 | :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] | 394 | checks whether ``tp->tp_flags & f`` is non-zero. |
| 395 | |
| 396 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 397 | .. data:: Py_TPFLAGS_HEAPTYPE |
| 398 | |
| 399 | This bit is set when the type object itself is allocated on the heap. In this |
| 400 | case, the :attr:`ob_type` field of its instances is considered a reference to |
| 401 | the type, and the type object is INCREF'ed when a new instance is created, and |
| 402 | DECREF'ed when an instance is destroyed (this does not apply to instances of |
| 403 | subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or |
| 404 | DECREF'ed). |
| 405 | |
| 406 | |
| 407 | .. data:: Py_TPFLAGS_BASETYPE |
| 408 | |
| 409 | This bit is set when the type can be used as the base type of another type. If |
| 410 | this bit is clear, the type cannot be subtyped (similar to a "final" class in |
| 411 | Java). |
| 412 | |
| 413 | |
| 414 | .. data:: Py_TPFLAGS_READY |
| 415 | |
| 416 | 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] | 417 | :c:func:`PyType_Ready`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 418 | |
| 419 | |
| 420 | .. data:: Py_TPFLAGS_READYING |
| 421 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 422 | 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] | 423 | the type object. |
| 424 | |
| 425 | |
| 426 | .. data:: Py_TPFLAGS_HAVE_GC |
| 427 | |
| 428 | 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] | 429 | is set, instances must be created using :c:func:`PyObject_GC_New` and |
| 430 | destroyed using :c:func:`PyObject_GC_Del`. More information in section |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 431 | :ref:`supporting-cycle-detection`. This bit also implies that the |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 432 | 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] | 433 | the type object. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 434 | |
| 435 | |
| 436 | .. data:: Py_TPFLAGS_DEFAULT |
| 437 | |
| 438 | This is a bitmask of all the bits that pertain to the existence of certain |
| 439 | fields in the type object and its extension structures. Currently, it includes |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 440 | the following bits: :const:`Py_TPFLAGS_HAVE_STACKLESS_EXTENSION`, |
| 441 | :const:`Py_TPFLAGS_HAVE_VERSION_TAG`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 442 | |
| 443 | |
Antoine Pitrou | f9f54a2 | 2014-04-29 01:39:03 +0200 | [diff] [blame] | 444 | .. data:: Py_TPFLAGS_LONG_SUBCLASS |
| 445 | .. data:: Py_TPFLAGS_LIST_SUBCLASS |
| 446 | .. data:: Py_TPFLAGS_TUPLE_SUBCLASS |
| 447 | .. data:: Py_TPFLAGS_BYTES_SUBCLASS |
| 448 | .. data:: Py_TPFLAGS_UNICODE_SUBCLASS |
| 449 | .. data:: Py_TPFLAGS_DICT_SUBCLASS |
| 450 | .. data:: Py_TPFLAGS_BASE_EXC_SUBCLASS |
| 451 | .. data:: Py_TPFLAGS_TYPE_SUBCLASS |
| 452 | |
| 453 | These flags are used by functions such as |
| 454 | :c:func:`PyLong_Check` to quickly determine if a type is a subclass |
| 455 | of a built-in type; such specific checks are faster than a generic |
| 456 | check, like :c:func:`PyObject_IsInstance`. Custom types that inherit |
| 457 | from built-ins should have their :c:member:`~PyTypeObject.tp_flags` |
| 458 | set appropriately, or the code that interacts with such types |
| 459 | will behave differently depending on what kind of check is used. |
| 460 | |
| 461 | |
Antoine Pitrou | 796564c | 2013-07-30 19:59:21 +0200 | [diff] [blame] | 462 | .. data:: Py_TPFLAGS_HAVE_FINALIZE |
| 463 | |
Antoine Pitrou | a68cbfa | 2013-08-01 21:14:43 +0200 | [diff] [blame] | 464 | 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] | 465 | type structure. |
| 466 | |
| 467 | .. versionadded:: 3.4 |
| 468 | |
| 469 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 470 | .. c:member:: char* PyTypeObject.tp_doc |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 471 | |
| 472 | An optional pointer to a NUL-terminated C string giving the docstring for this |
| 473 | type object. This is exposed as the :attr:`__doc__` attribute on the type and |
| 474 | instances of the type. |
| 475 | |
| 476 | This field is *not* inherited by subtypes. |
| 477 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 478 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 479 | .. c:member:: traverseproc PyTypeObject.tp_traverse |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 480 | |
| 481 | An optional pointer to a traversal function for the garbage collector. This is |
| 482 | only used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. More information |
| 483 | about Python's garbage collection scheme can be found in section |
| 484 | :ref:`supporting-cycle-detection`. |
| 485 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 486 | The :c:member:`~PyTypeObject.tp_traverse` pointer is used by the garbage collector to detect |
| 487 | 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] | 488 | simply calls :c:func:`Py_VISIT` on each of the instance's members that are Python |
| 489 | objects. For example, this is function :c:func:`local_traverse` from the |
Georg Brandl | 2067bfd | 2008-05-25 13:05:15 +0000 | [diff] [blame] | 490 | :mod:`_thread` extension module:: |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 491 | |
| 492 | static int |
| 493 | local_traverse(localobject *self, visitproc visit, void *arg) |
| 494 | { |
| 495 | Py_VISIT(self->args); |
| 496 | Py_VISIT(self->kw); |
| 497 | Py_VISIT(self->dict); |
| 498 | return 0; |
| 499 | } |
| 500 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 501 | 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] | 502 | in reference cycles. Although there is also a ``self->key`` member, it can only |
| 503 | be *NULL* or a Python string and therefore cannot be part of a reference cycle. |
| 504 | |
| 505 | On the other hand, even if you know a member can never be part of a cycle, as a |
| 506 | 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] | 507 | :func:`~gc.get_referents` function will include it. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 508 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 509 | Note that :c:func:`Py_VISIT` requires the *visit* and *arg* parameters to |
| 510 | :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] | 511 | anything. |
| 512 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 513 | This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_clear` and the |
| 514 | :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and |
| 515 | :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] | 516 | the subtype. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 517 | |
| 518 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 519 | .. c:member:: inquiry PyTypeObject.tp_clear |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 520 | |
| 521 | An optional pointer to a clear function for the garbage collector. This is only |
| 522 | used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. |
| 523 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 524 | The :c:member:`~PyTypeObject.tp_clear` member function is used to break reference cycles in cyclic |
| 525 | 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] | 526 | 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] | 527 | subtle, and if in any doubt supply a :c:member:`~PyTypeObject.tp_clear` function. For example, |
| 528 | 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] | 529 | 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] | 530 | 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] | 531 | 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] | 532 | rarely a good reason to avoid implementing :c:member:`~PyTypeObject.tp_clear`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 533 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 534 | 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] | 535 | those of its members that may be Python objects, and set its pointers to those |
| 536 | members to *NULL*, as in the following example:: |
| 537 | |
| 538 | static int |
| 539 | local_clear(localobject *self) |
| 540 | { |
| 541 | Py_CLEAR(self->key); |
| 542 | Py_CLEAR(self->args); |
| 543 | Py_CLEAR(self->kw); |
| 544 | Py_CLEAR(self->dict); |
| 545 | return 0; |
| 546 | } |
| 547 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 548 | 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] | 549 | delicate: the reference to the contained object must not be decremented until |
| 550 | after the pointer to the contained object is set to *NULL*. This is because |
| 551 | decrementing the reference count may cause the contained object to become trash, |
| 552 | triggering a chain of reclamation activity that may include invoking arbitrary |
| 553 | Python code (due to finalizers, or weakref callbacks, associated with the |
| 554 | contained object). If it's possible for such code to reference *self* again, |
| 555 | it's important that the pointer to the contained object be *NULL* at that time, |
| 556 | 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] | 557 | :c:func:`Py_CLEAR` macro performs the operations in a safe order. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 558 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 559 | 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] | 560 | it's not necessary to clear contained objects like Python strings or Python |
| 561 | integers, which can't participate in reference cycles. On the other hand, it may |
| 562 | 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] | 563 | :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] | 564 | |
| 565 | More information about Python's garbage collection scheme can be found in |
| 566 | section :ref:`supporting-cycle-detection`. |
| 567 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 568 | This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_traverse` and the |
| 569 | :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :c:member:`~PyTypeObject.tp_traverse`, and |
| 570 | :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] | 571 | the subtype. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 572 | |
| 573 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 574 | .. c:member:: richcmpfunc PyTypeObject.tp_richcompare |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 575 | |
Christian Heimes | e1c9811 | 2008-01-21 11:20:28 +0000 | [diff] [blame] | 576 | An optional pointer to the rich comparison function, whose signature is |
Andrew Svetlov | 0d50af4 | 2014-07-03 16:07:17 +0300 | [diff] [blame] | 577 | ``PyObject *tp_richcompare(PyObject *a, PyObject *b, int op)``. The first |
| 578 | parameter is guaranteed to be an instance of the type that is defined |
| 579 | by :c:type:`PyTypeObject`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 580 | |
Christian Heimes | e1c9811 | 2008-01-21 11:20:28 +0000 | [diff] [blame] | 581 | The function should return the result of the comparison (usually ``Py_True`` |
| 582 | or ``Py_False``). If the comparison is undefined, it must return |
| 583 | ``Py_NotImplemented``, if another error occurred it must return ``NULL`` and |
| 584 | set an exception condition. |
| 585 | |
| 586 | .. note:: |
| 587 | |
| 588 | If you want to implement a type for which only a limited set of |
| 589 | comparisons makes sense (e.g. ``==`` and ``!=``, but not ``<`` and |
| 590 | friends), directly raise :exc:`TypeError` in the rich comparison function. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 591 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 592 | This field is inherited by subtypes together with :c:member:`~PyTypeObject.tp_hash`: |
| 593 | a subtype inherits :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` when |
| 594 | the subtype's :c:member:`~PyTypeObject.tp_richcompare` and :c:member:`~PyTypeObject.tp_hash` are both |
Mark Dickinson | 9f98926 | 2009-02-02 21:29:40 +0000 | [diff] [blame] | 595 | *NULL*. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 596 | |
| 597 | 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] | 598 | :c:member:`~PyTypeObject.tp_richcompare` and for :c:func:`PyObject_RichCompare`: |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 599 | |
| 600 | +----------------+------------+ |
| 601 | | Constant | Comparison | |
| 602 | +================+============+ |
| 603 | | :const:`Py_LT` | ``<`` | |
| 604 | +----------------+------------+ |
| 605 | | :const:`Py_LE` | ``<=`` | |
| 606 | +----------------+------------+ |
| 607 | | :const:`Py_EQ` | ``==`` | |
| 608 | +----------------+------------+ |
| 609 | | :const:`Py_NE` | ``!=`` | |
| 610 | +----------------+------------+ |
| 611 | | :const:`Py_GT` | ``>`` | |
| 612 | +----------------+------------+ |
| 613 | | :const:`Py_GE` | ``>=`` | |
| 614 | +----------------+------------+ |
| 615 | |
Christian Heimes | e1c9811 | 2008-01-21 11:20:28 +0000 | [diff] [blame] | 616 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 617 | .. c:member:: long PyTypeObject.tp_weaklistoffset |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 618 | |
| 619 | If the instances of this type are weakly referenceable, this field is greater |
| 620 | than zero and contains the offset in the instance structure of the weak |
| 621 | 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] | 622 | :c:func:`PyObject_ClearWeakRefs` and the :c:func:`PyWeakref_\*` functions. The |
| 623 | 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] | 624 | initialized to *NULL*. |
| 625 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 626 | 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] | 627 | weak references to the type object itself. |
| 628 | |
| 629 | This field is inherited by subtypes, but see the rules listed below. A subtype |
| 630 | may override this offset; this means that the subtype uses a different weak |
| 631 | 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] | 632 | :c:member:`~PyTypeObject.tp_weaklistoffset`, this should not be a problem. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 633 | |
Serhiy Storchaka | 0b68a2d | 2013-10-09 13:26:17 +0300 | [diff] [blame] | 634 | 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] | 635 | and none of its base types are weakly referenceable, the type is made weakly |
| 636 | 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] | 637 | 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] | 638 | |
| 639 | When a type's :attr:`__slots__` declaration contains a slot named |
| 640 | :attr:`__weakref__`, that slot becomes the weak reference list head for |
| 641 | 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] | 642 | :c:member:`~PyTypeObject.tp_weaklistoffset`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 643 | |
| 644 | 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] | 645 | :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] | 646 | base type. |
| 647 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 648 | .. c:member:: getiterfunc PyTypeObject.tp_iter |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 649 | |
| 650 | An optional pointer to a function that returns an iterator for the object. Its |
| 651 | presence normally signals that the instances of this type are iterable (although |
Georg Brandl | 23e8db5 | 2008-04-07 19:17:06 +0000 | [diff] [blame] | 652 | sequences may be iterable without this function). |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 653 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 654 | This function has the same signature as :c:func:`PyObject_GetIter`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 655 | |
| 656 | This field is inherited by subtypes. |
| 657 | |
| 658 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 659 | .. c:member:: iternextfunc PyTypeObject.tp_iternext |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 660 | |
Georg Brandl | f392057 | 2008-04-30 20:06:53 +0000 | [diff] [blame] | 661 | An optional pointer to a function that returns the next item in an iterator. |
| 662 | When the iterator is exhausted, it must return *NULL*; a :exc:`StopIteration` |
| 663 | exception may or may not be set. When another error occurs, it must return |
| 664 | *NULL* too. Its presence signals that the instances of this type are |
| 665 | iterators. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 666 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 667 | 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] | 668 | function should return the iterator instance itself (not a new iterator |
| 669 | instance). |
| 670 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 671 | This function has the same signature as :c:func:`PyIter_Next`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 672 | |
| 673 | This field is inherited by subtypes. |
| 674 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 675 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 676 | .. c:member:: struct PyMethodDef* PyTypeObject.tp_methods |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 677 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 678 | 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] | 679 | structures, declaring regular methods of this type. |
| 680 | |
| 681 | 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] | 682 | :c:member:`~PyTypeObject.tp_dict` below) containing a method descriptor. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 683 | |
| 684 | This field is not inherited by subtypes (methods are inherited through a |
| 685 | different mechanism). |
| 686 | |
| 687 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 688 | .. c:member:: struct PyMemberDef* PyTypeObject.tp_members |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 689 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 690 | 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] | 691 | structures, declaring regular data members (fields or slots) of instances of |
| 692 | this type. |
| 693 | |
| 694 | 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] | 695 | :c:member:`~PyTypeObject.tp_dict` below) containing a member descriptor. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 696 | |
| 697 | This field is not inherited by subtypes (members are inherited through a |
| 698 | different mechanism). |
| 699 | |
| 700 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 701 | .. c:member:: struct PyGetSetDef* PyTypeObject.tp_getset |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 702 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 703 | 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] | 704 | structures, declaring computed attributes of instances of this type. |
| 705 | |
| 706 | 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] | 707 | :c:member:`~PyTypeObject.tp_dict` below) containing a getset descriptor. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 708 | |
| 709 | This field is not inherited by subtypes (computed attributes are inherited |
| 710 | through a different mechanism). |
| 711 | |
Georg Brandl | fbb56ed | 2010-12-06 22:02:48 +0000 | [diff] [blame] | 712 | .. XXX belongs elsewhere |
| 713 | |
| 714 | Docs for PyGetSetDef:: |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 715 | |
| 716 | typedef PyObject *(*getter)(PyObject *, void *); |
| 717 | typedef int (*setter)(PyObject *, PyObject *, void *); |
| 718 | |
| 719 | typedef struct PyGetSetDef { |
| 720 | char *name; /* attribute name */ |
| 721 | getter get; /* C function to get the attribute */ |
| 722 | setter set; /* C function to set the attribute */ |
| 723 | char *doc; /* optional doc string */ |
| 724 | void *closure; /* optional additional data for getter and setter */ |
| 725 | } PyGetSetDef; |
| 726 | |
| 727 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 728 | .. c:member:: PyTypeObject* PyTypeObject.tp_base |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 729 | |
| 730 | An optional pointer to a base type from which type properties are inherited. At |
| 731 | this level, only single inheritance is supported; multiple inheritance require |
| 732 | dynamically creating a type object by calling the metatype. |
| 733 | |
| 734 | This field is not inherited by subtypes (obviously), but it defaults to |
| 735 | ``&PyBaseObject_Type`` (which to Python programmers is known as the type |
| 736 | :class:`object`). |
| 737 | |
| 738 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 739 | .. c:member:: PyObject* PyTypeObject.tp_dict |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 740 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 741 | The type's dictionary is stored here by :c:func:`PyType_Ready`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 742 | |
| 743 | This field should normally be initialized to *NULL* before PyType_Ready is |
| 744 | called; it may also be initialized to a dictionary containing initial attributes |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 745 | 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] | 746 | attributes for the type may be added to this dictionary only if they don't |
| 747 | correspond to overloaded operations (like :meth:`__add__`). |
| 748 | |
| 749 | This field is not inherited by subtypes (though the attributes defined in here |
| 750 | are inherited through a different mechanism). |
| 751 | |
Benjamin Peterson | 77c4fd0 | 2011-08-09 16:07:01 -0500 | [diff] [blame] | 752 | .. warning:: |
| 753 | |
| 754 | 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] | 755 | :c:member:`~PyTypeObject.tp_dict` with the dictionary C-API. |
Benjamin Peterson | 77c4fd0 | 2011-08-09 16:07:01 -0500 | [diff] [blame] | 756 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 757 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 758 | .. c:member:: descrgetfunc PyTypeObject.tp_descr_get |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 759 | |
| 760 | An optional pointer to a "descriptor get" function. |
| 761 | |
| 762 | The function signature is :: |
| 763 | |
| 764 | PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type); |
| 765 | |
Georg Brandl | fbb56ed | 2010-12-06 22:02:48 +0000 | [diff] [blame] | 766 | .. XXX explain. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 767 | |
| 768 | This field is inherited by subtypes. |
| 769 | |
| 770 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 771 | .. c:member:: descrsetfunc PyTypeObject.tp_descr_set |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 772 | |
| 773 | An optional pointer to a "descriptor set" function. |
| 774 | |
| 775 | The function signature is :: |
| 776 | |
| 777 | int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value); |
| 778 | |
| 779 | This field is inherited by subtypes. |
| 780 | |
Georg Brandl | fbb56ed | 2010-12-06 22:02:48 +0000 | [diff] [blame] | 781 | .. XXX explain. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 782 | |
| 783 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 784 | .. c:member:: long PyTypeObject.tp_dictoffset |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 785 | |
| 786 | If the instances of this type have a dictionary containing instance variables, |
| 787 | this field is non-zero and contains the offset in the instances of the type of |
| 788 | the instance variable dictionary; this offset is used by |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 789 | :c:func:`PyObject_GenericGetAttr`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 790 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 791 | 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] | 792 | attributes of the type object itself. |
| 793 | |
| 794 | If the value of this field is greater than zero, it specifies the offset from |
| 795 | the start of the instance structure. If the value is less than zero, it |
| 796 | specifies the offset from the *end* of the instance structure. A negative |
| 797 | offset is more expensive to use, and should only be used when the instance |
| 798 | structure contains a variable-length part. This is used for example to add an |
| 799 | instance variable dictionary to subtypes of :class:`str` or :class:`tuple`. Note |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 800 | 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] | 801 | the end in that case, even though the dictionary is not included in the basic |
| 802 | object layout. On a system with a pointer size of 4 bytes, |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 803 | :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] | 804 | at the very end of the structure. |
| 805 | |
| 806 | 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] | 807 | :c:member:`~PyTypeObject.tp_dictoffset` as follows:: |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 808 | |
| 809 | dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset |
| 810 | if dictoffset is not aligned on sizeof(void*): |
| 811 | round up to sizeof(void*) |
| 812 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 813 | 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] | 814 | 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] | 815 | 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] | 816 | 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] | 817 | yourself; it is done for you by :c:func:`_PyObject_GetDictPtr`.) |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 818 | |
| 819 | This field is inherited by subtypes, but see the rules listed below. A subtype |
| 820 | may override this offset; this means that the subtype instances store the |
| 821 | 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] | 822 | 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] | 823 | |
Serhiy Storchaka | 0b68a2d | 2013-10-09 13:26:17 +0300 | [diff] [blame] | 824 | 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] | 825 | 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] | 826 | 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] | 827 | that slot's offset. |
| 828 | |
| 829 | 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] | 830 | 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] | 831 | |
Serhiy Storchaka | 0b68a2d | 2013-10-09 13:26:17 +0300 | [diff] [blame] | 832 | (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] | 833 | not have the expected effect, it just causes confusion. Maybe this should be |
| 834 | added as a feature just like :attr:`__weakref__` though.) |
| 835 | |
| 836 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 837 | .. c:member:: initproc PyTypeObject.tp_init |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 838 | |
| 839 | An optional pointer to an instance initialization function. |
| 840 | |
| 841 | This function corresponds to the :meth:`__init__` method of classes. Like |
| 842 | :meth:`__init__`, it is possible to create an instance without calling |
| 843 | :meth:`__init__`, and it is possible to reinitialize an instance by calling its |
| 844 | :meth:`__init__` method again. |
| 845 | |
| 846 | The function signature is :: |
| 847 | |
| 848 | int tp_init(PyObject *self, PyObject *args, PyObject *kwds) |
| 849 | |
| 850 | The self argument is the instance to be initialized; the *args* and *kwds* |
| 851 | arguments represent positional and keyword arguments of the call to |
| 852 | :meth:`__init__`. |
| 853 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 854 | The :c:member:`~PyTypeObject.tp_init` function, if not *NULL*, is called when an instance is |
| 855 | created normally by calling its type, after the type's :c:member:`~PyTypeObject.tp_new` function |
| 856 | 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] | 857 | 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] | 858 | :c:member:`~PyTypeObject.tp_init` function is called; if :c:member:`~PyTypeObject.tp_new` returns an instance of a |
| 859 | 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] | 860 | |
| 861 | This field is inherited by subtypes. |
| 862 | |
| 863 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 864 | .. c:member:: allocfunc PyTypeObject.tp_alloc |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 865 | |
| 866 | An optional pointer to an instance allocation function. |
| 867 | |
| 868 | The function signature is :: |
| 869 | |
| 870 | PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems) |
| 871 | |
| 872 | The purpose of this function is to separate memory allocation from memory |
| 873 | initialization. It should return a pointer to a block of memory of adequate |
| 874 | length for the instance, suitably aligned, and initialized to zeros, but with |
| 875 | :attr:`ob_refcnt` set to ``1`` and :attr:`ob_type` set to the type argument. If |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 876 | the type's :c:member:`~PyTypeObject.tp_itemsize` is non-zero, the object's :attr:`ob_size` field |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 877 | should be initialized to *nitems* and the length of the allocated memory block |
| 878 | should be ``tp_basicsize + nitems*tp_itemsize``, rounded up to a multiple of |
| 879 | ``sizeof(void*)``; otherwise, *nitems* is not used and the length of the block |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 880 | should be :c:member:`~PyTypeObject.tp_basicsize`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 881 | |
| 882 | Do not use this function to do any other instance initialization, not even to |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 883 | allocate additional memory; that should be done by :c:member:`~PyTypeObject.tp_new`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 884 | |
| 885 | This field is inherited by static subtypes, but not by dynamic subtypes |
| 886 | (subtypes created by a class statement); in the latter, this field is always set |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 887 | to :c:func:`PyType_GenericAlloc`, to force a standard heap allocation strategy. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 888 | That is also the recommended value for statically defined types. |
| 889 | |
| 890 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 891 | .. c:member:: newfunc PyTypeObject.tp_new |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 892 | |
| 893 | An optional pointer to an instance creation function. |
| 894 | |
| 895 | If this function is *NULL* for a particular type, that type cannot be called to |
| 896 | create new instances; presumably there is some other way to create instances, |
| 897 | like a factory function. |
| 898 | |
| 899 | The function signature is :: |
| 900 | |
| 901 | PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds) |
| 902 | |
| 903 | The subtype argument is the type of the object being created; the *args* and |
| 904 | *kwds* arguments represent positional and keyword arguments of the call to the |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 905 | 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] | 906 | function is called; it may be a subtype of that type (but not an unrelated |
| 907 | type). |
| 908 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 909 | 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] | 910 | to allocate space for the object, and then do only as much further |
| 911 | initialization as is absolutely necessary. Initialization that can safely be |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 912 | 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] | 913 | 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] | 914 | in :c:member:`~PyTypeObject.tp_new`, while for mutable types, most initialization should be |
| 915 | deferred to :c:member:`~PyTypeObject.tp_init`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 916 | |
| 917 | 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] | 918 | whose :c:member:`~PyTypeObject.tp_base` is *NULL* or ``&PyBaseObject_Type``. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 919 | |
| 920 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 921 | .. c:member:: destructor PyTypeObject.tp_free |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 922 | |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 923 | An optional pointer to an instance deallocation function. Its signature is |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 924 | :c:type:`freefunc`:: |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 925 | |
| 926 | void tp_free(void *) |
| 927 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 928 | 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] | 929 | |
| 930 | This field is inherited by static subtypes, but not by dynamic subtypes |
| 931 | (subtypes created by a class statement); in the latter, this field is set to a |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 932 | deallocator suitable to match :c:func:`PyType_GenericAlloc` and the value of the |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 933 | :const:`Py_TPFLAGS_HAVE_GC` flag bit. |
| 934 | |
| 935 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 936 | .. c:member:: inquiry PyTypeObject.tp_is_gc |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 937 | |
| 938 | An optional pointer to a function called by the garbage collector. |
| 939 | |
| 940 | The garbage collector needs to know whether a particular object is collectible |
| 941 | 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] | 942 | :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] | 943 | some types have a mixture of statically and dynamically allocated instances, and |
| 944 | the statically allocated instances are not collectible. Such types should |
| 945 | define this function; it should return ``1`` for a collectible instance, and |
| 946 | ``0`` for a non-collectible instance. The signature is :: |
| 947 | |
| 948 | int tp_is_gc(PyObject *self) |
| 949 | |
| 950 | (The only example of this are types themselves. The metatype, |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 951 | :c:data:`PyType_Type`, defines this function to distinguish between statically |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 952 | and dynamically allocated types.) |
| 953 | |
Georg Brandl | e6bcc91 | 2008-05-12 18:05:20 +0000 | [diff] [blame] | 954 | This field is inherited by subtypes. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 955 | |
| 956 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 957 | .. c:member:: PyObject* PyTypeObject.tp_bases |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 958 | |
| 959 | Tuple of base types. |
| 960 | |
| 961 | This is set for types created by a class statement. It should be *NULL* for |
| 962 | statically defined types. |
| 963 | |
| 964 | This field is not inherited. |
| 965 | |
| 966 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 967 | .. c:member:: PyObject* PyTypeObject.tp_mro |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 968 | |
| 969 | Tuple containing the expanded set of base types, starting with the type itself |
| 970 | and ending with :class:`object`, in Method Resolution Order. |
| 971 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 972 | This field is not inherited; it is calculated fresh by :c:func:`PyType_Ready`. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 973 | |
| 974 | |
Antoine Pitrou | 796564c | 2013-07-30 19:59:21 +0200 | [diff] [blame] | 975 | .. c:member:: destructor PyTypeObject.tp_finalize |
| 976 | |
| 977 | An optional pointer to an instance finalization function. Its signature is |
| 978 | :c:type:`destructor`:: |
| 979 | |
| 980 | void tp_finalize(PyObject *) |
| 981 | |
Antoine Pitrou | a68cbfa | 2013-08-01 21:14:43 +0200 | [diff] [blame] | 982 | 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] | 983 | finalizing an instance. It is called either from the garbage |
| 984 | collector (if the instance is part of an isolated reference cycle) or |
| 985 | just before the object is deallocated. Either way, it is guaranteed |
| 986 | to be called before attempting to break reference cycles, ensuring |
| 987 | that it finds the object in a sane state. |
| 988 | |
Antoine Pitrou | a68cbfa | 2013-08-01 21:14:43 +0200 | [diff] [blame] | 989 | :c:member:`~PyTypeObject.tp_finalize` should not mutate the current exception status; |
Antoine Pitrou | 796564c | 2013-07-30 19:59:21 +0200 | [diff] [blame] | 990 | therefore, a recommended way to write a non-trivial finalizer is:: |
| 991 | |
| 992 | static void |
| 993 | local_finalize(PyObject *self) |
| 994 | { |
| 995 | PyObject *error_type, *error_value, *error_traceback; |
| 996 | |
| 997 | /* Save the current exception, if any. */ |
| 998 | PyErr_Fetch(&error_type, &error_value, &error_traceback); |
| 999 | |
| 1000 | /* ... */ |
| 1001 | |
| 1002 | /* Restore the saved exception. */ |
| 1003 | PyErr_Restore(error_type, error_value, error_traceback); |
| 1004 | } |
| 1005 | |
| 1006 | For this field to be taken into account (even through inheritance), |
| 1007 | you must also set the :const:`Py_TPFLAGS_HAVE_FINALIZE` flags bit. |
| 1008 | |
| 1009 | This field is inherited by subtypes. |
| 1010 | |
| 1011 | .. versionadded:: 3.4 |
| 1012 | |
| 1013 | .. seealso:: "Safe object finalization" (:pep:`442`) |
| 1014 | |
| 1015 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1016 | .. c:member:: PyObject* PyTypeObject.tp_cache |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1017 | |
| 1018 | Unused. Not inherited. Internal use only. |
| 1019 | |
| 1020 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1021 | .. c:member:: PyObject* PyTypeObject.tp_subclasses |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1022 | |
| 1023 | List of weak references to subclasses. Not inherited. Internal use only. |
| 1024 | |
| 1025 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1026 | .. c:member:: PyObject* PyTypeObject.tp_weaklist |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1027 | |
| 1028 | Weak reference list head, for weak references to this type object. Not |
| 1029 | inherited. Internal use only. |
| 1030 | |
| 1031 | The remaining fields are only defined if the feature test macro |
| 1032 | :const:`COUNT_ALLOCS` is defined, and are for internal use only. They are |
| 1033 | documented here for completeness. None of these fields are inherited by |
| 1034 | subtypes. |
| 1035 | |
| 1036 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1037 | .. c:member:: Py_ssize_t PyTypeObject.tp_allocs |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1038 | |
| 1039 | Number of allocations. |
| 1040 | |
| 1041 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1042 | .. c:member:: Py_ssize_t PyTypeObject.tp_frees |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1043 | |
| 1044 | Number of frees. |
| 1045 | |
| 1046 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1047 | .. c:member:: Py_ssize_t PyTypeObject.tp_maxalloc |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1048 | |
| 1049 | Maximum simultaneously allocated objects. |
| 1050 | |
| 1051 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1052 | .. c:member:: PyTypeObject* PyTypeObject.tp_next |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1053 | |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1054 | 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] | 1055 | |
| 1056 | Also, note that, in a garbage collected Python, tp_dealloc may be called from |
| 1057 | any Python thread, not just the thread which created the object (if the object |
| 1058 | becomes part of a refcount cycle, that cycle might be collected by a garbage |
| 1059 | collection on any thread). This is not a problem for Python API calls, since |
| 1060 | the thread on which tp_dealloc is called will own the Global Interpreter Lock |
| 1061 | (GIL). However, if the object being destroyed in turn destroys objects from some |
| 1062 | other C or C++ library, care should be taken to ensure that destroying those |
| 1063 | objects on the thread which called tp_dealloc will not violate any assumptions |
| 1064 | of the library. |
| 1065 | |
| 1066 | |
| 1067 | .. _number-structs: |
| 1068 | |
| 1069 | Number Object Structures |
| 1070 | ======================== |
| 1071 | |
| 1072 | .. sectionauthor:: Amaury Forgeot d'Arc |
| 1073 | |
| 1074 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1075 | .. c:type:: PyNumberMethods |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1076 | |
| 1077 | This structure holds pointers to the functions which an object uses to |
| 1078 | implement the number protocol. Each function is used by the function of |
| 1079 | similar name documented in the :ref:`number` section. |
| 1080 | |
| 1081 | Here is the structure definition:: |
| 1082 | |
| 1083 | typedef struct { |
| 1084 | binaryfunc nb_add; |
| 1085 | binaryfunc nb_subtract; |
| 1086 | binaryfunc nb_multiply; |
| 1087 | binaryfunc nb_remainder; |
| 1088 | binaryfunc nb_divmod; |
| 1089 | ternaryfunc nb_power; |
| 1090 | unaryfunc nb_negative; |
| 1091 | unaryfunc nb_positive; |
| 1092 | unaryfunc nb_absolute; |
| 1093 | inquiry nb_bool; |
| 1094 | unaryfunc nb_invert; |
| 1095 | binaryfunc nb_lshift; |
| 1096 | binaryfunc nb_rshift; |
| 1097 | binaryfunc nb_and; |
| 1098 | binaryfunc nb_xor; |
| 1099 | binaryfunc nb_or; |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1100 | unaryfunc nb_int; |
Mark Dickinson | 8055afd | 2009-01-17 10:04:45 +0000 | [diff] [blame] | 1101 | void *nb_reserved; |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1102 | unaryfunc nb_float; |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1103 | |
| 1104 | binaryfunc nb_inplace_add; |
| 1105 | binaryfunc nb_inplace_subtract; |
| 1106 | binaryfunc nb_inplace_multiply; |
| 1107 | binaryfunc nb_inplace_remainder; |
| 1108 | ternaryfunc nb_inplace_power; |
| 1109 | binaryfunc nb_inplace_lshift; |
| 1110 | binaryfunc nb_inplace_rshift; |
| 1111 | binaryfunc nb_inplace_and; |
| 1112 | binaryfunc nb_inplace_xor; |
| 1113 | binaryfunc nb_inplace_or; |
| 1114 | |
| 1115 | binaryfunc nb_floor_divide; |
| 1116 | binaryfunc nb_true_divide; |
| 1117 | binaryfunc nb_inplace_floor_divide; |
| 1118 | binaryfunc nb_inplace_true_divide; |
| 1119 | |
| 1120 | unaryfunc nb_index; |
Benjamin Peterson | d51374e | 2014-04-09 23:55:56 -0400 | [diff] [blame] | 1121 | |
| 1122 | binaryfunc nb_matrix_multiply; |
| 1123 | binaryfunc nb_inplace_matrix_multiply; |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1124 | } PyNumberMethods; |
| 1125 | |
| 1126 | .. note:: |
| 1127 | |
| 1128 | Binary and ternary functions must check the type of all their operands, |
| 1129 | and implement the necessary conversions (at least one of the operands is |
| 1130 | an instance of the defined type). If the operation is not defined for the |
| 1131 | given operands, binary and ternary functions must return |
| 1132 | ``Py_NotImplemented``, if another error occurred they must return ``NULL`` |
| 1133 | and set an exception. |
| 1134 | |
Mark Dickinson | 8055afd | 2009-01-17 10:04:45 +0000 | [diff] [blame] | 1135 | .. note:: |
| 1136 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1137 | The :c:data:`nb_reserved` field should always be ``NULL``. It |
| 1138 | was previously called :c:data:`nb_long`, and was renamed in |
Mark Dickinson | 8055afd | 2009-01-17 10:04:45 +0000 | [diff] [blame] | 1139 | Python 3.0.1. |
| 1140 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1141 | |
| 1142 | .. _mapping-structs: |
| 1143 | |
| 1144 | Mapping Object Structures |
| 1145 | ========================= |
| 1146 | |
| 1147 | .. sectionauthor:: Amaury Forgeot d'Arc |
| 1148 | |
| 1149 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1150 | .. c:type:: PyMappingMethods |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1151 | |
| 1152 | This structure holds pointers to the functions which an object uses to |
| 1153 | implement the mapping protocol. It has three members: |
| 1154 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1155 | .. c:member:: lenfunc PyMappingMethods.mp_length |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1156 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1157 | This function is used by :c:func:`PyMapping_Length` and |
| 1158 | :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] | 1159 | *NULL* if the object has no defined length. |
| 1160 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1161 | .. c:member:: binaryfunc PyMappingMethods.mp_subscript |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1162 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1163 | This function is used by :c:func:`PyObject_GetItem` and has the same |
| 1164 | signature. This slot must be filled for the :c:func:`PyMapping_Check` |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1165 | function to return ``1``, it can be *NULL* otherwise. |
| 1166 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1167 | .. c:member:: objobjargproc PyMappingMethods.mp_ass_subscript |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1168 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1169 | This function is used by :c:func:`PyObject_SetItem` and has the same |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1170 | signature. If this slot is *NULL*, the object does not support item |
| 1171 | assignment. |
| 1172 | |
| 1173 | |
| 1174 | .. _sequence-structs: |
| 1175 | |
| 1176 | Sequence Object Structures |
| 1177 | ========================== |
| 1178 | |
| 1179 | .. sectionauthor:: Amaury Forgeot d'Arc |
| 1180 | |
| 1181 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1182 | .. c:type:: PySequenceMethods |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1183 | |
| 1184 | This structure holds pointers to the functions which an object uses to |
| 1185 | implement the sequence protocol. |
| 1186 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1187 | .. c:member:: lenfunc PySequenceMethods.sq_length |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1188 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1189 | This function is used by :c:func:`PySequence_Size` and :c:func:`PyObject_Size`, |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1190 | and has the same signature. |
| 1191 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1192 | .. c:member:: binaryfunc PySequenceMethods.sq_concat |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1193 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1194 | 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] | 1195 | signature. It is also used by the ``+`` operator, after trying the numeric |
Antoine Pitrou | 39668f5 | 2013-08-01 21:12:45 +0200 | [diff] [blame] | 1196 | addition via the :c:member:`~PyTypeObject.tp_as_number.nb_add` slot. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1197 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1198 | .. c:member:: ssizeargfunc PySequenceMethods.sq_repeat |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1199 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1200 | 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] | 1201 | signature. It is also used by the ``*`` operator, after trying numeric |
Benjamin Peterson | f0f7844 | 2014-04-08 10:44:30 -0400 | [diff] [blame] | 1202 | multiplication via the :c:member:`~PyTypeObject.tp_as_number.nb_multiply` |
| 1203 | slot. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1204 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1205 | .. c:member:: ssizeargfunc PySequenceMethods.sq_item |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1206 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1207 | This function is used by :c:func:`PySequence_GetItem` and has the same |
| 1208 | signature. This slot must be filled for the :c:func:`PySequence_Check` |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1209 | function to return ``1``, it can be *NULL* otherwise. |
| 1210 | |
| 1211 | Negative indexes are handled as follows: if the :attr:`sq_length` slot is |
| 1212 | filled, it is called and the sequence length is used to compute a positive |
| 1213 | index which is passed to :attr:`sq_item`. If :attr:`sq_length` is *NULL*, |
| 1214 | the index is passed as is to the function. |
| 1215 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1216 | .. c:member:: ssizeobjargproc PySequenceMethods.sq_ass_item |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1217 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1218 | This function is used by :c:func:`PySequence_SetItem` and has the same |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1219 | signature. This slot may be left to *NULL* if the object does not support |
| 1220 | item assignment. |
| 1221 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1222 | .. c:member:: objobjproc PySequenceMethods.sq_contains |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1223 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1224 | 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] | 1225 | signature. This slot may be left to *NULL*, in this case |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1226 | :c:func:`PySequence_Contains` simply traverses the sequence until it finds a |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1227 | match. |
| 1228 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1229 | .. c:member:: binaryfunc PySequenceMethods.sq_inplace_concat |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1230 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1231 | This function is used by :c:func:`PySequence_InPlaceConcat` and has the same |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1232 | signature. It should modify its first operand, and return it. |
| 1233 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1234 | .. c:member:: ssizeargfunc PySequenceMethods.sq_inplace_repeat |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1235 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1236 | This function is used by :c:func:`PySequence_InPlaceRepeat` and has the same |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1237 | signature. It should modify its first operand, and return it. |
| 1238 | |
| 1239 | .. XXX need to explain precedence between mapping and sequence |
| 1240 | .. XXX explains when to implement the sq_inplace_* slots |
| 1241 | |
| 1242 | |
| 1243 | .. _buffer-structs: |
| 1244 | |
| 1245 | Buffer Object Structures |
| 1246 | ======================== |
| 1247 | |
| 1248 | .. sectionauthor:: Greg J. Stein <greg@lyra.org> |
Benjamin Peterson | 9d0ced3 | 2008-09-16 02:24:31 +0000 | [diff] [blame] | 1249 | .. sectionauthor:: Benjamin Peterson |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 1250 | .. sectionauthor:: Stefan Krah |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1251 | |
Georg Brandl | 60203b4 | 2010-10-06 10:11:56 +0000 | [diff] [blame] | 1252 | .. c:type:: PyBufferProcs |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1253 | |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 1254 | This structure holds pointers to the functions required by the |
| 1255 | :ref:`Buffer protocol <bufferobjects>`. The protocol defines how |
| 1256 | an exporter object can expose its internal data to consumer objects. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1257 | |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 1258 | .. c:member:: getbufferproc PyBufferProcs.bf_getbuffer |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1259 | |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 1260 | The signature of this function is:: |
| 1261 | |
| 1262 | int (PyObject *exporter, Py_buffer *view, int flags); |
| 1263 | |
| 1264 | 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] | 1265 | Except for point (3), an implementation of this function MUST take these |
| 1266 | steps: |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 1267 | |
Stefan Krah | abd887d | 2012-03-06 14:55:06 +0100 | [diff] [blame] | 1268 | (1) Check if the request can be met. If not, raise :c:data:`PyExc_BufferError`, |
| 1269 | set :c:data:`view->obj` to *NULL* and return -1. |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 1270 | |
Stefan Krah | abd887d | 2012-03-06 14:55:06 +0100 | [diff] [blame] | 1271 | (2) Fill in the requested fields. |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 1272 | |
Stefan Krah | abd887d | 2012-03-06 14:55:06 +0100 | [diff] [blame] | 1273 | (3) Increment an internal counter for the number of exports. |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 1274 | |
Stefan Krah | abd887d | 2012-03-06 14:55:06 +0100 | [diff] [blame] | 1275 | (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] | 1276 | |
Stefan Krah | abd887d | 2012-03-06 14:55:06 +0100 | [diff] [blame] | 1277 | (5) Return 0. |
| 1278 | |
| 1279 | If *exporter* is part of a chain or tree of buffer providers, two main |
| 1280 | schemes can be used: |
| 1281 | |
| 1282 | * Re-export: Each member of the tree acts as the exporting object and |
| 1283 | sets :c:data:`view->obj` to a new reference to itself. |
| 1284 | |
| 1285 | * Redirect: The buffer request is redirected to the root object of the |
| 1286 | tree. Here, :c:data:`view->obj` will be a new reference to the root |
| 1287 | object. |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 1288 | |
| 1289 | The individual fields of *view* are described in section |
| 1290 | :ref:`Buffer structure <buffer-structure>`, the rules how an exporter |
| 1291 | must react to specific requests are in section |
| 1292 | :ref:`Buffer request types <buffer-request-types>`. |
| 1293 | |
| 1294 | All memory pointed to in the :c:type:`Py_buffer` structure belongs to |
| 1295 | the exporter and must remain valid until there are no consumers left. |
Stefan Krah | abd887d | 2012-03-06 14:55:06 +0100 | [diff] [blame] | 1296 | :c:member:`~Py_buffer.format`, :c:member:`~Py_buffer.shape`, |
| 1297 | :c:member:`~Py_buffer.strides`, :c:member:`~Py_buffer.suboffsets` |
| 1298 | and :c:member:`~Py_buffer.internal` |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 1299 | are read-only for the consumer. |
| 1300 | |
| 1301 | :c:func:`PyBuffer_FillInfo` provides an easy way of exposing a simple |
| 1302 | bytes buffer while dealing correctly with all request types. |
| 1303 | |
| 1304 | :c:func:`PyObject_GetBuffer` is the interface for the consumer that |
| 1305 | wraps this function. |
| 1306 | |
| 1307 | .. c:member:: releasebufferproc PyBufferProcs.bf_releasebuffer |
| 1308 | |
| 1309 | The signature of this function is:: |
| 1310 | |
| 1311 | void (PyObject *exporter, Py_buffer *view); |
| 1312 | |
| 1313 | 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] | 1314 | need to be released, :c:member:`PyBufferProcs.bf_releasebuffer` may be |
| 1315 | *NULL*. Otherwise, a standard implementation of this function will take |
| 1316 | these optional steps: |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 1317 | |
Stefan Krah | abd887d | 2012-03-06 14:55:06 +0100 | [diff] [blame] | 1318 | (1) Decrement an internal counter for the number of exports. |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 1319 | |
Stefan Krah | abd887d | 2012-03-06 14:55:06 +0100 | [diff] [blame] | 1320 | (2) If the counter is 0, free all memory associated with *view*. |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 1321 | |
| 1322 | 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] | 1323 | track of buffer-specific resources. This field is guaranteed to remain |
| 1324 | constant, while a consumer MAY pass a copy of the original buffer as the |
| 1325 | *view* argument. |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1326 | |
| 1327 | |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 1328 | This function MUST NOT decrement :c:data:`view->obj`, since that is |
Stefan Krah | abd887d | 2012-03-06 14:55:06 +0100 | [diff] [blame] | 1329 | done automatically in :c:func:`PyBuffer_Release` (this scheme is |
| 1330 | useful for breaking reference cycles). |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1331 | |
Georg Brandl | 54a3faa | 2008-01-20 09:30:57 +0000 | [diff] [blame] | 1332 | |
Stefan Krah | 9a2d99e | 2012-02-25 12:24:21 +0100 | [diff] [blame] | 1333 | :c:func:`PyBuffer_Release` is the interface for the consumer that |
| 1334 | wraps this function. |