cpython-lru_cache-weakref: Doc/api/newtypes.tex annotate

annotate Doc/api/newtypes.tex @ 27998:e27f58a50737 legacy-trunk

SF bug #690377: Dud footnote reference in distutils docs

author	Raymond Hettinger <python@rcn.com>
date	Fri, 21 Feb 2003 02:47:09 +0000
parents	b0539a450917
children	9070404f24fa

rev	line source
22857 e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 22613 diff changeset	1 \chapter{Object Implementation Support \label{newTypes}}
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 22613 diff changeset	2
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 22613 diff changeset	3
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 22613 diff changeset	4 This chapter describes the functions, types, and macros used when
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 22613 diff changeset	5 defining new object types.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	6
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	7
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	8 \section{Allocating Objects on the Heap
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	9 \label{allocating-objects}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	10
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	11 \begin{cfuncdesc}{PyObject}{_PyObject_New}{PyTypeObject type}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	12 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	13
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	14 \begin{cfuncdesc}{PyVarObject}{_PyObject_NewVar}{PyTypeObject type, int size}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	15 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	16
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	17 \begin{cfuncdesc}{void}{_PyObject_Del}{PyObject *op}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	18 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	19
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	20 \begin{cfuncdesc}{PyObject}{PyObject_Init}{PyObject op,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	21 PyTypeObject *type}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	22 Initialize a newly-allocated object \var{op} with its type and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	23 initial reference. Returns the initialized object. If \var{type}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	24 indicates that the object participates in the cyclic garbage
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	25 detector, it it added to the detector's set of observed objects.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	26 Other fields of the object are not affected.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	27 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	28
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	29 \begin{cfuncdesc}{PyVarObject}{PyObject_InitVar}{PyVarObject op,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	30 PyTypeObject *type, int size}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	31 This does everything \cfunction{PyObject_Init()} does, and also
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	32 initializes the length information for a variable-size object.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	33 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	34
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	35 \begin{cfuncdesc}{\var{TYPE}}{PyObject_New}{TYPE, PyTypeObject type}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	36 Allocate a new Python object using the C structure type \var{TYPE}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	37 and the Python type object \var{type}. Fields not defined by the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	38 Python object header are not initialized; the object's reference
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	39 count will be one. The size of the memory
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	40 allocation is determined from the \member{tp_basicsize} field of the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	41 type object.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	42 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	43
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	44 \begin{cfuncdesc}{\var{TYPE}}{PyObject_NewVar}{TYPE, PyTypeObject type,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	45 int size}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	46 Allocate a new Python object using the C structure type \var{TYPE}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	47 and the Python type object \var{type}. Fields not defined by the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	48 Python object header are not initialized. The allocated memory
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	49 allows for the \var{TYPE} structure plus \var{size} fields of the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	50 size given by the \member{tp_itemsize} field of \var{type}. This is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	51 useful for implementing objects like tuples, which are able to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	52 determine their size at construction time. Embedding the array of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	53 fields into the same allocation decreases the number of allocations,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	54 improving the memory management efficiency.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	55 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	56
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	57 \begin{cfuncdesc}{void}{PyObject_Del}{PyObject *op}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	58 Releases memory allocated to an object using
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	59 \cfunction{PyObject_New()} or \cfunction{PyObject_NewVar()}. This
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	60 is normally called from the \member{tp_dealloc} handler specified in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	61 the object's type. The fields of the object should not be accessed
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	62 after this call as the memory is no longer a valid Python object.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	63 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	64
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	65 \begin{cfuncdesc}{\var{TYPE}}{PyObject_NEW}{TYPE, PyTypeObject type}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	66 Macro version of \cfunction{PyObject_New()}, to gain performance at
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	67 the expense of safety. This does not check \var{type} for a \NULL{}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	68 value.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	69 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	70
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	71 \begin{cfuncdesc}{\var{TYPE}}{PyObject_NEW_VAR}{TYPE, PyTypeObject type,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	72 int size}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	73 Macro version of \cfunction{PyObject_NewVar()}, to gain performance
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	74 at the expense of safety. This does not check \var{type} for a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	75 \NULL{} value.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	76 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	77
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	78 \begin{cfuncdesc}{void}{PyObject_DEL}{PyObject *op}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	79 Macro version of \cfunction{PyObject_Del()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	80 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	81
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	82 \begin{cfuncdesc}{PyObject}{Py_InitModule}{char name,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	83 PyMethodDef *methods}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	84 Create a new module object based on a name and table of functions,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	85 returning the new module object.
24835 e399d0a875b7 Py_InitModule() and friends now accept NULL for the 'methods' Fred Drake <fdrake@acm.org> parents: 24603 diff changeset	86
e399d0a875b7 Py_InitModule() and friends now accept NULL for the 'methods' Fred Drake <fdrake@acm.org> parents: 24603 diff changeset	87 \versionchanged[Older versions of Python did not support \NULL{} as
e399d0a875b7 Py_InitModule() and friends now accept NULL for the 'methods' Fred Drake <fdrake@acm.org> parents: 24603 diff changeset	88 the value for the \var{methods} argument]{2.3}
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	89 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	90
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	91 \begin{cfuncdesc}{PyObject}{Py_InitModule3}{char name,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	92 PyMethodDef *methods,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	93 char *doc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	94 Create a new module object based on a name and table of functions,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	95 returning the new module object. If \var{doc} is non-\NULL, it will
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	96 be used to define the docstring for the module.
24835 e399d0a875b7 Py_InitModule() and friends now accept NULL for the 'methods' Fred Drake <fdrake@acm.org> parents: 24603 diff changeset	97
e399d0a875b7 Py_InitModule() and friends now accept NULL for the 'methods' Fred Drake <fdrake@acm.org> parents: 24603 diff changeset	98 \versionchanged[Older versions of Python did not support \NULL{} as
e399d0a875b7 Py_InitModule() and friends now accept NULL for the 'methods' Fred Drake <fdrake@acm.org> parents: 24603 diff changeset	99 the value for the \var{methods} argument]{2.3}
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	100 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	101
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	102 \begin{cfuncdesc}{PyObject}{Py_InitModule4}{char name,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	103 PyMethodDef *methods,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	104 char doc, PyObject self,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	105 int apiver}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	106 Create a new module object based on a name and table of functions,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	107 returning the new module object. If \var{doc} is non-\NULL, it will
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	108 be used to define the docstring for the module. If \var{self} is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	109 non-\NULL, it will passed to the functions of the module as their
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	110 (otherwise \NULL) first parameter. (This was added as an
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	111 experimental feature, and there are no known uses in the current
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	112 version of Python.) For \var{apiver}, the only value which should
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	113 be passed is defined by the constant \constant{PYTHON_API_VERSION}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	114
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	115 \note{Most uses of this function should probably be using
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	116 the \cfunction{Py_InitModule3()} instead; only use this if you are
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	117 sure you need it.}
24835 e399d0a875b7 Py_InitModule() and friends now accept NULL for the 'methods' Fred Drake <fdrake@acm.org> parents: 24603 diff changeset	118
e399d0a875b7 Py_InitModule() and friends now accept NULL for the 'methods' Fred Drake <fdrake@acm.org> parents: 24603 diff changeset	119 \versionchanged[Older versions of Python did not support \NULL{} as
e399d0a875b7 Py_InitModule() and friends now accept NULL for the 'methods' Fred Drake <fdrake@acm.org> parents: 24603 diff changeset	120 the value for the \var{methods} argument]{2.3}
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	121 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	122
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	123 DL_IMPORT
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	124
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	125 \begin{cvardesc}{PyObject}{_Py_NoneStruct}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	126 Object which is visible in Python as \code{None}. This should only
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	127 be accessed using the \code{Py_None} macro, which evaluates to a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	128 pointer to this object.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	129 \end{cvardesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	130
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	131
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	132 \section{Common Object Structures \label{common-structs}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	133
22926 3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	134 There are a large number of structures which are used in the
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	135 definition of object types for Python. This section describes these
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	136 structures and how they are used.
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	137
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	138 All Python objects ultimately share a small number of fields at the
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	139 beginning of the object's representation in memory. These are
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	140 represented by the \ctype{PyObject} and \ctype{PyVarObject} types,
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	141 which are defined, in turn, by the expansions of some macros also
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	142 used, whether directly or indirectly, in the definition of all other
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	143 Python objects.
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	144
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	145 \begin{ctypedesc}{PyObject}
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	146 All object types are extensions of this type. This is a type which
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	147 contains the information Python needs to treat a pointer to an
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	148 object as an object. In a normal ``release'' build, it contains
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	149 only the objects reference count and a pointer to the corresponding
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	150 type object. It corresponds to the fields defined by the
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	151 expansion of the \code{PyObject_VAR_HEAD} macro.
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	152 \end{ctypedesc}
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	153
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	154 \begin{ctypedesc}{PyVarObject}
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	155 This is an extension of \ctype{PyObject} that adds the
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	156 \member{ob_size} field. This is only used for objects that have
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	157 some notion of \emph{length}. This type does not often appear in
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	158 the Python/C API. It corresponds to the fields defined by the
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	159 expansion of the \code{PyObject_VAR_HEAD} macro.
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	160 \end{ctypedesc}
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	161
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	162 These macros are used in the definition of \ctype{PyObject} and
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	163 \ctype{PyVarObject}:
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	164
22926 3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	165 \begin{csimplemacrodesc}{PyObject_HEAD}
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	166 This is a macro which expands to the declarations of the fields of
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	167 the \ctype{PyObject} type; it is used when declaring new types which
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	168 represent objects without a varying length. The specific fields it
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	169 expands to depends on the definition of
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	170 \csimplemacro{Py_TRACE_REFS}. By default, that macro is not
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	171 defined, and \csimplemacro{PyObject_HEAD} expands to:
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	172 \begin{verbatim}
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	173 int ob_refcnt;
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	174 PyTypeObject *ob_type;
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	175 \end{verbatim}
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	176 When \csimplemacro{Py_TRACE_REFS} is defined, it expands to:
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	177 \begin{verbatim}
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	178 PyObject _ob_next, _ob_prev;
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	179 int ob_refcnt;
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	180 PyTypeObject *ob_type;
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	181 \end{verbatim}
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	182 \end{csimplemacrodesc}
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	183
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	184 \begin{csimplemacrodesc}{PyObject_VAR_HEAD}
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	185 This is a macro which expands to the declarations of the fields of
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	186 the \ctype{PyVarObject} type; it is used when declaring new types which
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	187 represent objects with a length that varies from instance to
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	188 instance. This macro always expands to:
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	189 \begin{verbatim}
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	190 PyObject_HEAD
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	191 int ob_size;
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	192 \end{verbatim}
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	193 Note that \csimplemacro{PyObject_HEAD} is part of the expansion, and
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	194 that it's own expansion varies depending on the definition of
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	195 \csimplemacro{Py_TRACE_REFS}.
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	196 \end{csimplemacrodesc}
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	197
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	198 PyObject_HEAD_INIT
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	199
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	200 \begin{ctypedesc}{PyCFunction}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	201 Type of the functions used to implement most Python callables in C.
22926 3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	202 Functions of this type take two \ctype{PyObject*} parameters and
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	203 return one such value. If the return value is \NULL, an exception
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	204 shall have been set. If not \NULL, the return value is interpreted
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	205 as the return value of the function as exposed in Python. The
3323f3f422db Started filling in the information about some of the basic types and macros Fred Drake <fdrake@acm.org> parents: 22857 diff changeset	206 function must return a new reference.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	207 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	208
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	209 \begin{ctypedesc}{PyMethodDef}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	210 Structure used to describe a method of an extension type. This
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	211 structure has four fields:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	212
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	213 \begin{tableiii}{l\|l\|l}{member}{Field}{C Type}{Meaning}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	214 \lineiii{ml_name}{char *}{name of the method}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	215 \lineiii{ml_meth}{PyCFunction}{pointer to the C implementation}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	216 \lineiii{ml_flags}{int}{flag bits indicating how the call should be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	217 constructed}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	218 \lineiii{ml_doc}{char *}{points to the contents of the docstring}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	219 \end{tableiii}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	220 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	221
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	222 The \member{ml_meth} is a C function pointer. The functions may be of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	223 different types, but they always return \ctype{PyObject*}. If the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	224 function is not of the \ctype{PyCFunction}, the compiler will require
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	225 a cast in the method table. Even though \ctype{PyCFunction} defines
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	226 the first parameter as \ctype{PyObject*}, it is common that the method
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	227 implementation uses a the specific C type of the \var{self} object.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	228
22613 ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	229 The \member{ml_flags} field is a bitfield which can include the
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	230 following flags. The individual flags indicate either a calling
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	231 convention or a binding convention. Of the calling convention flags,
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	232 only \constant{METH_VARARGS} and \constant{METH_KEYWORDS} can be
24603 73b309cf0213 Add some fine points: METH_KEYWORDS implies METH_VARARGS, and ob_size Guido van Rossum <guido@python.org> parents: 23602 diff changeset	233 combined (but note that \constant{METH_KEYWORDS} alone is equivalent
73b309cf0213 Add some fine points: METH_KEYWORDS implies METH_VARARGS, and ob_size Guido van Rossum <guido@python.org> parents: 23602 diff changeset	234 to \code{\constant{METH_VARARGS} \| \constant{METH_KEYWORDS}}).
73b309cf0213 Add some fine points: METH_KEYWORDS implies METH_VARARGS, and ob_size Guido van Rossum <guido@python.org> parents: 23602 diff changeset	235 Any of the calling convention flags can be combined with a
22613 ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	236 binding flag.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	237
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	238 \begin{datadesc}{METH_VARARGS}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	239 This is the typical calling convention, where the methods have the
23266 7b66cd15dce9 Fix a small mistake and complete some function prototypes. Thomas Heller <theller@ctypes.org> parents: 23111 diff changeset	240 type \ctype{PyCFunction}. The function expects two
21007 94fe17c67715 Add omitted word for clarity. Fred Drake <fdrake@acm.org> parents: 20390 diff changeset	241 \ctype{PyObject*} values. The first one is the \var{self} object for
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	242 methods; for module functions, it has the value given to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	243 \cfunction{Py_InitModule4()} (or \NULL{} if
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	244 \cfunction{Py_InitModule()} was used). The second parameter
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	245 (often called \var{args}) is a tuple object representing all
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	246 arguments. This parameter is typically processed using
27728 8d92af144c16 Correct lie about METH_NOARGS functions. Michael W. Hudson <mwh@python.net> parents: 27547 diff changeset	247 \cfunction{PyArg_ParseTuple()} or \cfunction{PyArg_UnpackTuple}.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	248 \end{datadesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	249
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	250 \begin{datadesc}{METH_KEYWORDS}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	251 Methods with these flags must be of type
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	252 \ctype{PyCFunctionWithKeywords}. The function expects three
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	253 parameters: \var{self}, \var{args}, and a dictionary of all the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	254 keyword arguments. The flag is typically combined with
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	255 \constant{METH_VARARGS}, and the parameters are typically processed
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	256 using \cfunction{PyArg_ParseTupleAndKeywords()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	257 \end{datadesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	258
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	259 \begin{datadesc}{METH_NOARGS}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	260 Methods without parameters don't need to check whether arguments are
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	261 given if they are listed with the \constant{METH_NOARGS} flag. They
27728 8d92af144c16 Correct lie about METH_NOARGS functions. Michael W. Hudson <mwh@python.net> parents: 27547 diff changeset	262 need to be of type \ctype{PyCFunction}. When used with object
8d92af144c16 Correct lie about METH_NOARGS functions. Michael W. Hudson <mwh@python.net> parents: 27547 diff changeset	263 methods, the first parameter is typically named \code{self} and will
8d92af144c16 Correct lie about METH_NOARGS functions. Michael W. Hudson <mwh@python.net> parents: 27547 diff changeset	264 hold a reference to the object instance. In all cases the second
8d92af144c16 Correct lie about METH_NOARGS functions. Michael W. Hudson <mwh@python.net> parents: 27547 diff changeset	265 parameter will be \NULL.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	266 \end{datadesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	267
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	268 \begin{datadesc}{METH_O}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	269 Methods with a single object argument can be listed with the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	270 \constant{METH_O} flag, instead of invoking
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	271 \cfunction{PyArg_ParseTuple()} with a \code{"O"} argument. They have
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	272 the type \ctype{PyCFunction}, with the \var{self} parameter, and a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	273 \ctype{PyObject*} parameter representing the single argument.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	274 \end{datadesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	275
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	276 \begin{datadesc}{METH_OLDARGS}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	277 This calling convention is deprecated. The method must be of type
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	278 \ctype{PyCFunction}. The second argument is \NULL{} if no arguments
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	279 are given, a single object if exactly one argument is given, and a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	280 tuple of objects if more than one argument is given. There is no
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	281 way for a function using this convention to distinguish between a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	282 call with multiple arguments and a call with a tuple as the only
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	283 argument.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	284 \end{datadesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	285
22613 ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	286 These two constants are not used to indicate the calling convention
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	287 but the binding when use with methods of classes. These may not be
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	288 used for functions defined for modules. At most one of these flags
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	289 may be set for any given method.
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	290
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	291 \begin{datadesc}{METH_CLASS}
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	292 The method will be passed the type object as the first parameter
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	293 rather than an instance of the type. This is used to create
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	294 \emph{class methods}, similar to what is created when using the
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	295 \function{classmethod()}\bifuncindex{classmethod} built-in
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	296 function.
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	297 \versionadded{2.3}
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	298 \end{datadesc}
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	299
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	300 \begin{datadesc}{METH_STATIC}
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	301 The method will be passed \NULL{} as the first parameter rather than
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	302 an instance of the type. This is used to create \emph{static
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	303 methods}, similar to what is created when using the
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	304 \function{staticmethod()}\bifuncindex{staticmethod} built-in
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	305 function.
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	306 \versionadded{2.3}
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	307 \end{datadesc}
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	308
ddc9543c76a0 Introduce two new flag bits that can be set in a PyMethodDef method Fred Drake <fdrake@acm.org> parents: 21159 diff changeset	309
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	310 \begin{cfuncdesc}{PyObject*}{Py_FindMethod}{PyMethodDef table[],
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	311 PyObject ob, char name}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	312 Return a bound method object for an extension type implemented in
21159 6fa96b329e15 Remove most references to __members__ and __methods__, leaving only one pair Fred Drake <fdrake@acm.org> parents: 21007 diff changeset	313 C. This can be useful in the implementation of a
6fa96b329e15 Remove most references to __members__ and __methods__, leaving only one pair Fred Drake <fdrake@acm.org> parents: 21007 diff changeset	314 \member{tp_getattro} or \member{tp_getattr} handler that does not
6fa96b329e15 Remove most references to __members__ and __methods__, leaving only one pair Fred Drake <fdrake@acm.org> parents: 21007 diff changeset	315 use the \cfunction{PyObject_GenericGetAttr()} function.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	316 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	317
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	318
23012 08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	319 \section{Type Objects \label{type-structs}}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	320
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	321 Perhaps one of the most important structures of the Python object
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	322 system is the structure that defines a new type: the
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	323 \ctype{PyTypeObject} structure. Type objects can be handled using any
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	324 of the \cfunction{PyObject_()} or \cfunction{PyType_()} functions,
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	325 but do not offer much that's interesting to most Python applications.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	326 These objects are fundamental to how objects behave, so they are very
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	327 important to the interpreter itself and to any extension module that
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	328 implements new types.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	329
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	330 Type objects are fairly large compared to most of the standard types.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	331 The reason for the size is that each type object stores a large number
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	332 of values, mostly C function pointers, each of which implements a
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	333 small part of the type's functionality. The fields of the type object
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	334 are examined in detail in this section. The fields will be described
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	335 in the order in which they occur in the structure.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	336
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	337 Typedefs:
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	338 unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	339 intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	340 destructor, freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc,
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	341 setattrofunc, cmpfunc, reprfunc, hashfunc
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	342
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	343 The structure definition for \ctype{PyTypeObject} can be found in
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	344 \file{Include/object.h}. For convenience of reference, this repeats
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	345 the definition found there:
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	346
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	347 \verbatiminput{typestruct.h}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	348
24603 73b309cf0213 Add some fine points: METH_KEYWORDS implies METH_VARARGS, and ob_size Guido van Rossum <guido@python.org> parents: 23602 diff changeset	349 The type object structure extends the \ctype{PyVarObject} structure.
73b309cf0213 Add some fine points: METH_KEYWORDS implies METH_VARARGS, and ob_size Guido van Rossum <guido@python.org> parents: 23602 diff changeset	350 The \member{ob_size} field is used for dynamic types (created
73b309cf0213 Add some fine points: METH_KEYWORDS implies METH_VARARGS, and ob_size Guido van Rossum <guido@python.org> parents: 23602 diff changeset	351 by \function{type_new()}, usually called from a class statement).
73b309cf0213 Add some fine points: METH_KEYWORDS implies METH_VARARGS, and ob_size Guido van Rossum <guido@python.org> parents: 23602 diff changeset	352 Note that \cdata{PyType_Type} (the metatype) initializes
73b309cf0213 Add some fine points: METH_KEYWORDS implies METH_VARARGS, and ob_size Guido van Rossum <guido@python.org> parents: 23602 diff changeset	353 \member{tp_itemsize}, which means that its instances (i.e. type
73b309cf0213 Add some fine points: METH_KEYWORDS implies METH_VARARGS, and ob_size Guido van Rossum <guido@python.org> parents: 23602 diff changeset	354 objects) \emph{must} have the \member{ob_size} field.
23012 08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	355
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	356 \begin{cmemberdesc}{PyObject}{PyObject*}{_ob_next}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	357 \cmemberline{PyObject}{PyObject*}{_ob_prev}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	358 These fields are only present when the macro \code{Py_TRACE_REFS} is
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	359 defined. Their initialization to \NULL{} is taken care of by the
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	360 \code{PyObject_HEAD_INIT} macro. For statically allocated objects,
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	361 these fields always remain \NULL. For dynamically allocated
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	362 objects, these two fields are used to link the object into a
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	363 doubly-linked list of \emph{all} live objects on the heap. This
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	364 could be used for various debugging purposes; currently the only use
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	365 is to print the objects that are still alive at the end of a run
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	366 when the environment variable \envvar{PYTHONDUMPREFS} is set.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	367
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	368 These fields are not inherited by subtypes.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	369 \end{cmemberdesc}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	370
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	371 \begin{cmemberdesc}{PyObject}{int}{ob_refcnt}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	372 This is the type object's reference count, initialized to \code{1}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	373 by the \code{PyObject_HEAD_INIT} macro. Note that for statically
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	374 allocated type objects, the type's instances (objects whose
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	375 \member{ob_type} points back to the type) do \emph{not} count as
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	376 references. But for dynamically allocated type objects, the
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	377 instances \emph{do} count as references.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	378
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	379 This field is not inherited by subtypes.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	380 \end{cmemberdesc}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	381
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	382 \begin{cmemberdesc}{PyObject}{PyTypeObject*}{ob_type}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	383 This is the type's type, in other words its metatype. It is
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	384 initialized by the argument to the \code{PyObject_HEAD_INIT} macro,
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	385 and its value should normally be \code{\&PyType_Type}. However, for
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	386 dynamically loadable extension modules that must be usable on
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	387 Windows (at least), the compiler complains that this is not a valid
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	388 initializer. Therefore, the convention is to pass \NULL{} to the
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	389 \code{PyObject_HEAD_INIT} macro and to initialize this field
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	390 explicitly at the start of the module's initialization function,
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	391 before doing anything else. This is typically done like this:
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	392
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	393 \begin{verbatim}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	394 Foo_Type.ob_type = &PyType_Type;
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	395 \end{verbatim}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	396
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	397 This should be done before any instances of the type are created.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	398 \cfunction{PyType_Ready()} checks if \member{ob_type} is \NULL, and
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	399 if so, initializes it: in Python 2.2, it is set to
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	400 \code{\&PyType_Type}; in Python 2.2.1 and later it will be
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	401 initialized to the \member{ob_type} field of the base class.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	402 \cfunction{PyType_Ready()} will not change this field if it is
23088 8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	403 non-zero.
23012 08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	404
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	405 In Python 2.2, this field is not inherited by subtypes. In 2.2.1,
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	406 and in 2.3 and beyond, it is inherited by subtypes.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	407 \end{cmemberdesc}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	408
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	409 \begin{cmemberdesc}{PyVarObject}{int}{ob_size}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	410 For statically allocated type objects, this should be initialized
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	411 to zero. For dynamically allocated type objects, this field has a
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	412 special internal meaning.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	413
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	414 This field is not inherited by subtypes.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	415 \end{cmemberdesc}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	416
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	417 \begin{cmemberdesc}{PyTypeObject}{char*}{tp_name}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	418 Pointer to a NUL-terminated string containing the name of the type.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	419 For types that are accessible as module globals, the string should
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	420 be the full module name, followed by a dot, followed by the type
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	421 name; for built-in types, it should be just the type name. If the
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	422 module is a submodule of a package, the full package name is part of
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	423 the full module name. For example, a type named \class{T} defined
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	424 in module \module{M} in subpackage \module{Q} in package \module{P}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	425 should have the \member{tp_name} initializer \code{"P.Q.M.T"}.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	426
27799 b0539a450917 Update advice about __module__ and __name__ and tp_name wrt. new types. Michael W. Hudson <mwh@python.net> parents: 27728 diff changeset	427 For dynamically allocated type objects, this should just be the type
b0539a450917 Update advice about __module__ and __name__ and tp_name wrt. new types. Michael W. Hudson <mwh@python.net> parents: 27728 diff changeset	428 name, and the module name explicitly stored in the type dict as the
b0539a450917 Update advice about __module__ and __name__ and tp_name wrt. new types. Michael W. Hudson <mwh@python.net> parents: 27728 diff changeset	429 value for key \code{'__module__'}.
23012 08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	430
27799 b0539a450917 Update advice about __module__ and __name__ and tp_name wrt. new types. Michael W. Hudson <mwh@python.net> parents: 27728 diff changeset	431 For statically allocated type objects, the tp_name field should
b0539a450917 Update advice about __module__ and __name__ and tp_name wrt. new types. Michael W. Hudson <mwh@python.net> parents: 27728 diff changeset	432 contain a dot. Everything before the last dot is made accessible as
b0539a450917 Update advice about __module__ and __name__ and tp_name wrt. new types. Michael W. Hudson <mwh@python.net> parents: 27728 diff changeset	433 the \member{__module__} attribute, and everything after the last dot
b0539a450917 Update advice about __module__ and __name__ and tp_name wrt. new types. Michael W. Hudson <mwh@python.net> parents: 27728 diff changeset	434 is made accessible as the \member{__name__} attribute.
b0539a450917 Update advice about __module__ and __name__ and tp_name wrt. new types. Michael W. Hudson <mwh@python.net> parents: 27728 diff changeset	435
b0539a450917 Update advice about __module__ and __name__ and tp_name wrt. new types. Michael W. Hudson <mwh@python.net> parents: 27728 diff changeset	436 If no dot is present, the entire \member{tp_name} field is made
b0539a450917 Update advice about __module__ and __name__ and tp_name wrt. new types. Michael W. Hudson <mwh@python.net> parents: 27728 diff changeset	437 accessible as the \member{__name__} attribute, and the
b0539a450917 Update advice about __module__ and __name__ and tp_name wrt. new types. Michael W. Hudson <mwh@python.net> parents: 27728 diff changeset	438 \member{__module__} attribute is undefined (unless explicitly set in
b0539a450917 Update advice about __module__ and __name__ and tp_name wrt. new types. Michael W. Hudson <mwh@python.net> parents: 27728 diff changeset	439 the dictionary, as explained above). This means your type will be
b0539a450917 Update advice about __module__ and __name__ and tp_name wrt. new types. Michael W. Hudson <mwh@python.net> parents: 27728 diff changeset	440 impossible to pickle.
23012 08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	441
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	442 This field is not inherited by subtypes.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	443 \end{cmemberdesc}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	444
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	445 \begin{cmemberdesc}{PyTypeObject}{int}{tp_basicsize}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	446 \cmemberline{PyTypeObject}{int}{tp_itemsize}
27547 ce748afbd6ef Fix typo Raymond Hettinger <python@rcn.com> parents: 26059 diff changeset	447 These fields allow calculating the size in bytes of instances of
23012 08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	448 the type.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	449
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	450 There are two kinds of types: types with fixed-length instances have
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	451 a zero \member{tp_itemsize} field, types with variable-length
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	452 instances have a non-zero \member{tp_itemsize} field. For a type
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	453 with fixed-length instances, all instances have the same size,
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	454 given in \member{tp_basicsize}.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	455
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	456 For a type with variable-length instances, the instances must have
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	457 an \member{ob_size} field, and the instance size is
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	458 \member{tp_basicsize} plus N times \member{tp_itemsize}, where N is
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	459 the ``length'' of the object. The value of N is typically stored in
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	460 the instance's \member{ob_size} field. There are exceptions: for
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	461 example, long ints use a negative \member{ob_size} to indicate a
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	462 negative number, and N is \code{abs(\member{ob_size})} there. Also,
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	463 the presence of an \member{ob_size} field in the instance layout
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	464 doesn't mean that the type is variable-length (for example, the list
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	465 type has fixed-length instances, yet those instances have a
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	466 meaningful \member{ob_size} field).
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	467
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	468 The basic size includes the fields in the instance declared by the
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	469 macro \csimplemacro{PyObject_HEAD} or
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	470 \csimplemacro{PyObject_VAR_HEAD} (whichever is used to declare the
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	471 instance struct) and this in turn includes the \member{_ob_prev} and
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	472 \member{_ob_next} fields if they are present. This means that the
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	473 only correct way to get an initializer for the \member{tp_basicsize}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	474 is to use the \keyword{sizeof} operator on the struct used to
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	475 declare the instance layout. The basic size does not include the GC
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	476 header size (this is new in Python 2.2; in 2.1 and 2.0, the GC
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	477 header size was included in \member{tp_basicsize}).
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	478
23053 04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	479 These fields are inherited separately by subtypes. If the base type
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	480 has a non-zero \member{tp_itemsize}, it is generally not safe to set
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	481 \member{tp_itemsize} to a different non-zero value in a subtype
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	482 (though this depends on the implementation of the base type).
23602 dbabb1f7ed3a Explain that tp_basicsize must provide alignment for the items. Guido van Rossum <guido@python.org> parents: 23266 diff changeset	483
dbabb1f7ed3a Explain that tp_basicsize must provide alignment for the items. Guido van Rossum <guido@python.org> parents: 23266 diff changeset	484 A note about alignment: if the variable items require a particular
dbabb1f7ed3a Explain that tp_basicsize must provide alignment for the items. Guido van Rossum <guido@python.org> parents: 23266 diff changeset	485 alignment, this should be taken care of by the value of
dbabb1f7ed3a Explain that tp_basicsize must provide alignment for the items. Guido van Rossum <guido@python.org> parents: 23266 diff changeset	486 \member{tp_basicsize}. Example: suppose a type implements an array
dbabb1f7ed3a Explain that tp_basicsize must provide alignment for the items. Guido van Rossum <guido@python.org> parents: 23266 diff changeset	487 of \code{double}. \member{tp_itemsize} is \code{sizeof(double)}.
dbabb1f7ed3a Explain that tp_basicsize must provide alignment for the items. Guido van Rossum <guido@python.org> parents: 23266 diff changeset	488 It is the programmer's responsibility that \member{tp_basicsize} is
dbabb1f7ed3a Explain that tp_basicsize must provide alignment for the items. Guido van Rossum <guido@python.org> parents: 23266 diff changeset	489 a multiple of \code{sizeof(double)} (assuming this is the alignment
dbabb1f7ed3a Explain that tp_basicsize must provide alignment for the items. Guido van Rossum <guido@python.org> parents: 23266 diff changeset	490 requirement for \code{double}).
23012 08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	491 \end{cmemberdesc}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	492
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	493 \begin{cmemberdesc}{PyTypeObject}{destructor}{tp_dealloc}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	494 A pointer to the instance destructor function. This function must
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	495 be defined unless the type guarantees that its instances will never
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	496 be deallocated (as is the case for the singletons \code{None} and
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	497 \code{Ellipsis}).
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	498
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	499 The destructor function is called by the \cfunction{Py_DECREF()} and
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	500 \cfunction{Py_XDECREF()} macros when the new reference count is
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	501 zero. At this point, the instance is still in existance, but there
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	502 are no references to it. The destructor function should free all
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	503 references which the instance owns, free all memory buffers owned by
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	504 the instance (using the freeing function corresponding to the
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	505 allocation function used to allocate the buffer), and finally (as
23088 8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	506 its last action) call the type's \member{tp_free} function. If the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	507 type is not subtypable (doesn't have the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	508 \constant{Py_TPFLAGS_BASETYPE} flag bit set), it is permissible to
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	509 call the object deallocator directly instead of via
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	510 \member{tp_free}. The object deallocator should be the one used to
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	511 allocate the instance; this is normally \cfunction{PyObject_Del()}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	512 if the instance was allocated using \cfunction{PyObject_New()} or
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	513 \cfunction{PyOject_VarNew()}, or \cfunction{PyObject_GC_Del()} if
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	514 the instance was allocated using \cfunction{PyObject_GC_New()} or
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	515 \cfunction{PyObject_GC_VarNew()}.
23012 08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	516
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	517 This field is inherited by subtypes.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	518 \end{cmemberdesc}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	519
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	520 \begin{cmemberdesc}{PyTypeObject}{printfunc}{tp_print}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	521 An optional pointer to the instance print function.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	522
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	523 The print function is only called when the instance is printed to a
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	524 \emph{real} file; when it is printed to a pseudo-file (like a
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	525 \class{StringIO} instance), the instance's \member{tp_repr} or
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	526 \member{tp_str} function is called to convert it to a string. These
23053 04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	527 are also called when the type's \member{tp_print} field is \NULL. A
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	528 type should never implement \member{tp_print} in a way that produces
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	529 different output than \member{tp_repr} or \member{tp_str} would.
23012 08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	530
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	531 The print function is called with the same signature as
25182 4b9844188d04 Document type and semantics of the tp_print return value. Closes SF 606464. Raymond Hettinger <python@rcn.com> parents: 24835 diff changeset	532 \cfunction{PyObject_Print()}: \code{int tp_print(PyObject *self, FILE
23012 08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	533 *file, int flags)}. The \var{self} argument is the instance to be
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	534 printed. The \var{file} argument is the stdio file to which it is
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	535 to be printed. The \var{flags} argument is composed of flag bits.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	536 The only flag bit currently defined is \constant{Py_PRINT_RAW}.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	537 When the \constant{Py_PRINT_RAW} flag bit is set, the instance
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	538 should be printed the same way as \member{tp_str} would format it;
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	539 when the \constant{Py_PRINT_RAW} flag bit is clear, the instance
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	540 should be printed the same was as \member{tp_repr} would format it.
25182 4b9844188d04 Document type and semantics of the tp_print return value. Closes SF 606464. Raymond Hettinger <python@rcn.com> parents: 24835 diff changeset	541 It should return \code{-1} and set an exception condition when an
4b9844188d04 Document type and semantics of the tp_print return value. Closes SF 606464. Raymond Hettinger <python@rcn.com> parents: 24835 diff changeset	542 error occurred during the comparison.
23012 08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	543
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	544 It is possible that the \member{tp_print} field will be deprecated.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	545 In any case, it is recommended not to define \member{tp_print}, but
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	546 instead to rely on \member{tp_repr} and \member{tp_str} for
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	547 printing.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	548
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	549 This field is inherited by subtypes.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	550 \end{cmemberdesc}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	551
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	552 \begin{cmemberdesc}{PyTypeObject}{getattrfunc}{tp_getattr}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	553 An optional pointer to the get-attribute-string function.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	554
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	555 This field is deprecated. When it is defined, it should point to a
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	556 function that acts the same as the \member{tp_getattro} function,
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	557 but taking a C string instead of a Python string object to give the
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	558 attribute name. The signature is the same as for
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	559 \cfunction{PyObject_GetAttrString()}.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	560
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	561 This field is inherited by subtypes together with
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	562 \member{tp_getattro}: a subtype inherits both \member{tp_getattr}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	563 and \member{tp_getattro} from its base type when the subtype's
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	564 \member{tp_getattr} and \member{tp_getattro} are both \NULL.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	565 \end{cmemberdesc}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	566
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	567 \begin{cmemberdesc}{PyTypeObject}{setattrfunc}{tp_setattr}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	568 An optional pointer to the set-attribute-string function.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	569
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	570 This field is deprecated. When it is defined, it should point to a
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	571 function that acts the same as the \member{tp_setattro} function,
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	572 but taking a C string instead of a Python string object to give the
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	573 attribute name. The signature is the same as for
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	574 \cfunction{PyObject_SetAttrString()}.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	575
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	576 This field is inherited by subtypes together with
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	577 \member{tp_setattro}: a subtype inherits both \member{tp_setattr}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	578 and \member{tp_setattro} from its base type when the subtype's
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	579 \member{tp_setattr} and \member{tp_setattro} are both \NULL.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	580 \end{cmemberdesc}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	581
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	582 \begin{cmemberdesc}{PyTypeObject}{cmpfunc}{tp_compare}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	583 An optional pointer to the three-way comparison function.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	584
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	585 The signature is the same as for \cfunction{PyObject_Compare()}.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	586 The function should return \code{1} if \var{self} greater than
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	587 \var{other}, \code{0} if \var{self} is equal to \var{other}, and
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	588 \code{-1} if \var{self} less than \var{other}. It should return
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	589 \code{-1} and set an exception condition when an error occurred
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	590 during the comparison.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	591
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	592 This field is inherited by subtypes together with
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	593 \member{tp_richcompare} and \member{tp_hash}: a subtypes inherits
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	594 all three of \member{tp_compare}, \member{tp_richcompare}, and
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	595 \member{tp_hash} when the subtype's \member{tp_compare},
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	596 \member{tp_richcompare}, and \member{tp_hash} are all \NULL.
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	597 \end{cmemberdesc}
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	598
23053 04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	599 \begin{cmemberdesc}{PyTypeObject}{reprfunc}{tp_repr}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	600 An optional pointer to a function that implements the built-in
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	601 function \function{repr()}.\bifuncindex{repr}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	602
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	603 The signature is the same as for \cfunction{PyObject_Repr()}; it
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	604 must return a string or a Unicode object. Ideally, this function
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	605 should return a string that, when passed to \function{eval()}, given
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	606 a suitable environment, returns an object with the same value. If
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	607 this is not feasible, it should return a string starting with
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	608 \character{\textless} and ending with \character{\textgreater} from
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	609 which both the type and the value of the object can be deduced.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	610
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	611 When this field is not set, a string of the form \samp{<\%s object
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	612 at \%p>} is returned, where \code{\%s} is replaced by the type name,
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	613 and \code{\%p} by the object's memory address.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	614
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	615 This field is inherited by subtypes.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	616 \end{cmemberdesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	617
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	618 PyNumberMethods *tp_as_number;
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	619
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	620 XXX
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	621
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	622 PySequenceMethods *tp_as_sequence;
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	623
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	624 XXX
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	625
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	626 PyMappingMethods *tp_as_mapping;
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	627
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	628 XXX
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	629
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	630 \begin{cmemberdesc}{PyTypeObject}{hashfunc}{tp_hash}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	631 An optional pointer to a function that implements the built-in
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	632 function \function{hash()}.\bifuncindex{hash}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	633
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	634 The signature is the same as for \cfunction{PyObject_Hash()}; it
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	635 must return a C long. The value \code{-1} should not be returned as
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	636 a normal return value; when an error occurs during the computation
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	637 of the hash value, the function should set an exception and return
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	638 \code{-1}.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	639
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	640 When this field is not set, two possibilities exist: if the
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	641 \member{tp_compare} and \member{tp_richcompare} fields are both
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	642 \NULL, a default hash value based on the object's address is
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	643 returned; otherwise, a \exception{TypeError} is raised.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	644
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	645 This field is inherited by subtypes together with
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	646 \member{tp_richcompare} and \member{tp_compare}: a subtypes inherits
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	647 all three of \member{tp_compare}, \member{tp_richcompare}, and
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	648 \member{tp_hash}, when the subtype's \member{tp_compare},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	649 \member{tp_richcompare} and \member{tp_hash} are all \NULL.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	650 \end{cmemberdesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	651
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	652 \begin{cmemberdesc}{PyTypeObject}{ternaryfunc}{tp_call}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	653 An optional pointer to a function that implements calling the
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	654 object. This should be \NULL{} if the object is not callable. The
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	655 signature is the same as for \cfunction{PyObject_Call()}.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	656
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	657 This field is inherited by subtypes.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	658 \end{cmemberdesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	659
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	660 \begin{cmemberdesc}{PyTypeObject}{reprfunc}{tp_str}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	661 An optional pointer to a function that implements the built-in
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	662 operation \function{str()}. (Note that \class{str} is a type now,
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	663 and \function{str()} calls the constructor for that type. This
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	664 constructor calls \cfunction{PyObject_Str()} to do the actual work,
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	665 and \cfunction{PyObject_Str()} will call this handler.)
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	666
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	667 The signature is the same as for \cfunction{PyObject_Str()}; it must
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	668 return a string or a Unicode object. This function should return a
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	669 ``friendly'' string representation of the object, as this is the
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	670 representation that will be used by the print statement.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	671
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	672 When this field is not set, \cfunction{PyObject_Repr()} is called to
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	673 return a string representation.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	674
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	675 This field is inherited by subtypes.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	676 \end{cmemberdesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	677
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	678 \begin{cmemberdesc}{PyTypeObject}{getattrofunc}{tp_getattro}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	679 An optional pointer to the get-attribute function.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	680
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	681 The signature is the same as for \cfunction{PyObject_GetAttr()}. It
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	682 is usually convenient to set this field to
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	683 \cfunction{PyObject_GenericGetAttr()}, which implements the normal
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	684 way of looking for object attributes.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	685
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	686 This field is inherited by subtypes together with
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	687 \member{tp_getattr}: a subtype inherits both \member{tp_getattr} and
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	688 \member{tp_getattro} from its base type when the subtype's
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	689 \member{tp_getattr} and \member{tp_getattro} are both \NULL.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	690 \end{cmemberdesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	691
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	692 \begin{cmemberdesc}{PyTypeObject}{setattrofunc}{tp_setattro}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	693 An optional pointer to the set-attribute function.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	694
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	695 The signature is the same as for \cfunction{PyObject_SetAttr()}. It
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	696 is usually convenient to set this field to
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	697 \cfunction{PyObject_GenericSetAttr()}, which implements the normal
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	698 way of setting object attributes.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	699
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	700 This field is inherited by subtypes together with
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	701 \member{tp_setattr}: a subtype inherits both \member{tp_setattr} and
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	702 \member{tp_setattro} from its base type when the subtype's
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	703 \member{tp_setattr} and \member{tp_setattro} are both \NULL.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	704 \end{cmemberdesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	705
23111 4079e9c23fc1 Add text on tp_as_buffer that refers tothe section that covers the topic. Fred Drake <fdrake@acm.org> parents: 23091 diff changeset	706 \begin{cmemberdesc}{PyTypeObject}{PyBufferProcs*}{tp_as_buffer}
4079e9c23fc1 Add text on tp_as_buffer that refers tothe section that covers the topic. Fred Drake <fdrake@acm.org> parents: 23091 diff changeset	707 Pointer to an additional structure contains fields relevant only to
4079e9c23fc1 Add text on tp_as_buffer that refers tothe section that covers the topic. Fred Drake <fdrake@acm.org> parents: 23091 diff changeset	708 objects which implement the buffer interface. These fields are
4079e9c23fc1 Add text on tp_as_buffer that refers tothe section that covers the topic. Fred Drake <fdrake@acm.org> parents: 23091 diff changeset	709 documented in ``Buffer Object Structures'' (section
4079e9c23fc1 Add text on tp_as_buffer that refers tothe section that covers the topic. Fred Drake <fdrake@acm.org> parents: 23091 diff changeset	710 \ref{buffer-structs}).
23053 04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	711
23111 4079e9c23fc1 Add text on tp_as_buffer that refers tothe section that covers the topic. Fred Drake <fdrake@acm.org> parents: 23091 diff changeset	712 The \member{tp_as_buffer} field is not inherited, but the contained
4079e9c23fc1 Add text on tp_as_buffer that refers tothe section that covers the topic. Fred Drake <fdrake@acm.org> parents: 23091 diff changeset	713 fields are inherited individually.
4079e9c23fc1 Add text on tp_as_buffer that refers tothe section that covers the topic. Fred Drake <fdrake@acm.org> parents: 23091 diff changeset	714 \end{cmemberdesc}
23053 04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	715
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	716 \begin{cmemberdesc}{PyTypeObject}{long}{tp_flags}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	717 This field is a bit mask of various flags. Some flags indicate
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	718 variant semantics for certain situations; others are used to
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	719 indicate that certain fields in the type object (or in the extension
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	720 structures referenced via \member{tp_as_number},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	721 \member{tp_as_sequence}, \member{tp_as_mapping}, and
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	722 \member{tp_as_buffer}) that were historically not always present are
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	723 valid; if such a flag bit is clear, the type fields it guards must
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	724 not be accessed and must be considered to have a zero or \NULL{}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	725 value instead.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	726
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	727 Inheritance of this field is complicated. Most flag bits are
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	728 inherited individually, i.e. if the base type has a flag bit set,
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	729 the subtype inherits this flag bit. The flag bits that pertain to
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	730 extension structures are strictly inherited if the extension
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	731 structure is inherited, i.e. the base type's value of the flag bit
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	732 is copied into the subtype together with a pointer to the extension
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	733 structure. The \constant{Py_TPFLAGS_HAVE_GC} flag bit is inherited
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	734 together with the \member{tp_traverse} and \member{tp_clear} fields,
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	735 i.e. if the \constant{Py_TPFLAGS_HAVE_GC} flag bit is clear in the
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	736 subtype and the \member{tp_traverse} and \member{tp_clear} fields in
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	737 the subtype exist (as indicated by the
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	738 \constant{Py_TPFLAGS_HAVE_RICHCOMPARE} flag bit) and have \NULL{}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	739 values.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	740
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	741 The following bit masks are currently defined; these can be or-ed
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	742 together using the \code{\|} operator to form the value of the
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	743 \member{tp_flags} field. The macro \cfunction{PyType_HasFeature()}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	744 takes a type and a flags value, \var{tp} and \var{f}, and checks
23088 8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	745 whether \code{\var{tp}->tp_flags \& \var{f}} is non-zero.
23053 04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	746
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	747 \begin{datadesc}{Py_TPFLAGS_HAVE_GETCHARBUFFER}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	748 If this bit is set, the \ctype{PyBufferProcs} struct referenced by
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	749 \member{tp_as_buffer} has the \member{bf_getcharbuffer} field.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	750 \end{datadesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	751
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	752 \begin{datadesc}{Py_TPFLAGS_HAVE_SEQUENCE_IN}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	753 If this bit is set, the \ctype{PySequenceMethods} struct
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	754 referenced by \member{tp_as_sequence} has the \member{sq_contains}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	755 field.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	756 \end{datadesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	757
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	758 \begin{datadesc}{Py_TPFLAGS_GC}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	759 This bit is obsolete. The bit it used to name is no longer in
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	760 use. The symbol is now defined as zero.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	761 \end{datadesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	762
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	763 \begin{datadesc}{Py_TPFLAGS_HAVE_INPLACEOPS}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	764 If this bit is set, the \ctype{PySequenceMethods} struct
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	765 referenced by \member{tp_as_sequence} and the
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	766 \ctype{PyNumberMethods} structure referenced by
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	767 \member{tp_as_number} contain the fields for in-place operators.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	768 In particular, this means that the \ctype{PyNumberMethods}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	769 structure has the fields \member{nb_inplace_add},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	770 \member{nb_inplace_subtract}, \member{nb_inplace_multiply},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	771 \member{nb_inplace_divide}, \member{nb_inplace_remainder},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	772 \member{nb_inplace_power}, \member{nb_inplace_lshift},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	773 \member{nb_inplace_rshift}, \member{nb_inplace_and},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	774 \member{nb_inplace_xor}, and \member{nb_inplace_or}; and the
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	775 \ctype{PySequenceMethods} struct has the fields
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	776 \member{sq_inplace_concat} and \member{sq_inplace_repeat}.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	777 \end{datadesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	778
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	779 \begin{datadesc}{Py_TPFLAGS_CHECKTYPES}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	780 If this bit is set, the binary and ternary operations in the
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	781 \ctype{PyNumberMethods} structure referenced by
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	782 \member{tp_as_number} accept arguments of arbitrary object types,
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	783 and do their own type conversions if needed. If this bit is
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	784 clear, those operations require that all arguments have the
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	785 current type as their type, and the caller is supposed to perform
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	786 a coercion operation first. This applies to \member{nb_add},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	787 \member{nb_subtract}, \member{nb_multiply}, \member{nb_divide},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	788 \member{nb_remainder}, \member{nb_divmod}, \member{nb_power},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	789 \member{nb_lshift}, \member{nb_rshift}, \member{nb_and},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	790 \member{nb_xor}, and \member{nb_or}.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	791 \end{datadesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	792
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	793 \begin{datadesc}{Py_TPFLAGS_HAVE_RICHCOMPARE}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	794 If this bit is set, the type object has the
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	795 \member{tp_richcompare} field, as well as the \member{tp_traverse}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	796 and the \member{tp_clear} fields.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	797 \end{datadesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	798
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	799 \begin{datadesc}{Py_TPFLAGS_HAVE_WEAKREFS}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	800 If this bit is set, the \member{tp_weaklistoffset} field is
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	801 defined. Instances of a type are weakly referenceable if the
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	802 type's \member{tp_weaklistoffset} field has a value greater than
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	803 zero.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	804 \end{datadesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	805
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	806 \begin{datadesc}{Py_TPFLAGS_HAVE_ITER}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	807 If this bit is set, the type object has the \member{tp_iter} and
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	808 \member{tp_iternext} fields.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	809 \end{datadesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	810
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	811 \begin{datadesc}{Py_TPFLAGS_HAVE_CLASS}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	812 If this bit is set, the type object has several new fields defined
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	813 starting in Python 2.2: \member{tp_methods}, \member{tp_members},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	814 \member{tp_getset}, \member{tp_base}, \member{tp_dict},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	815 \member{tp_descr_get}, \member{tp_descr_set},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	816 \member{tp_dictoffset}, \member{tp_init}, \member{tp_alloc},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	817 \member{tp_new}, \member{tp_free}, \member{tp_is_gc},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	818 \member{tp_bases}, \member{tp_mro}, \member{tp_cache},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	819 \member{tp_subclasses}, and \member{tp_weaklist}.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	820 \end{datadesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	821
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	822 \begin{datadesc}{Py_TPFLAGS_HEAPTYPE}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	823 This bit is set when the type object itself is allocated on the
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	824 heap. In this case, the \member{ob_type} field of its instances
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	825 is considered a reference to the type, and the type object is
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	826 INCREF'ed when a new instance is created, and DECREF'ed when an
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	827 instance is destroyed (this does not apply to instances of
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	828 subtypes; only the type referenced by the instance's ob_type gets
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	829 INCREF'ed or DECREF'ed).
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	830 \end{datadesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	831
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	832 \begin{datadesc}{Py_TPFLAGS_BASETYPE}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	833 This bit is set when the type can be used as the base type of
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	834 another type. If this bit is clear, the type cannot be subtyped
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	835 (similar to a "final" class in Java).
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	836 \end{datadesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	837
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	838 \begin{datadesc}{Py_TPFLAGS_READY}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	839 This bit is set when the type object has been fully initialized by
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	840 \cfunction{PyType_Ready()}.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	841 \end{datadesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	842
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	843 \begin{datadesc}{Py_TPFLAGS_READYING}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	844 This bit is set while \cfunction{PyType_Ready()} is in the process
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	845 of initializing the type object.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	846 \end{datadesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	847
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	848 \begin{datadesc}{Py_TPFLAGS_HAVE_GC}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	849 This bit is set when the object supports garbage collection. If
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	850 this bit is set, instances must be created using
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	851 \cfunction{PyObject_GC_New()} and destroyed using
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	852 \cfunction{PyObject_GC_Del()}. More information in section XXX
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	853 about garbage collection. This bit also implies that the
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	854 GC-related fields \member{tp_traverse} and \member{tp_clear} are
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	855 present in the type object; but those fields also exist when
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	856 \constant{Py_TPFLAGS_HAVE_GC} is clear but
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	857 \constant{Py_TPFLAGS_HAVE_RICHCOMPARE} is set).
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	858 \end{datadesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	859
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	860 \begin{datadesc}{Py_TPFLAGS_DEFAULT}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	861 This is a bitmask of all the bits that pertain to the existence of
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	862 certain fields in the type object and its extension structures.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	863 Currently, it includes the following bits:
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	864 \constant{Py_TPFLAGS_HAVE_GETCHARBUFFER},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	865 \constant{Py_TPFLAGS_HAVE_SEQUENCE_IN},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	866 \constant{Py_TPFLAGS_HAVE_INPLACEOPS},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	867 \constant{Py_TPFLAGS_HAVE_RICHCOMPARE},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	868 \constant{Py_TPFLAGS_HAVE_WEAKREFS},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	869 \constant{Py_TPFLAGS_HAVE_ITER}, and
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	870 \constant{Py_TPFLAGS_HAVE_CLASS}.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	871 \end{datadesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	872 \end{cmemberdesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	873
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	874 \begin{cmemberdesc}{PyTypeObject}{char*}{tp_doc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	875 An optional pointer to a NUL-terminated C string giving the
23088 8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	876 docstring for this type object. This is exposed as the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	877 \member{__doc__} attribute on the type and instances of the type.
23053 04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	878
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	879 This field is \emph{not} inherited by subtypes.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	880 \end{cmemberdesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	881
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	882 The following three fields only exist if the
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	883 \constant{Py_TPFLAGS_HAVE_RICHCOMPARE} flag bit is set.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	884
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	885 \begin{cmemberdesc}{PyTypeObject}{traverseproc}{tp_traverse}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	886 An optional pointer to a traversal function for the garbage
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	887 collector. This is only used if the \constant{Py_TPFLAGS_HAVE_GC}
27799 b0539a450917 Update advice about __module__ and __name__ and tp_name wrt. new types. Michael W. Hudson <mwh@python.net> parents: 27728 diff changeset	888 flag bit is set. More information in section
b0539a450917 Update advice about __module__ and __name__ and tp_name wrt. new types. Michael W. Hudson <mwh@python.net> parents: 27728 diff changeset	889 \ref{supporting-cycle-detection} about garbage collection.
23053 04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	890
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	891 This field is inherited by subtypes together with \member{tp_clear}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	892 and the \constant{Py_TPFLAGS_HAVE_GC} flag bit: the flag bit,
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	893 \member{tp_traverse}, and \member{tp_clear} are all inherited from
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	894 the base type if they are all zero in the subtype \emph{and} the
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	895 subtype has the \constant{Py_TPFLAGS_HAVE_RICHCOMPARE} flag bit set.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	896 \end{cmemberdesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	897
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	898 \begin{cmemberdesc}{PyTypeObject}{inquiry}{tp_clear}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	899 An optional pointer to a clear function for the garbage collector.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	900 This is only used if the \constant{Py_TPFLAGS_HAVE_GC} flag bit is
27799 b0539a450917 Update advice about __module__ and __name__ and tp_name wrt. new types. Michael W. Hudson <mwh@python.net> parents: 27728 diff changeset	901 set. More information in section
b0539a450917 Update advice about __module__ and __name__ and tp_name wrt. new types. Michael W. Hudson <mwh@python.net> parents: 27728 diff changeset	902 \ref{supporting-cycle-detection} about garbage collection.
23053 04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	903
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	904 This field is inherited by subtypes together with \member{tp_clear}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	905 and the \constant{Py_TPFLAGS_HAVE_GC} flag bit: the flag bit,
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	906 \member{tp_traverse}, and \member{tp_clear} are all inherited from
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	907 the base type if they are all zero in the subtype \emph{and} the
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	908 subtype has the \constant{Py_TPFLAGS_HAVE_RICHCOMPARE} flag bit set.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	909 \end{cmemberdesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	910
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	911 \begin{cmemberdesc}{PyTypeObject}{richcmpfunc}{tp_richcompare}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	912 An optional pointer to the rich comparison function.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	913
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	914 The signature is the same as for \cfunction{PyObject_RichCompare()}.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	915 The function should return \code{1} if the requested comparison
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	916 returns true, \code{0} if it returns false. It should return
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	917 \code{-1} and set an exception condition when an error occurred
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	918 during the comparison.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	919
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	920 This field is inherited by subtypes together with
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	921 \member{tp_compare} and \member{tp_hash}: a subtype inherits all
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	922 three of \member{tp_compare}, \member{tp_richcompare}, and
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	923 \member{tp_hash}, when the subtype's \member{tp_compare},
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	924 \member{tp_richcompare}, and \member{tp_hash} are all \NULL.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	925
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	926 The following constants are defined to be used as the third argument
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	927 for \member{tp_richcompare} and for \cfunction{PyObject_RichCompare()}:
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	928
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	929 \begin{tableii}{l\|c}{constant}{Constant}{Comparison}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	930 \lineii{Py_LT}{\code{<}}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	931 \lineii{Py_LE}{\code{<=}}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	932 \lineii{Py_EQ}{\code{==}}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	933 \lineii{Py_NE}{\code{!=}}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	934 \lineii{Py_GT}{\code{>}}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	935 \lineii{Py_GE}{\code{>=}}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	936 \end{tableii}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	937 \end{cmemberdesc}
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	938
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	939 The next field only exists if the \constant{Py_TPFLAGS_HAVE_WEAKREFS}
23088 8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	940 flag bit is set.
23053 04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	941
23088 8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	942 \begin{cmemberdesc}{PyTypeObject}{long}{tp_weaklistoffset}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	943 If the instances of this type are weakly referenceable, this field
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	944 is greater than zero and contains the offset in the instance
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	945 structure of the weak reference list head (ignoring the GC header,
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	946 if present); this offset is used by
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	947 \cfunction{PyObject_ClearWeakRefs()} and the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	948 \cfunction{PyWeakref_*()} functions. The instance structure needs
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	949 to include a field of type \ctype{PyObject*} which is initialized to
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	950 \NULL.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	951
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	952 Do not confuse this field with \member{tp_weaklist}; that is the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	953 list head for weak references to the type object itself.
23053 04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	954
23088 8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	955 This field is inherited by subtypes, but see the rules listed below.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	956 A subtype may override this offset; this means that the subtype uses
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	957 a different weak reference list head than the base type. Since the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	958 list head is always found via \member{tp_weaklistoffset}, this
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	959 should not be a problem.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	960
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	961 When a type defined by a class statement has no \member{__slots__}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	962 declaration, and none of its base types are weakly referenceable,
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	963 the type is made weakly referenceable by adding a weak reference
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	964 list head slot to the instance layout and setting the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	965 \member{tp_weaklistoffset} of that slot's offset.
23053 04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	966
23088 8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	967 When a type's \member{__slots__} declaration contains a slot named
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	968 \member{__weakref__}, that slot becomes the weak reference list head
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	969 for instances of the type, and the slot's offset is stored in the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	970 type's \member{tp_weaklistoffset}.
23053 04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	971
23088 8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	972 When a type's \member{__slots__} declaration does not contain a slot
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	973 named \member{__weakref__}, the type inherits its
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	974 \member{tp_weaklistoffset} from its base type.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	975 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	976
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	977 The next two fields only exist if the
23053 04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	978 \constant{Py_TPFLAGS_HAVE_CLASS} flag bit is set.
04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	979
23088 8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	980 \begin{cmemberdesc}{PyTypeObject}{getiterfunc}{tp_iter}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	981 An optional pointer to a function that returns an iterator for the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	982 object. Its presence normally signals that the instances of this
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	983 type are iterable (although sequences may be iterable without this
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	984 function, and classic instances always have this function, even if
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	985 they don't define an \method{__iter__()} method).
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	986
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	987 This function has the same signature as
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	988 \cfunction{PyObject_GetIter()}.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	989
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	990 This field is inherited by subtypes.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	991 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	992
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	993 \begin{cmemberdesc}{PyTypeObject}{iternextfunc}{tp_iternext}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	994 An optional pointer to a function that returns the next item in an
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	995 iterator, or raises \exception{StopIteration} when the iterator is
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	996 exhausted. Its presence normally signals that the instances of this
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	997 type are iterators (although classic instances always have this
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	998 function, even if they don't define a \method{next()} method).
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	999
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1000 Iterator types should also define the \member{tp_iter} function, and
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1001 that function should return the iterator instance itself (not a new
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1002 iterator instance).
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1003
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1004 This function has the same signature as \cfunction{PyIter_Next()}.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1005
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1006 This field is inherited by subtypes.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1007 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1008
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1009 The next fields, up to and including \member{tp_weaklist}, only exist
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1010 if the \constant{Py_TPFLAGS_HAVE_CLASS} flag bit is set.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1011
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1012 \begin{cmemberdesc}{PyTypeObject}{struct PyMethodDef*}{tp_methods}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1013 An optional pointer to a static \NULL-terminated array of
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1014 \ctype{PyMethodDef} structures, declaring regular methods of this
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1015 type.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1016
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1017 For each entry in the array, an entry is added to the type's
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1018 dictionary (see \member{tp_dict} below) containing a method
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1019 descriptor.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1020
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1021 This field is not inherited by subtypes (methods are
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1022 inherited through a different mechanism).
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1023 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1024
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1025 \begin{cmemberdesc}{PyTypeObject}{struct PyMemberDef*}{tp_members}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1026 An optional pointer to a static \NULL-terminated array of
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1027 \ctype{PyMemberDef} structures, declaring regular data members
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1028 (fields or slots) of instances of this type.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1029
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1030 For each entry in the array, an entry is added to the type's
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1031 dictionary (see \member{tp_dict} below) containing a member
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1032 descriptor.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1033
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1034 This field is not inherited by subtypes (members are inherited
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1035 through a different mechanism).
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1036 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1037
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1038 \begin{cmemberdesc}{PyTypeObject}{struct PyGetSetDef*}{tp_getset}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1039 An optional pointer to a static \NULL-terminated array of
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1040 \ctype{PyGetSetDef} structures, declaring computed attributes of
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1041 instances of this type.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1042
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1043 For each entry in the array, an entry is added to the type's
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1044 dictionary (see \member{tp_dict} below) containing a getset
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1045 descriptor.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1046
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1047 This field is not inherited by subtypes (computed attributes are
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1048 inherited through a different mechanism).
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1049
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1050 Docs for PyGetSetDef (XXX belong elsewhere):
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1051
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1052 \begin{verbatim}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1053 typedef PyObject (getter)(PyObject , void );
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1054 typedef int (setter)(PyObject , PyObject , void );
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1055
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1056 typedef struct PyGetSetDef {
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1057 char name; / attribute name */
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1058 getter get; /* C function to get the attribute */
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1059 setter set; /* C function to set the attribute */
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1060 char doc; / optional doc string */
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1061 void closure; / optional additional data for getter and setter */
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1062 } PyGetSetDef;
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1063 \end{verbatim}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1064 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1065
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1066 \begin{cmemberdesc}{PyTypeObject}{PyTypeObject*}{tp_base}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1067 An optional pointer to a base type from which type properties are
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1068 inherited. At this level, only single inheritance is supported;
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1069 multiple inheritance require dynamically creating a type object by
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1070 calling the metatype.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1071
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1072 This field is not inherited by subtypes (obviously), but it defaults
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1073 to \code{\&PyBaseObject_Type} (which to Python programmers is known
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1074 as the type \class{object}).
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1075 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1076
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1077 \begin{cmemberdesc}{PyTypeObject}{PyObject*}{tp_dict}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1078 The type's dictionary is stored here by \cfunction{PyType_Ready()}.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1079
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1080 This field should normally be initialized to \NULL{} before
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1081 PyType_Ready is called; it may also be initialized to a dictionary
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1082 containing initial attributes for the type. Once
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1083 \cfunction{PyType_Ready()} has initialized the type, extra
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1084 attributes for the type may be added to this dictionary only if they
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1085 don't correspond to overloaded operations (like \method{__add__()}).
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1086
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1087 This field is not inherited by subtypes (though the attributes
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1088 defined in here are inherited through a different mechanism).
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1089 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1090
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1091 \begin{cmemberdesc}{PyTypeObject}{descrgetfunc}{tp_descr_get}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1092 An optional pointer to a "descriptor get" function.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1093
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1094 XXX blah, blah.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1095
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1096 This field is inherited by subtypes.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1097 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1098
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1099 \begin{cmemberdesc}{PyTypeObject}{descrsetfunc}{tp_descr_set}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1100 An optional pointer to a "descriptor set" function.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1101
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1102 XXX blah, blah.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1103
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1104 This field is inherited by subtypes.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1105 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1106
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1107 \begin{cmemberdesc}{PyTypeObject}{long}{tp_dictoffset}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1108 If the instances of this type have a dictionary containing instance
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1109 variables, this field is non-zero and contains the offset in the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1110 instances of the type of the instance variable dictionary; this
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1111 offset is used by \cfunction{PyObject_GenericGetAttr()}.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1112
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1113 Do not confuse this field with \member{tp_dict}; that is the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1114 dictionary for attributes of the type object itself.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1115
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1116 If the value of this field is greater than zero, it specifies the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1117 offset from the start of the instance structure. If the value is
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1118 less than zero, it specifies the offset from the end of the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1119 instance structure. A negative offset is more expensive to use, and
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1120 should only be used when the instance structure contains a
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1121 variable-length part. This is used for example to add an instance
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1122 variable dictionary to subtypes of \class{str} or \class{tuple}.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1123 Note that the \member{tp_basicsize} field should account for the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1124 dictionary added to the end in that case, even though the dictionary
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1125 is not included in the basic object layout. On a system with a
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1126 pointer size of 4 bytes, \member{tp_dictoffset} should be set to
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1127 \code{-4} to indicate that the dictionary is at the very end of the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1128 structure.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1129
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1130 The real dictionary offset in an instance can be computed from a
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1131 negative \member{tp_dictoffset} as follows:
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1132
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1133 \begin{verbatim}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1134 dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1135 if dictoffset is not aligned on sizeof(void*):
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1136 round up to sizeof(void*)
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1137 \end{verbatim}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1138
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1139 where \member{tp_basicsize}, \member{tp_itemsize} and
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1140 \member{tp_dictoffset} are taken from the type object, and
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1141 \member{ob_size} is taken from the instance. The absolute value is
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1142 taken because long ints use the sign of \member{ob_size} to store
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1143 the sign of the number. (There's never a need to do this
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1144 calculation yourself; it is done for you by
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1145 \cfunction{_PyObject_GetDictPtr()}.)
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1146
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1147 This field is inherited by subtypes, but see the rules listed below.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1148 A subtype may override this offset; this means that the subtype
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1149 instances store the dictionary at a difference offset than the base
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1150 type. Since the dictionary is always found via
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1151 \member{tp_dictoffset}, this should not be a problem.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1152
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1153 When a type defined by a class statement has no \member{__slots__}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1154 declaration, and none of its base types has an instance variable
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1155 dictionary, a dictionary slot is added to the instance layout and
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1156 the \member{tp_dictoffset} is set to that slot's offset.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1157
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1158 When a type defined by a class statement has a \member{__slots__}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1159 declaration, the type inherits its \member{tp_dictoffset} from its
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1160 base type.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1161
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1162 (Adding a slot named \member{__dict__} to the \member{__slots__}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1163 declaration does not have the expected effect, it just causes
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1164 confusion. Maybe this should be added as a feature just like
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1165 \member{__weakref__} though.)
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1166 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1167
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1168 \begin{cmemberdesc}{PyTypeObject}{initproc}{tp_init}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1169 An optional pointer to an instance initialization function.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1170
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1171 This function corresponds to the \method{__init__()} method of
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1172 classes. Like \method{__init__()}, it is possible to create an
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1173 instance without calling \method{__init__()}, and it is possible to
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1174 reinitialize an instance by calling its \method{__init__()} method
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1175 again.
23053 04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	1176
23088 8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1177 The function signature is
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1178
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1179 \begin{verbatim}
23266 7b66cd15dce9 Fix a small mistake and complete some function prototypes. Thomas Heller <theller@ctypes.org> parents: 23111 diff changeset	1180 int tp_init(PyObject self, PyObject args, PyObject *kwds)
23088 8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1181 \end{verbatim}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1182
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1183 The self argument is the instance to be initialized; the \var{args}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1184 and \var{kwds} arguments represent positional and keyword arguments
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1185 of the call to \method{__init__()}.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1186
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1187 The \member{tp_init} function, if not \NULL, is called when an
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1188 instance is created normally by calling its type, after the type's
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1189 \member{tp_new} function has returned an instance of the type. If
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1190 the \member{tp_new} function returns an instance of some other type
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1191 that is not a subtype of the original type, no \member{tp_init}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1192 function is called; if \member{tp_new} returns an instance of a
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1193 subtype of the original type, the subtype's \member{tp_init} is
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1194 called. (VERSION NOTE: described here is what is implemented in
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1195 Python 2.2.1 and later. In Python 2.2, the \member{tp_init} of the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1196 type of the object returned by \member{tp_new} was always called, if
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1197 not \NULL.)
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1198
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1199 This field is inherited by subtypes.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1200 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1201
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1202 \begin{cmemberdesc}{PyTypeObject}{allocfunc}{tp_alloc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1203 An optional pointer to an instance allocation function.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1204
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1205 The function signature is
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1206
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1207 \begin{verbatim}
23266 7b66cd15dce9 Fix a small mistake and complete some function prototypes. Thomas Heller <theller@ctypes.org> parents: 23111 diff changeset	1208 PyObject tp_alloc(PyTypeObject self, int nitems)
23088 8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1209 \end{verbatim}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1210
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1211 The purpose of this function is to separate memory allocation from
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1212 memory initialization. It should return a pointer to a block of
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1213 memory of adequate length for the instance, suitably aligned, and
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1214 initialized to zeros, but with \member{ob_refcnt} set to \code{1}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1215 and \member{ob_type} set to the type argument. If the type's
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1216 \member{tp_itemsize} is non-zero, the object's \member{ob_size} field
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1217 should be initialized to \var{nitems} and the length of the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1218 allocated memory block should be \code{tp_basicsize +
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1219 \var{nitems}*tp_itemsize}, rounded up to a multiple of
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1220 \code{sizeof(void*)}; otherwise, \var{nitems} is not used and the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1221 length of the block should be \member{tp_basicsize}.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1222
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1223 Do not use this function to do any other instance initialization,
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1224 not even to allocate additional memory; that should be done by
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1225 \member{tp_new}.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1226
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1227 This field is inherited by static subtypes, but not by dynamic
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1228 subtypes (subtypes created by a class statement); in the latter,
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1229 this field is always set to \cfunction{PyType_GenericAlloc()}, to
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1230 force a standard heap allocation strategy. That is also the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1231 recommended value for statically defined types.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1232 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1233
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1234 \begin{cmemberdesc}{PyTypeObject}{newfunc}{tp_new}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1235 An optional pointer to an instance creation function.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1236
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1237 If this function is \NULL{} for a particular type, that type cannot
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1238 be called to create new instances; presumably there is some other
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1239 way to create instances, like a factory function.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1240
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1241 The function signature is
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1242
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1243 \begin{verbatim}
23266 7b66cd15dce9 Fix a small mistake and complete some function prototypes. Thomas Heller <theller@ctypes.org> parents: 23111 diff changeset	1244 PyObject tp_new(PyTypeObject subtype, PyObject args, PyObject kwds)
23088 8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1245 \end{verbatim}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1246
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1247 The subtype argument is the type of the object being created; the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1248 \var{args} and \var{kwds} arguments represent positional and keyword
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1249 arguments of the call to the type. Note that subtype doesn't have
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1250 to equal the type whose \member{tp_new} function is called; it may
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1251 be a subtype of that type (but not an unrelated type).
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1252
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1253 The \member{tp_new} function should call
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1254 \code{\var{subtype}->tp_alloc(\var{subtype}, \var{nitems})} to
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1255 allocate space for the object, and then do only as much further
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1256 initialization as is absolutely necessary. Initialization that can
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1257 safely be ignored or repeated should be placed in the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1258 \member{tp_init} handler. A good rule of thumb is that for
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1259 immutable types, all initialization should take place in
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1260 \member{tp_new}, while for mutable types, most initialization should
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1261 be deferred to \member{tp_init}.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1262
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1263 This field is inherited by subtypes, except it is not inherited by
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1264 static types whose \member{tp_base} is \NULL{} or
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1265 \code{\&PyBaseObject_Type}. The latter exception is a precaution so
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1266 that old extension types don't become callable simply by being
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1267 linked with Python 2.2.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1268 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1269
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1270 \begin{cmemberdesc}{PyTypeObject}{destructor}{tp_free}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1271 An optional pointer to an instance deallocation function.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1272
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1273 The signature of this function has changed slightly: in Python
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1274 2.2 and 2.2.1, its signature is \ctype{destructor}:
23053 04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	1275
23088 8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1276 \begin{verbatim}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1277 void tp_free(PyObject *)
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1278 \end{verbatim}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1279
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1280 In Python 2.3 and beyond, its signature is \ctype{freefunc}:
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1281
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1282 \begin{verbatim}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1283 void tp_free(void *)
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1284 \end{verbatim}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1285
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1286 The only initializer that is compatible with both versions is
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1287 \code{_PyObject_Del}, whose definition has suitably adapted in
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1288 Python 2.3.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1289
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1290 This field is inherited by static subtypes, but not by dynamic
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1291 subtypes (subtypes created by a class statement); in the latter,
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1292 this field is set to a deallocator suitable to match
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1293 \cfunction{PyType_GenericAlloc()} and the value of the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1294 \constant{Py_TPFLAGS_HAVE_GC} flag bit.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1295 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1296
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1297 \begin{cmemberdesc}{PyTypeObject}{inquiry}{tp_is_gc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1298 An optional pointer to a function called by the garbage collector.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1299
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1300 The garbage collector needs to know whether a particular object is
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1301 collectible or not. Normally, it is sufficient to look at the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1302 object's type's \member{tp_flags} field, and check the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1303 \constant{Py_TPFLAGS_HAVE_GC} flag bit. But some types have a
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1304 mixture of statically and dynamically allocated instances, and the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1305 statically allocated instances are not collectible. Such types
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1306 should define this function; it should return \code{1} for a
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1307 collectible instance, and \code{0} for a non-collectible instance.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1308 The signature is
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1309
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1310 \begin{verbatim}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1311 int tp_is_gc(PyObject *self)
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1312 \end{verbatim}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1313
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1314 (The only example of this are types themselves. The metatype,
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1315 \cdata{PyType_Type}, defines this function to distinguish between
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1316 statically and dynamically allocated types.)
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1317
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1318 This field is inherited by subtypes. (VERSION NOTE: in Python
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1319 2.2, it was not inherited. It is inherited in 2.2.1 and later
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1320 versions.)
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1321 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1322
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1323 \begin{cmemberdesc}{PyTypeObject}{PyObject*}{tp_bases}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1324 Tuple of base types.
23053 04fbf65c73ef Integrated more text from Guido. Fred Drake <fdrake@acm.org> parents: 23012 diff changeset	1325
23088 8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1326 This is set for types created by a class statement. It should be
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1327 \NULL{} for statically defined types.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1328
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1329 This field is not inherited.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1330 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1331
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1332 \begin{cmemberdesc}{PyTypeObject}{PyObject*}{tp_mro}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1333 Tuple containing the expanded set of base types, starting with the
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1334 type itself and ending with \class{object}, in Method Resolution
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1335 Order.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1336
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1337 This field is not inherited; it is calculated fresh by
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1338 \cfunction{PyType_Ready()}.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1339 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1340
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1341 \begin{cmemberdesc}{PyTypeObject}{PyObject*}{tp_cache}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1342 Unused. Not inherited. Internal use only.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1343 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1344
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1345 \begin{cmemberdesc}{PyTypeObject}{PyObject*}{tp_subclasses}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1346 List of weak references to subclasses. Not inherited. Internal
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1347 use only.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1348 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1349
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1350 \begin{cmemberdesc}{PyTypeObject}{PyObject*}{tp_weaklist}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1351 Weak reference list head, for weak references to this type
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1352 object. Not inherited. Internal use only.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1353 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1354
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1355 The remaining fields are only defined if the feature test macro
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1356 \constant{COUNT_ALLOCS} is defined, and are for internal use only.
23091 99757562bfb9 Minor wording change. Fred Drake <fdrake@acm.org> parents: 23088 diff changeset	1357 They are documented here for completeness. None of these fields are
23088 8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1358 inherited by subtypes.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1359
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1360 \begin{cmemberdesc}{PyTypeObject}{int}{tp_allocs}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1361 Number of allocations.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1362 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1363
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1364 \begin{cmemberdesc}{PyTypeObject}{int}{tp_frees}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1365 Number of frees.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1366 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1367
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1368 \begin{cmemberdesc}{PyTypeObject}{int}{tp_maxalloc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1369 Maximum simultaneously allocated objects.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1370 \end{cmemberdesc}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1371
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1372 \begin{cmemberdesc}{PyTypeObject}{PyTypeObject*}{tp_next}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1373 Pointer to the next type object with a non-zero \member{tp_allocs}
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1374 field.
8c7a39d0fefd Add more text from Guido on the type structure fields. Fred Drake <fdrake@acm.org> parents: 23053 diff changeset	1375 \end{cmemberdesc}
23012 08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	1376
08ab0a6bf1eb Integrate a bunch of new text from Guido. Fred Drake <fdrake@acm.org> parents: 22926 diff changeset	1377
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1378 \section{Mapping Object Structures \label{mapping-structs}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1379
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1380 \begin{ctypedesc}{PyMappingMethods}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1381 Structure used to hold pointers to the functions used to implement
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1382 the mapping protocol for an extension type.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1383 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1384
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1385
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1386 \section{Number Object Structures \label{number-structs}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1387
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1388 \begin{ctypedesc}{PyNumberMethods}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1389 Structure used to hold pointers to the functions an extension type
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1390 uses to implement the number protocol.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1391 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1392
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1393
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1394 \section{Sequence Object Structures \label{sequence-structs}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1395
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1396 \begin{ctypedesc}{PySequenceMethods}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1397 Structure used to hold pointers to the functions which an object
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1398 uses to implement the sequence protocol.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1399 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1400
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1401
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1402 \section{Buffer Object Structures \label{buffer-structs}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1403 \sectionauthor{Greg J. Stein}{greg@lyra.org}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1404
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1405 The buffer interface exports a model where an object can expose its
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1406 internal data as a set of chunks of data, where each chunk is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1407 specified as a pointer/length pair. These chunks are called
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1408 \dfn{segments} and are presumed to be non-contiguous in memory.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1409
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1410 If an object does not export the buffer interface, then its
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1411 \member{tp_as_buffer} member in the \ctype{PyTypeObject} structure
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1412 should be \NULL. Otherwise, the \member{tp_as_buffer} will point to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1413 a \ctype{PyBufferProcs} structure.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1414
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1415 \note{It is very important that your \ctype{PyTypeObject} structure
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1416 uses \constant{Py_TPFLAGS_DEFAULT} for the value of the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1417 \member{tp_flags} member rather than \code{0}. This tells the Python
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1418 runtime that your \ctype{PyBufferProcs} structure contains the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1419 \member{bf_getcharbuffer} slot. Older versions of Python did not have
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1420 this member, so a new Python interpreter using an old extension needs
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1421 to be able to test for its presence before using it.}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1422
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1423 \begin{ctypedesc}{PyBufferProcs}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1424 Structure used to hold the function pointers which define an
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1425 implementation of the buffer protocol.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1426
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1427 The first slot is \member{bf_getreadbuffer}, of type
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1428 \ctype{getreadbufferproc}. If this slot is \NULL, then the object
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1429 does not support reading from the internal data. This is
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1430 non-sensical, so implementors should fill this in, but callers
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1431 should test that the slot contains a non-\NULL{} value.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1432
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1433 The next slot is \member{bf_getwritebuffer} having type
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1434 \ctype{getwritebufferproc}. This slot may be \NULL{} if the object
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1435 does not allow writing into its returned buffers.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1436
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1437 The third slot is \member{bf_getsegcount}, with type
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1438 \ctype{getsegcountproc}. This slot must not be \NULL{} and is used
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1439 to inform the caller how many segments the object contains. Simple
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1440 objects such as \ctype{PyString_Type} and \ctype{PyBuffer_Type}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1441 objects contain a single segment.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1442
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1443 The last slot is \member{bf_getcharbuffer}, of type
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1444 \ctype{getcharbufferproc}. This slot will only be present if the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1445 \constant{Py_TPFLAGS_HAVE_GETCHARBUFFER} flag is present in the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1446 \member{tp_flags} field of the object's \ctype{PyTypeObject}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1447 Before using this slot, the caller should test whether it is present
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1448 by using the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1449 \cfunction{PyType_HasFeature()}\ttindex{PyType_HasFeature()}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1450 function. If present, it may be \NULL, indicating that the object's
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1451 contents cannot be used as \emph{8-bit characters}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1452 The slot function may also raise an error if the object's contents
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1453 cannot be interpreted as 8-bit characters. For example, if the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1454 object is an array which is configured to hold floating point
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1455 values, an exception may be raised if a caller attempts to use
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1456 \member{bf_getcharbuffer} to fetch a sequence of 8-bit characters.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1457 This notion of exporting the internal buffers as ``text'' is used to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1458 distinguish between objects that are binary in nature, and those
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1459 which have character-based content.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1460
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1461 \note{The current policy seems to state that these characters
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1462 may be multi-byte characters. This implies that a buffer size of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1463 \var{N} does not mean there are \var{N} characters present.}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1464 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1465
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1466 \begin{datadesc}{Py_TPFLAGS_HAVE_GETCHARBUFFER}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1467 Flag bit set in the type structure to indicate that the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1468 \member{bf_getcharbuffer} slot is known. This being set does not
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1469 indicate that the object supports the buffer interface or that the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1470 \member{bf_getcharbuffer} slot is non-\NULL.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1471 \end{datadesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1472
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1473 \begin{ctypedesc}[getreadbufferproc]{int (*getreadbufferproc)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1474 (PyObject self, int segment, void *ptrptr)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1475 Return a pointer to a readable segment of the buffer. This function
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1476 is allowed to raise an exception, in which case it must return
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1477 \code{-1}. The \var{segment} which is passed must be zero or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1478 positive, and strictly less than the number of segments returned by
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1479 the \member{bf_getsegcount} slot function. On success, it returns
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1480 the length of the buffer memory, and sets \code{*\var{ptrptr}} to a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1481 pointer to that memory.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1482 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1483
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1484 \begin{ctypedesc}[getwritebufferproc]{int (*getwritebufferproc)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1485 (PyObject self, int segment, void *ptrptr)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1486 Return a pointer to a writable memory buffer in
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1487 \code{*\var{ptrptr}}, and the length of that segment as the function
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1488 return value. The memory buffer must correspond to buffer segment
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1489 \var{segment}. Must return \code{-1} and set an exception on
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1490 error. \exception{TypeError} should be raised if the object only
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1491 supports read-only buffers, and \exception{SystemError} should be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1492 raised when \var{segment} specifies a segment that doesn't exist.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1493 % Why doesn't it raise ValueError for this one?
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1494 % GJS: because you shouldn't be calling it with an invalid
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1495 % segment. That indicates a blatant programming error in the C
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1496 % code.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1497 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1498
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1499 \begin{ctypedesc}[getsegcountproc]{int (*getsegcountproc)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1500 (PyObject self, int lenp)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1501 Return the number of memory segments which comprise the buffer. If
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1502 \var{lenp} is not \NULL, the implementation must report the sum of
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1503 the sizes (in bytes) of all segments in \code{*\var{lenp}}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1504 The function cannot fail.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1505 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1506
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1507 \begin{ctypedesc}[getcharbufferproc]{int (*getcharbufferproc)
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1508 (PyObject self, int segment, const char *ptrptr)}
26059 3c23e4c3da02 Minor cleanups, markup. Fred Drake <fdrake@acm.org> parents: 26002 diff changeset	1509 Return the size of the memory buffer in \var{ptrptr} for segment
3c23e4c3da02 Minor cleanups, markup. Fred Drake <fdrake@acm.org> parents: 26002 diff changeset	1510 \var{segment}. \code{*\var{ptrptr}} is set to the memory buffer.
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1511 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1512
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1513
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1514 \section{Supporting the Iterator Protocol
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1515 \label{supporting-iteration}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1516
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1517
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1518 \section{Supporting Cyclic Garbarge Collection
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1519 \label{supporting-cycle-detection}}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1520
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1521 Python's support for detecting and collecting garbage which involves
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1522 circular references requires support from object types which are
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1523 ``containers'' for other objects which may also be containers. Types
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1524 which do not store references to other objects, or which only store
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1525 references to atomic types (such as numbers or strings), do not need
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1526 to provide any explicit support for garbage collection.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1527
22857 e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 22613 diff changeset	1528 An example showing the use of these interfaces can be found in
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 22613 diff changeset	1529 ``\ulink{Supporting the Cycle
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 22613 diff changeset	1530 Collector}{../ext/example-cycle-support.html}'' in
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 22613 diff changeset	1531 \citetitle[../ext/ext.html]{Extending and Embedding the Python
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 22613 diff changeset	1532 Interpreter}.
e24b8d0b6470 Move reference material on PyArg_Parse() out of the Extending & Embedding Fred Drake <fdrake@acm.org>* parents: 22613 diff changeset	1533
20390 946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1534 To create a container type, the \member{tp_flags} field of the type
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1535 object must include the \constant{Py_TPFLAGS_HAVE_GC} and provide an
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1536 implementation of the \member{tp_traverse} handler. If instances of the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1537 type are mutable, a \member{tp_clear} implementation must also be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1538 provided.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1539
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1540 \begin{datadesc}{Py_TPFLAGS_HAVE_GC}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1541 Objects with a type with this flag set must conform with the rules
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1542 documented here. For convenience these objects will be referred to
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1543 as container objects.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1544 \end{datadesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1545
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1546 Constructors for container types must conform to two rules:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1547
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1548 \begin{enumerate}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1549 \item The memory for the object must be allocated using
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1550 \cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_VarNew()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1551
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1552 \item Once all the fields which may contain references to other
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1553 containers are initialized, it must call
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1554 \cfunction{PyObject_GC_Track()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1555 \end{enumerate}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1556
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1557 \begin{cfuncdesc}{\var{TYPE}}{PyObject_GC_New}{TYPE, PyTypeObject type}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1558 Analogous to \cfunction{PyObject_New()} but for container objects with
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1559 the \constant{Py_TPFLAGS_HAVE_GC} flag set.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1560 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1561
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1562 \begin{cfuncdesc}{\var{TYPE}}{PyObject_GC_NewVar}{TYPE, PyTypeObject type,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1563 int size}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1564 Analogous to \cfunction{PyObject_NewVar()} but for container objects
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1565 with the \constant{Py_TPFLAGS_HAVE_GC} flag set.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1566 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1567
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1568 \begin{cfuncdesc}{PyVarObject }{PyObject_GC_Resize}{PyVarObject op, int}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1569 Resize an object allocated by \cfunction{PyObject_NewVar()}. Returns
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1570 the resized object or \NULL{} on failure.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1571 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1572
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1573 \begin{cfuncdesc}{void}{PyObject_GC_Track}{PyObject *op}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1574 Adds the object \var{op} to the set of container objects tracked by
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1575 the collector. The collector can run at unexpected times so objects
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1576 must be valid while being tracked. This should be called once all
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1577 the fields followed by the \member{tp_traverse} handler become valid,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1578 usually near the end of the constructor.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1579 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1580
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1581 \begin{cfuncdesc}{void}{_PyObject_GC_TRACK}{PyObject *op}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1582 A macro version of \cfunction{PyObject_GC_Track()}. It should not be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1583 used for extension modules.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1584 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1585
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1586 Similarly, the deallocator for the object must conform to a similar
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1587 pair of rules:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1588
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1589 \begin{enumerate}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1590 \item Before fields which refer to other containers are invalidated,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1591 \cfunction{PyObject_GC_UnTrack()} must be called.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1592
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1593 \item The object's memory must be deallocated using
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1594 \cfunction{PyObject_GC_Del()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1595 \end{enumerate}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1596
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1597 \begin{cfuncdesc}{void}{PyObject_GC_Del}{PyObject *op}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1598 Releases memory allocated to an object using
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1599 \cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_NewVar()}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1600 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1601
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1602 \begin{cfuncdesc}{void}{PyObject_GC_UnTrack}{PyObject *op}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1603 Remove the object \var{op} from the set of container objects tracked
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1604 by the collector. Note that \cfunction{PyObject_GC_Track()} can be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1605 called again on this object to add it back to the set of tracked
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1606 objects. The deallocator (\member{tp_dealloc} handler) should call
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1607 this for the object before any of the fields used by the
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1608 \member{tp_traverse} handler become invalid.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1609 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1610
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1611 \begin{cfuncdesc}{void}{_PyObject_GC_UNTRACK}{PyObject *op}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1612 A macro version of \cfunction{PyObject_GC_UnTrack()}. It should not be
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1613 used for extension modules.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1614 \end{cfuncdesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1615
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1616 The \member{tp_traverse} handler accepts a function parameter of this
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1617 type:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1618
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1619 \begin{ctypedesc}[visitproc]{int (visitproc)(PyObject object, void *arg)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1620 Type of the visitor function passed to the \member{tp_traverse}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1621 handler. The function should be called with an object to traverse
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1622 as \var{object} and the third parameter to the \member{tp_traverse}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1623 handler as \var{arg}.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1624 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1625
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1626 The \member{tp_traverse} handler must have the following type:
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1627
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1628 \begin{ctypedesc}[traverseproc]{int (traverseproc)(PyObject self,
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1629 visitproc visit, void *arg)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1630 Traversal function for a container object. Implementations must
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1631 call the \var{visit} function for each object directly contained by
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1632 \var{self}, with the parameters to \var{visit} being the contained
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1633 object and the \var{arg} value passed to the handler. If
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1634 \var{visit} returns a non-zero value then an error has occurred and
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1635 that value should be returned immediately.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1636 \end{ctypedesc}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1637
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1638 The \member{tp_clear} handler must be of the \ctype{inquiry} type, or
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1639 \NULL{} if the object is immutable.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1640
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1641 \begin{ctypedesc}[inquiry]{int (inquiry)(PyObject self)}
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1642 Drop references that may have created reference cycles. Immutable
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1643 objects do not have to define this method since they can never
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1644 directly create reference cycles. Note that the object must still
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1645 be valid after calling this method (don't just call
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1646 \cfunction{Py_DECREF()} on a reference). The collector will call
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1647 this method if it detects that this object is involved in a
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1648 reference cycle.
946bebd00132 Break the Python/C API manual into smaller files by chapter. This manual Fred Drake <fdrake@acm.org> parents: diff changeset	1649 \end{ctypedesc}

Mercurial > cpython-lru_cache-weakref

annotate Doc/api/newtypes.tex @ 27998:e27f58a50737 legacy-trunk