mirror of
https://github.com/python/cpython.git
synced 2025-11-03 19:34:08 +00:00
256 lines
11 KiB
TeX
256 lines
11 KiB
TeX
\section{Standard Module \sectcode{pickle}}
|
|
\label{module-pickle}
|
|
\stmodindex{pickle}
|
|
\index{persistency}
|
|
\indexii{persistent}{objects}
|
|
\indexii{serializing}{objects}
|
|
\indexii{marshalling}{objects}
|
|
\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 the act of converting objects to a
|
|
stream of bytes (and back: ``unpickling'').
|
|
This is a more primitive notion than
|
|
persistency --- although \code{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 \code{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
|
|
\code{shelve} provides a simple interface to pickle and unpickle
|
|
objects on ``dbm''-style database files.
|
|
\refstmodindex{shelve}
|
|
|
|
\strong{Note:} The \code{pickle} module is rather slow. A
|
|
reimplementation of the same algorithm in C, which is up to 1000 times
|
|
faster, is available as the \code{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 a base class for
|
|
inheritance).
|
|
|
|
Unlike the built-in module \code{marshal}, \code{pickle} handles the
|
|
following correctly:
|
|
\refbimodindex{marshal}
|
|
|
|
\begin{itemize}
|
|
|
|
\item recursive objects (objects containing references to themselves)
|
|
|
|
\item object sharing (references to the same object in different places)
|
|
|
|
\item user-defined classes and their instances
|
|
|
|
\end{itemize}
|
|
|
|
The data format used by \code{pickle} is Python-specific. This has
|
|
the advantage that there are no restrictions imposed by external
|
|
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.
|
|
|
|
By default, the \code{pickle} data format uses a printable \ASCII{}
|
|
representation. This is slightly more voluminous than a binary
|
|
representation. The big 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.
|
|
|
|
A binary format, which is slightly more efficient, can be chosen by
|
|
specifying a nonzero (true) value for the \var{bin} argument to the
|
|
\code{Pickler} constructor or the \code{dump()} and \code{dumps()}
|
|
functions. The binary format is not the default because of backwards
|
|
compatibility with the Python 1.4 pickle module. In a future version,
|
|
the default may change to binary.
|
|
|
|
The \code{pickle} module doesn't handle code objects, which the
|
|
\code{marshal} module does. I suppose \code{pickle} could, and maybe
|
|
it should, but there's probably no great need for it right now (as
|
|
long as \code{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}
|
|
|
|
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
|
|
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,
|
|
the persistent module must define a method \code{persistent_id} which
|
|
returns either \code{None} or the persistent ID of the object.
|
|
|
|
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.
|
|
Furthermore, all its instance variables must be picklable.
|
|
|
|
\renewcommand{\indexsubitem}{(pickle protocol)}
|
|
|
|
When a pickled class instance is unpickled, its \code{__init__} method
|
|
is normally \emph{not} invoked. \strong{Note:} This is a deviation
|
|
from previous versions of this module; the change was introduced in
|
|
Python 1.5b2. The reason for the change is that in many cases it is
|
|
desirable to have a constructor that requires arguments; it is a
|
|
(minor) nuisance to have to provide a \code{__getinitargs__} method.
|
|
|
|
If it is desirable that the \code{__init__} method be called on
|
|
unpickling, a class can define a method \code{__getinitargs__()},
|
|
which should return a {\em tuple} containing the arguments to be
|
|
passed to the class constructor (\code{__init__()}).
|
|
\ttindex{__getinitargs__}
|
|
\ttindex{__init__}
|
|
|
|
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
|
|
unpickled state. (Note that these methods can also be used to
|
|
implement copying class instances.) If there is no
|
|
\code{__getstate__()} method, the instance's \code{__dict__} is
|
|
pickled. If there is no \code{__setstate__()} method, the pickled
|
|
object must be a dictionary and its items are assigned to the new
|
|
instance's dictionary. (If a class defines both \code{__getstate__()}
|
|
and \code{__setstate__()}, the state object needn't be a dictionary
|
|
--- these methods can do what they want.) This protocol is also used
|
|
by the shallow and deep copying operations defined in the \code{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
|
|
pickled. This is done on purpose, so you can fix bugs in a class or
|
|
add methods and still load objects that were created with an earlier
|
|
version of the class. If you plan to have long-lived objects that
|
|
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:
|
|
|
|
\bcode\begin{verbatim}
|
|
p = pickle.Pickler(f)
|
|
p.dump(x)
|
|
\end{verbatim}\ecode
|
|
%
|
|
A shorthand for this is:
|
|
|
|
\bcode\begin{verbatim}
|
|
pickle.dump(x, f)
|
|
\end{verbatim}\ecode
|
|
%
|
|
To unpickle an object \code{x} from a file \code{f}, open for reading:
|
|
|
|
\bcode\begin{verbatim}
|
|
u = pickle.Unpickler(f)
|
|
x = u.load()
|
|
\end{verbatim}\ecode
|
|
%
|
|
A shorthand is:
|
|
|
|
\bcode\begin{verbatim}
|
|
x = pickle.load(f)
|
|
\end{verbatim}\ecode
|
|
%
|
|
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 constructor for the \code{Pickler} class has an optional second
|
|
argument, \var{bin}. If this is present and nonzero, the binary
|
|
pickle format is used; if it is zero or absent, the (less efficient,
|
|
but backwards compatible) text pickle format is used. The
|
|
\code{Unpickler} class does not have an argument to distinguish
|
|
between binary and text pickle formats; it accepts either format.
|
|
|
|
The following types can be pickled:
|
|
\begin{itemize}
|
|
|
|
\item \code{None}
|
|
|
|
\item integers, long integers, floating point numbers
|
|
|
|
\item strings
|
|
|
|
\item tuples, lists and dictionaries containing only picklable objects
|
|
|
|
\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 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\optional{, bin}}
|
|
Write a pickled representation of \var{obect} 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 present and nonzero, the binary
|
|
pickle format is used; if it is zero or absent, the (less efficient)
|
|
text pickle format is used.
|
|
\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\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
|
|
present and nonzero, the binary pickle format is used; if it is zero
|
|
or absent, the (less efficient) text pickle format is used.
|
|
\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}
|