📄 module-pickle.html
字号:
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>3.11 pickle -- Python object serialization</title>
<META NAME="description" CONTENT="3.11 pickle -- Python object serialization">
<META NAME="keywords" CONTENT="lib">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="STYLESHEET" href="lib.css" tppabs="http://www.python.org/doc/current/lib/lib.css">
<LINK REL="next" href="module-cPickle.html" tppabs="http://www.python.org/doc/current/lib/module-cPickle.html">
<LINK REL="previous" href="module-linecache.html" tppabs="http://www.python.org/doc/current/lib/module-linecache.html">
<LINK REL="up" href="python.html" tppabs="http://www.python.org/doc/current/lib/python.html">
<LINK REL="next" href="pickle-example.html" tppabs="http://www.python.org/doc/current/lib/pickle-example.html">
</head>
<body>
<DIV CLASS="navigation"><table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td><A href="module-linecache.html" tppabs="http://www.python.org/doc/current/lib/module-linecache.html"><img src="previous.gif" tppabs="http://www.python.org/doc/current/icons/previous.gif" border="0" height="32"
alt="Previous Page" width="32"></A></td>
<td><A href="python.html" tppabs="http://www.python.org/doc/current/lib/python.html"><img src="up.gif" tppabs="http://www.python.org/doc/current/icons/up.gif" border="0" height="32"
alt="Up One Level" width="32"></A></td>
<td><A href="pickle-example.html" tppabs="http://www.python.org/doc/current/lib/pickle-example.html"><img src="next.gif" tppabs="http://www.python.org/doc/current/icons/next.gif" border="0" height="32"
alt="Next Page" width="32"></A></td>
<td align="center" width="100%">Python Library Reference</td>
<td><A href="contents.html" tppabs="http://www.python.org/doc/current/lib/contents.html"><img src="contents.gif" tppabs="http://www.python.org/doc/current/icons/contents.gif" border="0" height="32"
alt="Contents" width="32"></A></td>
<td><a href="modindex.html" tppabs="http://www.python.org/doc/current/lib/modindex.html" title="Module Index"><img src="modules.gif" tppabs="http://www.python.org/doc/current/icons/modules.gif" border="0" height="32"
alt="Module Index" width="32"></a></td>
<td><A href="genindex.html" tppabs="http://www.python.org/doc/current/lib/genindex.html"><img src="index.gif" tppabs="http://www.python.org/doc/current/icons/index.gif" border="0" height="32"
alt="Index" width="32"></A></td>
</tr></table>
<b class="navlabel">Previous:</b> <a class="sectref" href="module-linecache.html" tppabs="http://www.python.org/doc/current/lib/module-linecache.html">3.10 linecache </A>
<b class="navlabel">Up:</b> <a class="sectref" href="python.html" tppabs="http://www.python.org/doc/current/lib/python.html">3. Python Runtime Services</A>
<b class="navlabel">Next:</b> <a class="sectref" href="pickle-example.html" tppabs="http://www.python.org/doc/current/lib/pickle-example.html">3.11.1 Example</A>
<br><hr></DIV>
<!--End of Navigation Panel-->
<H1><A NAME="SECTION0051100000000000000000">
3.11 <tt class="module">pickle</tt> --
Python object serialization</A>
</H1>
<P>
<P>
<P>
The <tt class="module">pickle</tt> 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 persistence -- although <tt class="module">pickle</tt>
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 <tt class="module">pickle</tt> 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
<tt class='module'><a href="module-shelve.html" tppabs="http://www.python.org/doc/current/lib/module-shelve.html">shelve</a></tt> provides a simple interface
to pickle and unpickle objects on DBM-style database files.
<P>
<b>Note:</b> The <tt class="module">pickle</tt> module is rather slow. A
reimplementation of the same algorithm in C, which is up to 1000 times
faster, is available as the
<tt class='module'><a href="module-cPickle.html" tppabs="http://www.python.org/doc/current/lib/module-cPickle.html">cPickle</a></tt> module. This has the same
interface except that <tt class="class">Pickler</tt> and <tt class="class">Unpickler</tt> are
factory functions, not classes (so they cannot be used as base classes
for inheritance).
<P>
Although the <tt class="module">pickle</tt> module can use the built-in module
<tt class='module'><a href="module-marshal.html" tppabs="http://www.python.org/doc/current/lib/module-marshal.html">marshal</a></tt> internally, it differs from
<tt class='module'><a href="module-marshal.html" tppabs="http://www.python.org/doc/current/lib/module-marshal.html">marshal</a></tt> in the way it handles certain kinds of data:
<P>
<UL>
<LI>Recursive objects (objects containing references to themselves):
<tt class="module">pickle</tt> keeps track of the objects it has already
serialized, so later references to the same object won't be
serialized again. (The <tt class='module'><a href="module-marshal.html" tppabs="http://www.python.org/doc/current/lib/module-marshal.html">marshal</a></tt> module breaks for
this.)
<P>
</LI>
<LI>Object sharing (references to the same object in different
places): This is similar to self-referencing objects;
<tt class="module">pickle</tt> stores the object once, and ensures that all
other references point to the master copy. Shared objects
remain shared, which can be very important for mutable objects.
<P>
</LI>
<LI>User-defined classes and their instances: <tt class='module'><a href="module-marshal.html" tppabs="http://www.python.org/doc/current/lib/module-marshal.html">marshal</a></tt>
does not support these at all, but <tt class="module">pickle</tt> can save
and restore class instances transparently. The class definition
must be importable and live in the same module as when the
object was stored.
<P>
</LI>
</UL>
<P>
The data format used by <tt class="module">pickle</tt> is Python-specific. This has
the advantage that there are no restrictions imposed by external
standards such as
XDR (which can't
represent pointer sharing); however it means that non-Python programs
may not be able to reconstruct pickled Python objects.
<P>
By default, the <tt class="module">pickle</tt> 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 <tt class="module">pickle</tt>'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.
<P>
A binary format, which is slightly more efficient, can be chosen by
specifying a nonzero (true) value for the <var>bin</var> argument to the
<tt class="class">Pickler</tt> constructor or the <tt class="function">dump()</tt> and <tt class="function">dumps()</tt>
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.
<P>
The <tt class="module">pickle</tt> module doesn't handle code objects, which the
<tt class='module'><a href="module-marshal.html" tppabs="http://www.python.org/doc/current/lib/module-marshal.html">marshal</a></tt> module does. I suppose
<tt class="module">pickle</tt> could, and maybe it should, but there's probably no
great need for it right now (as long as <tt class='module'><a href="module-marshal.html" tppabs="http://www.python.org/doc/current/lib/module-marshal.html">marshal</a></tt> continues
to be used for reading and writing code objects), and at least this
avoids the possibility of smuggling Trojan horses into a program.
<P>
For the benefit of persistence modules written using <tt class="module">pickle</tt>, 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 <tt class="module">pickle</tt> module -- the
persistent object module will have to implement a method
<tt class="method">persistent_load()</tt>. To write references to persistent objects,
the persistent module must define a method <tt class="method">persistent_id()</tt> which
returns either <code>None</code> or the persistent ID of the object.
<P>
There are some restrictions on the pickling of class instances.
<P>
First of all, the class must be defined at the top level in a module.
Furthermore, all its instance variables must be picklable.
<P>
<P>
When a pickled class instance is unpickled, its <tt class="method">__init__()</tt> method
is normally <i>not</i> invoked. <b>Note:</b> 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 <tt class="method">__getinitargs__()</tt> method.
<P>
If it is desirable that the <tt class="method">__init__()</tt> method be called on
unpickling, a class can define a method <tt class="method">__getinitargs__()</tt>,
which should return a <i>tuple</i> containing the arguments to be
passed to the class constructor (<tt class="method">__init__()</tt>). This method is
called at pickle time; the tuple it returns is incorporated in the
pickle for the instance.
<P>
Classes can further influence how their instances are pickled -- if
the class
defines the method <tt class="method">__getstate__()</tt>, it is called and the return
state is pickled as the contents for the instance, and if the class
defines the method <tt class="method">__setstate__()</tt>, it is called with the
unpickled state. (Note that these methods can also be used to
implement copying class instances.) If there is no
<tt class="method">__getstate__()</tt> method, the instance's <tt class="member">__dict__</tt> is
pickled. If there is no <tt class="method">__setstate__()</tt> method, the pickled
object must be a dictionary and its items are assigned to the new
instance's dictionary. (If a class defines both <tt class="method">__getstate__()</tt>
and <tt class="method">__setstate__()</tt>, 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
<tt class='module'><a href="module-copy.html" tppabs="http://www.python.org/doc/current/lib/module-copy.html">copy</a></tt> module.
<P>
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 <tt class="method">__setstate__()</tt> method.
<P>
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.
<P>
<P>
The interface can be summarized as follows.
<P>
To pickle an object <code>x</code> onto a file <code>f</code>, open for writing:
<P>
⌨️ 快捷键说明
复制代码
Ctrl + C
搜索代码
Ctrl + F
全屏模式
F11
切换主题
Ctrl + Shift + D
显示快捷键
?
增大字号
Ctrl + =
减小字号
Ctrl + -