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

[akuchling at users.sourceforge.net]

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

Modified Files:
	libpickle.tex 
Log Message:
[Bug #984952] Include some material from PEP 307

Index: libpickle.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libpickle.tex,v
retrieving revision 1.49
retrieving revision 1.50
diff -C2 -d -r1.49 -r1.50
*** libpickle.tex	5 May 2004 04:56:06 -0000	1.49
--- libpickle.tex	7 Aug 2004 15:49:24 -0000	1.50
***************
*** 516,521 ****
  
  If a string is returned, it names a global variable whose contents are
! pickled as normal.  When a tuple is returned, it must be of length two
! or three, with the following semantics:
  
  \begin{itemize}
--- 516,521 ----
  
  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}
***************
*** 531,535 ****
  \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
--- 531,534 ----
***************
*** 539,542 ****
--- 538,558 ----
        \member{__dict__}.
  
+ \item Optionally, an iterator (and not a sequence) yielding successive
+ list items.  These list items will be pickled, and appended to the
+ object using either \code{obj.append(\var{item})} or
+ \code{obj.extend(\var{list_of_items})}.  This is primarily used for
+ list subclasses, but may be used by other classes as long as they have
+ \method{append()} and \method{extend()} methods with the appropriate
+ signature.  (Whether \method{append()} or \method{extend()} is used
+ depends on which pickle protocol version is used as well as the number
+ of items to append, so both must be supported.)
+ 
+ \item Optionally, an iterator (not a sequence)
+ yielding successive dictionary items, which should be tuples of the
+ form \code{(\var{key}, \var{value})}.  These items will be pickled
+ and stored to the object using \code{obj[\var{key}] = \var{value}}.
+ This is primarily used for dictionary subclasses, but may be used by
+ other classes as long as they implement \method{__setitem__}.
+ 
  \end{itemize}
  
***************
*** 560,564 ****
  
  The registered constructor is deemed a ``safe constructor'' for purposes
! of unpickling as described above.
  
  \subsubsection{Pickling and unpickling external objects}
--- 576,595 ----
  
  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__}.
! \method{__reduce_ex__}, when it exists, is called in preference over
! \method{__reduce__} (you may still provide \method{__reduce__} for
! backwards compatibility).  The \method{__reduce_ex__} method will be
! called with a single integer argument, the protocol version.
! 
! The \class{object} class implements both \method{__reduce__} and
! \method{__reduce_ex__}; however, if a subclass overrides
! \method{__reduce__} but not \method{__reduce_ex__}, the
! \method{__reduce_ex__} implementation detects this and calls
! \method{__reduce__}.
! 
! 
  
  \subsubsection{Pickling and unpickling external objects}