cpython-lru_cache-weakref: Doc/c-api/typeobj.rst annotate

annotate Doc/c-api/typeobj.rst @ 58925:eecf1bef052d 2.6

Merged revisions 78207 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r78207 | ezio.melotti | 2010-02-17 01:26:09 +0200 (Wed, 17 Feb 2010) | 1 line #7930: fix stripid ........

author	Ezio Melotti <ezio.melotti@gmail.com>
date	Tue, 16 Feb 2010 23:29:44 +0000
parents	9b24d010133f
children	5b1da32c9d4e

rev	line source
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1 .. highlightlang:: c
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	2
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	3 .. _type-structs:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	4
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	5 Type Objects
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	6 ============
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	7
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	8 Perhaps one of the most important structures of the Python object system is the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	9 structure that defines a new type: the :ctype:`PyTypeObject` structure. Type
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	10 objects can be handled using any of the :cfunc:`PyObject_\*` or
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	11 :cfunc:`PyType_\*` functions, but do not offer much that's interesting to most
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	12 Python applications. These objects are fundamental to how objects behave, so
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	13 they are very important to the interpreter itself and to any extension module
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	14 that implements new types.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	15
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	16 Type objects are fairly large compared to most of the standard types. The reason
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	17 for the size is that each type object stores a large number of values, mostly C
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	18 function pointers, each of which implements a small part of the type's
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	19 functionality. The fields of the type object are examined in detail in this
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	20 section. The fields will be described in the order in which they occur in the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	21 structure.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	22
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	23 Typedefs: unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	24 intintargfunc, intobjargproc, intintobjargproc, objobjargproc, destructor,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	25 freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	26 cmpfunc, reprfunc, hashfunc
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	27
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	28 The structure definition for :ctype:`PyTypeObject` can be found in
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	29 :file:`Include/object.h`. For convenience of reference, this repeats the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	30 definition found there:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	31
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	32 .. literalinclude:: ../includes/typestruct.h
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	33
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	34
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	35 The type object structure extends the :ctype:`PyVarObject` structure. The
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	36 :attr:`ob_size` field is used for dynamic types (created by :func:`type_new`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	37 usually called from a class statement). Note that :cdata:`PyType_Type` (the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	38 metatype) initializes :attr:`tp_itemsize`, which means that its instances (i.e.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	39 type objects) must have the :attr:`ob_size` field.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	40
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	41
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	42 .. cmember:: PyObject* PyObject._ob_next
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	43 PyObject* PyObject._ob_prev
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	44
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	45 These fields are only present when the macro ``Py_TRACE_REFS`` is defined.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	46 Their initialization to NULL is taken care of by the ``PyObject_HEAD_INIT``
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	47 macro. For statically allocated objects, these fields always remain NULL.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	48 For dynamically allocated objects, these two fields are used to link the object
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	49 into a doubly-linked list of all live objects on the heap. This could be used
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	50 for various debugging purposes; currently the only use is to print the objects
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	51 that are still alive at the end of a run when the environment variable
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	52 :envvar:`PYTHONDUMPREFS` is set.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	53
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	54 These fields are not inherited by subtypes.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	55
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	56
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	57 .. cmember:: Py_ssize_t PyObject.ob_refcnt
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	58
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	59 This is the type object's reference count, initialized to ``1`` by the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	60 ``PyObject_HEAD_INIT`` macro. Note that for statically allocated type objects,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	61 the type's instances (objects whose :attr:`ob_type` points back to the type) do
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	62 not count as references. But for dynamically allocated type objects, the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	63 instances do count as references.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	64
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	65 This field is not inherited by subtypes.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	66
53588 817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 52909 diff changeset	67 .. versionchanged:: 2.5
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 52909 diff changeset	68 This field used to be an :ctype:`int` type. This might require changes
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 52909 diff changeset	69 in your code for properly supporting 64-bit systems.
817d8b28cd6b Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from Jeroen Ruigrok van der Werven <asmodai@in-nomine.org> parents: 52909 diff changeset	70
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	71
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	72 .. cmember:: PyTypeObject* PyObject.ob_type
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	73
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	74 This is the type's type, in other words its metatype. It is initialized by the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	75 argument to the ``PyObject_HEAD_INIT`` macro, and its value should normally be
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	76 ``&PyType_Type``. However, for dynamically loadable extension modules that must
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	77 be usable on Windows (at least), the compiler complains that this is not a valid
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	78 initializer. Therefore, the convention is to pass NULL to the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	79 ``PyObject_HEAD_INIT`` macro and to initialize this field explicitly at the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	80 start of the module's initialization function, before doing anything else. This
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	81 is typically done like this::
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	82
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	83 Foo_Type.ob_type = &PyType_Type;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	84
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	85 This should be done before any instances of the type are created.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	86 :cfunc:`PyType_Ready` checks if :attr:`ob_type` is NULL, and if so,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	87 initializes it: in Python 2.2, it is set to ``&PyType_Type``; in Python 2.2.1
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	88 and later it is initialized to the :attr:`ob_type` field of the base class.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	89 :cfunc:`PyType_Ready` will not change this field if it is non-zero.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	90
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	91 In Python 2.2, this field is not inherited by subtypes. In 2.2.1, and in 2.3
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	92 and beyond, it is inherited by subtypes.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	93
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	94
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	95 .. cmember:: Py_ssize_t PyVarObject.ob_size
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	96
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	97 For statically allocated type objects, this should be initialized to zero. For
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	98 dynamically allocated type objects, this field has a special internal meaning.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	99
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	100 This field is not inherited by subtypes.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	101
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	102
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	103 .. cmember:: char* PyTypeObject.tp_name
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	104
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	105 Pointer to a NUL-terminated string containing the name of the type. For types
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	106 that are accessible as module globals, the string should be the full module
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	107 name, followed by a dot, followed by the type name; for built-in types, it
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	108 should be just the type name. If the module is a submodule of a package, the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	109 full package name is part of the full module name. For example, a type named
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	110 :class:`T` defined in module :mod:`M` in subpackage :mod:`Q` in package :mod:`P`
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	111 should have the :attr:`tp_name` initializer ``"P.Q.M.T"``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	112
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	113 For dynamically allocated type objects, this should just be the type name, and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	114 the module name explicitly stored in the type dict as the value for key
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	115 ``'__module__'``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	116
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	117 For statically allocated type objects, the tp_name field should contain a dot.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	118 Everything before the last dot is made accessible as the :attr:`__module__`
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	119 attribute, and everything after the last dot is made accessible as the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	120 :attr:`__name__` attribute.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	121
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	122 If no dot is present, the entire :attr:`tp_name` field is made accessible as the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	123 :attr:`__name__` attribute, and the :attr:`__module__` attribute is undefined
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	124 (unless explicitly set in the dictionary, as explained above). This means your
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	125 type will be impossible to pickle.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	126
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	127 This field is not inherited by subtypes.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	128
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	129
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	130 .. cmember:: Py_ssize_t PyTypeObject.tp_basicsize
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	131 Py_ssize_t PyTypeObject.tp_itemsize
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	132
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	133 These fields allow calculating the size in bytes of instances of the type.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	134
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	135 There are two kinds of types: types with fixed-length instances have a zero
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	136 :attr:`tp_itemsize` field, types with variable-length instances have a non-zero
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	137 :attr:`tp_itemsize` field. For a type with fixed-length instances, all
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	138 instances have the same size, given in :attr:`tp_basicsize`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	139
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	140 For a type with variable-length instances, the instances must have an
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	141 :attr:`ob_size` field, and the instance size is :attr:`tp_basicsize` plus N
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	142 times :attr:`tp_itemsize`, where N is the "length" of the object. The value of
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	143 N is typically stored in the instance's :attr:`ob_size` field. There are
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	144 exceptions: for example, long ints use a negative :attr:`ob_size` to indicate a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	145 negative number, and N is ``abs(ob_size)`` there. Also, the presence of an
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	146 :attr:`ob_size` field in the instance layout doesn't mean that the instance
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	147 structure is variable-length (for example, the structure for the list type has
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	148 fixed-length instances, yet those instances have a meaningful :attr:`ob_size`
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	149 field).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	150
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	151 The basic size includes the fields in the instance declared by the macro
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	152 :cmacro:`PyObject_HEAD` or :cmacro:`PyObject_VAR_HEAD` (whichever is used to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	153 declare the instance struct) and this in turn includes the :attr:`_ob_prev` and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	154 :attr:`_ob_next` fields if they are present. This means that the only correct
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	155 way to get an initializer for the :attr:`tp_basicsize` is to use the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	156 ``sizeof`` operator on the struct used to declare the instance layout.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	157 The basic size does not include the GC header size (this is new in Python 2.2;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	158 in 2.1 and 2.0, the GC header size was included in :attr:`tp_basicsize`).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	159
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	160 These fields are inherited separately by subtypes. If the base type has a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	161 non-zero :attr:`tp_itemsize`, it is generally not safe to set
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	162 :attr:`tp_itemsize` to a different non-zero value in a subtype (though this
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	163 depends on the implementation of the base type).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	164
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	165 A note about alignment: if the variable items require a particular alignment,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	166 this should be taken care of by the value of :attr:`tp_basicsize`. Example:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	167 suppose a type implements an array of ``double``. :attr:`tp_itemsize` is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	168 ``sizeof(double)``. It is the programmer's responsibility that
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	169 :attr:`tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	170 alignment requirement for ``double``).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	171
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	172
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	173 .. cmember:: destructor PyTypeObject.tp_dealloc
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	174
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	175 A pointer to the instance destructor function. This function must be defined
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	176 unless the type guarantees that its instances will never be deallocated (as is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	177 the case for the singletons ``None`` and ``Ellipsis``).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	178
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	179 The destructor function is called by the :cfunc:`Py_DECREF` and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	180 :cfunc:`Py_XDECREF` macros when the new reference count is zero. At this point,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	181 the instance is still in existence, but there are no references to it. The
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	182 destructor function should free all references which the instance owns, free all
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	183 memory buffers owned by the instance (using the freeing function corresponding
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	184 to the allocation function used to allocate the buffer), and finally (as its
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	185 last action) call the type's :attr:`tp_free` function. If the type is not
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	186 subtypable (doesn't have the :const:`Py_TPFLAGS_BASETYPE` flag bit set), it is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	187 permissible to call the object deallocator directly instead of via
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	188 :attr:`tp_free`. The object deallocator should be the one used to allocate the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	189 instance; this is normally :cfunc:`PyObject_Del` if the instance was allocated
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	190 using :cfunc:`PyObject_New` or :cfunc:`PyObject_VarNew`, or
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	191 :cfunc:`PyObject_GC_Del` if the instance was allocated using
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	192 :cfunc:`PyObject_GC_New` or :cfunc:`PyObject_GC_VarNew`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	193
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	194 This field is inherited by subtypes.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	195
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	196
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	197 .. cmember:: printfunc PyTypeObject.tp_print
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	198
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	199 An optional pointer to the instance print function.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	200
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	201 The print function is only called when the instance is printed to a real file;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	202 when it is printed to a pseudo-file (like a :class:`StringIO` instance), the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	203 instance's :attr:`tp_repr` or :attr:`tp_str` function is called to convert it to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	204 a string. These are also called when the type's :attr:`tp_print` field is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	205 NULL. A type should never implement :attr:`tp_print` in a way that produces
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	206 different output than :attr:`tp_repr` or :attr:`tp_str` would.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	207
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	208 The print function is called with the same signature as :cfunc:`PyObject_Print`:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	209 ``int tp_print(PyObject self, FILE file, int flags)``. The self argument is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	210 the instance to be printed. The file argument is the stdio file to which it
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	211 is to be printed. The flags argument is composed of flag bits. The only flag
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	212 bit currently defined is :const:`Py_PRINT_RAW`. When the :const:`Py_PRINT_RAW`
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	213 flag bit is set, the instance should be printed the same way as :attr:`tp_str`
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	214 would format it; when the :const:`Py_PRINT_RAW` flag bit is clear, the instance
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	215 should be printed the same was as :attr:`tp_repr` would format it. It should
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	216 return ``-1`` and set an exception condition when an error occurred during the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	217 comparison.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	218
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	219 It is possible that the :attr:`tp_print` field will be deprecated. In any case,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	220 it is recommended not to define :attr:`tp_print`, but instead to rely on
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	221 :attr:`tp_repr` and :attr:`tp_str` for printing.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	222
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	223 This field is inherited by subtypes.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	224
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	225
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	226 .. cmember:: getattrfunc PyTypeObject.tp_getattr
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	227
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	228 An optional pointer to the get-attribute-string function.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	229
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	230 This field is deprecated. When it is defined, it should point to a function
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	231 that acts the same as the :attr:`tp_getattro` function, but taking a C string
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	232 instead of a Python string object to give the attribute name. The signature is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	233 the same as for :cfunc:`PyObject_GetAttrString`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	234
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	235 This field is inherited by subtypes together with :attr:`tp_getattro`: a subtype
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	236 inherits both :attr:`tp_getattr` and :attr:`tp_getattro` from its base type when
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	237 the subtype's :attr:`tp_getattr` and :attr:`tp_getattro` are both NULL.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	238
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	239
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	240 .. cmember:: setattrfunc PyTypeObject.tp_setattr
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	241
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	242 An optional pointer to the set-attribute-string function.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	243
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	244 This field is deprecated. When it is defined, it should point to a function
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	245 that acts the same as the :attr:`tp_setattro` function, but taking a C string
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	246 instead of a Python string object to give the attribute name. The signature is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	247 the same as for :cfunc:`PyObject_SetAttrString`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	248
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	249 This field is inherited by subtypes together with :attr:`tp_setattro`: a subtype
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	250 inherits both :attr:`tp_setattr` and :attr:`tp_setattro` from its base type when
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	251 the subtype's :attr:`tp_setattr` and :attr:`tp_setattro` are both NULL.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	252
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	253
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	254 .. cmember:: cmpfunc PyTypeObject.tp_compare
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	255
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	256 An optional pointer to the three-way comparison function.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	257
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	258 The signature is the same as for :cfunc:`PyObject_Compare`. The function should
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	259 return ``1`` if self greater than other, ``0`` if self is equal to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	260 other, and ``-1`` if self less than other. It should return ``-1`` and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	261 set an exception condition when an error occurred during the comparison.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	262
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	263 This field is inherited by subtypes together with :attr:`tp_richcompare` and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	264 :attr:`tp_hash`: a subtypes inherits all three of :attr:`tp_compare`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	265 :attr:`tp_richcompare`, and :attr:`tp_hash` when the subtype's
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	266 :attr:`tp_compare`, :attr:`tp_richcompare`, and :attr:`tp_hash` are all NULL.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	267
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	268
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	269 .. cmember:: reprfunc PyTypeObject.tp_repr
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	270
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	271 .. index:: builtin: repr
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	272
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	273 An optional pointer to a function that implements the built-in function
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	274 :func:`repr`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	275
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	276 The signature is the same as for :cfunc:`PyObject_Repr`; it must return a string
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	277 or a Unicode object. Ideally, this function should return a string that, when
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	278 passed to :func:`eval`, given a suitable environment, returns an object with the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	279 same value. If this is not feasible, it should return a string starting with
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	280 ``'<'`` and ending with ``'>'`` from which both the type and the value of the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	281 object can be deduced.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	282
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	283 When this field is not set, a string of the form ``<%s object at %p>`` is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	284 returned, where ``%s`` is replaced by the type name, and ``%p`` by the object's
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	285 memory address.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	286
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	287 This field is inherited by subtypes.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	288
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	289 .. cmember:: PyNumberMethods* tp_as_number
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	290
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	291 Pointer to an additional structure that contains fields relevant only to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	292 objects which implement the number protocol. These fields are documented in
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	293 :ref:`number-structs`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	294
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	295 The :attr:`tp_as_number` field is not inherited, but the contained fields are
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	296 inherited individually.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	297
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	298
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	299 .. cmember:: PySequenceMethods* tp_as_sequence
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	300
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	301 Pointer to an additional structure that contains fields relevant only to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	302 objects which implement the sequence protocol. These fields are documented
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	303 in :ref:`sequence-structs`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	304
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	305 The :attr:`tp_as_sequence` field is not inherited, but the contained fields
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	306 are inherited individually.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	307
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	308
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	309 .. cmember:: PyMappingMethods* tp_as_mapping
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	310
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	311 Pointer to an additional structure that contains fields relevant only to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	312 objects which implement the mapping protocol. These fields are documented in
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	313 :ref:`mapping-structs`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	314
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	315 The :attr:`tp_as_mapping` field is not inherited, but the contained fields
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	316 are inherited individually.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	317
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	318
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	319 .. cmember:: hashfunc PyTypeObject.tp_hash
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	320
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	321 .. index:: builtin: hash
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	322
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	323 An optional pointer to a function that implements the built-in function
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	324 :func:`hash`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	325
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	326 The signature is the same as for :cfunc:`PyObject_Hash`; it must return a C
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	327 long. The value ``-1`` should not be returned as a normal return value; when an
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	328 error occurs during the computation of the hash value, the function should set
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	329 an exception and return ``-1``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	330
48284 2254aa824d4d Issue 2235: document PyObject_HashNotImplemented Nick Coghlan <ncoghlan@gmail.com> parents: 46609 diff changeset	331 This field can be set explicitly to :cfunc:`PyObject_HashNotImplemented` to
2254aa824d4d Issue 2235: document PyObject_HashNotImplemented Nick Coghlan <ncoghlan@gmail.com> parents: 46609 diff changeset	332 block inheritance of the hash method from a parent type. This is interpreted
2254aa824d4d Issue 2235: document PyObject_HashNotImplemented Nick Coghlan <ncoghlan@gmail.com> parents: 46609 diff changeset	333 as the equivalent of ``__hash__ = None`` at the Python level, causing
2254aa824d4d Issue 2235: document PyObject_HashNotImplemented Nick Coghlan <ncoghlan@gmail.com> parents: 46609 diff changeset	334 ``isinstance(o, collections.Hashable)`` to correctly return ``False``. Note
2254aa824d4d Issue 2235: document PyObject_HashNotImplemented Nick Coghlan <ncoghlan@gmail.com> parents: 46609 diff changeset	335 that the converse is also true - setting ``__hash__ = None`` on a class at
2254aa824d4d Issue 2235: document PyObject_HashNotImplemented Nick Coghlan <ncoghlan@gmail.com> parents: 46609 diff changeset	336 the Python level will result in the ``tp_hash`` slot being set to
2254aa824d4d Issue 2235: document PyObject_HashNotImplemented Nick Coghlan <ncoghlan@gmail.com> parents: 46609 diff changeset	337 :cfunc:`PyObject_HashNotImplemented`.
2254aa824d4d Issue 2235: document PyObject_HashNotImplemented Nick Coghlan <ncoghlan@gmail.com> parents: 46609 diff changeset	338
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	339 When this field is not set, two possibilities exist: if the :attr:`tp_compare`
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	340 and :attr:`tp_richcompare` fields are both NULL, a default hash value based on
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	341 the object's address is returned; otherwise, a :exc:`TypeError` is raised.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	342
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	343 This field is inherited by subtypes together with :attr:`tp_richcompare` and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	344 :attr:`tp_compare`: a subtypes inherits all three of :attr:`tp_compare`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	345 :attr:`tp_richcompare`, and :attr:`tp_hash`, when the subtype's
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	346 :attr:`tp_compare`, :attr:`tp_richcompare` and :attr:`tp_hash` are all NULL.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	347
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	348
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	349 .. cmember:: ternaryfunc PyTypeObject.tp_call
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	350
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	351 An optional pointer to a function that implements calling the object. This
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	352 should be NULL if the object is not callable. The signature is the same as
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	353 for :cfunc:`PyObject_Call`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	354
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	355 This field is inherited by subtypes.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	356
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	357
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	358 .. cmember:: reprfunc PyTypeObject.tp_str
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	359
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	360 An optional pointer to a function that implements the built-in operation
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	361 :func:`str`. (Note that :class:`str` is a type now, and :func:`str` calls the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	362 constructor for that type. This constructor calls :cfunc:`PyObject_Str` to do
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	363 the actual work, and :cfunc:`PyObject_Str` will call this handler.)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	364
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	365 The signature is the same as for :cfunc:`PyObject_Str`; it must return a string
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	366 or a Unicode object. This function should return a "friendly" string
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	367 representation of the object, as this is the representation that will be used by
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	368 the print statement.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	369
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	370 When this field is not set, :cfunc:`PyObject_Repr` is called to return a string
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	371 representation.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	372
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	373 This field is inherited by subtypes.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	374
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	375
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	376 .. cmember:: getattrofunc PyTypeObject.tp_getattro
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	377
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	378 An optional pointer to the get-attribute function.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	379
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	380 The signature is the same as for :cfunc:`PyObject_GetAttr`. It is usually
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	381 convenient to set this field to :cfunc:`PyObject_GenericGetAttr`, which
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	382 implements the normal way of looking for object attributes.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	383
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	384 This field is inherited by subtypes together with :attr:`tp_getattr`: a subtype
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	385 inherits both :attr:`tp_getattr` and :attr:`tp_getattro` from its base type when
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	386 the subtype's :attr:`tp_getattr` and :attr:`tp_getattro` are both NULL.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	387
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	388
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	389 .. cmember:: setattrofunc PyTypeObject.tp_setattro
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	390
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	391 An optional pointer to the set-attribute function.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	392
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	393 The signature is the same as for :cfunc:`PyObject_SetAttr`. It is usually
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	394 convenient to set this field to :cfunc:`PyObject_GenericSetAttr`, which
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	395 implements the normal way of setting object attributes.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	396
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	397 This field is inherited by subtypes together with :attr:`tp_setattr`: a subtype
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	398 inherits both :attr:`tp_setattr` and :attr:`tp_setattro` from its base type when
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	399 the subtype's :attr:`tp_setattr` and :attr:`tp_setattro` are both NULL.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	400
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	401
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	402 .. cmember:: PyBufferProcs* PyTypeObject.tp_as_buffer
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	403
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	404 Pointer to an additional structure that contains fields relevant only to objects
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	405 which implement the buffer interface. These fields are documented in
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	406 :ref:`buffer-structs`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	407
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	408 The :attr:`tp_as_buffer` field is not inherited, but the contained fields are
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	409 inherited individually.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	410
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	411
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	412 .. cmember:: long PyTypeObject.tp_flags
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	413
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	414 This field is a bit mask of various flags. Some flags indicate variant
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	415 semantics for certain situations; others are used to indicate that certain
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	416 fields in the type object (or in the extension structures referenced via
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	417 :attr:`tp_as_number`, :attr:`tp_as_sequence`, :attr:`tp_as_mapping`, and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	418 :attr:`tp_as_buffer`) that were historically not always present are valid; if
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	419 such a flag bit is clear, the type fields it guards must not be accessed and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	420 must be considered to have a zero or NULL value instead.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	421
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	422 Inheritance of this field is complicated. Most flag bits are inherited
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	423 individually, i.e. if the base type has a flag bit set, the subtype inherits
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	424 this flag bit. The flag bits that pertain to extension structures are strictly
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	425 inherited if the extension structure is inherited, i.e. the base type's value of
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	426 the flag bit is copied into the subtype together with a pointer to the extension
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	427 structure. The :const:`Py_TPFLAGS_HAVE_GC` flag bit is inherited together with
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	428 the :attr:`tp_traverse` and :attr:`tp_clear` fields, i.e. if the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	429 :const:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	430 :attr:`tp_traverse` and :attr:`tp_clear` fields in the subtype exist (as
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	431 indicated by the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit) and have NULL
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	432 values.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	433
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	434 The following bit masks are currently defined; these can be ORed together using
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	435 the ``\|`` operator to form the value of the :attr:`tp_flags` field. The macro
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	436 :cfunc:`PyType_HasFeature` takes a type and a flags value, tp and f, and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	437 checks whether ``tp->tp_flags & f`` is non-zero.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	438
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	439
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	440 .. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	441
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	442 If this bit is set, the :ctype:`PyBufferProcs` struct referenced by
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	443 :attr:`tp_as_buffer` has the :attr:`bf_getcharbuffer` field.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	444
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	445
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	446 .. data:: Py_TPFLAGS_HAVE_SEQUENCE_IN
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	447
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	448 If this bit is set, the :ctype:`PySequenceMethods` struct referenced by
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	449 :attr:`tp_as_sequence` has the :attr:`sq_contains` field.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	450
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	451
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	452 .. data:: Py_TPFLAGS_GC
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	453
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	454 This bit is obsolete. The bit it used to name is no longer in use. The symbol
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	455 is now defined as zero.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	456
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	457
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	458 .. data:: Py_TPFLAGS_HAVE_INPLACEOPS
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	459
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	460 If this bit is set, the :ctype:`PySequenceMethods` struct referenced by
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	461 :attr:`tp_as_sequence` and the :ctype:`PyNumberMethods` structure referenced by
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	462 :attr:`tp_as_number` contain the fields for in-place operators. In particular,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	463 this means that the :ctype:`PyNumberMethods` structure has the fields
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	464 :attr:`nb_inplace_add`, :attr:`nb_inplace_subtract`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	465 :attr:`nb_inplace_multiply`, :attr:`nb_inplace_divide`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	466 :attr:`nb_inplace_remainder`, :attr:`nb_inplace_power`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	467 :attr:`nb_inplace_lshift`, :attr:`nb_inplace_rshift`, :attr:`nb_inplace_and`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	468 :attr:`nb_inplace_xor`, and :attr:`nb_inplace_or`; and the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	469 :ctype:`PySequenceMethods` struct has the fields :attr:`sq_inplace_concat` and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	470 :attr:`sq_inplace_repeat`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	471
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	472
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	473 .. data:: Py_TPFLAGS_CHECKTYPES
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	474
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	475 If this bit is set, the binary and ternary operations in the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	476 :ctype:`PyNumberMethods` structure referenced by :attr:`tp_as_number` accept
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	477 arguments of arbitrary object types, and do their own type conversions if
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	478 needed. If this bit is clear, those operations require that all arguments have
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	479 the current type as their type, and the caller is supposed to perform a coercion
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	480 operation first. This applies to :attr:`nb_add`, :attr:`nb_subtract`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	481 :attr:`nb_multiply`, :attr:`nb_divide`, :attr:`nb_remainder`, :attr:`nb_divmod`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	482 :attr:`nb_power`, :attr:`nb_lshift`, :attr:`nb_rshift`, :attr:`nb_and`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	483 :attr:`nb_xor`, and :attr:`nb_or`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	484
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	485
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	486 .. data:: Py_TPFLAGS_HAVE_RICHCOMPARE
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	487
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	488 If this bit is set, the type object has the :attr:`tp_richcompare` field, as
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	489 well as the :attr:`tp_traverse` and the :attr:`tp_clear` fields.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	490
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	491
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	492 .. data:: Py_TPFLAGS_HAVE_WEAKREFS
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	493
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	494 If this bit is set, the :attr:`tp_weaklistoffset` field is defined. Instances
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	495 of a type are weakly referenceable if the type's :attr:`tp_weaklistoffset` field
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	496 has a value greater than zero.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	497
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	498
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	499 .. data:: Py_TPFLAGS_HAVE_ITER
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	500
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	501 If this bit is set, the type object has the :attr:`tp_iter` and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	502 :attr:`tp_iternext` fields.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	503
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	504
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	505 .. data:: Py_TPFLAGS_HAVE_CLASS
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	506
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	507 If this bit is set, the type object has several new fields defined starting in
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	508 Python 2.2: :attr:`tp_methods`, :attr:`tp_members`, :attr:`tp_getset`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	509 :attr:`tp_base`, :attr:`tp_dict`, :attr:`tp_descr_get`, :attr:`tp_descr_set`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	510 :attr:`tp_dictoffset`, :attr:`tp_init`, :attr:`tp_alloc`, :attr:`tp_new`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	511 :attr:`tp_free`, :attr:`tp_is_gc`, :attr:`tp_bases`, :attr:`tp_mro`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	512 :attr:`tp_cache`, :attr:`tp_subclasses`, and :attr:`tp_weaklist`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	513
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	514
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	515 .. data:: Py_TPFLAGS_HEAPTYPE
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	516
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	517 This bit is set when the type object itself is allocated on the heap. In this
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	518 case, the :attr:`ob_type` field of its instances is considered a reference to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	519 the type, and the type object is INCREF'ed when a new instance is created, and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	520 DECREF'ed when an instance is destroyed (this does not apply to instances of
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	521 subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	522 DECREF'ed).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	523
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	524
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	525 .. data:: Py_TPFLAGS_BASETYPE
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	526
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	527 This bit is set when the type can be used as the base type of another type. If
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	528 this bit is clear, the type cannot be subtyped (similar to a "final" class in
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	529 Java).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	530
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	531
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	532 .. data:: Py_TPFLAGS_READY
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	533
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	534 This bit is set when the type object has been fully initialized by
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	535 :cfunc:`PyType_Ready`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	536
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	537
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	538 .. data:: Py_TPFLAGS_READYING
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	539
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	540 This bit is set while :cfunc:`PyType_Ready` is in the process of initializing
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	541 the type object.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	542
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	543
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	544 .. data:: Py_TPFLAGS_HAVE_GC
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	545
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	546 This bit is set when the object supports garbage collection. If this bit
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	547 is set, instances must be created using :cfunc:`PyObject_GC_New` and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	548 destroyed using :cfunc:`PyObject_GC_Del`. More information in section
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	549 :ref:`supporting-cycle-detection`. This bit also implies that the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	550 GC-related fields :attr:`tp_traverse` and :attr:`tp_clear` are present in
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	551 the type object; but those fields also exist when
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	552 :const:`Py_TPFLAGS_HAVE_GC` is clear but
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	553 :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` is set.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	554
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	555
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	556 .. data:: Py_TPFLAGS_DEFAULT
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	557
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	558 This is a bitmask of all the bits that pertain to the existence of certain
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	559 fields in the type object and its extension structures. Currently, it includes
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	560 the following bits: :const:`Py_TPFLAGS_HAVE_GETCHARBUFFER`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	561 :const:`Py_TPFLAGS_HAVE_SEQUENCE_IN`, :const:`Py_TPFLAGS_HAVE_INPLACEOPS`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	562 :const:`Py_TPFLAGS_HAVE_RICHCOMPARE`, :const:`Py_TPFLAGS_HAVE_WEAKREFS`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	563 :const:`Py_TPFLAGS_HAVE_ITER`, and :const:`Py_TPFLAGS_HAVE_CLASS`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	564
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	565
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	566 .. cmember:: char* PyTypeObject.tp_doc
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	567
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	568 An optional pointer to a NUL-terminated C string giving the docstring for this
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	569 type object. This is exposed as the :attr:`__doc__` attribute on the type and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	570 instances of the type.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	571
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	572 This field is not inherited by subtypes.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	573
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	574 The following three fields only exist if the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	575 :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit is set.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	576
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	577
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	578 .. cmember:: traverseproc PyTypeObject.tp_traverse
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	579
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	580 An optional pointer to a traversal function for the garbage collector. This is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	581 only used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. More information
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	582 about Python's garbage collection scheme can be found in section
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	583 :ref:`supporting-cycle-detection`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	584
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	585 The :attr:`tp_traverse` pointer is used by the garbage collector to detect
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	586 reference cycles. A typical implementation of a :attr:`tp_traverse` function
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	587 simply calls :cfunc:`Py_VISIT` on each of the instance's members that are Python
45429 853af5bbb497 A lot more typo fixes by Ori Avtalion. Georg Brandl <georg@python.org> parents: 44830 diff changeset	588 objects. For example, this is function :cfunc:`local_traverse` from the
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	589 :mod:`thread` extension module::
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	590
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	591 static int
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	592 local_traverse(localobject self, visitproc visit, void arg)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	593 {
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	594 Py_VISIT(self->args);
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	595 Py_VISIT(self->kw);
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	596 Py_VISIT(self->dict);
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	597 return 0;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	598 }
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	599
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	600 Note that :cfunc:`Py_VISIT` is called only on those members that can participate
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	601 in reference cycles. Although there is also a ``self->key`` member, it can only
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	602 be NULL or a Python string and therefore cannot be part of a reference cycle.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	603
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	604 On the other hand, even if you know a member can never be part of a cycle, as a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	605 debugging aid you may want to visit it anyway just so the :mod:`gc` module's
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	606 :func:`get_referents` function will include it.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	607
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	608 Note that :cfunc:`Py_VISIT` requires the visit and arg parameters to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	609 :cfunc:`local_traverse` to have these specific names; don't name them just
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	610 anything.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	611
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	612 This field is inherited by subtypes together with :attr:`tp_clear` and the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	613 :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	614 :attr:`tp_clear` are all inherited from the base type if they are all zero in
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	615 the subtype and the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	616 bit set.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	617
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	618
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	619 .. cmember:: inquiry PyTypeObject.tp_clear
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	620
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	621 An optional pointer to a clear function for the garbage collector. This is only
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	622 used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	623
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	624 The :attr:`tp_clear` member function is used to break reference cycles in cyclic
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	625 garbage detected by the garbage collector. Taken together, all :attr:`tp_clear`
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	626 functions in the system must combine to break all reference cycles. This is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	627 subtle, and if in any doubt supply a :attr:`tp_clear` function. For example,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	628 the tuple type does not implement a :attr:`tp_clear` function, because it's
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	629 possible to prove that no reference cycle can be composed entirely of tuples.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	630 Therefore the :attr:`tp_clear` functions of other types must be sufficient to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	631 break any cycle containing a tuple. This isn't immediately obvious, and there's
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	632 rarely a good reason to avoid implementing :attr:`tp_clear`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	633
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	634 Implementations of :attr:`tp_clear` should drop the instance's references to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	635 those of its members that may be Python objects, and set its pointers to those
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	636 members to NULL, as in the following example::
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	637
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	638 static int
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	639 local_clear(localobject *self)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	640 {
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	641 Py_CLEAR(self->key);
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	642 Py_CLEAR(self->args);
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	643 Py_CLEAR(self->kw);
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	644 Py_CLEAR(self->dict);
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	645 return 0;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	646 }
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	647
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	648 The :cfunc:`Py_CLEAR` macro should be used, because clearing references is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	649 delicate: the reference to the contained object must not be decremented until
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	650 after the pointer to the contained object is set to NULL. This is because
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	651 decrementing the reference count may cause the contained object to become trash,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	652 triggering a chain of reclamation activity that may include invoking arbitrary
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	653 Python code (due to finalizers, or weakref callbacks, associated with the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	654 contained object). If it's possible for such code to reference self again,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	655 it's important that the pointer to the contained object be NULL at that time,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	656 so that self knows the contained object can no longer be used. The
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	657 :cfunc:`Py_CLEAR` macro performs the operations in a safe order.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	658
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	659 Because the goal of :attr:`tp_clear` functions is to break reference cycles,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	660 it's not necessary to clear contained objects like Python strings or Python
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	661 integers, which can't participate in reference cycles. On the other hand, it may
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	662 be convenient to clear all contained Python objects, and write the type's
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	663 :attr:`tp_dealloc` function to invoke :attr:`tp_clear`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	664
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	665 More information about Python's garbage collection scheme can be found in
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	666 section :ref:`supporting-cycle-detection`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	667
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	668 This field is inherited by subtypes together with :attr:`tp_traverse` and the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	669 :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	670 :attr:`tp_clear` are all inherited from the base type if they are all zero in
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	671 the subtype and the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	672 bit set.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	673
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	674
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	675 .. cmember:: richcmpfunc PyTypeObject.tp_richcompare
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	676
44830 0f072edb3343 #1219903: fix tp_richcompare docs. Georg Brandl <georg@python.org> parents: 44796 diff changeset	677 An optional pointer to the rich comparison function, whose signature is
0f072edb3343 #1219903: fix tp_richcompare docs. Georg Brandl <georg@python.org> parents: 44796 diff changeset	678 ``PyObject tp_richcompare(PyObject a, PyObject *b, int op)``.
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	679
44830 0f072edb3343 #1219903: fix tp_richcompare docs. Georg Brandl <georg@python.org> parents: 44796 diff changeset	680 The function should return the result of the comparison (usually ``Py_True``
0f072edb3343 #1219903: fix tp_richcompare docs. Georg Brandl <georg@python.org> parents: 44796 diff changeset	681 or ``Py_False``). If the comparison is undefined, it must return
0f072edb3343 #1219903: fix tp_richcompare docs. Georg Brandl <georg@python.org> parents: 44796 diff changeset	682 ``Py_NotImplemented``, if another error occurred it must return ``NULL`` and
0f072edb3343 #1219903: fix tp_richcompare docs. Georg Brandl <georg@python.org> parents: 44796 diff changeset	683 set an exception condition.
0f072edb3343 #1219903: fix tp_richcompare docs. Georg Brandl <georg@python.org> parents: 44796 diff changeset	684
0f072edb3343 #1219903: fix tp_richcompare docs. Georg Brandl <georg@python.org> parents: 44796 diff changeset	685 .. note::
0f072edb3343 #1219903: fix tp_richcompare docs. Georg Brandl <georg@python.org> parents: 44796 diff changeset	686
0f072edb3343 #1219903: fix tp_richcompare docs. Georg Brandl <georg@python.org> parents: 44796 diff changeset	687 If you want to implement a type for which only a limited set of
0f072edb3343 #1219903: fix tp_richcompare docs. Georg Brandl <georg@python.org> parents: 44796 diff changeset	688 comparisons makes sense (e.g. ``==`` and ``!=``, but not ``<`` and
0f072edb3343 #1219903: fix tp_richcompare docs. Georg Brandl <georg@python.org> parents: 44796 diff changeset	689 friends), directly raise :exc:`TypeError` in the rich comparison function.
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	690
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	691 This field is inherited by subtypes together with :attr:`tp_compare` and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	692 :attr:`tp_hash`: a subtype inherits all three of :attr:`tp_compare`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	693 :attr:`tp_richcompare`, and :attr:`tp_hash`, when the subtype's
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	694 :attr:`tp_compare`, :attr:`tp_richcompare`, and :attr:`tp_hash` are all NULL.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	695
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	696 The following constants are defined to be used as the third argument for
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	697 :attr:`tp_richcompare` and for :cfunc:`PyObject_RichCompare`:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	698
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	699 +----------------+------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	700 \| Constant \| Comparison \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	701 +================+============+
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	702 \| :const:`Py_LT` \| ``<`` \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	703 +----------------+------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	704 \| :const:`Py_LE` \| ``<=`` \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	705 +----------------+------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	706 \| :const:`Py_EQ` \| ``==`` \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	707 +----------------+------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	708 \| :const:`Py_NE` \| ``!=`` \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	709 +----------------+------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	710 \| :const:`Py_GT` \| ``>`` \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	711 +----------------+------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	712 \| :const:`Py_GE` \| ``>=`` \|
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	713 +----------------+------------+
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	714
44830 0f072edb3343 #1219903: fix tp_richcompare docs. Georg Brandl <georg@python.org> parents: 44796 diff changeset	715
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	716 The next field only exists if the :const:`Py_TPFLAGS_HAVE_WEAKREFS` flag bit is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	717 set.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	718
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	719 .. cmember:: long PyTypeObject.tp_weaklistoffset
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	720
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	721 If the instances of this type are weakly referenceable, this field is greater
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	722 than zero and contains the offset in the instance structure of the weak
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	723 reference list head (ignoring the GC header, if present); this offset is used by
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	724 :cfunc:`PyObject_ClearWeakRefs` and the :cfunc:`PyWeakref_\*` functions. The
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	725 instance structure needs to include a field of type :ctype:`PyObject\*` which is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	726 initialized to NULL.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	727
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	728 Do not confuse this field with :attr:`tp_weaklist`; that is the list head for
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	729 weak references to the type object itself.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	730
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	731 This field is inherited by subtypes, but see the rules listed below. A subtype
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	732 may override this offset; this means that the subtype uses a different weak
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	733 reference list head than the base type. Since the list head is always found via
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	734 :attr:`tp_weaklistoffset`, this should not be a problem.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	735
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	736 When a type defined by a class statement has no :attr:`__slots__` declaration,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	737 and none of its base types are weakly referenceable, the type is made weakly
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	738 referenceable by adding a weak reference list head slot to the instance layout
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	739 and setting the :attr:`tp_weaklistoffset` of that slot's offset.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	740
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	741 When a type's :attr:`__slots__` declaration contains a slot named
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	742 :attr:`__weakref__`, that slot becomes the weak reference list head for
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	743 instances of the type, and the slot's offset is stored in the type's
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	744 :attr:`tp_weaklistoffset`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	745
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	746 When a type's :attr:`__slots__` declaration does not contain a slot named
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	747 :attr:`__weakref__`, the type inherits its :attr:`tp_weaklistoffset` from its
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	748 base type.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	749
50786 2d453b221bec Merged revisions 68292,68344,68361,68378,68424,68426,68429-68430,68450,68457,68480-68481,68493,68495,68499,68501,68512,68514-68515 via svnmerge from Georg Brandl <georg@python.org> parents: 48284 diff changeset	750 The next two fields only exist if the :const:`Py_TPFLAGS_HAVE_ITER` flag bit is
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	751 set.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	752
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	753
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	754 .. cmember:: getiterfunc PyTypeObject.tp_iter
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	755
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	756 An optional pointer to a function that returns an iterator for the object. Its
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	757 presence normally signals that the instances of this type are iterable (although
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	758 sequences may be iterable without this function, and classic instances always
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	759 have this function, even if they don't define an :meth:`__iter__` method).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	760
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	761 This function has the same signature as :cfunc:`PyObject_GetIter`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	762
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	763 This field is inherited by subtypes.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	764
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	765
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	766 .. cmember:: iternextfunc PyTypeObject.tp_iternext
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	767
46609 01be1c8f006b #2727: clarify tp_iternext docs. Georg Brandl <georg@python.org> parents: 45429 diff changeset	768 An optional pointer to a function that returns the next item in an iterator.
01be1c8f006b #2727: clarify tp_iternext docs. Georg Brandl <georg@python.org> parents: 45429 diff changeset	769 When the iterator is exhausted, it must return NULL; a :exc:`StopIteration`
01be1c8f006b #2727: clarify tp_iternext docs. Georg Brandl <georg@python.org> parents: 45429 diff changeset	770 exception may or may not be set. When another error occurs, it must return
01be1c8f006b #2727: clarify tp_iternext docs. Georg Brandl <georg@python.org> parents: 45429 diff changeset	771 NULL too. Its presence normally signals that the instances of this type
01be1c8f006b #2727: clarify tp_iternext docs. Georg Brandl <georg@python.org> parents: 45429 diff changeset	772 are iterators (although classic instances always have this function, even if
01be1c8f006b #2727: clarify tp_iternext docs. Georg Brandl <georg@python.org> parents: 45429 diff changeset	773 they don't define a :meth:`next` method).
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	774
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	775 Iterator types should also define the :attr:`tp_iter` function, and that
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	776 function should return the iterator instance itself (not a new iterator
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	777 instance).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	778
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	779 This function has the same signature as :cfunc:`PyIter_Next`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	780
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	781 This field is inherited by subtypes.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	782
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	783 The next fields, up to and including :attr:`tp_weaklist`, only exist if the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	784 :const:`Py_TPFLAGS_HAVE_CLASS` flag bit is set.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	785
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	786
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	787 .. cmember:: struct PyMethodDef* PyTypeObject.tp_methods
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	788
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	789 An optional pointer to a static NULL-terminated array of :ctype:`PyMethodDef`
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	790 structures, declaring regular methods of this type.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	791
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	792 For each entry in the array, an entry is added to the type's dictionary (see
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	793 :attr:`tp_dict` below) containing a method descriptor.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	794
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	795 This field is not inherited by subtypes (methods are inherited through a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	796 different mechanism).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	797
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	798
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	799 .. cmember:: struct PyMemberDef* PyTypeObject.tp_members
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	800
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	801 An optional pointer to a static NULL-terminated array of :ctype:`PyMemberDef`
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	802 structures, declaring regular data members (fields or slots) of instances of
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	803 this type.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	804
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	805 For each entry in the array, an entry is added to the type's dictionary (see
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	806 :attr:`tp_dict` below) containing a member descriptor.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	807
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	808 This field is not inherited by subtypes (members are inherited through a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	809 different mechanism).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	810
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	811
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	812 .. cmember:: struct PyGetSetDef* PyTypeObject.tp_getset
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	813
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	814 An optional pointer to a static NULL-terminated array of :ctype:`PyGetSetDef`
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	815 structures, declaring computed attributes of instances of this type.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	816
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	817 For each entry in the array, an entry is added to the type's dictionary (see
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	818 :attr:`tp_dict` below) containing a getset descriptor.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	819
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	820 This field is not inherited by subtypes (computed attributes are inherited
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	821 through a different mechanism).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	822
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	823 Docs for PyGetSetDef (XXX belong elsewhere)::
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	824
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	825 typedef PyObject (getter)(PyObject , void );
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	826 typedef int (setter)(PyObject , PyObject , void );
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	827
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	828 typedef struct PyGetSetDef {
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	829 char name; / attribute name */
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	830 getter get; /* C function to get the attribute */
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	831 setter set; /* C function to set the attribute */
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	832 char doc; / optional doc string */
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	833 void closure; / optional additional data for getter and setter */
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	834 } PyGetSetDef;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	835
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	836
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	837 .. cmember:: PyTypeObject* PyTypeObject.tp_base
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	838
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	839 An optional pointer to a base type from which type properties are inherited. At
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	840 this level, only single inheritance is supported; multiple inheritance require
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	841 dynamically creating a type object by calling the metatype.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	842
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	843 This field is not inherited by subtypes (obviously), but it defaults to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	844 ``&PyBaseObject_Type`` (which to Python programmers is known as the type
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	845 :class:`object`).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	846
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	847
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	848 .. cmember:: PyObject* PyTypeObject.tp_dict
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	849
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	850 The type's dictionary is stored here by :cfunc:`PyType_Ready`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	851
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	852 This field should normally be initialized to NULL before PyType_Ready is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	853 called; it may also be initialized to a dictionary containing initial attributes
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	854 for the type. Once :cfunc:`PyType_Ready` has initialized the type, extra
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	855 attributes for the type may be added to this dictionary only if they don't
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	856 correspond to overloaded operations (like :meth:`__add__`).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	857
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	858 This field is not inherited by subtypes (though the attributes defined in here
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	859 are inherited through a different mechanism).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	860
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	861
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	862 .. cmember:: descrgetfunc PyTypeObject.tp_descr_get
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	863
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	864 An optional pointer to a "descriptor get" function.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	865
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	866 The function signature is ::
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	867
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	868 PyObject * tp_descr_get(PyObject self, PyObject obj, PyObject *type);
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	869
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	870 XXX explain.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	871
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	872 This field is inherited by subtypes.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	873
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	874
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	875 .. cmember:: descrsetfunc PyTypeObject.tp_descr_set
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	876
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	877 An optional pointer to a "descriptor set" function.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	878
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	879 The function signature is ::
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	880
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	881 int tp_descr_set(PyObject self, PyObject obj, PyObject *value);
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	882
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	883 This field is inherited by subtypes.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	884
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	885 XXX explain.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	886
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	887
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	888 .. cmember:: long PyTypeObject.tp_dictoffset
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	889
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	890 If the instances of this type have a dictionary containing instance variables,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	891 this field is non-zero and contains the offset in the instances of the type of
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	892 the instance variable dictionary; this offset is used by
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	893 :cfunc:`PyObject_GenericGetAttr`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	894
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	895 Do not confuse this field with :attr:`tp_dict`; that is the dictionary for
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	896 attributes of the type object itself.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	897
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	898 If the value of this field is greater than zero, it specifies the offset from
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	899 the start of the instance structure. If the value is less than zero, it
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	900 specifies the offset from the end of the instance structure. A negative
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	901 offset is more expensive to use, and should only be used when the instance
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	902 structure contains a variable-length part. This is used for example to add an
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	903 instance variable dictionary to subtypes of :class:`str` or :class:`tuple`. Note
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	904 that the :attr:`tp_basicsize` field should account for the dictionary added to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	905 the end in that case, even though the dictionary is not included in the basic
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	906 object layout. On a system with a pointer size of 4 bytes,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	907 :attr:`tp_dictoffset` should be set to ``-4`` to indicate that the dictionary is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	908 at the very end of the structure.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	909
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	910 The real dictionary offset in an instance can be computed from a negative
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	911 :attr:`tp_dictoffset` as follows::
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	912
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	913 dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	914 if dictoffset is not aligned on sizeof(void*):
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	915 round up to sizeof(void*)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	916
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	917 where :attr:`tp_basicsize`, :attr:`tp_itemsize` and :attr:`tp_dictoffset` are
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	918 taken from the type object, and :attr:`ob_size` is taken from the instance. The
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	919 absolute value is taken because long ints use the sign of :attr:`ob_size` to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	920 store the sign of the number. (There's never a need to do this calculation
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	921 yourself; it is done for you by :cfunc:`_PyObject_GetDictPtr`.)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	922
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	923 This field is inherited by subtypes, but see the rules listed below. A subtype
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	924 may override this offset; this means that the subtype instances store the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	925 dictionary at a difference offset than the base type. Since the dictionary is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	926 always found via :attr:`tp_dictoffset`, this should not be a problem.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	927
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	928 When a type defined by a class statement has no :attr:`__slots__` declaration,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	929 and none of its base types has an instance variable dictionary, a dictionary
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	930 slot is added to the instance layout and the :attr:`tp_dictoffset` is set to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	931 that slot's offset.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	932
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	933 When a type defined by a class statement has a :attr:`__slots__` declaration,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	934 the type inherits its :attr:`tp_dictoffset` from its base type.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	935
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	936 (Adding a slot named :attr:`__dict__` to the :attr:`__slots__` declaration does
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	937 not have the expected effect, it just causes confusion. Maybe this should be
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	938 added as a feature just like :attr:`__weakref__` though.)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	939
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	940
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	941 .. cmember:: initproc PyTypeObject.tp_init
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	942
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	943 An optional pointer to an instance initialization function.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	944
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	945 This function corresponds to the :meth:`__init__` method of classes. Like
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	946 :meth:`__init__`, it is possible to create an instance without calling
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	947 :meth:`__init__`, and it is possible to reinitialize an instance by calling its
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	948 :meth:`__init__` method again.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	949
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	950 The function signature is ::
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	951
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	952 int tp_init(PyObject self, PyObject args, PyObject *kwds)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	953
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	954 The self argument is the instance to be initialized; the args and kwds
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	955 arguments represent positional and keyword arguments of the call to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	956 :meth:`__init__`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	957
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	958 The :attr:`tp_init` function, if not NULL, is called when an instance is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	959 created normally by calling its type, after the type's :attr:`tp_new` function
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	960 has returned an instance of the type. If the :attr:`tp_new` function returns an
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	961 instance of some other type that is not a subtype of the original type, no
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	962 :attr:`tp_init` function is called; if :attr:`tp_new` returns an instance of a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	963 subtype of the original type, the subtype's :attr:`tp_init` is called. (VERSION
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	964 NOTE: described here is what is implemented in Python 2.2.1 and later. In
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	965 Python 2.2, the :attr:`tp_init` of the type of the object returned by
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	966 :attr:`tp_new` was always called, if not NULL.)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	967
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	968 This field is inherited by subtypes.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	969
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	970
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	971 .. cmember:: allocfunc PyTypeObject.tp_alloc
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	972
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	973 An optional pointer to an instance allocation function.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	974
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	975 The function signature is ::
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	976
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	977 PyObject tp_alloc(PyTypeObject self, Py_ssize_t nitems)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	978
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	979 The purpose of this function is to separate memory allocation from memory
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	980 initialization. It should return a pointer to a block of memory of adequate
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	981 length for the instance, suitably aligned, and initialized to zeros, but with
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	982 :attr:`ob_refcnt` set to ``1`` and :attr:`ob_type` set to the type argument. If
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	983 the type's :attr:`tp_itemsize` is non-zero, the object's :attr:`ob_size` field
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	984 should be initialized to nitems and the length of the allocated memory block
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	985 should be ``tp_basicsize + nitems*tp_itemsize``, rounded up to a multiple of
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	986 ``sizeof(void)``; otherwise, nitems* is not used and the length of the block
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	987 should be :attr:`tp_basicsize`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	988
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	989 Do not use this function to do any other instance initialization, not even to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	990 allocate additional memory; that should be done by :attr:`tp_new`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	991
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	992 This field is inherited by static subtypes, but not by dynamic subtypes
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	993 (subtypes created by a class statement); in the latter, this field is always set
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	994 to :cfunc:`PyType_GenericAlloc`, to force a standard heap allocation strategy.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	995 That is also the recommended value for statically defined types.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	996
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	997
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	998 .. cmember:: newfunc PyTypeObject.tp_new
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	999
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1000 An optional pointer to an instance creation function.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1001
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1002 If this function is NULL for a particular type, that type cannot be called to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1003 create new instances; presumably there is some other way to create instances,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1004 like a factory function.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1005
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1006 The function signature is ::
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1007
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1008 PyObject tp_new(PyTypeObject subtype, PyObject args, PyObject kwds)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1009
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1010 The subtype argument is the type of the object being created; the args and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1011 kwds arguments represent positional and keyword arguments of the call to the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1012 type. Note that subtype doesn't have to equal the type whose :attr:`tp_new`
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1013 function is called; it may be a subtype of that type (but not an unrelated
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1014 type).
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1015
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1016 The :attr:`tp_new` function should call ``subtype->tp_alloc(subtype, nitems)``
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1017 to allocate space for the object, and then do only as much further
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1018 initialization as is absolutely necessary. Initialization that can safely be
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1019 ignored or repeated should be placed in the :attr:`tp_init` handler. A good
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1020 rule of thumb is that for immutable types, all initialization should take place
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1021 in :attr:`tp_new`, while for mutable types, most initialization should be
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1022 deferred to :attr:`tp_init`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1023
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1024 This field is inherited by subtypes, except it is not inherited by static types
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1025 whose :attr:`tp_base` is NULL or ``&PyBaseObject_Type``. The latter exception
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1026 is a precaution so that old extension types don't become callable simply by
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1027 being linked with Python 2.2.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1028
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1029
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1030 .. cmember:: destructor PyTypeObject.tp_free
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1031
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1032 An optional pointer to an instance deallocation function.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1033
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1034 The signature of this function has changed slightly: in Python 2.2 and 2.2.1,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1035 its signature is :ctype:`destructor`::
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1036
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1037 void tp_free(PyObject *)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1038
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1039 In Python 2.3 and beyond, its signature is :ctype:`freefunc`::
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1040
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1041 void tp_free(void *)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1042
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1043 The only initializer that is compatible with both versions is ``_PyObject_Del``,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1044 whose definition has suitably adapted in Python 2.3.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1045
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1046 This field is inherited by static subtypes, but not by dynamic subtypes
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1047 (subtypes created by a class statement); in the latter, this field is set to a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1048 deallocator suitable to match :cfunc:`PyType_GenericAlloc` and the value of the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1049 :const:`Py_TPFLAGS_HAVE_GC` flag bit.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1050
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1051
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1052 .. cmember:: inquiry PyTypeObject.tp_is_gc
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1053
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1054 An optional pointer to a function called by the garbage collector.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1055
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1056 The garbage collector needs to know whether a particular object is collectible
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1057 or not. Normally, it is sufficient to look at the object's type's
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1058 :attr:`tp_flags` field, and check the :const:`Py_TPFLAGS_HAVE_GC` flag bit. But
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1059 some types have a mixture of statically and dynamically allocated instances, and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1060 the statically allocated instances are not collectible. Such types should
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1061 define this function; it should return ``1`` for a collectible instance, and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1062 ``0`` for a non-collectible instance. The signature is ::
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1063
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1064 int tp_is_gc(PyObject *self)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1065
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1066 (The only example of this are types themselves. The metatype,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1067 :cdata:`PyType_Type`, defines this function to distinguish between statically
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1068 and dynamically allocated types.)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1069
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1070 This field is inherited by subtypes. (VERSION NOTE: in Python 2.2, it was not
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1071 inherited. It is inherited in 2.2.1 and later versions.)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1072
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1073
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1074 .. cmember:: PyObject* PyTypeObject.tp_bases
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1075
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1076 Tuple of base types.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1077
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1078 This is set for types created by a class statement. It should be NULL for
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1079 statically defined types.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1080
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1081 This field is not inherited.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1082
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1083
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1084 .. cmember:: PyObject* PyTypeObject.tp_mro
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1085
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1086 Tuple containing the expanded set of base types, starting with the type itself
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1087 and ending with :class:`object`, in Method Resolution Order.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1088
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1089 This field is not inherited; it is calculated fresh by :cfunc:`PyType_Ready`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1090
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1091
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1092 .. cmember:: PyObject* PyTypeObject.tp_cache
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1093
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1094 Unused. Not inherited. Internal use only.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1095
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1096
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1097 .. cmember:: PyObject* PyTypeObject.tp_subclasses
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1098
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1099 List of weak references to subclasses. Not inherited. Internal use only.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1100
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1101
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1102 .. cmember:: PyObject* PyTypeObject.tp_weaklist
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1103
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1104 Weak reference list head, for weak references to this type object. Not
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1105 inherited. Internal use only.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1106
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1107 The remaining fields are only defined if the feature test macro
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1108 :const:`COUNT_ALLOCS` is defined, and are for internal use only. They are
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1109 documented here for completeness. None of these fields are inherited by
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1110 subtypes.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1111
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1112
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1113 .. cmember:: Py_ssize_t PyTypeObject.tp_allocs
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1114
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1115 Number of allocations.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1116
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1117
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1118 .. cmember:: Py_ssize_t PyTypeObject.tp_frees
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1119
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1120 Number of frees.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1121
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1122
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1123 .. cmember:: Py_ssize_t PyTypeObject.tp_maxalloc
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1124
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1125 Maximum simultaneously allocated objects.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1126
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1127
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1128 .. cmember:: PyTypeObject* PyTypeObject.tp_next
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1129
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1130 Pointer to the next type object with a non-zero :attr:`tp_allocs` field.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1131
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1132 Also, note that, in a garbage collected Python, tp_dealloc may be called from
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1133 any Python thread, not just the thread which created the object (if the object
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1134 becomes part of a refcount cycle, that cycle might be collected by a garbage
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1135 collection on any thread). This is not a problem for Python API calls, since
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1136 the thread on which tp_dealloc is called will own the Global Interpreter Lock
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1137 (GIL). However, if the object being destroyed in turn destroys objects from some
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1138 other C or C++ library, care should be taken to ensure that destroying those
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1139 objects on the thread which called tp_dealloc will not violate any assumptions
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1140 of the library.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1141
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1142
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1143 .. _number-structs:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1144
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1145 Number Object Structures
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1146 ========================
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1147
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1148 .. sectionauthor:: Amaury Forgeot d'Arc
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1149
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1150
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1151 .. ctype:: PyNumberMethods
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1152
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1153 This structure holds pointers to the functions which an object uses to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1154 implement the number protocol. Almost every function below is used by the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1155 function of similar name documented in the :ref:`number` section.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1156
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1157 Here is the structure definition::
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1158
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1159 typedef struct {
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1160 binaryfunc nb_add;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1161 binaryfunc nb_subtract;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1162 binaryfunc nb_multiply;
56819 9b24d010133f Merged revisions 74210,74239,74252-74253,74256,74258-74261,74332-74333,74404,74411,74445,74465,74467,74488 via svnmerge from Georg Brandl <georg@python.org> parents: 53588 diff changeset	1163 binaryfunc nb_divide;
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1164 binaryfunc nb_remainder;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1165 binaryfunc nb_divmod;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1166 ternaryfunc nb_power;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1167 unaryfunc nb_negative;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1168 unaryfunc nb_positive;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1169 unaryfunc nb_absolute;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1170 inquiry nb_nonzero; /* Used by PyObject_IsTrue */
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1171 unaryfunc nb_invert;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1172 binaryfunc nb_lshift;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1173 binaryfunc nb_rshift;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1174 binaryfunc nb_and;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1175 binaryfunc nb_xor;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1176 binaryfunc nb_or;
45429 853af5bbb497 A lot more typo fixes by Ori Avtalion. Georg Brandl <georg@python.org> parents: 44830 diff changeset	1177 coercion nb_coerce; /* Used by the coerce() function */
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1178 unaryfunc nb_int;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1179 unaryfunc nb_long;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1180 unaryfunc nb_float;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1181 unaryfunc nb_oct;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1182 unaryfunc nb_hex;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1183
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1184 /* Added in release 2.0 */
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1185 binaryfunc nb_inplace_add;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1186 binaryfunc nb_inplace_subtract;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1187 binaryfunc nb_inplace_multiply;
52909 f3b26a729e82 Merged revisions 69578-69580,69901,69907,69994,70022-70023,70025-70026,70166,70273,70275,70342,70386-70387,70389-70390,70392-70393,70395,70397,70400,70418 via svnmerge Georg Brandl <georg@python.org> parents: 50786 diff changeset	1188 binaryfunc nb_inplace_divide;
44796 13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1189 binaryfunc nb_inplace_remainder;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1190 ternaryfunc nb_inplace_power;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1191 binaryfunc nb_inplace_lshift;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1192 binaryfunc nb_inplace_rshift;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1193 binaryfunc nb_inplace_and;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1194 binaryfunc nb_inplace_xor;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1195 binaryfunc nb_inplace_or;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1196
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1197 /* Added in release 2.2 */
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1198 binaryfunc nb_floor_divide;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1199 binaryfunc nb_true_divide;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1200 binaryfunc nb_inplace_floor_divide;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1201 binaryfunc nb_inplace_true_divide;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1202
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1203 /* Added in release 2.5 */
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1204 unaryfunc nb_index;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1205 } PyNumberMethods;
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1206
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1207
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1208 Binary and ternary functions may receive different kinds of arguments, depending
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1209 on the flag bit :const:`Py_TPFLAGS_CHECKTYPES`:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1210
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1211 - If :const:`Py_TPFLAGS_CHECKTYPES` is not set, the function arguments are
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1212 guaranteed to be of the object's type; the caller is responsible for calling
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1213 the coercion method specified by the :attr:`nb_coerce` member to convert the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1214 arguments:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1215
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1216 .. cmember:: coercion PyNumberMethods.nb_coerce
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1217
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1218 This function is used by :cfunc:`PyNumber_CoerceEx` and has the same
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1219 signature. The first argument is always a pointer to an object of the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1220 defined type. If the conversion to a common "larger" type is possible, the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1221 function replaces the pointers with new references to the converted objects
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1222 and returns ``0``. If the conversion is not possible, the function returns
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1223 ``1``. If an error condition is set, it will return ``-1``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1224
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1225 - If the :const:`Py_TPFLAGS_CHECKTYPES` flag is set, binary and ternary
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1226 functions must check the type of all their operands, and implement the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1227 necessary conversions (at least one of the operands is an instance of the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1228 defined type). This is the recommended way; with Python 3.0 coercion will
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1229 disappear completely.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1230
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1231 If the operation is not defined for the given operands, binary and ternary
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1232 functions must return ``Py_NotImplemented``, if another error occurred they must
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1233 return ``NULL`` and set an exception.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1234
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1235
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1236 .. _mapping-structs:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1237
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1238 Mapping Object Structures
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1239 =========================
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1240
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1241 .. sectionauthor:: Amaury Forgeot d'Arc
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1242
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1243
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1244 .. ctype:: PyMappingMethods
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1245
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1246 This structure holds pointers to the functions which an object uses to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1247 implement the mapping protocol. It has three members:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1248
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1249 .. cmember:: lenfunc PyMappingMethods.mp_length
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1250
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1251 This function is used by :cfunc:`PyMapping_Length` and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1252 :cfunc:`PyObject_Size`, and has the same signature. This slot may be set to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1253 NULL if the object has no defined length.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1254
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1255 .. cmember:: binaryfunc PyMappingMethods.mp_subscript
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1256
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1257 This function is used by :cfunc:`PyObject_GetItem` and has the same
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1258 signature. This slot must be filled for the :cfunc:`PyMapping_Check`
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1259 function to return ``1``, it can be NULL otherwise.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1260
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1261 .. cmember:: objobjargproc PyMappingMethods.mp_ass_subscript
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1262
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1263 This function is used by :cfunc:`PyObject_SetItem` and has the same
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1264 signature. If this slot is NULL, the object does not support item
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1265 assignment.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1266
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1267
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1268 .. _sequence-structs:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1269
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1270 Sequence Object Structures
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1271 ==========================
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1272
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1273 .. sectionauthor:: Amaury Forgeot d'Arc
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1274
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1275
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1276 .. ctype:: PySequenceMethods
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1277
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1278 This structure holds pointers to the functions which an object uses to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1279 implement the sequence protocol.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1280
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1281 .. cmember:: lenfunc PySequenceMethods.sq_length
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1282
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1283 This function is used by :cfunc:`PySequence_Size` and :cfunc:`PyObject_Size`,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1284 and has the same signature.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1285
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1286 .. cmember:: binaryfunc PySequenceMethods.sq_concat
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1287
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1288 This function is used by :cfunc:`PySequence_Concat` and has the same
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1289 signature. It is also used by the ``+`` operator, after trying the numeric
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1290 addition via the :attr:`tp_as_number.nb_add` slot.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1291
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1292 .. cmember:: ssizeargfunc PySequenceMethods.sq_repeat
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1293
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1294 This function is used by :cfunc:`PySequence_Repeat` and has the same
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1295 signature. It is also used by the ``*`` operator, after trying numeric
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1296 multiplication via the :attr:`tp_as_number.nb_mul` slot.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1297
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1298 .. cmember:: ssizeargfunc PySequenceMethods.sq_item
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1299
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1300 This function is used by :cfunc:`PySequence_GetItem` and has the same
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1301 signature. This slot must be filled for the :cfunc:`PySequence_Check`
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1302 function to return ``1``, it can be NULL otherwise.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1303
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1304 Negative indexes are handled as follows: if the :attr:`sq_length` slot is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1305 filled, it is called and the sequence length is used to compute a positive
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1306 index which is passed to :attr:`sq_item`. If :attr:`sq_length` is NULL,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1307 the index is passed as is to the function.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1308
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1309 .. cmember:: ssizeobjargproc PySequenceMethods.sq_ass_item
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1310
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1311 This function is used by :cfunc:`PySequence_SetItem` and has the same
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1312 signature. This slot may be left to NULL if the object does not support
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1313 item assignment.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1314
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1315 .. cmember:: objobjproc PySequenceMethods.sq_contains
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1316
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1317 This function may be used by :cfunc:`PySequence_Contains` and has the same
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1318 signature. This slot may be left to NULL, in this case
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1319 :cfunc:`PySequence_Contains` simply traverses the sequence until it finds a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1320 match.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1321
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1322 .. cmember:: binaryfunc PySequenceMethods.sq_inplace_concat
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1323
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1324 This function is used by :cfunc:`PySequence_InPlaceConcat` and has the same
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1325 signature. It should modify its first operand, and return it.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1326
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1327 .. cmember:: ssizeargfunc PySequenceMethods.sq_inplace_repeat
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1328
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1329 This function is used by :cfunc:`PySequence_InPlaceRepeat` and has the same
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1330 signature. It should modify its first operand, and return it.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1331
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1332 .. XXX need to explain precedence between mapping and sequence
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1333 .. XXX explains when to implement the sq_inplace_* slots
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1334
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1335
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1336 .. _buffer-structs:
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1337
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1338 Buffer Object Structures
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1339 ========================
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1340
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1341 .. sectionauthor:: Greg J. Stein <greg@lyra.org>
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1342
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1343
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1344 The buffer interface exports a model where an object can expose its internal
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1345 data as a set of chunks of data, where each chunk is specified as a
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1346 pointer/length pair. These chunks are called :dfn:`segments` and are presumed
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1347 to be non-contiguous in memory.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1348
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1349 If an object does not export the buffer interface, then its :attr:`tp_as_buffer`
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1350 member in the :ctype:`PyTypeObject` structure should be NULL. Otherwise, the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1351 :attr:`tp_as_buffer` will point to a :ctype:`PyBufferProcs` structure.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1352
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1353 .. note::
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1354
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1355 It is very important that your :ctype:`PyTypeObject` structure uses
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1356 :const:`Py_TPFLAGS_DEFAULT` for the value of the :attr:`tp_flags` member rather
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1357 than ``0``. This tells the Python runtime that your :ctype:`PyBufferProcs`
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1358 structure contains the :attr:`bf_getcharbuffer` slot. Older versions of Python
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1359 did not have this member, so a new Python interpreter using an old extension
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1360 needs to be able to test for its presence before using it.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1361
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1362
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1363 .. ctype:: PyBufferProcs
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1364
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1365 Structure used to hold the function pointers which define an implementation of
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1366 the buffer protocol.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1367
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1368 The first slot is :attr:`bf_getreadbuffer`, of type :ctype:`getreadbufferproc`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1369 If this slot is NULL, then the object does not support reading from the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1370 internal data. This is non-sensical, so implementors should fill this in, but
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1371 callers should test that the slot contains a non-NULL value.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1372
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1373 The next slot is :attr:`bf_getwritebuffer` having type
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1374 :ctype:`getwritebufferproc`. This slot may be NULL if the object does not
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1375 allow writing into its returned buffers.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1376
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1377 The third slot is :attr:`bf_getsegcount`, with type :ctype:`getsegcountproc`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1378 This slot must not be NULL and is used to inform the caller how many segments
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1379 the object contains. Simple objects such as :ctype:`PyString_Type` and
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1380 :ctype:`PyBuffer_Type` objects contain a single segment.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1381
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1382 .. index:: single: PyType_HasFeature()
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1383
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1384 The last slot is :attr:`bf_getcharbuffer`, of type :ctype:`getcharbufferproc`.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1385 This slot will only be present if the :const:`Py_TPFLAGS_HAVE_GETCHARBUFFER`
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1386 flag is present in the :attr:`tp_flags` field of the object's
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1387 :ctype:`PyTypeObject`. Before using this slot, the caller should test whether it
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1388 is present by using the :cfunc:`PyType_HasFeature` function. If the flag is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1389 present, :attr:`bf_getcharbuffer` may be NULL, indicating that the object's
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1390 contents cannot be used as 8-bit characters. The slot function may also raise
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1391 an error if the object's contents cannot be interpreted as 8-bit characters.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1392 For example, if the object is an array which is configured to hold floating
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1393 point values, an exception may be raised if a caller attempts to use
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1394 :attr:`bf_getcharbuffer` to fetch a sequence of 8-bit characters. This notion of
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1395 exporting the internal buffers as "text" is used to distinguish between objects
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1396 that are binary in nature, and those which have character-based content.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1397
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1398 .. note::
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1399
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1400 The current policy seems to state that these characters may be multi-byte
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1401 characters. This implies that a buffer size of N does not mean there are N
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1402 characters present.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1403
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1404
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1405 .. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1406
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1407 Flag bit set in the type structure to indicate that the :attr:`bf_getcharbuffer`
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1408 slot is known. This being set does not indicate that the object supports the
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1409 buffer interface or that the :attr:`bf_getcharbuffer` slot is non-NULL.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1410
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1411
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1412 .. ctype:: Py_ssize_t (readbufferproc) (PyObject self, Py_ssize_t segment, void **ptrptr)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1413
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1414 Return a pointer to a readable segment of the buffer in ``*ptrptr``. This
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1415 function is allowed to raise an exception, in which case it must return ``-1``.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1416 The segment which is specified must be zero or positive, and strictly less
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1417 than the number of segments returned by the :attr:`bf_getsegcount` slot
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1418 function. On success, it returns the length of the segment, and sets
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1419 ``*ptrptr`` to a pointer to that memory.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1420
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1421
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1422 .. ctype:: Py_ssize_t (writebufferproc) (PyObject self, Py_ssize_t segment, void **ptrptr)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1423
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1424 Return a pointer to a writable memory buffer in ``*ptrptr``, and the length of
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1425 that segment as the function return value. The memory buffer must correspond to
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1426 buffer segment segment. Must return ``-1`` and set an exception on error.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1427 :exc:`TypeError` should be raised if the object only supports read-only buffers,
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1428 and :exc:`SystemError` should be raised when segment specifies a segment that
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1429 doesn't exist.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1430
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1431 .. Why doesn't it raise ValueError for this one?
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1432 GJS: because you shouldn't be calling it with an invalid
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1433 segment. That indicates a blatant programming error in the C code.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1434
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1435
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1436 .. ctype:: Py_ssize_t (segcountproc) (PyObject self, Py_ssize_t *lenp)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1437
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1438 Return the number of memory segments which comprise the buffer. If lenp is
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1439 not NULL, the implementation must report the sum of the sizes (in bytes) of
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1440 all segments in ``*lenp``. The function cannot fail.
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1441
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1442
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1443 .. ctype:: Py_ssize_t (charbufferproc) (PyObject self, Py_ssize_t segment, const char **ptrptr)
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1444
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1445 Return the size of the segment segment that ptrptr is set to. ``*ptrptr``
13dc65fe8599 Split the monstrous C API manual files in smaller parts. Georg Brandl <georg@python.org> parents: diff changeset	1446 is set to the memory buffer. Returns ``-1`` on error.

Mercurial > cpython-lru_cache-weakref

annotate Doc/c-api/typeobj.rst @ 58925:eecf1bef052d 2.6