[Bug #984952] Include more material from PEP 307.

I haven't tried to include all the material on old-style classes using protocols 0,1.  The details are lengthy; someone who knows
more about the pickle module should decide if they're important enough
to be in the docs or not.

1 files changed, 35 insertions, 30 deletions

diff --git a/Doc/lib/libpickle.tex b/Doc/lib/libpickle.tex
index 1e01c70..989e321 100644
--- a/Doc/lib/libpickle.tex
+++ b/Doc/lib/libpickle.tex
@@ -515,21 +515,36 @@ time \method{__reduce__()} will be called with no arguments, and it
 must return either a string or a tuple.
 
 If a string is returned, it names a global variable whose contents are
-pickled as normal.  When a tuple is returned, it must be between two
-and five elements long, with the following semantics:
+pickled as normal.  The string returned by \method{__reduce__} should
+be the object's local name relative to its module; the pickle module
+searches the module namespace to determine the object's module.
+
+When a tuple is returned, it must be between two and five elements
+long. Optional elements can either be omitted, or \code{None} can be provided 
+as their value.  The semantics of each element are:
 
 \begin{itemize}
 
-\item A callable object, which in the unpickling environment must be
-      either a class, a callable registered as a ``safe constructor''
-      (see below), or it must have an attribute
-      \member{__safe_for_unpickling__} with a true value.  Otherwise,
-      an \exception{UnpicklingError} will be raised in the unpickling
-      environment.  Note that as usual, the callable itself is pickled
-      by name.
+\item A callable object that will be called to create the initial
+version of the object.  The next element of the tuple will provide
+arguments for this callable, and later elements provide additional
+state information that will subsequently be used to fully reconstruct
+the pickled date.
+
+In the unpickling environment this object must be either a class, a
+callable registered as a ``safe constructor'' (see below), or it must
+have an attribute \member{__safe_for_unpickling__} with a true value.
+Otherwise, an \exception{UnpicklingError} will be raised in the
+unpickling environment.  Note that as usual, the callable itself is
+pickled by name.
 
 \item A tuple of arguments for the callable object, or \code{None}.
-\deprecated{2.3}{Use the tuple of arguments instead}								
+\deprecated{2.3}{If this item is \code{None}, then instead of calling
+the callable directly, its \method{__basicnew__()} method is called
+without arguments; this method should also return the unpickled
+object.  Providing \code{None} is deprecated, however; return a
+tuple of arguments instead.}
+
 \item Optionally, the object's state, which will be passed to
       the object's \method{__setstate__()} method as described in
       section~\ref{pickle-inst}.  If the object has no
@@ -556,26 +571,6 @@ other classes as long as they implement \method{__setitem__}.
 
 \end{itemize}
 
-Upon unpickling, the callable will be called (provided that it meets
-the above criteria), passing in the tuple of arguments; it should
-return the unpickled object.
-
-If the second item was \code{None}, then instead of calling the
-callable directly, its \method{__basicnew__()} method is called
-without arguments.  It should also return the unpickled object.
-
-\deprecated{2.3}{Use the tuple of arguments instead}
-
-An alternative to implementing a \method{__reduce__()} method on the
-object to be pickled, is to register the callable with the
-\refmodule[copyreg]{copy_reg} module.  This module provides a way
-for programs to register ``reduction functions'' and constructors for
-user-defined types.   Reduction functions have the same semantics and
-interface as the \method{__reduce__()} method described above, except
-that they are called with a single argument, the object to be pickled.
-
-The registered constructor is deemed a ``safe constructor'' for purposes
-
 It is sometimes useful to know the protocol version when implementing
 \method{__reduce__}.  This can be done by implementing a method named
 \method{__reduce_ex__} instead of \method{__reduce__}.
@@ -590,6 +585,16 @@ The \class{object} class implements both \method{__reduce__} and
 \method{__reduce_ex__} implementation detects this and calls
 \method{__reduce__}.
 
+An alternative to implementing a \method{__reduce__()} method on the
+object to be pickled, is to register the callable with the
+\refmodule[copyreg]{copy_reg} module.  This module provides a way
+for programs to register ``reduction functions'' and constructors for
+user-defined types.   Reduction functions have the same semantics and
+interface as the \method{__reduce__()} method described above, except
+that they are called with a single argument, the object to be pickled.
+
+The registered constructor is deemed a ``safe constructor'' for purposes
+of unpickling as described above.
 
 
 \subsubsection{Pickling and unpickling external objects}