Integrate a bunch of new text from Guido.

1 files changed, 262 insertions, 6 deletions

diff --git a/Doc/api/newtypes.tex b/Doc/api/newtypes.tex
index a009a75..9bf73b5 100644
--- a/Doc/api/newtypes.tex
+++ b/Doc/api/newtypes.tex
@@ -188,12 +188,6 @@ These macros are used in the definition of \ctype{PyObject} and
 
 PyObject_HEAD_INIT
 
-Typedefs:
-unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
-intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
-destructor, printfunc, getattrfunc, getattrofunc, setattrfunc,
-setattrofunc, cmpfunc, reprfunc, hashfunc
-
 \begin{ctypedesc}{PyCFunction}
   Type of the functions used to implement most Python callables in C.
   Functions of this type take two \ctype{PyObject*} parameters and
@@ -311,6 +305,268 @@ may be set for any given method.
 \end{cfuncdesc}
 
 
+\section{Type Objects \label{type-structs}}
+
+Perhaps one of the most important structures of the Python object
+system is the structure that defines a new type: the
+\ctype{PyTypeObject} structure.  Type objects can be handled using any
+of the \cfunction{PyObject_*()} or \cfunction{PyType_*()} functions,
+but do not offer much that's interesting to most Python applications.
+These objects are fundamental to how objects behave, so they are very
+important to the interpreter itself and to any extension module that
+implements new types.
+
+Type objects are fairly large compared to most of the standard types.
+The reason for the size is that each type object stores a large number
+of values, mostly C function pointers, each of which implements a
+small part of the type's functionality.  The fields of the type object
+are examined in detail in this section.  The fields will be described
+in the order in which they occur in the structure.
+
+Typedefs:
+unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
+intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
+destructor, freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc,
+setattrofunc, cmpfunc, reprfunc, hashfunc
+
+The structure definition for \ctype{PyTypeObject} can be found in
+\file{Include/object.h}.  For convenience of reference, this repeats
+the definition found there:
+
+\verbatiminput{typestruct.h}
+
+The type object structure extends the \ctype{PyVarObject} structure,
+though it does not actually need the the \member{ob_size} field.  The
+inclusion of this field is a historical accident that must be
+maintained to ensure binary compatibility between new versions of
+Python and older compiled extensions.
+
+\begin{cmemberdesc}{PyObject}{PyObject*}{_ob_next}
+\cmemberline{PyObject}{PyObject*}{_ob_prev}
+  These fields are only present when the macro \code{Py_TRACE_REFS} is
+  defined.  Their initialization to \NULL{} is taken care of by the
+  \code{PyObject_HEAD_INIT} macro.  For statically allocated objects,
+  these fields always remain \NULL.  For dynamically allocated
+  objects, these two fields are used to link the object into a
+  doubly-linked list of \emph{all} live objects on the heap.  This
+  could be used for various debugging purposes; currently the only use
+  is to print the objects that are still alive at the end of a run
+  when the environment variable \envvar{PYTHONDUMPREFS} is set.
+
+  These fields are not inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyObject}{int}{ob_refcnt}
+  This is the type object's reference count, initialized to \code{1}
+  by the \code{PyObject_HEAD_INIT} macro.  Note that for statically
+  allocated type objects, the type's instances (objects whose
+  \member{ob_type} points back to the type) do \emph{not} count as
+  references.  But for dynamically allocated type objects, the
+  instances \emph{do} count as references.
+
+  This field is not inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyObject}{PyTypeObject*}{ob_type}
+  This is the type's type, in other words its metatype.  It is
+  initialized by the argument to the \code{PyObject_HEAD_INIT} macro,
+  and its value should normally be \code{\&PyType_Type}.  However, for
+  dynamically loadable extension modules that must be usable on
+  Windows (at least), the compiler complains that this is not a valid
+  initializer.  Therefore, the convention is to pass \NULL{} to the
+  \code{PyObject_HEAD_INIT} macro and to initialize this field
+  explicitly at the start of the module's initialization function,
+  before doing anything else.  This is typically done like this:
+
+\begin{verbatim}
+Foo_Type.ob_type = &PyType_Type;
+\end{verbatim}
+
+  This should be done before any instances of the type are created.
+  \cfunction{PyType_Ready()} checks if \member{ob_type} is \NULL, and
+  if so, initializes it: in Python 2.2, it is set to
+  \code{\&PyType_Type}; in Python 2.2.1 and later it will be
+  initialized to the \member{ob_type} field of the base class.
+  \cfunction{PyType_Ready()} will not change this field if it is
+  nonzero.
+
+  In Python 2.2, this field is not inherited by subtypes.  In 2.2.1,
+  and in 2.3 and beyond, it is inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyVarObject}{int}{ob_size}
+  For statically allocated type objects, this should be initialized
+  to zero.  For dynamically allocated type objects, this field has a
+  special internal meaning.
+
+  This field is not inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{char*}{tp_name}
+  Pointer to a NUL-terminated string containing the name of the type.
+  For types that are accessible as module globals, the string should
+  be the full module name, followed by a dot, followed by the type
+  name; for built-in types, it should be just the type name.  If the
+  module is a submodule of a package, the full package name is part of
+  the full module name.  For example, a type named \class{T} defined
+  in module \module{M} in subpackage \module{Q} in package \module{P}
+  should have the \member{tp_name} initializer \code{"P.Q.M.T"}.
+
+  For dynamically allocated type objects, this may be just the type
+  name, if the module name is explicitly stored in the type dict as
+  the value for key \code{'__module__'}.
+
+  If the tp_name field contains a dot, everything before the last dot
+  is made accessible as the \member{__module__} attribute, and
+  everything after the last dot is made accessible as the
+  \member{__name__} attribute.  If no dot is present, the entire
+  \member{tp_name} field is made accessible as the \member{__name__}
+  attribute, and the \member{__module__} attribute is undefined
+  (unless explicitly set in the dictionary, as explained above).
+
+  This field is not inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{int}{tp_basicsize}
+\cmemberline{PyTypeObject}{int}{tp_itemsize}
+  These fields allow calculating the size in byte of instances of
+  the type.
+
+  There are two kinds of types: types with fixed-length instances have
+  a zero \member{tp_itemsize} field, types with variable-length
+  instances have a non-zero \member{tp_itemsize} field.  For a type
+  with fixed-length instances, all instances have the same size,
+  given in \member{tp_basicsize}.
+
+  For a type with variable-length instances, the instances must have
+  an \member{ob_size} field, and the instance size is
+  \member{tp_basicsize} plus N times \member{tp_itemsize}, where N is
+  the ``length'' of the object.  The value of N is typically stored in
+  the instance's \member{ob_size} field.  There are exceptions:  for
+  example, long ints use a negative \member{ob_size} to indicate a
+  negative number, and N is \code{abs(\member{ob_size})} there.  Also,
+  the presence of an \member{ob_size} field in the instance layout
+  doesn't mean that the type is variable-length (for example, the list
+  type has fixed-length instances, yet those instances have a
+  meaningful \member{ob_size} field).
+
+  The basic size includes the fields in the instance declared by the
+  macro \csimplemacro{PyObject_HEAD} or
+  \csimplemacro{PyObject_VAR_HEAD} (whichever is used to declare the
+  instance struct) and this in turn includes the \member{_ob_prev} and
+  \member{_ob_next} fields if they are present.  This means that the
+  only correct way to get an initializer for the \member{tp_basicsize}
+  is to use the \keyword{sizeof} operator on the struct used to
+  declare the instance layout.  The basic size does not include the GC
+  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.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{destructor}{tp_dealloc}
+  A pointer to the instance destructor function.  This function must
+  be defined unless the type guarantees that its instances will never
+  be deallocated (as is the case for the singletons \code{None} and
+  \code{Ellipsis}).
+
+  The destructor function is called by the \cfunction{Py_DECREF()} and
+  \cfunction{Py_XDECREF()} macros when the new reference count is
+  zero.  At this point, the instance is still in existance, but there
+  are no references to it.  The destructor function should free all
+  references which the instance owns, free all memory buffers owned by
+  the instance (using the freeing function corresponding to the
+  allocation function used to allocate the buffer), and finally (as
+  its last action) call the type's \member{tp_free} slot.  If the type
+  is not subtypable (doesn't have the \constant{Py_TPFLAGS_BASETYPE}
+  flag bit set), it is permissible to call the object deallocator
+  directly instead of via \member{tp_free}.  The object deallocator
+  should be the one used to allocate the instance; this is normally
+  \cfunction{PyObject_Del()} if the instance was allocated using
+  \cfunction{PyObject_New()} or \cfunction{PyOject_VarNew()}, or
+  \cfunction{PyObject_GC_Del()} if the instance was allocated using
+  \cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_VarNew()}.
+
+  This field is inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{printfunc}{tp_print}
+  An optional pointer to the instance print function.
+
+  The print function is only called when the instance is printed to a
+  \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.
+
+  The print function is called with the same signature as
+  \cfunction{PyObject_Print()}: \code{tp_print(PyObject *self, FILE
+  *file, int flags)}.  The \var{self} argument is the instance to be
+  printed.  The \var{file} argument is the stdio file to which it is
+  to be printed.  The \var{flags} argument is composed of flag bits.
+  The only flag bit currently defined is \constant{Py_PRINT_RAW}.
+  When the \constant{Py_PRINT_RAW} flag bit is set, the instance
+  should be printed the same way as \member{tp_str} would format it;
+  when the \constant{Py_PRINT_RAW} flag bit is clear, the instance
+  should be printed the same was as \member{tp_repr} would format it.
+
+  It is possible that the \member{tp_print} field will be deprecated.
+  In any case, it is recommended not to define \member{tp_print}, but
+  instead to rely on \member{tp_repr} and \member{tp_str} for
+  printing.
+
+  This field is inherited by subtypes.
+\end{cmemberdesc}
+
+\begin{cmemberdesc}{PyTypeObject}{getattrfunc}{tp_getattr}
+  An optional pointer to the get-attribute-string function.
+
+  This field is deprecated.  When it is defined, it should point to a
+  function that acts the same as the \member{tp_getattro} function,
+  but taking a C string instead of a Python string object to give the
+  attribute name.  The signature is the same as for
+  \cfunction{PyObject_GetAttrString()}.
+
+  This field is inherited by subtypes together with
+  \member{tp_getattro}: 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}{setattrfunc}{tp_setattr}
+  An optional pointer to the set-attribute-string function.
+
+  This field is deprecated.  When it is defined, it should point to a
+  function that acts the same as the \member{tp_setattro} function,
+  but taking a C string instead of a Python string object to give the
+  attribute name.  The signature is the same as for
+  \cfunction{PyObject_SetAttrString()}.
+
+  This field is inherited by subtypes together with
+  \member{tp_setattro}: 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}
+
+\begin{cmemberdesc}{PyTypeObject}{cmpfunc}{tp_compare}
+  An optional pointer to the three-way comparison function.
+
+  The signature is the same as for \cfunction{PyObject_Compare()}.
+  The function should return \code{1} if \var{self} greater than
+  \var{other}, \code{0} if \var{self} is equal to \var{other}, and
+  \code{-1} if \var{self} less than \var{other}.  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_richcompare} and \member{tp_hash}: 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}
+
+
+
 \section{Mapping Object Structures \label{mapping-structs}}
 
 \begin{ctypedesc}{PyMappingMethods}