PageRenderTime 469ms CodeModel.GetById 182ms app.highlight 149ms RepoModel.GetById 122ms app.codeStats 1ms

/Doc/c-api/typeobj.rst

http://unladen-swallow.googlecode.com/
ReStructuredText | 1445 lines | 1001 code | 444 blank | 0 comment | 0 complexity | a3332f02c96e981b0351df36b6f30844 MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1.. highlightlang:: c
   2
   3.. _type-structs:
   4
   5Type Objects
   6============
   7
   8Perhaps one of the most important structures of the Python object system is the
   9structure that defines a new type: the :ctype:`PyTypeObject` structure.  Type
  10objects can be handled using any of the :cfunc:`PyObject_\*` or
  11:cfunc:`PyType_\*` functions, but do not offer much that's interesting to most
  12Python applications. These objects are fundamental to how objects behave, so
  13they are very important to the interpreter itself and to any extension module
  14that implements new types.
  15
  16Type objects are fairly large compared to most of the standard types. The reason
  17for the size is that each type object stores a large number of values, mostly C
  18function pointers, each of which implements a small part of the type's
  19functionality.  The fields of the type object are examined in detail in this
  20section.  The fields will be described in the order in which they occur in the
  21structure.
  22
  23Typedefs: unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
  24intintargfunc, intobjargproc, intintobjargproc, objobjargproc, destructor,
  25freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc,
  26cmpfunc, reprfunc, hashfunc
  27
  28The structure definition for :ctype:`PyTypeObject` can be found in
  29:file:`Include/object.h`.  For convenience of reference, this repeats the
  30definition found there:
  31
  32.. literalinclude:: ../includes/typestruct.h
  33
  34
  35The type object structure extends the :ctype:`PyVarObject` structure. The
  36:attr:`ob_size` field is used for dynamic types (created by  :func:`type_new`,
  37usually called from a class statement). Note that :cdata:`PyType_Type` (the
  38metatype) initializes :attr:`tp_itemsize`, which means that its instances (i.e.
  39type objects) *must* have the :attr:`ob_size` field.
  40
  41
  42.. cmember:: PyObject* PyObject._ob_next
  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
  57.. cmember:: Py_ssize_t PyObject.ob_refcnt
  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   .. versionchanged:: 2.5
  68      This field used to be an :ctype:`int` type. This might require changes
  69      in your code for properly supporting 64-bit systems.
  70
  71
  72.. cmember:: PyTypeObject* PyObject.ob_type
  73
  74   This is the type's type, in other words its metatype.  It is initialized by the
  75   argument to the ``PyObject_HEAD_INIT`` macro, and its value should normally be
  76   ``&PyType_Type``.  However, for dynamically loadable extension modules that must
  77   be usable on Windows (at least), the compiler complains that this is not a valid
  78   initializer.  Therefore, the convention is to pass *NULL* to the
  79   ``PyObject_HEAD_INIT`` macro and to initialize this field explicitly at the
  80   start of the module's initialization function, before doing anything else.  This
  81   is typically done like this::
  82
  83      Foo_Type.ob_type = &PyType_Type;
  84
  85   This should be done before any instances of the type are created.
  86   :cfunc:`PyType_Ready` checks if :attr:`ob_type` is *NULL*, and if so,
  87   initializes it: in Python 2.2, it is set to ``&PyType_Type``; in Python 2.2.1
  88   and later it is initialized to the :attr:`ob_type` field of the base class.
  89   :cfunc:`PyType_Ready` will not change this field if it is non-zero.
  90
  91   In Python 2.2, this field is not inherited by subtypes.  In 2.2.1, and in 2.3
  92   and beyond, it is inherited by subtypes.
  93
  94
  95.. cmember:: Py_ssize_t PyVarObject.ob_size
  96
  97   For statically allocated type objects, this should be initialized to zero.  For
  98   dynamically allocated type objects, this field has a special internal meaning.
  99
 100   This field is not inherited by subtypes.
 101
 102
 103.. cmember:: char* PyTypeObject.tp_name
 104
 105   Pointer to a NUL-terminated string containing the name of the type. For types
 106   that are accessible as module globals, the string should be the full module
 107   name, followed by a dot, followed by the type name; for built-in types, it
 108   should be just the type name.  If the module is a submodule of a package, the
 109   full package name is part of the full module name.  For example, a type named
 110   :class:`T` defined in module :mod:`M` in subpackage :mod:`Q` in package :mod:`P`
 111   should have the :attr:`tp_name` initializer ``"P.Q.M.T"``.
 112
 113   For dynamically allocated type objects, this should just be the type name, and
 114   the module name explicitly stored in the type dict as the value for key
 115   ``'__module__'``.
 116
 117   For statically allocated type objects, the tp_name field should contain a dot.
 118   Everything before the last dot is made accessible as the :attr:`__module__`
 119   attribute, and everything after the last dot is made accessible as the
 120   :attr:`__name__` attribute.
 121
 122   If no dot is present, the entire :attr:`tp_name` field is made accessible as the
 123   :attr:`__name__` attribute, and the :attr:`__module__` attribute is undefined
 124   (unless explicitly set in the dictionary, as explained above).  This means your
 125   type will be impossible to pickle.
 126
 127   This field is not inherited by subtypes.
 128
 129
 130.. cmember:: Py_ssize_t PyTypeObject.tp_basicsize
 131             Py_ssize_t PyTypeObject.tp_itemsize
 132
 133   These fields allow calculating the size in bytes of instances of the type.
 134
 135   There are two kinds of types: types with fixed-length instances have a zero
 136   :attr:`tp_itemsize` field, types with variable-length instances have a non-zero
 137   :attr:`tp_itemsize` field.  For a type with fixed-length instances, all
 138   instances have the same size, given in :attr:`tp_basicsize`.
 139
 140   For a type with variable-length instances, the instances must have an
 141   :attr:`ob_size` field, and the instance size is :attr:`tp_basicsize` plus N
 142   times :attr:`tp_itemsize`, where N is the "length" of the object.  The value of
 143   N is typically stored in the instance's :attr:`ob_size` field.  There are
 144   exceptions:  for example, long ints use a negative :attr:`ob_size` to indicate a
 145   negative number, and N is ``abs(ob_size)`` there.  Also, the presence of an
 146   :attr:`ob_size` field in the instance layout doesn't mean that the instance
 147   structure is variable-length (for example, the structure for the list type has
 148   fixed-length instances, yet those instances have a meaningful :attr:`ob_size`
 149   field).
 150
 151   The basic size includes the fields in the instance declared by the macro
 152   :cmacro:`PyObject_HEAD` or :cmacro:`PyObject_VAR_HEAD` (whichever is used to
 153   declare the instance struct) and this in turn includes the :attr:`_ob_prev` and
 154   :attr:`_ob_next` fields if they are present.  This means that the only correct
 155   way to get an initializer for the :attr:`tp_basicsize` is to use the
 156   ``sizeof`` operator on the struct used to declare the instance layout.
 157   The basic size does not include the GC header size (this is new in Python 2.2;
 158   in 2.1 and 2.0, the GC header size was included in :attr:`tp_basicsize`).
 159
 160   These fields are inherited separately by subtypes.  If the base type has a
 161   non-zero :attr:`tp_itemsize`, it is generally not safe to set
 162   :attr:`tp_itemsize` to a different non-zero value in a subtype (though this
 163   depends on the implementation of the base type).
 164
 165   A note about alignment: if the variable items require a particular alignment,
 166   this should be taken care of by the value of :attr:`tp_basicsize`.  Example:
 167   suppose a type implements an array of ``double``. :attr:`tp_itemsize` is
 168   ``sizeof(double)``. It is the programmer's responsibility that
 169   :attr:`tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the
 170   alignment requirement for ``double``).
 171
 172
 173.. cmember:: destructor PyTypeObject.tp_dealloc
 174
 175   A pointer to the instance destructor function.  This function must be defined
 176   unless the type guarantees that its instances will never be deallocated (as is
 177   the case for the singletons ``None`` and ``Ellipsis``).
 178
 179   The destructor function is called by the :cfunc:`Py_DECREF` and
 180   :cfunc:`Py_XDECREF` macros when the new reference count is zero.  At this point,
 181   the instance is still in existence, but there are no references to it.  The
 182   destructor function should free all references which the instance owns, free all
 183   memory buffers owned by the instance (using the freeing function corresponding
 184   to the allocation function used to allocate the buffer), and finally (as its
 185   last action) call the type's :attr:`tp_free` function.  If the type is not
 186   subtypable (doesn't have the :const:`Py_TPFLAGS_BASETYPE` flag bit set), it is
 187   permissible to call the object deallocator directly instead of via
 188   :attr:`tp_free`.  The object deallocator should be the one used to allocate the
 189   instance; this is normally :cfunc:`PyObject_Del` if the instance was allocated
 190   using :cfunc:`PyObject_New` or :cfunc:`PyObject_VarNew`, or
 191   :cfunc:`PyObject_GC_Del` if the instance was allocated using
 192   :cfunc:`PyObject_GC_New` or :cfunc:`PyObject_GC_VarNew`.
 193
 194   This field is inherited by subtypes.
 195
 196
 197.. cmember:: printfunc PyTypeObject.tp_print
 198
 199   An optional pointer to the instance print function.
 200
 201   The print function is only called when the instance is printed to a *real* file;
 202   when it is printed to a pseudo-file (like a :class:`StringIO` instance), the
 203   instance's :attr:`tp_repr` or :attr:`tp_str` function is called to convert it to
 204   a string.  These are also called when the type's :attr:`tp_print` field is
 205   *NULL*.  A type should never implement :attr:`tp_print` in a way that produces
 206   different output than :attr:`tp_repr` or :attr:`tp_str` would.
 207
 208   The print function is called with the same signature as :cfunc:`PyObject_Print`:
 209   ``int tp_print(PyObject *self, FILE *file, int flags)``.  The *self* argument is
 210   the instance to be printed.  The *file* argument is the stdio file to which it
 211   is to be printed.  The *flags* argument is composed of flag bits. The only flag
 212   bit currently defined is :const:`Py_PRINT_RAW`. When the :const:`Py_PRINT_RAW`
 213   flag bit is set, the instance should be printed the same way as :attr:`tp_str`
 214   would format it; when the :const:`Py_PRINT_RAW` flag bit is clear, the instance
 215   should be printed the same was as :attr:`tp_repr` would format it. It should
 216   return ``-1`` and set an exception condition when an error occurred during the
 217   comparison.
 218
 219   It is possible that the :attr:`tp_print` field will be deprecated. In any case,
 220   it is recommended not to define :attr:`tp_print`, but instead to rely on
 221   :attr:`tp_repr` and :attr:`tp_str` for printing.
 222
 223   This field is inherited by subtypes.
 224
 225
 226.. cmember:: getattrfunc PyTypeObject.tp_getattr
 227
 228   An optional pointer to the get-attribute-string function.
 229
 230   This field is deprecated.  When it is defined, it should point to a function
 231   that acts the same as the :attr:`tp_getattro` function, but taking a C string
 232   instead of a Python string object to give the attribute name.  The signature is
 233   the same as for :cfunc:`PyObject_GetAttrString`.
 234
 235   This field is inherited by subtypes together with :attr:`tp_getattro`: a subtype
 236   inherits both :attr:`tp_getattr` and :attr:`tp_getattro` from its base type when
 237   the subtype's :attr:`tp_getattr` and :attr:`tp_getattro` are both *NULL*.
 238
 239
 240.. cmember:: setattrfunc PyTypeObject.tp_setattr
 241
 242   An optional pointer to the set-attribute-string function.
 243
 244   This field is deprecated.  When it is defined, it should point to a function
 245   that acts the same as the :attr:`tp_setattro` function, but taking a C string
 246   instead of a Python string object to give the attribute name.  The signature is
 247   the same as for :cfunc:`PyObject_SetAttrString`.
 248
 249   This field is inherited by subtypes together with :attr:`tp_setattro`: a subtype
 250   inherits both :attr:`tp_setattr` and :attr:`tp_setattro` from its base type when
 251   the subtype's :attr:`tp_setattr` and :attr:`tp_setattro` are both *NULL*.
 252
 253
 254.. cmember:: cmpfunc PyTypeObject.tp_compare
 255
 256   An optional pointer to the three-way comparison function.
 257
 258   The signature is the same as for :cfunc:`PyObject_Compare`. The function should
 259   return ``1`` if *self* greater than *other*, ``0`` if *self* is equal to
 260   *other*, and ``-1`` if *self* less than *other*.  It should return ``-1`` and
 261   set an exception condition when an error occurred during the comparison.
 262
 263   This field is inherited by subtypes together with :attr:`tp_richcompare` and
 264   :attr:`tp_hash`: a subtypes inherits all three of :attr:`tp_compare`,
 265   :attr:`tp_richcompare`, and :attr:`tp_hash` when the subtype's
 266   :attr:`tp_compare`, :attr:`tp_richcompare`, and :attr:`tp_hash` are all *NULL*.
 267
 268
 269.. cmember:: reprfunc PyTypeObject.tp_repr
 270
 271   .. index:: builtin: repr
 272
 273   An optional pointer to a function that implements the built-in function
 274   :func:`repr`.
 275
 276   The signature is the same as for :cfunc:`PyObject_Repr`; it must return a string
 277   or a Unicode object.  Ideally, this function should return a string that, when
 278   passed to :func:`eval`, given a suitable environment, returns an object with the
 279   same value.  If this is not feasible, it should return a string starting with
 280   ``'<'`` and ending with ``'>'`` from which both the type and the value of the
 281   object can be deduced.
 282
 283   When this field is not set, a string of the form ``<%s object at %p>`` is
 284   returned, where ``%s`` is replaced by the type name, and ``%p`` by the object's
 285   memory address.
 286
 287   This field is inherited by subtypes.
 288
 289.. cmember:: PyNumberMethods* tp_as_number
 290
 291   Pointer to an additional structure that contains fields relevant only to
 292   objects which implement the number protocol.  These fields are documented in
 293   :ref:`number-structs`.
 294
 295   The :attr:`tp_as_number` field is not inherited, but the contained fields are
 296   inherited individually.
 297
 298
 299.. cmember:: PySequenceMethods* tp_as_sequence
 300
 301   Pointer to an additional structure that contains fields relevant only to
 302   objects which implement the sequence protocol.  These fields are documented
 303   in :ref:`sequence-structs`.
 304
 305   The :attr:`tp_as_sequence` field is not inherited, but the contained fields
 306   are inherited individually.
 307
 308
 309.. cmember:: PyMappingMethods* tp_as_mapping
 310
 311   Pointer to an additional structure that contains fields relevant only to
 312   objects which implement the mapping protocol.  These fields are documented in
 313   :ref:`mapping-structs`.
 314
 315   The :attr:`tp_as_mapping` field is not inherited, but the contained fields
 316   are inherited individually.
 317
 318
 319.. cmember:: hashfunc PyTypeObject.tp_hash
 320
 321   .. index:: builtin: hash
 322
 323   An optional pointer to a function that implements the built-in function
 324   :func:`hash`.
 325
 326   The signature is the same as for :cfunc:`PyObject_Hash`; it must return a C
 327   long.  The value ``-1`` should not be returned as a normal return value; when an
 328   error occurs during the computation of the hash value, the function should set
 329   an exception and return ``-1``.
 330
 331   This field can be set explicitly to :cfunc:`PyObject_HashNotImplemented` to
 332   block inheritance of the hash method from a parent type. This is interpreted
 333   as the equivalent of ``__hash__ = None`` at the Python level, causing
 334   ``isinstance(o, collections.Hashable)`` to correctly return ``False``. Note
 335   that the converse is also true - setting ``__hash__ = None`` on a class at
 336   the Python level will result in the ``tp_hash`` slot being set to
 337   :cfunc:`PyObject_HashNotImplemented`.
 338
 339   When this field is not set, two possibilities exist: if the :attr:`tp_compare`
 340   and :attr:`tp_richcompare` fields are both *NULL*, a default hash value based on
 341   the object's address is returned; otherwise, a :exc:`TypeError` is raised.
 342
 343   This field is inherited by subtypes together with :attr:`tp_richcompare` and
 344   :attr:`tp_compare`: a subtypes inherits all three of :attr:`tp_compare`,
 345   :attr:`tp_richcompare`, and :attr:`tp_hash`, when the subtype's
 346   :attr:`tp_compare`, :attr:`tp_richcompare` and :attr:`tp_hash` are all *NULL*.
 347
 348
 349.. cmember:: ternaryfunc PyTypeObject.tp_call
 350
 351   An optional pointer to a function that implements calling the object.  This
 352   should be *NULL* if the object is not callable.  The signature is the same as
 353   for :cfunc:`PyObject_Call`.
 354
 355   This field is inherited by subtypes.
 356
 357
 358.. cmember:: reprfunc PyTypeObject.tp_str
 359
 360   An optional pointer to a function that implements the built-in operation
 361   :func:`str`.  (Note that :class:`str` is a type now, and :func:`str` calls the
 362   constructor for that type.  This constructor calls :cfunc:`PyObject_Str` to do
 363   the actual work, and :cfunc:`PyObject_Str` will call this handler.)
 364
 365   The signature is the same as for :cfunc:`PyObject_Str`; it must return a string
 366   or a Unicode object.  This function should return a "friendly" string
 367   representation of the object, as this is the representation that will be used by
 368   the print statement.
 369
 370   When this field is not set, :cfunc:`PyObject_Repr` is called to return a string
 371   representation.
 372
 373   This field is inherited by subtypes.
 374
 375
 376.. cmember:: getattrofunc PyTypeObject.tp_getattro
 377
 378   An optional pointer to the get-attribute function.
 379
 380   The signature is the same as for :cfunc:`PyObject_GetAttr`.  It is usually
 381   convenient to set this field to :cfunc:`PyObject_GenericGetAttr`, which
 382   implements the normal way of looking for object attributes.
 383
 384   This field is inherited by subtypes together with :attr:`tp_getattr`: a subtype
 385   inherits both :attr:`tp_getattr` and :attr:`tp_getattro` from its base type when
 386   the subtype's :attr:`tp_getattr` and :attr:`tp_getattro` are both *NULL*.
 387
 388
 389.. cmember:: setattrofunc PyTypeObject.tp_setattro
 390
 391   An optional pointer to the set-attribute function.
 392
 393   The signature is the same as for :cfunc:`PyObject_SetAttr`.  It is usually
 394   convenient to set this field to :cfunc:`PyObject_GenericSetAttr`, which
 395   implements the normal way of setting object attributes.
 396
 397   This field is inherited by subtypes together with :attr:`tp_setattr`: a subtype
 398   inherits both :attr:`tp_setattr` and :attr:`tp_setattro` from its base type when
 399   the subtype's :attr:`tp_setattr` and :attr:`tp_setattro` are both *NULL*.
 400
 401
 402.. cmember:: PyBufferProcs* PyTypeObject.tp_as_buffer
 403
 404   Pointer to an additional structure that contains fields relevant only to objects
 405   which implement the buffer interface.  These fields are documented in
 406   :ref:`buffer-structs`.
 407
 408   The :attr:`tp_as_buffer` field is not inherited, but the contained fields are
 409   inherited individually.
 410
 411
 412.. cmember:: long PyTypeObject.tp_flags
 413
 414   This field is a bit mask of various flags.  Some flags indicate variant
 415   semantics for certain situations; others are used to indicate that certain
 416   fields in the type object (or in the extension structures referenced via
 417   :attr:`tp_as_number`, :attr:`tp_as_sequence`, :attr:`tp_as_mapping`, and
 418   :attr:`tp_as_buffer`) that were historically not always present are valid; if
 419   such a flag bit is clear, the type fields it guards must not be accessed and
 420   must be considered to have a zero or *NULL* value instead.
 421
 422   Inheritance of this field is complicated.  Most flag bits are inherited
 423   individually, i.e. if the base type has a flag bit set, the subtype inherits
 424   this flag bit.  The flag bits that pertain to extension structures are strictly
 425   inherited if the extension structure is inherited, i.e. the base type's value of
 426   the flag bit is copied into the subtype together with a pointer to the extension
 427   structure.  The :const:`Py_TPFLAGS_HAVE_GC` flag bit is inherited together with
 428   the :attr:`tp_traverse` and :attr:`tp_clear` fields, i.e. if the
 429   :const:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the
 430   :attr:`tp_traverse` and :attr:`tp_clear` fields in the subtype exist (as
 431   indicated by the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit) and have *NULL*
 432   values.
 433
 434   The following bit masks are currently defined; these can be ORed together using
 435   the ``|`` operator to form the value of the :attr:`tp_flags` field.  The macro
 436   :cfunc:`PyType_HasFeature` takes a type and a flags value, *tp* and *f*, and
 437   checks whether ``tp->tp_flags & f`` is non-zero.
 438
 439
 440   .. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER
 441
 442      If this bit is set, the :ctype:`PyBufferProcs` struct referenced by
 443      :attr:`tp_as_buffer` has the :attr:`bf_getcharbuffer` field.
 444
 445
 446   .. data:: Py_TPFLAGS_HAVE_SEQUENCE_IN
 447
 448      If this bit is set, the :ctype:`PySequenceMethods` struct referenced by
 449      :attr:`tp_as_sequence` has the :attr:`sq_contains` field.
 450
 451
 452   .. data:: Py_TPFLAGS_GC
 453
 454      This bit is obsolete.  The bit it used to name is no longer in use.  The symbol
 455      is now defined as zero.
 456
 457
 458   .. data:: Py_TPFLAGS_HAVE_INPLACEOPS
 459
 460      If this bit is set, the :ctype:`PySequenceMethods` struct referenced by
 461      :attr:`tp_as_sequence` and the :ctype:`PyNumberMethods` structure referenced by
 462      :attr:`tp_as_number` contain the fields for in-place operators. In particular,
 463      this means that the :ctype:`PyNumberMethods` structure has the fields
 464      :attr:`nb_inplace_add`, :attr:`nb_inplace_subtract`,
 465      :attr:`nb_inplace_multiply`, :attr:`nb_inplace_divide`,
 466      :attr:`nb_inplace_remainder`, :attr:`nb_inplace_power`,
 467      :attr:`nb_inplace_lshift`, :attr:`nb_inplace_rshift`, :attr:`nb_inplace_and`,
 468      :attr:`nb_inplace_xor`, and :attr:`nb_inplace_or`; and the
 469      :ctype:`PySequenceMethods` struct has the fields :attr:`sq_inplace_concat` and
 470      :attr:`sq_inplace_repeat`.
 471
 472
 473   .. data:: Py_TPFLAGS_CHECKTYPES
 474
 475      If this bit is set, the binary and ternary operations in the
 476      :ctype:`PyNumberMethods` structure referenced by :attr:`tp_as_number` accept
 477      arguments of arbitrary object types, and do their own type conversions if
 478      needed.  If this bit is clear, those operations require that all arguments have
 479      the current type as their type, and the caller is supposed to perform a coercion
 480      operation first.  This applies to :attr:`nb_add`, :attr:`nb_subtract`,
 481      :attr:`nb_multiply`, :attr:`nb_divide`, :attr:`nb_remainder`, :attr:`nb_divmod`,
 482      :attr:`nb_power`, :attr:`nb_lshift`, :attr:`nb_rshift`, :attr:`nb_and`,
 483      :attr:`nb_xor`, and :attr:`nb_or`.
 484
 485
 486   .. data:: Py_TPFLAGS_HAVE_RICHCOMPARE
 487
 488      If this bit is set, the type object has the :attr:`tp_richcompare` field, as
 489      well as the :attr:`tp_traverse` and the :attr:`tp_clear` fields.
 490
 491
 492   .. data:: Py_TPFLAGS_HAVE_WEAKREFS
 493
 494      If this bit is set, the :attr:`tp_weaklistoffset` field is defined.  Instances
 495      of a type are weakly referenceable if the type's :attr:`tp_weaklistoffset` field
 496      has a value greater than zero.
 497
 498
 499   .. data:: Py_TPFLAGS_HAVE_ITER
 500
 501      If this bit is set, the type object has the :attr:`tp_iter` and
 502      :attr:`tp_iternext` fields.
 503
 504
 505   .. data:: Py_TPFLAGS_HAVE_CLASS
 506
 507      If this bit is set, the type object has several new fields defined starting in
 508      Python 2.2: :attr:`tp_methods`, :attr:`tp_members`, :attr:`tp_getset`,
 509      :attr:`tp_base`, :attr:`tp_dict`, :attr:`tp_descr_get`, :attr:`tp_descr_set`,
 510      :attr:`tp_dictoffset`, :attr:`tp_init`, :attr:`tp_alloc`, :attr:`tp_new`,
 511      :attr:`tp_free`, :attr:`tp_is_gc`, :attr:`tp_bases`, :attr:`tp_mro`,
 512      :attr:`tp_cache`, :attr:`tp_subclasses`, and :attr:`tp_weaklist`.
 513
 514
 515   .. data:: Py_TPFLAGS_HEAPTYPE
 516
 517      This bit is set when the type object itself is allocated on the heap.  In this
 518      case, the :attr:`ob_type` field of its instances is considered a reference to
 519      the type, and the type object is INCREF'ed when a new instance is created, and
 520      DECREF'ed when an instance is destroyed (this does not apply to instances of
 521      subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or
 522      DECREF'ed).
 523
 524
 525   .. data:: Py_TPFLAGS_BASETYPE
 526
 527      This bit is set when the type can be used as the base type of another type.  If
 528      this bit is clear, the type cannot be subtyped (similar to a "final" class in
 529      Java).
 530
 531
 532   .. data:: Py_TPFLAGS_READY
 533
 534      This bit is set when the type object has been fully initialized by
 535      :cfunc:`PyType_Ready`.
 536
 537
 538   .. data:: Py_TPFLAGS_READYING
 539
 540      This bit is set while :cfunc:`PyType_Ready` is in the process of initializing
 541      the type object.
 542
 543
 544   .. data:: Py_TPFLAGS_HAVE_GC
 545
 546      This bit is set when the object supports garbage collection.  If this bit
 547      is set, instances must be created using :cfunc:`PyObject_GC_New` and
 548      destroyed using :cfunc:`PyObject_GC_Del`.  More information in section
 549      :ref:`supporting-cycle-detection`.  This bit also implies that the
 550      GC-related fields :attr:`tp_traverse` and :attr:`tp_clear` are present in
 551      the type object; but those fields also exist when
 552      :const:`Py_TPFLAGS_HAVE_GC` is clear but
 553      :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` is set.
 554
 555
 556   .. data:: Py_TPFLAGS_DEFAULT
 557
 558      This is a bitmask of all the bits that pertain to the existence of certain
 559      fields in the type object and its extension structures. Currently, it includes
 560      the following bits: :const:`Py_TPFLAGS_HAVE_GETCHARBUFFER`,
 561      :const:`Py_TPFLAGS_HAVE_SEQUENCE_IN`, :const:`Py_TPFLAGS_HAVE_INPLACEOPS`,
 562      :const:`Py_TPFLAGS_HAVE_RICHCOMPARE`, :const:`Py_TPFLAGS_HAVE_WEAKREFS`,
 563      :const:`Py_TPFLAGS_HAVE_ITER`, and :const:`Py_TPFLAGS_HAVE_CLASS`.
 564
 565
 566.. cmember:: char* PyTypeObject.tp_doc
 567
 568   An optional pointer to a NUL-terminated C string giving the docstring for this
 569   type object.  This is exposed as the :attr:`__doc__` attribute on the type and
 570   instances of the type.
 571
 572   This field is *not* inherited by subtypes.
 573
 574The following three fields only exist if the
 575:const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit is set.
 576
 577
 578.. cmember:: traverseproc PyTypeObject.tp_traverse
 579
 580   An optional pointer to a traversal function for the garbage collector.  This is
 581   only used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set.  More information
 582   about Python's garbage collection scheme can be found in section
 583   :ref:`supporting-cycle-detection`.
 584
 585   The :attr:`tp_traverse` pointer is used by the garbage collector to detect
 586   reference cycles. A typical implementation of a :attr:`tp_traverse` function
 587   simply calls :cfunc:`Py_VISIT` on each of the instance's members that are Python
 588   objects.  For example, this is function :cfunc:`local_traverse` from the
 589   :mod:`thread` extension module::
 590
 591      static int
 592      local_traverse(localobject *self, visitproc visit, void *arg)
 593      {
 594          Py_VISIT(self->args);
 595          Py_VISIT(self->kw);
 596          Py_VISIT(self->dict);
 597          return 0;
 598      }
 599
 600   Note that :cfunc:`Py_VISIT` is called only on those members that can participate
 601   in reference cycles.  Although there is also a ``self->key`` member, it can only
 602   be *NULL* or a Python string and therefore cannot be part of a reference cycle.
 603
 604   On the other hand, even if you know a member can never be part of a cycle, as a
 605   debugging aid you may want to visit it anyway just so the :mod:`gc` module's
 606   :func:`get_referents` function will include it.
 607
 608   Note that :cfunc:`Py_VISIT` requires the *visit* and *arg* parameters to
 609   :cfunc:`local_traverse` to have these specific names; don't name them just
 610   anything.
 611
 612   This field is inherited by subtypes together with :attr:`tp_clear` and the
 613   :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and
 614   :attr:`tp_clear` are all inherited from the base type if they are all zero in
 615   the subtype *and* the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag
 616   bit set.
 617
 618
 619.. cmember:: inquiry PyTypeObject.tp_clear
 620
 621   An optional pointer to a clear function for the garbage collector. This is only
 622   used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set.
 623
 624   The :attr:`tp_clear` member function is used to break reference cycles in cyclic
 625   garbage detected by the garbage collector.  Taken together, all :attr:`tp_clear`
 626   functions in the system must combine to break all reference cycles.  This is
 627   subtle, and if in any doubt supply a :attr:`tp_clear` function.  For example,
 628   the tuple type does not implement a :attr:`tp_clear` function, because it's
 629   possible to prove that no reference cycle can be composed entirely of tuples.
 630   Therefore the :attr:`tp_clear` functions of other types must be sufficient to
 631   break any cycle containing a tuple.  This isn't immediately obvious, and there's
 632   rarely a good reason to avoid implementing :attr:`tp_clear`.
 633
 634   Implementations of :attr:`tp_clear` should drop the instance's references to
 635   those of its members that may be Python objects, and set its pointers to those
 636   members to *NULL*, as in the following example::
 637
 638      static int
 639      local_clear(localobject *self)
 640      {
 641          Py_CLEAR(self->key);
 642          Py_CLEAR(self->args);
 643          Py_CLEAR(self->kw);
 644          Py_CLEAR(self->dict);
 645          return 0;
 646      }
 647
 648   The :cfunc:`Py_CLEAR` macro should be used, because clearing references is
 649   delicate:  the reference to the contained object must not be decremented until
 650   after the pointer to the contained object is set to *NULL*.  This is because
 651   decrementing the reference count may cause the contained object to become trash,
 652   triggering a chain of reclamation activity that may include invoking arbitrary
 653   Python code (due to finalizers, or weakref callbacks, associated with the
 654   contained object). If it's possible for such code to reference *self* again,
 655   it's important that the pointer to the contained object be *NULL* at that time,
 656   so that *self* knows the contained object can no longer be used.  The
 657   :cfunc:`Py_CLEAR` macro performs the operations in a safe order.
 658
 659   Because the goal of :attr:`tp_clear` functions is to break reference cycles,
 660   it's not necessary to clear contained objects like Python strings or Python
 661   integers, which can't participate in reference cycles. On the other hand, it may
 662   be convenient to clear all contained Python objects, and write the type's
 663   :attr:`tp_dealloc` function to invoke :attr:`tp_clear`.
 664
 665   More information about Python's garbage collection scheme can be found in
 666   section :ref:`supporting-cycle-detection`.
 667
 668   This field is inherited by subtypes together with :attr:`tp_traverse` and the
 669   :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and
 670   :attr:`tp_clear` are all inherited from the base type if they are all zero in
 671   the subtype *and* the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag
 672   bit set.
 673
 674
 675.. cmember:: richcmpfunc PyTypeObject.tp_richcompare
 676
 677   An optional pointer to the rich comparison function, whose signature is
 678   ``PyObject *tp_richcompare(PyObject *a, PyObject *b, int op)``.
 679
 680   The function should return the result of the comparison (usually ``Py_True``
 681   or ``Py_False``).  If the comparison is undefined, it must return
 682   ``Py_NotImplemented``, if another error occurred it must return ``NULL`` and
 683   set an exception condition.
 684
 685   .. note::
 686
 687      If you want to implement a type for which only a limited set of
 688      comparisons makes sense (e.g. ``==`` and ``!=``, but not ``<`` and
 689      friends), directly raise :exc:`TypeError` in the rich comparison function.
 690
 691   This field is inherited by subtypes together with :attr:`tp_compare` and
 692   :attr:`tp_hash`: a subtype inherits all three of :attr:`tp_compare`,
 693   :attr:`tp_richcompare`, and :attr:`tp_hash`, when the subtype's
 694   :attr:`tp_compare`, :attr:`tp_richcompare`, and :attr:`tp_hash` are all *NULL*.
 695
 696   The following constants are defined to be used as the third argument for
 697   :attr:`tp_richcompare` and for :cfunc:`PyObject_RichCompare`:
 698
 699   +----------------+------------+
 700   | Constant       | Comparison |
 701   +================+============+
 702   | :const:`Py_LT` | ``<``      |
 703   +----------------+------------+
 704   | :const:`Py_LE` | ``<=``     |
 705   +----------------+------------+
 706   | :const:`Py_EQ` | ``==``     |
 707   +----------------+------------+
 708   | :const:`Py_NE` | ``!=``     |
 709   +----------------+------------+
 710   | :const:`Py_GT` | ``>``      |
 711   +----------------+------------+
 712   | :const:`Py_GE` | ``>=``     |
 713   +----------------+------------+
 714
 715
 716The next field only exists if the :const:`Py_TPFLAGS_HAVE_WEAKREFS` flag bit is
 717set.
 718
 719.. cmember:: long PyTypeObject.tp_weaklistoffset
 720
 721   If the instances of this type are weakly referenceable, this field is greater
 722   than zero and contains the offset in the instance structure of the weak
 723   reference list head (ignoring the GC header, if present); this offset is used by
 724   :cfunc:`PyObject_ClearWeakRefs` and the :cfunc:`PyWeakref_\*` functions.  The
 725   instance structure needs to include a field of type :ctype:`PyObject\*` which is
 726   initialized to *NULL*.
 727
 728   Do not confuse this field with :attr:`tp_weaklist`; that is the list head for
 729   weak references to the type object itself.
 730
 731   This field is inherited by subtypes, but see the rules listed below. A subtype
 732   may override this offset; this means that the subtype uses a different weak
 733   reference list head than the base type.  Since the list head is always found via
 734   :attr:`tp_weaklistoffset`, this should not be a problem.
 735
 736   When a type defined by a class statement has no :attr:`__slots__` declaration,
 737   and none of its base types are weakly referenceable, the type is made weakly
 738   referenceable by adding a weak reference list head slot to the instance layout
 739   and setting the :attr:`tp_weaklistoffset` of that slot's offset.
 740
 741   When a type's :attr:`__slots__` declaration contains a slot named
 742   :attr:`__weakref__`, that slot becomes the weak reference list head for
 743   instances of the type, and the slot's offset is stored in the type's
 744   :attr:`tp_weaklistoffset`.
 745
 746   When a type's :attr:`__slots__` declaration does not contain a slot named
 747   :attr:`__weakref__`, the type inherits its :attr:`tp_weaklistoffset` from its
 748   base type.
 749
 750The next two fields only exist if the :const:`Py_TPFLAGS_HAVE_ITER` flag bit is
 751set.
 752
 753
 754.. cmember:: getiterfunc PyTypeObject.tp_iter
 755
 756   An optional pointer to a function that returns an iterator for the object.  Its
 757   presence normally signals that the instances of this type are iterable (although
 758   sequences may be iterable without this function, and classic instances always
 759   have this function, even if they don't define an :meth:`__iter__` method).
 760
 761   This function has the same signature as :cfunc:`PyObject_GetIter`.
 762
 763   This field is inherited by subtypes.
 764
 765
 766.. cmember:: iternextfunc PyTypeObject.tp_iternext
 767
 768   An optional pointer to a function that returns the next item in an iterator.
 769   When the iterator is exhausted, it must return *NULL*; a :exc:`StopIteration`
 770   exception may or may not be set.  When another error occurs, it must return
 771   *NULL* too.  Its presence normally signals that the instances of this type
 772   are iterators (although classic instances always have this function, even if
 773   they don't define a :meth:`next` method).
 774
 775   Iterator types should also define the :attr:`tp_iter` function, and that
 776   function should return the iterator instance itself (not a new iterator
 777   instance).
 778
 779   This function has the same signature as :cfunc:`PyIter_Next`.
 780
 781   This field is inherited by subtypes.
 782
 783The next fields, up to and including :attr:`tp_weaklist`, only exist if the
 784:const:`Py_TPFLAGS_HAVE_CLASS` flag bit is set.
 785
 786
 787.. cmember:: struct PyMethodDef* PyTypeObject.tp_methods
 788
 789   An optional pointer to a static *NULL*-terminated array of :ctype:`PyMethodDef`
 790   structures, declaring regular methods of this type.
 791
 792   For each entry in the array, an entry is added to the type's dictionary (see
 793   :attr:`tp_dict` below) containing a method descriptor.
 794
 795   This field is not inherited by subtypes (methods are inherited through a
 796   different mechanism).
 797
 798
 799.. cmember:: struct PyMemberDef* PyTypeObject.tp_members
 800
 801   An optional pointer to a static *NULL*-terminated array of :ctype:`PyMemberDef`
 802   structures, declaring regular data members (fields or slots) of instances of
 803   this type.
 804
 805   For each entry in the array, an entry is added to the type's dictionary (see
 806   :attr:`tp_dict` below) containing a member descriptor.
 807
 808   This field is not inherited by subtypes (members are inherited through a
 809   different mechanism).
 810
 811
 812.. cmember:: struct PyGetSetDef* PyTypeObject.tp_getset
 813
 814   An optional pointer to a static *NULL*-terminated array of :ctype:`PyGetSetDef`
 815   structures, declaring computed attributes of instances of this type.
 816
 817   For each entry in the array, an entry is added to the type's dictionary (see
 818   :attr:`tp_dict` below) containing a getset descriptor.
 819
 820   This field is not inherited by subtypes (computed attributes are inherited
 821   through a different mechanism).
 822
 823   Docs for PyGetSetDef (XXX belong elsewhere)::
 824
 825      typedef PyObject *(*getter)(PyObject *, void *);
 826      typedef int (*setter)(PyObject *, PyObject *, void *);
 827
 828      typedef struct PyGetSetDef {
 829          char *name;    /* attribute name */
 830          getter get;    /* C function to get the attribute */
 831          setter set;    /* C function to set the attribute */
 832          char *doc;     /* optional doc string */
 833          void *closure; /* optional additional data for getter and setter */
 834      } PyGetSetDef;
 835
 836
 837.. cmember:: PyTypeObject* PyTypeObject.tp_base
 838
 839   An optional pointer to a base type from which type properties are inherited.  At
 840   this level, only single inheritance is supported; multiple inheritance require
 841   dynamically creating a type object by calling the metatype.
 842
 843   This field is not inherited by subtypes (obviously), but it defaults to
 844   ``&PyBaseObject_Type`` (which to Python programmers is known as the type
 845   :class:`object`).
 846
 847
 848.. cmember:: PyObject* PyTypeObject.tp_dict
 849
 850   The type's dictionary is stored here by :cfunc:`PyType_Ready`.
 851
 852   This field should normally be initialized to *NULL* before PyType_Ready is
 853   called; it may also be initialized to a dictionary containing initial attributes
 854   for the type.  Once :cfunc:`PyType_Ready` has initialized the type, extra
 855   attributes for the type may be added to this dictionary only if they don't
 856   correspond to overloaded operations (like :meth:`__add__`).
 857
 858   This field is not inherited by subtypes (though the attributes defined in here
 859   are inherited through a different mechanism).
 860
 861
 862.. cmember:: descrgetfunc PyTypeObject.tp_descr_get
 863
 864   An optional pointer to a "descriptor get" function.
 865
 866   The function signature is ::
 867
 868      PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);
 869
 870   XXX explain.
 871
 872   This field is inherited by subtypes.
 873
 874
 875.. cmember:: descrsetfunc PyTypeObject.tp_descr_set
 876
 877   An optional pointer to a "descriptor set" function.
 878
 879   The function signature is ::
 880
 881      int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);
 882
 883   This field is inherited by subtypes.
 884
 885   XXX explain.
 886
 887
 888.. cmember:: long PyTypeObject.tp_dictoffset
 889
 890   If the instances of this type have a dictionary containing instance variables,
 891   this field is non-zero and contains the offset in the instances of the type of
 892   the instance variable dictionary; this offset is used by
 893   :cfunc:`PyObject_GenericGetAttr`.
 894
 895   Do not confuse this field with :attr:`tp_dict`; that is the dictionary for
 896   attributes of the type object itself.
 897
 898   If the value of this field is greater than zero, it specifies the offset from
 899   the start of the instance structure.  If the value is less than zero, it
 900   specifies the offset from the *end* of the instance structure.  A negative
 901   offset is more expensive to use, and should only be used when the instance
 902   structure contains a variable-length part.  This is used for example to add an
 903   instance variable dictionary to subtypes of :class:`str` or :class:`tuple`. Note
 904   that the :attr:`tp_basicsize` field should account for the dictionary added to
 905   the end in that case, even though the dictionary is not included in the basic
 906   object layout.  On a system with a pointer size of 4 bytes,
 907   :attr:`tp_dictoffset` should be set to ``-4`` to indicate that the dictionary is
 908   at the very end of the structure.
 909
 910   The real dictionary offset in an instance can be computed from a negative
 911   :attr:`tp_dictoffset` as follows::
 912
 913      dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset
 914      if dictoffset is not aligned on sizeof(void*):
 915          round up to sizeof(void*)
 916
 917   where :attr:`tp_basicsize`, :attr:`tp_itemsize` and :attr:`tp_dictoffset` are
 918   taken from the type object, and :attr:`ob_size` is taken from the instance.  The
 919   absolute value is taken because long ints use the sign of :attr:`ob_size` to
 920   store the sign of the number.  (There's never a need to do this calculation
 921   yourself; it is done for you by :cfunc:`_PyObject_GetDictPtr`.)
 922
 923   This field is inherited by subtypes, but see the rules listed below. A subtype
 924   may override this offset; this means that the subtype instances store the
 925   dictionary at a difference offset than the base type.  Since the dictionary is
 926   always found via :attr:`tp_dictoffset`, this should not be a problem.
 927
 928   When a type defined by a class statement has no :attr:`__slots__` declaration,
 929   and none of its base types has an instance variable dictionary, a dictionary
 930   slot is added to the instance layout and the :attr:`tp_dictoffset` is set to
 931   that slot's offset.
 932
 933   When a type defined by a class statement has a :attr:`__slots__` declaration,
 934   the type inherits its :attr:`tp_dictoffset` from its base type.
 935
 936   (Adding a slot named :attr:`__dict__` to the :attr:`__slots__` declaration does
 937   not have the expected effect, it just causes confusion.  Maybe this should be
 938   added as a feature just like :attr:`__weakref__` though.)
 939
 940
 941.. cmember:: initproc PyTypeObject.tp_init
 942
 943   An optional pointer to an instance initialization function.
 944
 945   This function corresponds to the :meth:`__init__` method of classes.  Like
 946   :meth:`__init__`, it is possible to create an instance without calling
 947   :meth:`__init__`, and it is possible to reinitialize an instance by calling its
 948   :meth:`__init__` method again.
 949
 950   The function signature is ::
 951
 952      int tp_init(PyObject *self, PyObject *args, PyObject *kwds)
 953
 954   The self argument is the instance to be initialized; the *args* and *kwds*
 955   arguments represent positional and keyword arguments of the call to
 956   :meth:`__init__`.
 957
 958   The :attr:`tp_init` function, if not *NULL*, is called when an instance is
 959   created normally by calling its type, after the type's :attr:`tp_new` function
 960   has returned an instance of the type.  If the :attr:`tp_new` function returns an
 961   instance of some other type that is not a subtype of the original type, no
 962   :attr:`tp_init` function is called; if :attr:`tp_new` returns an instance of a
 963   subtype of the original type, the subtype's :attr:`tp_init` is called.  (VERSION
 964   NOTE: described here is what is implemented in Python 2.2.1 and later.  In
 965   Python 2.2, the :attr:`tp_init` of the type of the object returned by
 966   :attr:`tp_new` was always called, if not *NULL*.)
 967
 968   This field is inherited by subtypes.
 969
 970
 971.. cmember:: allocfunc PyTypeObject.tp_alloc
 972
 973   An optional pointer to an instance allocation function.
 974
 975   The function signature is ::
 976
 977      PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems)
 978
 979   The purpose of this function is to separate memory allocation from memory
 980   initialization.  It should return a pointer to a block of memory of adequate
 981   length for the instance, suitably aligned, and initialized to zeros, but with
 982   :attr:`ob_refcnt` set to ``1`` and :attr:`ob_type` set to the type argument.  If
 983   the type's :attr:`tp_itemsize` is non-zero, the object's :attr:`ob_size` field
 984   should be initialized to *nitems* and the length of the allocated memory block
 985   should be ``tp_basicsize + nitems*tp_itemsize``, rounded up to a multiple of
 986   ``sizeof(void*)``; otherwise, *nitems* is not used and the length of the block
 987   should be :attr:`tp_basicsize`.
 988
 989   Do not use this function to do any other instance initialization, not even to
 990   allocate additional memory; that should be done by :attr:`tp_new`.
 991
 992   This field is inherited by static subtypes, but not by dynamic subtypes
 993   (subtypes created by a class statement); in the latter, this field is always set
 994   to :cfunc:`PyType_GenericAlloc`, to force a standard heap allocation strategy.
 995   That is also the recommended value for statically defined types.
 996
 997
 998.. cmember:: newfunc PyTypeObject.tp_new
 999
