Integrated more text from Guido.

Doc/api/newtypes.tex

@@ -461,7 +461,10 @@ Foo_Type.ob_type = &PyType_Type;
   header size (this is new in Python 2.2; in 2.1 and 2.0, the GC
   header size was included in \member{tp_basicsize}).
 
-  These fields are inherited by subtypes.
+  These fields are inherited separately by subtypes.  If the base type
+  has a non-zero \member{tp_itemsize}, it is generally not safe to set
+  \member{tp_itemsize} to a different non-zero value in a subtype
+  (though this depends on the implementation of the base type).
 \end{cmemberdesc}
 
 \begin{cmemberdesc}{PyTypeObject}{destructor}{tp_dealloc}
@@ -497,7 +500,9 @@ Foo_Type.ob_type = &PyType_Type;
   \emph{real} file; when it is printed to a pseudo-file (like a
   \class{StringIO} instance), the instance's \member{tp_repr} or
   \member{tp_str} function is called to convert it to a string.  These
-  are also called when the type's \member{tp_print} field is \NULL.
+  are also called when the type's \member{tp_print} field is \NULL.  A
+  type should never implement \member{tp_print} in a way that produces
+  different output than \member{tp_repr} or \member{tp_str} would.
 
   The print function is called with the same signature as
   \cfunction{PyObject_Print()}: \code{tp_print(PyObject *self, FILE
@@ -565,6 +570,358 @@ Foo_Type.ob_type = &PyType_Type;
   \member{tp_richcompare}, and \member{tp_hash} are all \NULL.
 \end{cmemberdesc}
 
+\begin{cmemberdesc}{PyTypeObject}{reprfunc}{tp_repr}
+  An optional pointer to a function that implements the built-in
+  function \function{repr()}.\bifuncindex{repr}
+
+  The signature is the same as for \cfunction{PyObject_Repr()}; it
+  must return a string or a Unicode object.  Ideally, this function
+  should return a string that, when passed to \function{eval()}, given
+  a suitable environment, returns an object with the same value.  If
+  this is not feasible, it should return a string starting with
+  \character{\textless} and ending with \character{\textgreater} from
+  which both the type and the value of the object can be deduced.
+
+  When this field is not set, a string of the form \samp{<\%s object
+  at \%p>} is returned, where \code{\%s} is replaced by the type name,
+  and \code{\%p} by the object's memory address.
+
+  This field is inherited by subtypes.
+\end{cmemberdesc}
+
+PyNumberMethods *tp_as_number;
+
+    XXX
+
+PySequenceMethods *tp_as_sequence;
+
+    XXX
+
+PyMappingMethods *tp_as_mapping;
+
+    XXX
+
+\begin{cmemberdesc}{PyTypeObject}{hashfunc}{tp_hash}
+  An optional pointer to a function that implements the built-in
+  function \function{hash()}.\bifuncindex{hash}
+
+  The signature is the same as for \cfunction{PyObject_Hash()}; it
+  must return a C long.  The value \code{-1} should not be returned as
+  a normal return value; when an error occurs during the computation
+  of the hash value, the function should set an exception and return
+  \code{-1}.
+
+  When this field is not set, two possibilities exist: if the
+  \member{tp_compare} and \member{tp_richcompare} fields are both
+  \NULL, a default hash value based on the object's address is
+  returned; otherwise, a \exception{TypeError} is raised.
+
+  This field is inherited by subtypes together with
+  \member{tp_richcompare} and \member{tp_compare}: a subtypes inherits
+  all three of \member{tp_compare}, \member{tp_richcompare}, and
+  \member{tp_hash}, when the subtype's \member{tp_compare},
+  \member{tp_richcompare} and \member{tp_hash} are all \NULL.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{ternaryfunc}{tp_call}
+  An optional pointer to a function that implements calling the
+  object.  This should be \NULL{} if the object is not callable.  The
+  signature is the same as for \cfunction{PyObject_Call()}.
+
+  This field is inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{reprfunc}{tp_str}
+  An optional pointer to a function that implements the built-in
+  operation \function{str()}.  (Note that \class{str} is a type now,
+  and \function{str()} calls the constructor for that type.  This
+  constructor calls \cfunction{PyObject_Str()} to do the actual work,
+  and \cfunction{PyObject_Str()} will call this handler.)
+
+  The signature is the same as for \cfunction{PyObject_Str()}; it must
+  return a string or a Unicode object.  This function should return a
+  ``friendly'' string representation of the object, as this is the
+  representation that will be used by the print statement.
+
+  When this field is not set, \cfunction{PyObject_Repr()} is called to
+  return a string representation.
+
+  This field is inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{getattrofunc}{tp_getattro}
+  An optional pointer to the get-attribute function.
+
+  The signature is the same as for \cfunction{PyObject_GetAttr()}.  It
+  is usually convenient to set this field to
+  \cfunction{PyObject_GenericGetAttr()}, which implements the normal
+  way of looking for object attributes.
+
+  This field is inherited by subtypes together with
+  \member{tp_getattr}: a subtype inherits both \member{tp_getattr} and
+  \member{tp_getattro} from its base type when the subtype's
+  \member{tp_getattr} and \member{tp_getattro} are both \NULL.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{setattrofunc}{tp_setattro}
+  An optional pointer to the set-attribute function.
+
+  The signature is the same as for \cfunction{PyObject_SetAttr()}.  It
+  is usually convenient to set this field to
+  \cfunction{PyObject_GenericSetAttr()}, which implements the normal
+  way of setting object attributes.
+
+  This field is inherited by subtypes together with
+  \member{tp_setattr}: a subtype inherits both \member{tp_setattr} and
+  \member{tp_setattro} from its base type when the subtype's
+  \member{tp_setattr} and \member{tp_setattro} are both \NULL.
+\end{cmemberdesc}
+
+PyBufferProcs *tp_as_buffer;
+
+    XXX
+
+\begin{cmemberdesc}{PyTypeObject}{long}{tp_flags}
+  This field is a bit mask of various flags.  Some flags indicate
+  variant semantics for certain situations; others are used to
+  indicate that certain fields in the type object (or in the extension
+  structures referenced via \member{tp_as_number},
+  \member{tp_as_sequence}, \member{tp_as_mapping}, and
+  \member{tp_as_buffer}) that were historically not always present are
+  valid; if such a flag bit is clear, the type fields it guards must
+  not be accessed and must be considered to have a zero or \NULL{}
+  value instead.
+
+  Inheritance of this field is complicated.  Most flag bits are
+  inherited individually, i.e. if the base type has a flag bit set,
+  the subtype inherits this flag bit.  The flag bits that pertain to
+  extension structures are strictly inherited if the extension
+  structure is inherited, i.e. the base type's value of the flag bit
+  is copied into the subtype together with a pointer to the extension
+  structure.  The \constant{Py_TPFLAGS_HAVE_GC} flag bit is inherited
+  together with the \member{tp_traverse} and \member{tp_clear} fields,
+  i.e. if the \constant{Py_TPFLAGS_HAVE_GC} flag bit is clear in the
+  subtype and the \member{tp_traverse} and \member{tp_clear} fields in
+  the subtype exist (as indicated by the
+  \constant{Py_TPFLAGS_HAVE_RICHCOMPARE} flag bit) and have \NULL{}
+  values.
+
+  The following bit masks are currently defined; these can be or-ed
+  together using the \code{|} operator to form the value of the
+  \member{tp_flags} field.  The macro \cfunction{PyType_HasFeature()}
+  takes a type and a flags value, \var{tp} and \var{f}, and checks
+  whether \code{\var{tp}->tp_flags \& \var{f}} is nonzero.
+
+  \begin{datadesc}{Py_TPFLAGS_HAVE_GETCHARBUFFER}
+    If this bit is set, the \ctype{PyBufferProcs} struct referenced by
+    \member{tp_as_buffer} has the \member{bf_getcharbuffer} field.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_HAVE_SEQUENCE_IN}
+    If this bit is set, the \ctype{PySequenceMethods} struct
+    referenced by \member{tp_as_sequence} has the \member{sq_contains}
+    field.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_GC}
+    This bit is obsolete.  The bit it used to name is no longer in
+    use.  The symbol is now defined as zero.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_HAVE_INPLACEOPS}
+    If this bit is set, the \ctype{PySequenceMethods} struct
+    referenced by \member{tp_as_sequence} and the
+    \ctype{PyNumberMethods} structure referenced by
+    \member{tp_as_number} contain the fields for in-place operators.
+    In particular, this means that the \ctype{PyNumberMethods}
+    structure has the fields \member{nb_inplace_add},
+    \member{nb_inplace_subtract}, \member{nb_inplace_multiply},
+    \member{nb_inplace_divide}, \member{nb_inplace_remainder},
+    \member{nb_inplace_power}, \member{nb_inplace_lshift},
+    \member{nb_inplace_rshift}, \member{nb_inplace_and},
+    \member{nb_inplace_xor}, and \member{nb_inplace_or}; and the
+    \ctype{PySequenceMethods} struct has the fields
+    \member{sq_inplace_concat} and \member{sq_inplace_repeat}.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_CHECKTYPES}
+    If this bit is set, the binary and ternary operations in the
+    \ctype{PyNumberMethods} structure referenced by
+    \member{tp_as_number} accept arguments of arbitrary object types,
+    and do their own type conversions if needed.  If this bit is
+    clear, those operations require that all arguments have the
+    current type as their type, and the caller is supposed to perform
+    a coercion operation first.  This applies to \member{nb_add},
+    \member{nb_subtract}, \member{nb_multiply}, \member{nb_divide},
+    \member{nb_remainder}, \member{nb_divmod}, \member{nb_power},
+    \member{nb_lshift}, \member{nb_rshift}, \member{nb_and},
+    \member{nb_xor}, and \member{nb_or}.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_HAVE_RICHCOMPARE}
+    If this bit is set, the type object has the
+    \member{tp_richcompare} field, as well as the \member{tp_traverse}
+    and the \member{tp_clear} fields.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_HAVE_WEAKREFS}
+    If this bit is set, the \member{tp_weaklistoffset} field is
+    defined.  Instances of a type are weakly referenceable if the
+    type's \member{tp_weaklistoffset} field has a value greater than
+    zero.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_HAVE_ITER}
+    If this bit is set, the type object has the \member{tp_iter} and
+    \member{tp_iternext} fields.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_HAVE_CLASS}
+    If this bit is set, the type object has several new fields defined
+    starting in Python 2.2: \member{tp_methods}, \member{tp_members},
+    \member{tp_getset}, \member{tp_base}, \member{tp_dict},
+    \member{tp_descr_get}, \member{tp_descr_set},
+    \member{tp_dictoffset}, \member{tp_init}, \member{tp_alloc},
+    \member{tp_new}, \member{tp_free}, \member{tp_is_gc},
+    \member{tp_bases}, \member{tp_mro}, \member{tp_cache},
+    \member{tp_subclasses}, and \member{tp_weaklist}.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_HEAPTYPE}
+    This bit is set when the type object itself is allocated on the
+    heap.  In this case, the \member{ob_type} field of its instances
+    is considered a reference to the type, and the type object is
+    INCREF'ed when a new instance is created, and DECREF'ed when an
+    instance is destroyed (this does not apply to instances of
+    subtypes; only the type referenced by the instance's ob_type gets
+    INCREF'ed or DECREF'ed).
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_BASETYPE}
+    This bit is set when the type can be used as the base type of
+    another type.  If this bit is clear, the type cannot be subtyped
+    (similar to a "final" class in Java).
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_READY}
+    This bit is set when the type object has been fully initialized by
+    \cfunction{PyType_Ready()}.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_READYING}
+    This bit is set while \cfunction{PyType_Ready()} is in the process
+    of initializing the type object.
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_HAVE_GC}
+    This bit is set when the object supports garbage collection.  If
+    this bit is set, instances must be created using
+    \cfunction{PyObject_GC_New()} and destroyed using
+    \cfunction{PyObject_GC_Del()}.  More information in section XXX
+    about garbage collection.  This bit also implies that the
+    GC-related fields \member{tp_traverse} and \member{tp_clear} are
+    present in the type object; but those fields also exist when
+    \constant{Py_TPFLAGS_HAVE_GC} is clear but
+    \constant{Py_TPFLAGS_HAVE_RICHCOMPARE} is set).
+  \end{datadesc}
+
+  \begin{datadesc}{Py_TPFLAGS_DEFAULT}
+    This is a bitmask of all the bits that pertain to the existence of
+    certain fields in the type object and its extension structures.
+    Currently, it includes the following bits:
+    \constant{Py_TPFLAGS_HAVE_GETCHARBUFFER},
+    \constant{Py_TPFLAGS_HAVE_SEQUENCE_IN},
+    \constant{Py_TPFLAGS_HAVE_INPLACEOPS},
+    \constant{Py_TPFLAGS_HAVE_RICHCOMPARE},
+    \constant{Py_TPFLAGS_HAVE_WEAKREFS},
+    \constant{Py_TPFLAGS_HAVE_ITER}, and
+    \constant{Py_TPFLAGS_HAVE_CLASS}.
+  \end{datadesc}
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{char*}{tp_doc}
+  An optional pointer to a NUL-terminated C string giving the
+  docstring for this type object.
+
+  This field is \emph{not} inherited by subtypes.
+\end{cmemberdesc}
+
+The following three fields only exist if the
+\constant{Py_TPFLAGS_HAVE_RICHCOMPARE} flag bit is set.
+
+\begin{cmemberdesc}{PyTypeObject}{traverseproc}{tp_traverse}
+  An optional pointer to a traversal function for the garbage
+  collector.  This is only used if the \constant{Py_TPFLAGS_HAVE_GC}
+  flag bit is set.  More information in section XXX about garbage
+  collection.
+
+  This field is inherited by subtypes together with \member{tp_clear}
+  and the \constant{Py_TPFLAGS_HAVE_GC} flag bit: the flag bit,
+  \member{tp_traverse}, and \member{tp_clear} are all inherited from
+  the base type if they are all zero in the subtype \emph{and} the
+  subtype has the \constant{Py_TPFLAGS_HAVE_RICHCOMPARE} flag bit set.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{inquiry}{tp_clear}
+  An optional pointer to a clear function for the garbage collector.
+  This is only used if the \constant{Py_TPFLAGS_HAVE_GC} flag bit is
+  set.  More information in section XXX about garbage collection.
+
+  This field is inherited by subtypes together with \member{tp_clear}
+  and the \constant{Py_TPFLAGS_HAVE_GC} flag bit: the flag bit,
+  \member{tp_traverse}, and \member{tp_clear} are all inherited from
+  the base type if they are all zero in the subtype \emph{and} the
+  subtype has the \constant{Py_TPFLAGS_HAVE_RICHCOMPARE} flag bit set.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{richcmpfunc}{tp_richcompare}
+  An optional pointer to the rich comparison function.
+
+  The signature is the same as for \cfunction{PyObject_RichCompare()}.
+  The function should return \code{1} if the requested comparison
+  returns true, \code{0} if it returns false.  It should return
+  \code{-1} and set an exception condition when an error occurred
+  during the comparison.
+
+  This field is inherited by subtypes together with
+  \member{tp_compare} and \member{tp_hash}: a subtype inherits all
+  three of \member{tp_compare}, \member{tp_richcompare}, and
+  \member{tp_hash}, when the subtype's \member{tp_compare},
+  \member{tp_richcompare}, and \member{tp_hash} are all \NULL.
+
+  The following constants are defined to be used as the third argument
+  for \member{tp_richcompare} and for \cfunction{PyObject_RichCompare()}:
+
+  \begin{tableii}{l|c}{constant}{Constant}{Comparison}
+    \lineii{Py_LT}{\code{<}}
+    \lineii{Py_LE}{\code{<=}}
+    \lineii{Py_EQ}{\code{==}}
+    \lineii{Py_NE}{\code{!=}}
+    \lineii{Py_GT}{\code{>}}
+    \lineii{Py_GE}{\code{>=}}
+  \end{tableii}
+\end{cmemberdesc}
+
+The next field only exists if the \constant{Py_TPFLAGS_HAVE_WEAKREFS}
+flag bit is set.  (XXX ???)
+
+long tp_weaklistoffset;
+
+    XXX
+
+
+The remaining fields only exist if the
+\constant{Py_TPFLAGS_HAVE_CLASS} flag bit is set.
+
+/* Added in release 2.2 */
+/* Iterators */
+getiterfunc tp_iter;
+
+    XXX
+
+iternextfunc tp_iternext;
+
+    XXX
 
 
 \section{Mapping Object Structures \label{mapping-structs}}