Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
2 | <html> | |
3 | <head> | |
4 | <link rel="STYLESHEET" href="lib.css" type='text/css' /> | |
5 | <link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" /> | |
6 | <link rel='start' href='../index.html' title='Python Documentation Index' /> | |
7 | <link rel="first" href="lib.html" title='Python Library Reference' /> | |
8 | <link rel='contents' href='contents.html' title="Contents" /> | |
9 | <link rel='index' href='genindex.html' title='Index' /> | |
10 | <link rel='last' href='about.html' title='About this document...' /> | |
11 | <link rel='help' href='about.html' title='About this document...' /> | |
12 | <link rel="next" href="node66.html" /> | |
13 | <link rel="prev" href="node64.html" /> | |
14 | <link rel="parent" href="module-pickle.html" /> | |
15 | <link rel="next" href="node66.html" /> | |
16 | <meta name='aesop' content='information' /> | |
17 | <title>3.14.3 Usage</title> | |
18 | </head> | |
19 | <body> | |
20 | <DIV CLASS="navigation"> | |
21 | <div id='top-navigation-panel' xml:id='top-navigation-panel'> | |
22 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
23 | <tr> | |
24 | <td class='online-navigation'><a rel="prev" title="3.14.2 Data stream format" | |
25 | href="node64.html"><img src='../icons/previous.png' | |
26 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
27 | <td class='online-navigation'><a rel="parent" title="3.14 pickle " | |
28 | href="module-pickle.html"><img src='../icons/up.png' | |
29 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
30 | <td class='online-navigation'><a rel="next" title="3.14.4 What can be" | |
31 | href="node66.html"><img src='../icons/next.png' | |
32 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
33 | <td align="center" width="100%">Python Library Reference</td> | |
34 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
35 | href="contents.html"><img src='../icons/contents.png' | |
36 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
37 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
38 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
39 | <td class='online-navigation'><a rel="index" title="Index" | |
40 | href="genindex.html"><img src='../icons/index.png' | |
41 | border='0' height='32' alt='Index' width='32' /></A></td> | |
42 | </tr></table> | |
43 | <div class='online-navigation'> | |
44 | <b class="navlabel">Previous:</b> | |
45 | <a class="sectref" rel="prev" href="node64.html">3.14.2 Data stream format</A> | |
46 | <b class="navlabel">Up:</b> | |
47 | <a class="sectref" rel="parent" href="module-pickle.html">3.14 pickle </A> | |
48 | <b class="navlabel">Next:</b> | |
49 | <a class="sectref" rel="next" href="node66.html">3.14.4 What can be</A> | |
50 | </div> | |
51 | <hr /></div> | |
52 | </DIV> | |
53 | <!--End of Navigation Panel--> | |
54 | ||
55 | <H2><A NAME="SECTION0051430000000000000000"> | |
56 | 3.14.3 Usage</A> | |
57 | </H2> | |
58 | ||
59 | <P> | |
60 | To serialize an object hierarchy, you first create a pickler, then you | |
61 | call the pickler's <tt class="method">dump()</tt> method. To de-serialize a data | |
62 | stream, you first create an unpickler, then you call the unpickler's | |
63 | <tt class="method">load()</tt> method. The <tt class="module">pickle</tt> module provides the | |
64 | following constant: | |
65 | ||
66 | <P> | |
67 | <dl><dt><b><tt id='l2h-633' xml:id='l2h-633'>HIGHEST_PROTOCOL</tt></b></dt> | |
68 | <dd> | |
69 | The highest protocol version available. This value can be passed | |
70 | as a <var>protocol</var> value. | |
71 | ||
72 | <span class="versionnote">New in version 2.3.</span> | |
73 | ||
74 | </dd></dl> | |
75 | ||
76 | <P> | |
77 | The <tt class="module">pickle</tt> module provides the | |
78 | following functions to make this process more convenient: | |
79 | ||
80 | <P> | |
81 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
82 | <td><nobr><b><tt id='l2h-634' xml:id='l2h-634' class="function">dump</tt></b>(</nobr></td> | |
83 | <td><var>obj, file</var><big>[</big><var>, protocol</var><big>[</big><var>, bin</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
84 | <dd> | |
85 | Write a pickled representation of <var>obj</var> to the open file object | |
86 | <var>file</var>. This is equivalent to | |
87 | <code>Pickler(<var>file</var>, <var>protocol</var>, <var>bin</var>).dump(<var>obj</var>)</code>. | |
88 | ||
89 | <P> | |
90 | If the <var>protocol</var> parameter is omitted, protocol 0 is used. | |
91 | If <var>protocol</var> is specified as a negative value | |
92 | or <tt class="constant">HIGHEST_PROTOCOL</tt>, | |
93 | the highest protocol version will be used. | |
94 | ||
95 | <P> | |
96 | ||
97 | <span class="versionnote">Changed in version 2.3: | |
98 | The <var>protocol</var> parameter was added. | |
99 | The <var>bin</var> parameter is deprecated and only provided | |
100 | for backwards compatibility. You should use the <var>protocol</var> | |
101 | parameter instead.</span> | |
102 | ||
103 | <P> | |
104 | If the optional <var>bin</var> argument is true, the binary pickle format | |
105 | is used; otherwise the (less efficient) text pickle format is used | |
106 | (for backwards compatibility, this is the default). | |
107 | ||
108 | <P> | |
109 | <var>file</var> must have a <tt class="method">write()</tt> method that accepts a single | |
110 | string argument. It can thus be a file object opened for writing, a | |
111 | <tt class="module"><a href="module-StringIO.html">StringIO</a></tt> object, or any other custom | |
112 | object that meets this interface. | |
113 | </dl> | |
114 | ||
115 | <P> | |
116 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
117 | <td><nobr><b><tt id='l2h-635' xml:id='l2h-635' class="function">load</tt></b>(</nobr></td> | |
118 | <td><var>file</var>)</td></tr></table></dt> | |
119 | <dd> | |
120 | Read a string from the open file object <var>file</var> and interpret it as | |
121 | a pickle data stream, reconstructing and returning the original object | |
122 | hierarchy. This is equivalent to <code>Unpickler(<var>file</var>).load()</code>. | |
123 | ||
124 | <P> | |
125 | <var>file</var> must have two methods, a <tt class="method">read()</tt> method that takes | |
126 | an integer argument, and a <tt class="method">readline()</tt> method that requires no | |
127 | arguments. Both methods should return a string. Thus <var>file</var> can | |
128 | be a file object opened for reading, a | |
129 | <tt class="module">StringIO</tt> object, or any other custom | |
130 | object that meets this interface. | |
131 | ||
132 | <P> | |
133 | This function automatically determines whether the data stream was | |
134 | written in binary mode or not. | |
135 | </dl> | |
136 | ||
137 | <P> | |
138 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
139 | <td><nobr><b><tt id='l2h-636' xml:id='l2h-636' class="function">dumps</tt></b>(</nobr></td> | |
140 | <td><var>obj</var><big>[</big><var>, protocol</var><big>[</big><var>, bin</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
141 | <dd> | |
142 | Return the pickled representation of the object as a string, instead | |
143 | of writing it to a file. | |
144 | ||
145 | <P> | |
146 | If the <var>protocol</var> parameter is omitted, protocol 0 is used. | |
147 | If <var>protocol</var> is specified as a negative value | |
148 | or <tt class="constant">HIGHEST_PROTOCOL</tt>, | |
149 | the highest protocol version will be used. | |
150 | ||
151 | <P> | |
152 | ||
153 | <span class="versionnote">Changed in version 2.3: | |
154 | The <var>protocol</var> parameter was added. | |
155 | The <var>bin</var> parameter is deprecated and only provided | |
156 | for backwards compatibility. You should use the <var>protocol</var> | |
157 | parameter instead.</span> | |
158 | ||
159 | <P> | |
160 | If the optional <var>bin</var> argument is | |
161 | true, the binary pickle format is used; otherwise the (less efficient) | |
162 | text pickle format is used (this is the default). | |
163 | </dl> | |
164 | ||
165 | <P> | |
166 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
167 | <td><nobr><b><tt id='l2h-637' xml:id='l2h-637' class="function">loads</tt></b>(</nobr></td> | |
168 | <td><var>string</var>)</td></tr></table></dt> | |
169 | <dd> | |
170 | Read a pickled object hierarchy from a string. Characters in the | |
171 | string past the pickled object's representation are ignored. | |
172 | </dl> | |
173 | ||
174 | <P> | |
175 | The <tt class="module">pickle</tt> module also defines three exceptions: | |
176 | ||
177 | <P> | |
178 | <dl><dt><b><span class="typelabel">exception</span> <tt id='l2h-638' xml:id='l2h-638' class="exception">PickleError</tt></b></dt> | |
179 | <dd> | |
180 | A common base class for the other exceptions defined below. This | |
181 | inherits from <tt class="exception">Exception</tt>. | |
182 | </dd></dl> | |
183 | ||
184 | <P> | |
185 | <dl><dt><b><span class="typelabel">exception</span> <tt id='l2h-639' xml:id='l2h-639' class="exception">PicklingError</tt></b></dt> | |
186 | <dd> | |
187 | This exception is raised when an unpicklable object is passed to | |
188 | the <tt class="method">dump()</tt> method. | |
189 | </dd></dl> | |
190 | ||
191 | <P> | |
192 | <dl><dt><b><span class="typelabel">exception</span> <tt id='l2h-640' xml:id='l2h-640' class="exception">UnpicklingError</tt></b></dt> | |
193 | <dd> | |
194 | This exception is raised when there is a problem unpickling an object. | |
195 | Note that other exceptions may also be raised during unpickling, | |
196 | including (but not necessarily limited to) <tt class="exception">AttributeError</tt>, | |
197 | <tt class="exception">EOFError</tt>, <tt class="exception">ImportError</tt>, and <tt class="exception">IndexError</tt>. | |
198 | </dd></dl> | |
199 | ||
200 | <P> | |
201 | The <tt class="module">pickle</tt> module also exports two callables<A NAME="tex2html15" | |
202 | HREF="#foot8968"><SUP>3.3</SUP></A>, <tt class="class">Pickler</tt> and <tt class="class">Unpickler</tt>: | |
203 | ||
204 | <P> | |
205 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
206 | <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-641' xml:id='l2h-641' class="class">Pickler</tt></b>(</nobr></td> | |
207 | <td><var>file</var><big>[</big><var>, protocol</var><big>[</big><var>, bin</var><big>]</big><var></var><big>]</big><var></var>)</td></tr></table></dt> | |
208 | <dd> | |
209 | This takes a file-like object to which it will write a pickle data | |
210 | stream. | |
211 | ||
212 | <P> | |
213 | If the <var>protocol</var> parameter is omitted, protocol 0 is used. | |
214 | If <var>protocol</var> is specified as a negative value, | |
215 | the highest protocol version will be used. | |
216 | ||
217 | <P> | |
218 | ||
219 | <span class="versionnote">Changed in version 2.3: | |
220 | The <var>bin</var> parameter is deprecated and only provided | |
221 | for backwards compatibility. You should use the <var>protocol</var> | |
222 | parameter instead.</span> | |
223 | ||
224 | <P> | |
225 | Optional <var>bin</var> if true, tells the pickler to use the more | |
226 | efficient binary pickle format, otherwise the ASCII format is used | |
227 | (this is the default). | |
228 | ||
229 | <P> | |
230 | <var>file</var> must have a <tt class="method">write()</tt> method that accepts a single | |
231 | string argument. It can thus be an open file object, a | |
232 | <tt class="module">StringIO</tt> object, or any other custom | |
233 | object that meets this interface. | |
234 | </dl> | |
235 | ||
236 | <P> | |
237 | <tt class="class">Pickler</tt> objects define one (or two) public methods: | |
238 | ||
239 | <P> | |
240 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
241 | <td><nobr><b><tt id='l2h-642' xml:id='l2h-642' class="method">dump</tt></b>(</nobr></td> | |
242 | <td><var>obj</var>)</td></tr></table></dt> | |
243 | <dd> | |
244 | Write a pickled representation of <var>obj</var> to the open file object | |
245 | given in the constructor. Either the binary or ASCII format will | |
246 | be used, depending on the value of the <var>bin</var> flag passed to the | |
247 | constructor. | |
248 | </dl> | |
249 | ||
250 | <P> | |
251 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
252 | <td><nobr><b><tt id='l2h-643' xml:id='l2h-643' class="method">clear_memo</tt></b>(</nobr></td> | |
253 | <td><var></var>)</td></tr></table></dt> | |
254 | <dd> | |
255 | Clears the pickler's ``memo''. The memo is the data structure that | |
256 | remembers which objects the pickler has already seen, so that shared | |
257 | or recursive objects pickled by reference and not by value. This | |
258 | method is useful when re-using picklers. | |
259 | ||
260 | <P> | |
261 | <div class="note"><b class="label">Note:</b> | |
262 | Prior to Python 2.3, <tt class="method">clear_memo()</tt> was only available on the | |
263 | picklers created by <tt class="module"><a href="module-cPickle.html">cPickle</a></tt>. In the <tt class="module">pickle</tt> module, | |
264 | picklers have an instance variable called <tt class="member">memo</tt> which is a | |
265 | Python dictionary. So to clear the memo for a <tt class="module">pickle</tt> module | |
266 | pickler, you could do the following: | |
267 | ||
268 | <P> | |
269 | <div class="verbatim"><pre> | |
270 | mypickler.memo.clear() | |
271 | </pre></div> | |
272 | ||
273 | <P> | |
274 | Code that does not need to support older versions of Python should | |
275 | simply use <tt class="method">clear_memo()</tt>. | |
276 | </div> | |
277 | </dl> | |
278 | ||
279 | <P> | |
280 | It is possible to make multiple calls to the <tt class="method">dump()</tt> method of | |
281 | the same <tt class="class">Pickler</tt> instance. These must then be matched to the | |
282 | same number of calls to the <tt class="method">load()</tt> method of the | |
283 | corresponding <tt class="class">Unpickler</tt> instance. If the same object is | |
284 | pickled by multiple <tt class="method">dump()</tt> calls, the <tt class="method">load()</tt> will | |
285 | all yield references to the same object.<A NAME="tex2html16" | |
286 | HREF="#foot8970"><SUP>3.4</SUP></A> | |
287 | <P> | |
288 | <tt class="class">Unpickler</tt> objects are defined as: | |
289 | ||
290 | <P> | |
291 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
292 | <td><nobr><b><span class="typelabel">class</span> <tt id='l2h-644' xml:id='l2h-644' class="class">Unpickler</tt></b>(</nobr></td> | |
293 | <td><var>file</var>)</td></tr></table></dt> | |
294 | <dd> | |
295 | This takes a file-like object from which it will read a pickle data | |
296 | stream. This class automatically determines whether the data stream | |
297 | was written in binary mode or not, so it does not need a flag as in | |
298 | the <tt class="class">Pickler</tt> factory. | |
299 | ||
300 | <P> | |
301 | <var>file</var> must have two methods, a <tt class="method">read()</tt> method that takes | |
302 | an integer argument, and a <tt class="method">readline()</tt> method that requires no | |
303 | arguments. Both methods should return a string. Thus <var>file</var> can | |
304 | be a file object opened for reading, a | |
305 | <tt class="module">StringIO</tt> object, or any other custom | |
306 | object that meets this interface. | |
307 | </dl> | |
308 | ||
309 | <P> | |
310 | <tt class="class">Unpickler</tt> objects have one (or two) public methods: | |
311 | ||
312 | <P> | |
313 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
314 | <td><nobr><b><tt id='l2h-645' xml:id='l2h-645' class="method">load</tt></b>(</nobr></td> | |
315 | <td><var></var>)</td></tr></table></dt> | |
316 | <dd> | |
317 | Read a pickled object representation from the open file object given | |
318 | in the constructor, and return the reconstituted object hierarchy | |
319 | specified therein. | |
320 | </dl> | |
321 | ||
322 | <P> | |
323 | <dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline"> | |
324 | <td><nobr><b><tt id='l2h-646' xml:id='l2h-646' class="method">noload</tt></b>(</nobr></td> | |
325 | <td><var></var>)</td></tr></table></dt> | |
326 | <dd> | |
327 | This is just like <tt class="method">load()</tt> except that it doesn't actually | |
328 | create any objects. This is useful primarily for finding what's | |
329 | called ``persistent ids'' that may be referenced in a pickle data | |
330 | stream. See section <A href="pickle-protocol.html#pickle-protocol">3.14.5</A> below for more details. | |
331 | ||
332 | <P> | |
333 | <strong>Note:</strong> the <tt class="method">noload()</tt> method is currently only | |
334 | available on <tt class="class">Unpickler</tt> objects created with the | |
335 | <tt class="module">cPickle</tt> module. <tt class="module">pickle</tt> module <tt class="class">Unpickler</tt>s do | |
336 | not have the <tt class="method">noload()</tt> method. | |
337 | </dl> | |
338 | ||
339 | <P> | |
340 | <BR><HR><H4>Footnotes</H4> | |
341 | <DL> | |
342 | <DT><A NAME="foot8968">... callables</A><A | |
343 | HREF="node65.html#tex2html15"><SUP>3.3</SUP></A></DT> | |
344 | <DD>In the | |
345 | <tt class="module">pickle</tt> module these callables are classes, which you could | |
346 | subclass to customize the behavior. However, in the <tt class="module"><a href="module-cPickle.html">cPickle</a></tt> | |
347 | module these callables are factory functions and so cannot be | |
348 | subclassed. One common reason to subclass is to control what | |
349 | objects can actually be unpickled. See section <A href="pickle-sub.html#pickle-sub">3.14.6</A> for | |
350 | more details. | |
351 | ||
352 | </DD> | |
353 | <DT><A NAME="foot8970">... object.</A><A | |
354 | HREF="node65.html#tex2html16"><SUP>3.4</SUP></A></DT> | |
355 | <DD><em>Warning</em>: this | |
356 | is intended for pickling multiple objects without intervening | |
357 | modifications to the objects or their parts. If you modify an object | |
358 | and then pickle it again using the same <tt class="class">Pickler</tt> instance, the | |
359 | object is not pickled again -- a reference to it is pickled and the | |
360 | <tt class="class">Unpickler</tt> will return the old value, not the modified one. | |
361 | There are two problems here: (1) detecting changes, and (2) | |
362 | marshalling a minimal set of changes. Garbage Collection may also | |
363 | become a problem here. | |
364 | ||
365 | </DD> | |
366 | </DL> | |
367 | <DIV CLASS="navigation"> | |
368 | <div class='online-navigation'> | |
369 | <p></p><hr /> | |
370 | <table align="center" width="100%" cellpadding="0" cellspacing="2"> | |
371 | <tr> | |
372 | <td class='online-navigation'><a rel="prev" title="3.14.2 Data stream format" | |
373 | href="node64.html"><img src='../icons/previous.png' | |
374 | border='0' height='32' alt='Previous Page' width='32' /></A></td> | |
375 | <td class='online-navigation'><a rel="parent" title="3.14 pickle " | |
376 | href="module-pickle.html"><img src='../icons/up.png' | |
377 | border='0' height='32' alt='Up One Level' width='32' /></A></td> | |
378 | <td class='online-navigation'><a rel="next" title="3.14.4 What can be" | |
379 | href="node66.html"><img src='../icons/next.png' | |
380 | border='0' height='32' alt='Next Page' width='32' /></A></td> | |
381 | <td align="center" width="100%">Python Library Reference</td> | |
382 | <td class='online-navigation'><a rel="contents" title="Table of Contents" | |
383 | href="contents.html"><img src='../icons/contents.png' | |
384 | border='0' height='32' alt='Contents' width='32' /></A></td> | |
385 | <td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png' | |
386 | border='0' height='32' alt='Module Index' width='32' /></a></td> | |
387 | <td class='online-navigation'><a rel="index" title="Index" | |
388 | href="genindex.html"><img src='../icons/index.png' | |
389 | border='0' height='32' alt='Index' width='32' /></A></td> | |
390 | </tr></table> | |
391 | <div class='online-navigation'> | |
392 | <b class="navlabel">Previous:</b> | |
393 | <a class="sectref" rel="prev" href="node64.html">3.14.2 Data stream format</A> | |
394 | <b class="navlabel">Up:</b> | |
395 | <a class="sectref" rel="parent" href="module-pickle.html">3.14 pickle </A> | |
396 | <b class="navlabel">Next:</b> | |
397 | <a class="sectref" rel="next" href="node66.html">3.14.4 What can be</A> | |
398 | </div> | |
399 | </div> | |
400 | <hr /> | |
401 | <span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span> | |
402 | </DIV> | |
403 | <!--End of Navigation Panel--> | |
404 | <ADDRESS> | |
405 | See <i><a href="about.html">About this document...</a></i> for information on suggesting changes. | |
406 | </ADDRESS> | |
407 | </BODY> | |
408 | </HTML> |