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