| 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> |