1000   An optional pointer to an instance creation function.
1001
1002   If this function is *NULL* for a particular type, that type cannot be called to
1003   create new instances; presumably there is some other way to create instances,
1004   like a factory function.
1005
1006   The function signature is ::
1007
1008      PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds)
1009
1010   The subtype argument is the type of the object being created; the *args* and
1011   *kwds* arguments represent positional and keyword arguments of the call to the
1012   type.  Note that subtype doesn't have to equal the type whose :attr:`tp_new`
1013   function is called; it may be a subtype of that type (but not an unrelated
1014   type).
1015
1016   The :attr:`tp_new` function should call ``subtype->tp_alloc(subtype, nitems)``
1017   to allocate space for the object, and then do only as much further
1018   initialization as is absolutely necessary.  Initialization that can safely be
1019   ignored or repeated should be placed in the :attr:`tp_init` handler.  A good
1020   rule of thumb is that for immutable types, all initialization should take place
1021   in :attr:`tp_new`, while for mutable types, most initialization should be
1022   deferred to :attr:`tp_init`.
1023
1024   This field is inherited by subtypes, except it is not inherited by static types
1025   whose :attr:`tp_base` is *NULL* or ``&PyBaseObject_Type``.  The latter exception
1026   is a precaution so that old extension types don't become callable simply by
1027   being linked with Python 2.2.
1028
1029
1030.. cmember:: destructor PyTypeObject.tp_free
1031
1032   An optional pointer to an instance deallocation function.
1033
1034   The signature of this function has changed slightly: in Python 2.2 and 2.2.1,
1035   its signature is :ctype:`destructor`::
1036
1037      void tp_free(PyObject *)
1038
1039   In Python 2.3 and beyond, its signature is :ctype:`freefunc`::
1040
1041      void tp_free(void *)
1042
1043   The only initializer that is compatible with both versions is ``_PyObject_Del``,
1044   whose definition has suitably adapted in Python 2.3.
1045
1046   This field is inherited by static subtypes, but not by dynamic subtypes
1047   (subtypes created by a class statement); in the latter, this field is set to a
1048   deallocator suitable to match :cfunc:`PyType_GenericAlloc` and the value of the
1049   :const:`Py_TPFLAGS_HAVE_GC` flag bit.
1050
1051
1052.. cmember:: inquiry PyTypeObject.tp_is_gc
1053
1054   An optional pointer to a function called by the garbage collector.
1055
1056   The garbage collector needs to know whether a particular object is collectible
1057   or not.  Normally, it is sufficient to look at the object's type's
1058   :attr:`tp_flags` field, and check the :const:`Py_TPFLAGS_HAVE_GC` flag bit.  But
1059   some types have a mixture of statically and dynamically allocated instances, and
1060   the statically allocated instances are not collectible.  Such types should
1061   define this function; it should return ``1`` for a collectible instance, and
1062   ``0`` for a non-collectible instance. The signature is ::
1063
1064      int tp_is_gc(PyObject *self)
1065
1066   (The only example of this are types themselves.  The metatype,
1067   :cdata:`PyType_Type`, defines this function to distinguish between statically
1068   and dynamically allocated types.)
1069
1070   This field is inherited by subtypes.  (VERSION NOTE: in Python 2.2, it was not
1071   inherited.  It is inherited in 2.2.1 and later versions.)
1072
1073
1074.. cmember:: PyObject* PyTypeObject.tp_bases
1075
1076   Tuple of base types.
1077
1078   This is set for types created by a class statement.  It should be *NULL* for
1079   statically defined types.
1080
1081   This field is not inherited.
1082
1083
1084.. cmember:: PyObject* PyTypeObject.tp_mro
1085
1086   Tuple containing the expanded set of base types, starting with the type itself
1087   and ending with :class:`object`, in Method Resolution Order.
1088
1089   This field is not inherited; it is calculated fresh by :cfunc:`PyType_Ready`.
1090
1091
1092.. cmember:: PyObject* PyTypeObject.tp_cache
1093
1094   Unused.  Not inherited.  Internal use only.
1095
1096
1097.. cmember:: PyObject* PyTypeObject.tp_subclasses
1098
1099   List of weak references to subclasses.  Not inherited.  Internal use only.
1100
1101
1102.. cmember:: PyObject* PyTypeObject.tp_weaklist
1103
1104   Weak reference list head, for weak references to this type object.  Not
1105   inherited.  Internal use only.
1106
1107The remaining fields are only defined if the feature test macro
1108:const:`COUNT_ALLOCS` is defined, and are for internal use only. They are
1109documented here for completeness.  None of these fields are inherited by
1110subtypes.
1111
1112
1113.. cmember:: Py_ssize_t PyTypeObject.tp_allocs
1114
1115   Number of allocations.
1116
1117
1118.. cmember:: P…

Large files files are truncated, but you can click here to view the full file