[Python-checkins] python/dist/src/Doc/lib libpickle.tex,1.50,1.51

[akuchling at users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv14464

Modified Files:
	libpickle.tex 
Log Message:
[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.

Index: libpickle.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libpickle.tex,v
retrieving revision 1.50
retrieving revision 1.51
diff -C2 -d -r1.50 -r1.51
*** libpickle.tex	7 Aug 2004 15:49:24 -0000	1.50
--- libpickle.tex	7 Aug 2004 16:24:18 -0000	1.51
***************
*** 516,534 ****
  
  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:
  
  \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 tuple of arguments for the callable object, or \code{None}.
! \deprecated{2.3}{Use the tuple of arguments instead}								
  \item Optionally, the object's state, which will be passed to
        the object's \method{__setstate__()} method as described in
--- 516,549 ----
  
  If a string is returned, it names a global variable whose contents are
! 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 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}{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
***************
*** 557,580 ****
  \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
--- 572,575 ----
***************
*** 591,594 ****
--- 586,599 ----
  \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.