Fix a few markup nits, improve some index entries.

freddrake · freddrake · commit 41796918afe5 · 1999-07-02T14:25:37.000Z
diff --git a/Doc/lib/libpickle.tex b/Doc/lib/libpickle.tex
@@ -12,29 +12,30 @@ \section{\module{pickle} ---
 \indexii{pickling}{objects}
 
 
-The \module{pickle} module implements a basic but powerful algorithm for
-``pickling'' (a.k.a.\ serializing, marshalling or flattening) nearly
-arbitrary Python objects.  This is the act of converting objects to a
-stream of bytes (and back: ``unpickling'').
-This is a more primitive notion than
-persistency --- although \module{pickle} reads and writes file objects,
-it does not handle the issue of naming persistent objects, nor the
-(even more complicated) area of concurrent access to persistent
-objects.  The \module{pickle} module can transform a complex object into
-a byte stream and it can transform the byte stream into an object with
-the same internal structure.  The most obvious thing to do with these
-byte streams is to write them onto a file, but it is also conceivable
-to send them across a network or store them in a database.  The module
+The \module{pickle} module implements a basic but powerful algorithm
+for ``pickling'' (a.k.a.\ serializing, marshalling or flattening)
+nearly arbitrary Python objects.  This is the act of converting
+objects to a stream of bytes (and back: ``unpickling'').  This is a
+more primitive notion than persistency --- although \module{pickle}
+reads and writes file objects, it does not handle the issue of naming
+persistent objects, nor the (even more complicated) area of concurrent
+access to persistent objects.  The \module{pickle} module can
+transform a complex object into a byte stream and it can transform the
+byte stream into an object with the same internal structure.  The most
+obvious thing to do with these byte streams is to write them onto a
+file, but it is also conceivable to send them across a network or
+store them in a database.  The module
 \refmodule{shelve}\refstmodindex{shelve} provides a simple interface
 to pickle and unpickle objects on DBM-style database files.
 
 
 \strong{Note:} The \module{pickle} module is rather slow.  A
 reimplementation of the same algorithm in C, which is up to 1000 times
-faster, is available as the \refmodule{cPickle}\refbimodindex{cPickle}
-module.  This has the same interface except that \code{Pickler} and
-\code{Unpickler} are factory functions, not classes (so they cannot be
-used as base classes for inheritance).
+faster, is available as the
+\refmodule{cPickle}\refbimodindex{cPickle} module.  This has the same
+interface except that \class{Pickler} and \class{Unpickler} are
+factory functions, not classes (so they cannot be used as base classes
+for inheritance).
 
 Unlike the built-in module \refmodule{marshal}\refbimodindex{marshal},
 \module{pickle} handles the following correctly:
@@ -72,12 +73,11 @@ \section{\module{pickle} ---
 the default may change to binary.
 
 The \module{pickle} module doesn't handle code objects, which the
-\refmodule{marshal} module does.  I suppose \module{pickle} could, and maybe
-it should, but there's probably no great need for it right now (as
-long as \refmodule{marshal} continues to be used for reading and writing
-code objects), and at least this avoids the possibility of smuggling
-Trojan horses into a program.
-\refbimodindex{marshal}
+\refmodule{marshal}\refbimodindex{marshal} module does.  I suppose
+\module{pickle} could, and maybe it should, but there's probably no
+great need for it right now (as long as \refmodule{marshal} continues
+to be used for reading and writing code objects), and at least this
+avoids the possibility of smuggling Trojan horses into a program.
 
 For the benefit of persistency modules written using \module{pickle}, it
 supports the notion of a reference to an object outside the pickled
@@ -109,10 +109,15 @@ \section{\module{pickle} ---
 passed to the class constructor (\method{__init__()}).  This method is
 called at pickle time; the tuple it returns is incorporated in the
 pickle for the instance.
-\ttindex{__getinitargs__()}
-\ttindex{__init__()}
-
-Classes can further influence how their instances are pickled --- if the class
+\withsubitem{(copy protocol)}{\ttindex{__getinitargs__()}}
+\withsubitem{(instance constructor)}{\ttindex{__init__()}}
+
+Classes can further influence how their instances are pickled --- if
+the class
+\withsubitem{(copy protocol)}{
+  \ttindex{__getstate__()}\ttindex{__setstate__()}}
+\withsubitem{(instance attribute)}{
+  \ttindex{__dict__}}
 defines the method \method{__getstate__()}, it is called and the return
 state is pickled as the contents for the instance, and if the class
 defines the method \method{__setstate__()}, it is called with the
@@ -126,9 +131,6 @@ \section{\module{pickle} ---
 --- these methods can do what they want.)  This protocol is also used
 by the shallow and deep copying operations defined in the
 \refmodule{copy}\refstmodindex{copy} module.
-\ttindex{__getstate__()}
-\ttindex{__setstate__()}
-\ttindex{__dict__}
 
 Note that when class instances are pickled, their class's code and
 data are not pickled along with them.  Only the instance data are
@@ -175,12 +177,12 @@ \section{\module{pickle} ---
 \end{verbatim}
 
 The \class{Pickler} class only calls the method \code{f.write()} with a
+\withsubitem{(class in pickle)}{
+  \ttindex{Unpickler}\ttindex{Pickler}}
 string argument.  The \class{Unpickler} calls the methods \code{f.read()}
 (with an integer argument) and \code{f.readline()} (without argument),
 both returning a string.  It is explicitly allowed to pass non-file
 objects here, as long as they have the right methods.
-\ttindex{Unpickler}
-\ttindex{Pickler}
 
 The constructor for the \class{Pickler} class has an optional second
 argument, \var{bin}.  If this is present and nonzero, the binary
@@ -190,6 +192,7 @@ \section{\module{pickle} ---
 between binary and text pickle formats; it accepts either format.
 
 The following types can be pickled:
+
 \begin{itemize}
 
 \item \code{None}
@@ -257,7 +260,7 @@ \section{\module{pickle} ---
 
 \begin{excdesc}{PicklingError}
 This exception is raised when an unpicklable object is passed to
-\code{Pickler.dump()}.
+\method{Pickler.dump()}.
 \end{excdesc}
 
 
@@ -283,11 +286,11 @@ \section{\module{cPickle} ---
 
 
 The \module{cPickle} module provides a similar interface and identical
-functionality as the \refmodule{pickle} module, but can be up to 1000
-times faster since it is implemented in C.  The only other
-important difference to note is that \function{Pickler()} and
-\function{Unpickler()} are functions and not classes, and so cannot be
-subclassed.  This should not be an issue in most cases.
+functionality as the \refmodule{pickle}\refstmodindex{pickle} module,
+but can be up to 1000 times faster since it is implemented in C.  The
+only other important difference to note is that \function{Pickler()}
+and \function{Unpickler()} are functions and not classes, and so
+cannot be subclassed.  This should not be an issue in most cases.
 
 The format of the pickle data is identical to that produced using the
 \refmodule{pickle} module, so it is possible to use \refmodule{pickle} and
