[Python-checkins] python/dist/src/Doc/lib libpickle.tex,1.38,1.39

[nnorwitz@users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv9238/Doc/lib

Modified Files:
	libpickle.tex 
Log Message:
Try to doc the new pickle details being implemented as part of PEP 307.
Needs review.


Index: libpickle.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libpickle.tex,v
retrieving revision 1.38
retrieving revision 1.39
diff -C2 -d -r1.38 -r1.39
*** libpickle.tex	27 Nov 2002 05:26:46 -0000	1.38
--- libpickle.tex	13 Feb 2003 03:12:48 -0000	1.39
***************
*** 127,134 ****
  the pickled file with a standard text editor.
  
  A binary format, which is slightly more efficient, can be chosen by
  specifying a true value for the \var{bin} argument to the
  \class{Pickler} constructor or the \function{dump()} and \function{dumps()}
! functions.
  
  \subsection{Usage}
--- 127,159 ----
  the pickled file with a standard text editor.
  
+ There are currently 3 different protocols which can be used for pickling.
+ 
+ \begin{itemize}
+ 
+ \item Protocol version 0 is the original ASCII protocol and is backwards
+ compatible with earlier versions of Python.
+ 
+ \item Protocol version 1 is the old binary format which is also compatible
+ with earlier versions of Python.
+ 
+ \item Protocol version 2 was introduced in Python 2.3.  It provides
+ much more efficient pickling of new-style classes.
+ 
+ \end{itemize}
+ 
+ Refer to PEP 307 for more information.
+ 
+ If a \var{protocol} is not specified, protocol 0 is used.
+ If \var{protocol} is specified as a negative value,
+ the highest protocol version will be used.
+ 
+ \versionchanged[The \var{bin} parameter is deprecated and only provided
+ for backwards compatibility.  You should use the \var{protocol}
+ parameter instead]{2.3}
+ 
  A binary format, which is slightly more efficient, can be chosen by
  specifying a true value for the \var{bin} argument to the
  \class{Pickler} constructor or the \function{dump()} and \function{dumps()}
! functions.  A \var{protocol} version >= 1 implies use of a binary format.
  
  \subsection{Usage}
***************
*** 140,147 ****
  following functions to make this process more convenient:
  
! \begin{funcdesc}{dump}{object, file\optional{, bin}}
  Write a pickled representation of \var{object} to the open file object
  \var{file}.  This is equivalent to
! \code{Pickler(\var{file}, \var{bin}).dump(\var{object})}.
  If the optional \var{bin} argument is true, the binary pickle format
  is used; otherwise the (less efficient) text pickle format is used
--- 165,182 ----
  following functions to make this process more convenient:
  
! \begin{funcdesc}{dump}{object, file\optional{, protocol\optional{, bin}}}
  Write a pickled representation of \var{object} to the open file object
  \var{file}.  This is equivalent to
! \code{Pickler(\var{file}, \var{protocol}, \var{bin}).dump(\var{object})}.
! 
! If the \var{protocol} parameter is ommitted, protocol 0 is used.
! If \var{protocol} is specified as a negative value,
! the highest protocol version will be used.
! 
! \versionchanged[The \var{protocol} parameter was added.
! The \var{bin} parameter is deprecated and only provided
! for backwards compatibility.  You should use the \var{protocol}
! parameter instead]{2.3}
! 
  If the optional \var{bin} argument is true, the binary pickle format
  is used; otherwise the (less efficient) text pickle format is used
***************
*** 170,176 ****
  \end{funcdesc}
  
! \begin{funcdesc}{dumps}{object\optional{, bin}}
  Return the pickled representation of the object as a string, instead
! of writing it to a file.  If the optional \var{bin} argument is
  true, the binary pickle format is used; otherwise the (less efficient)
  text pickle format is used (this is the default).
--- 205,222 ----
  \end{funcdesc}
  
! \begin{funcdesc}{dumps}{object\optional{, protocol\optional{, bin}}}
  Return the pickled representation of the object as a string, instead
! of writing it to a file.
! 
! If the \var{protocol} parameter is ommitted, protocol 0 is used.
! If \var{protocol} is specified as a negative value,
! the highest protocol version will be used.
! 
! \versionchanged[The \var{protocol} parameter was added.
! The \var{bin} parameter is deprecated and only provided
! for backwards compatibility.  You should use the \var{protocol}
! parameter instead]{2.3}
! 
! If the optional \var{bin} argument is
  true, the binary pickle format is used; otherwise the (less efficient)
  text pickle format is used (this is the default).
***************
*** 211,217 ****
  \class{Unpickler}:
  
! \begin{classdesc}{Pickler}{file\optional{, bin}}
  This takes a file-like object to which it will write a pickle data
! stream.  Optional \var{bin} if true, tells the pickler to use the more
  efficient binary pickle format, otherwise the \ASCII{} format is used
  (this is the default).
--- 257,273 ----
  \class{Unpickler}:
  
! \begin{classdesc}{Pickler}{file\optional{, protocol\optional{, bin}}}
  This takes a file-like object to which it will write a pickle data
! stream.  
! 
! If the \var{protocol} parameter is ommitted, protocol 0 is used.
! If \var{protocol} is specified as a negative value,
! the highest protocol version will be used.
! 
! \versionchanged[The \var{bin} parameter is deprecated and only provided
! for backwards compatibility.  You should use the \var{protocol}
! parameter instead]{2.3}
! 
! Optional \var{bin} if true, tells the pickler to use the more
  efficient binary pickle format, otherwise the \ASCII{} format is used
  (this is the default).