summaryrefslogtreecommitdiffstats
path: root/Doc/libpickle.tex
diff options
context:
space:
mode:
authorGuido van Rossum <guido@python.org>1995-03-17 16:07:09 (GMT)
committerGuido van Rossum <guido@python.org>1995-03-17 16:07:09 (GMT)
commit470be14c8aa23a35a1f4d1f1260a66a85d3f3cd9 (patch)
tree4fd0b8eda81e63366598e55362ceac85adafccb4 /Doc/libpickle.tex
parent7760cdea81166b7741561043c58dae171811fb2f (diff)
downloadcpython-470be14c8aa23a35a1f4d1f1260a66a85d3f3cd9.zip
cpython-470be14c8aa23a35a1f4d1f1260a66a85d3f3cd9.tar.gz
cpython-470be14c8aa23a35a1f4d1f1260a66a85d3f3cd9.tar.bz2
mass changes; fix titles; add examples; correct typos; clarifications;
unified style; etc.
Diffstat (limited to 'Doc/libpickle.tex')
-rw-r--r--Doc/libpickle.tex110
1 files changed, 83 insertions, 27 deletions
diff --git a/Doc/libpickle.tex b/Doc/libpickle.tex
index 5c01d36..8dc29e4 100644
--- a/Doc/libpickle.tex
+++ b/Doc/libpickle.tex
@@ -1,4 +1,4 @@
-\section{Built-in module \sectcode{pickle}}
+\section{Standard Module \sectcode{pickle}}
\stmodindex{pickle}
\index{persistency}
\indexii{persistent}{objects}
@@ -7,6 +7,8 @@
\indexii{flattening}{objects}
\indexii{pickling}{objects}
+\renewcommand{\indexsubitem}{(in module pickle)}
+
The \code{pickle} module implements a basic but powerful algorithm for
``pickling'' (a.k.a.\ serializing, marshalling or flattening) nearly
arbitrary Python objects. This is a more primitive notion than
@@ -28,11 +30,11 @@ following correctly:
\begin{itemize}
-\item recursive objects
+\item recursive objects (objects containing references to themselves)
-\item pointer sharing
+\item object sharing (references to the same object in different places)
-\item instances of user-defined classes
+\item user-defined classes and their instances
\end{itemize}
@@ -42,13 +44,13 @@ standards such as CORBA (which probably can't represent pointer
sharing or recursive objects); however it means that non-Python
programs may not be able to reconstruct pickled Python objects.
-The \code{pickle} data format uses a printable ASCII representation.
+The \code{pickle} data format uses a printable \ASCII{} representation.
This is slightly more voluminous than a binary representation.
However, small integers actually take {\em less} space when
represented as minimal-size decimal strings than when represented as
32-bit binary numbers, and strings are only much longer if they
contain many control characters or 8-bit characters. The big
-advantage of using printable ASCII (and of some other characteristics
+advantage of using printable \ASCII{} (and of some other characteristics
of \code{pickle}'s representation) is that for debugging or recovery
purposes it is possible for a human to read the pickled file with a
standard text editor. (I could have gone a step further and used a
@@ -67,7 +69,7 @@ Trojan horses into a program.
For the benefit of persistency modules written using \code{pickle}, it
supports the notion of a reference to an object outside the pickled
data stream. Such objects are referenced by a name, which is an
-arbitrary string of printable ASCII characters. The resolution of
+arbitrary string of printable \ASCII{} characters. The resolution of
such names is not defined by the \code{pickle} module --- the
persistent object module will have to implement a method
\code{persistent_load}. To write references to persistent objects,
@@ -78,6 +80,8 @@ There are some restrictions on the pickling of class instances.
First of all, the class must be defined at the top level in a module.
+\renewcommand{\indexsubitem}{(pickle protocol)}
+
Next, it must normally be possible to create class instances by
calling the class without arguments. If this is undesirable, the
class can define a method \code{__getinitargs__()}, which should
@@ -86,7 +90,7 @@ class constructor (\code{__init__()}).
\ttindex{__getinitargs__}
\ttindex{__init__}
-Classes can further influence how they are pickled --- if the class
+Classes can further influence how their instances are pickled --- if the class
defines the method \code{__getstate__()}, it is called and the return
state is pickled as the contents for the instance, and if the class
defines the method \code{__setstate__()}, it is called with the
@@ -113,6 +117,13 @@ will see many versions of a class, it may be worthwhile to put a version
number in the objects so that suitable conversions can be made by the
class's \code{__setstate__()} method.
+When a class itself is pickled, only its name is pickled --- the class
+definition is not pickled, but re-imported by the unpickling process.
+Therefore, the restriction that the class must be defined at the top
+level in a module applies to pickled classes as well.
+
+\renewcommand{\indexsubitem}{(in module pickle)}
+
The interface can be summarized as follows.
To pickle an object \code{x} onto a file \code{f}, open for writing:
@@ -122,6 +133,12 @@ p = pickle.Pickler(f)
p.dump(x)
\end{verbatim}
+A shorthand for this is:
+
+\begin{verbatim}
+pickle.dump(x, f)
+\end{verbatim}
+
To unpickle an object \code{x} from a file \code{f}, open for reading:
\begin{verbatim}
@@ -129,11 +146,19 @@ u = pickle.Unpickler(f)
x = u.load(x)
\end{verbatim}
+A shorthand is:
+
+\begin{verbatim}
+x = pickle.load(f)
+\end{verbatim}
+
The \code{Pickler} class only calls the method \code{f.write} with a
string argument. The \code{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 following types can be pickled:
\begin{itemize}
@@ -146,25 +171,56 @@ The following types can be pickled:
\item tuples, lists and dictionaries containing only picklable objects
-\item class instances whose \code{__dict__} or \code{__setstate__()}
-is picklable
+\item classes that are defined at the top level in a module
+
+\item instances of such classes whose \code{__dict__} or
+\code{__setstate__()} is picklable
\end{itemize}
-Attempts to pickle unpicklable objects will raise an exception; when
-this happens, an unspecified number of bytes may have been written to
-the file argument.
-
-It is possible to make multiple calls to \code{Pickler.dump()} or to
-\code{Unpickler.load()}, as long as there is a one-to-one
-correspondence between \code{Pickler} and \code{Unpickler} objects and
-between \code{dump} and \code{load} calls for any pair of
-corresponding \code{Pickler} and \code{Unpicklers}. {\em Warning}:
-this is intended for pickling multiple objects without intervening
-modifications to the objects or their parts. If you modify an object
-and then pickle it again using the same \code{Pickler} instance, the
-object is not pickled again --- a reference to it is pickled and the
-\code{Unpickler} will return the old value, not the modified one. (There
-are two problems here: (a) detecting changes, and (b) marshalling a
-minimal set of changes. I have no answers. Garbage Collection may
-also become a problem here.)
+Attempts to pickle unpicklable objects will raise the
+\code{PicklingError} exception; when this happens, an unspecified
+number of bytes may have been written to the file.
+
+It is possible to make multiple calls to the \code{dump()} method of
+the same \code{Pickler} instance. These must then be matched to the
+same number of calls to the \code{load()} instance of the
+corresponding \code{Unpickler} instance. If the same object is
+pickled by multiple \code{dump()} calls, the \code{load()} will all
+yield references to the same object. {\em Warning}: this is intended
+for pickling multiple objects without intervening modifications to the
+objects or their parts. If you modify an object and then pickle it
+again using the same \code{Pickler} instance, the object is not
+pickled again --- a reference to it is pickled and the
+\code{Unpickler} will return the old value, not the modified one.
+(There are two problems here: (a) detecting changes, and (b)
+marshalling a minimal set of changes. I have no answers. Garbage
+Collection may also become a problem here.)
+
+Apart from the \code{Pickler} and \code{Unpickler} classes, the
+module defines the following functions, and an exception:
+
+\begin{funcdesc}{dump}{object\, file}
+Write a pickled representation of \var{obect} to the open file object
+\var{file}. This is equivalent to \code{Pickler(file).dump(object)}.
+\end{funcdesc}
+
+\begin{funcdesc}{load}{file}
+Read a pickled object from the open file object \var{file}. This is
+equivalent to \code{Unpickler(file).load()}.
+\end{funcdesc}
+
+\begin{funcdesc}{dumps}{object}
+Return the pickled representation of the object as a string, instead
+of writing it to a file.
+\end{funcdesc}
+
+\begin{funcdesc}{loads}{string}
+Read a pickled object from a string instead of a file. Characters in
+the string past the pickled object's representation are ignored.
+\end{funcdesc}
+
+\begin{excdesc}{PicklingError}
+This exception is raised when an unpicklable object is passed to
+\code{Pickler.dump()}.
+\end{excdesc}