Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 1 | \section{\module{pickle} --- |
Fred Drake | ffbe687 | 1999-04-22 21:23:22 +0000 | [diff] [blame] | 2 | Python object serialization} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 3 | |
Fred Drake | ffbe687 | 1999-04-22 21:23:22 +0000 | [diff] [blame] | 4 | \declaremodule{standard}{pickle} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 5 | \modulesynopsis{Convert Python objects to streams of bytes and back.} |
| 6 | |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 7 | \index{persistency} |
| 8 | \indexii{persistent}{objects} |
| 9 | \indexii{serializing}{objects} |
| 10 | \indexii{marshalling}{objects} |
| 11 | \indexii{flattening}{objects} |
| 12 | \indexii{pickling}{objects} |
| 13 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 14 | |
Fred Drake | 4179691 | 1999-07-02 14:25:37 +0000 | [diff] [blame] | 15 | The \module{pickle} module implements a basic but powerful algorithm |
| 16 | for ``pickling'' (a.k.a.\ serializing, marshalling or flattening) |
| 17 | nearly arbitrary Python objects. This is the act of converting |
| 18 | objects to a stream of bytes (and back: ``unpickling''). This is a |
| 19 | more primitive notion than persistency --- although \module{pickle} |
| 20 | reads and writes file objects, it does not handle the issue of naming |
| 21 | persistent objects, nor the (even more complicated) area of concurrent |
| 22 | access to persistent objects. The \module{pickle} module can |
| 23 | transform a complex object into a byte stream and it can transform the |
| 24 | byte stream into an object with the same internal structure. The most |
| 25 | obvious thing to do with these byte streams is to write them onto a |
| 26 | file, but it is also conceivable to send them across a network or |
| 27 | store them in a database. The module |
Fred Drake | ffbe687 | 1999-04-22 21:23:22 +0000 | [diff] [blame] | 28 | \refmodule{shelve}\refstmodindex{shelve} provides a simple interface |
| 29 | to pickle and unpickle objects on DBM-style database files. |
| 30 | |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 31 | |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 32 | \strong{Note:} The \module{pickle} module is rather slow. A |
Fred Drake | ffbe687 | 1999-04-22 21:23:22 +0000 | [diff] [blame] | 33 | reimplementation of the same algorithm in C, which is up to 1000 times |
Fred Drake | 4179691 | 1999-07-02 14:25:37 +0000 | [diff] [blame] | 34 | faster, is available as the |
| 35 | \refmodule{cPickle}\refbimodindex{cPickle} module. This has the same |
| 36 | interface except that \class{Pickler} and \class{Unpickler} are |
| 37 | factory functions, not classes (so they cannot be used as base classes |
| 38 | for inheritance). |
Guido van Rossum | 736fe5e | 1997-12-09 20:45:08 +0000 | [diff] [blame] | 39 | |
Fred Drake | ffbe687 | 1999-04-22 21:23:22 +0000 | [diff] [blame] | 40 | Unlike the built-in module \refmodule{marshal}\refbimodindex{marshal}, |
| 41 | \module{pickle} handles the following correctly: |
| 42 | |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 43 | |
| 44 | \begin{itemize} |
| 45 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 46 | \item recursive objects (objects containing references to themselves) |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 47 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 48 | \item object sharing (references to the same object in different places) |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 49 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 50 | \item user-defined classes and their instances |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 51 | |
| 52 | \end{itemize} |
| 53 | |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 54 | The data format used by \module{pickle} is Python-specific. This has |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 55 | the advantage that there are no restrictions imposed by external |
Fred Drake | ffbe687 | 1999-04-22 21:23:22 +0000 | [diff] [blame] | 56 | standards such as |
| 57 | XDR\index{XDR}\index{External Data Representation} (which can't |
| 58 | represent pointer sharing); however it means that non-Python programs |
| 59 | may not be able to reconstruct pickled Python objects. |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 60 | |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 61 | By default, the \module{pickle} data format uses a printable \ASCII{} |
Guido van Rossum | 736fe5e | 1997-12-09 20:45:08 +0000 | [diff] [blame] | 62 | representation. This is slightly more voluminous than a binary |
| 63 | representation. The big advantage of using printable \ASCII{} (and of |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 64 | some other characteristics of \module{pickle}'s representation) is that |
Guido van Rossum | 736fe5e | 1997-12-09 20:45:08 +0000 | [diff] [blame] | 65 | for debugging or recovery purposes it is possible for a human to read |
| 66 | the pickled file with a standard text editor. |
| 67 | |
| 68 | A binary format, which is slightly more efficient, can be chosen by |
| 69 | specifying a nonzero (true) value for the \var{bin} argument to the |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 70 | \class{Pickler} constructor or the \function{dump()} and \function{dumps()} |
Guido van Rossum | 736fe5e | 1997-12-09 20:45:08 +0000 | [diff] [blame] | 71 | functions. The binary format is not the default because of backwards |
| 72 | compatibility with the Python 1.4 pickle module. In a future version, |
| 73 | the default may change to binary. |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 74 | |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 75 | The \module{pickle} module doesn't handle code objects, which the |
Fred Drake | 4179691 | 1999-07-02 14:25:37 +0000 | [diff] [blame] | 76 | \refmodule{marshal}\refbimodindex{marshal} module does. I suppose |
| 77 | \module{pickle} could, and maybe it should, but there's probably no |
| 78 | great need for it right now (as long as \refmodule{marshal} continues |
| 79 | to be used for reading and writing code objects), and at least this |
| 80 | avoids the possibility of smuggling Trojan horses into a program. |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 81 | |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 82 | For the benefit of persistency modules written using \module{pickle}, it |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 83 | supports the notion of a reference to an object outside the pickled |
| 84 | data stream. Such objects are referenced by a name, which is an |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 85 | arbitrary string of printable \ASCII{} characters. The resolution of |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 86 | such names is not defined by the \module{pickle} module --- the |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 87 | persistent object module will have to implement a method |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 88 | \method{persistent_load()}. To write references to persistent objects, |
| 89 | the persistent module must define a method \method{persistent_id()} which |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 90 | returns either \code{None} or the persistent ID of the object. |
| 91 | |
| 92 | There are some restrictions on the pickling of class instances. |
| 93 | |
| 94 | First of all, the class must be defined at the top level in a module. |
Guido van Rossum | 736fe5e | 1997-12-09 20:45:08 +0000 | [diff] [blame] | 95 | Furthermore, all its instance variables must be picklable. |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 96 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 97 | \setindexsubitem{(pickle protocol)} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 98 | |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 99 | When a pickled class instance is unpickled, its \method{__init__()} method |
Guido van Rossum | 736fe5e | 1997-12-09 20:45:08 +0000 | [diff] [blame] | 100 | is normally \emph{not} invoked. \strong{Note:} This is a deviation |
| 101 | from previous versions of this module; the change was introduced in |
| 102 | Python 1.5b2. The reason for the change is that in many cases it is |
| 103 | desirable to have a constructor that requires arguments; it is a |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 104 | (minor) nuisance to have to provide a \method{__getinitargs__()} method. |
Guido van Rossum | 736fe5e | 1997-12-09 20:45:08 +0000 | [diff] [blame] | 105 | |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 106 | If it is desirable that the \method{__init__()} method be called on |
| 107 | unpickling, a class can define a method \method{__getinitargs__()}, |
Fred Drake | cf7e830 | 1998-01-09 22:36:51 +0000 | [diff] [blame] | 108 | which should return a \emph{tuple} containing the arguments to be |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 109 | passed to the class constructor (\method{__init__()}). This method is |
Guido van Rossum | 5793039 | 1997-12-30 17:44:48 +0000 | [diff] [blame] | 110 | called at pickle time; the tuple it returns is incorporated in the |
| 111 | pickle for the instance. |
Fred Drake | 4179691 | 1999-07-02 14:25:37 +0000 | [diff] [blame] | 112 | \withsubitem{(copy protocol)}{\ttindex{__getinitargs__()}} |
| 113 | \withsubitem{(instance constructor)}{\ttindex{__init__()}} |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 114 | |
Fred Drake | 4179691 | 1999-07-02 14:25:37 +0000 | [diff] [blame] | 115 | Classes can further influence how their instances are pickled --- if |
| 116 | the class |
| 117 | \withsubitem{(copy protocol)}{ |
| 118 | \ttindex{__getstate__()}\ttindex{__setstate__()}} |
| 119 | \withsubitem{(instance attribute)}{ |
| 120 | \ttindex{__dict__}} |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 121 | defines the method \method{__getstate__()}, it is called and the return |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 122 | state is pickled as the contents for the instance, and if the class |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 123 | defines the method \method{__setstate__()}, it is called with the |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 124 | unpickled state. (Note that these methods can also be used to |
| 125 | implement copying class instances.) If there is no |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 126 | \method{__getstate__()} method, the instance's \member{__dict__} is |
| 127 | pickled. If there is no \method{__setstate__()} method, the pickled |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 128 | object must be a dictionary and its items are assigned to the new |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 129 | instance's dictionary. (If a class defines both \method{__getstate__()} |
| 130 | and \method{__setstate__()}, the state object needn't be a dictionary |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 131 | --- these methods can do what they want.) This protocol is also used |
Fred Drake | ffbe687 | 1999-04-22 21:23:22 +0000 | [diff] [blame] | 132 | by the shallow and deep copying operations defined in the |
| 133 | \refmodule{copy}\refstmodindex{copy} module. |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 134 | |
| 135 | Note that when class instances are pickled, their class's code and |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 136 | data are not pickled along with them. Only the instance data are |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 137 | pickled. This is done on purpose, so you can fix bugs in a class or |
| 138 | add methods and still load objects that were created with an earlier |
| 139 | version of the class. If you plan to have long-lived objects that |
Guido van Rossum | 6bb1adc | 1995-03-13 10:03:32 +0000 | [diff] [blame] | 140 | will see many versions of a class, it may be worthwhile to put a version |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 141 | number in the objects so that suitable conversions can be made by the |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 142 | class's \method{__setstate__()} method. |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 143 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 144 | When a class itself is pickled, only its name is pickled --- the class |
| 145 | definition is not pickled, but re-imported by the unpickling process. |
| 146 | Therefore, the restriction that the class must be defined at the top |
| 147 | level in a module applies to pickled classes as well. |
| 148 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 149 | \setindexsubitem{(in module pickle)} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 150 | |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 151 | The interface can be summarized as follows. |
| 152 | |
| 153 | To pickle an object \code{x} onto a file \code{f}, open for writing: |
| 154 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 155 | \begin{verbatim} |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 156 | p = pickle.Pickler(f) |
| 157 | p.dump(x) |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 158 | \end{verbatim} |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 159 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 160 | A shorthand for this is: |
| 161 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 162 | \begin{verbatim} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 163 | pickle.dump(x, f) |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 164 | \end{verbatim} |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 165 | |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 166 | To unpickle an object \code{x} from a file \code{f}, open for reading: |
| 167 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 168 | \begin{verbatim} |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 169 | u = pickle.Unpickler(f) |
Guido van Rossum | 96628a9 | 1995-04-10 11:34:00 +0000 | [diff] [blame] | 170 | x = u.load() |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 171 | \end{verbatim} |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 172 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 173 | A shorthand is: |
| 174 | |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 175 | \begin{verbatim} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 176 | x = pickle.load(f) |
Fred Drake | 1947991 | 1998-02-13 06:58:54 +0000 | [diff] [blame] | 177 | \end{verbatim} |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 178 | |
| 179 | The \class{Pickler} class only calls the method \code{f.write()} with a |
Fred Drake | 4179691 | 1999-07-02 14:25:37 +0000 | [diff] [blame] | 180 | \withsubitem{(class in pickle)}{ |
| 181 | \ttindex{Unpickler}\ttindex{Pickler}} |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 182 | string argument. The \class{Unpickler} calls the methods \code{f.read()} |
Fred Drake | cf7e830 | 1998-01-09 22:36:51 +0000 | [diff] [blame] | 183 | (with an integer argument) and \code{f.readline()} (without argument), |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 184 | both returning a string. It is explicitly allowed to pass non-file |
| 185 | objects here, as long as they have the right methods. |
| 186 | |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 187 | The constructor for the \class{Pickler} class has an optional second |
Guido van Rossum | 736fe5e | 1997-12-09 20:45:08 +0000 | [diff] [blame] | 188 | argument, \var{bin}. If this is present and nonzero, the binary |
| 189 | pickle format is used; if it is zero or absent, the (less efficient, |
| 190 | but backwards compatible) text pickle format is used. The |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 191 | \class{Unpickler} class does not have an argument to distinguish |
Guido van Rossum | 736fe5e | 1997-12-09 20:45:08 +0000 | [diff] [blame] | 192 | between binary and text pickle formats; it accepts either format. |
| 193 | |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 194 | The following types can be pickled: |
Fred Drake | 4179691 | 1999-07-02 14:25:37 +0000 | [diff] [blame] | 195 | |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 196 | \begin{itemize} |
| 197 | |
| 198 | \item \code{None} |
| 199 | |
| 200 | \item integers, long integers, floating point numbers |
| 201 | |
| 202 | \item strings |
| 203 | |
| 204 | \item tuples, lists and dictionaries containing only picklable objects |
| 205 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 206 | \item classes that are defined at the top level in a module |
| 207 | |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 208 | \item instances of such classes whose \member{__dict__} or |
| 209 | \method{__setstate__()} is picklable |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 210 | |
| 211 | \end{itemize} |
| 212 | |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 213 | Attempts to pickle unpicklable objects will raise the |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 214 | \exception{PicklingError} exception; when this happens, an unspecified |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 215 | number of bytes may have been written to the file. |
Guido van Rossum | d188358 | 1995-02-15 15:53:08 +0000 | [diff] [blame] | 216 | |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 217 | It is possible to make multiple calls to the \method{dump()} method of |
| 218 | the same \class{Pickler} instance. These must then be matched to the |
| 219 | same number of calls to the \method{load()} method of the |
| 220 | corresponding \class{Unpickler} instance. If the same object is |
| 221 | pickled by multiple \method{dump()} calls, the \method{load()} will all |
Fred Drake | cf7e830 | 1998-01-09 22:36:51 +0000 | [diff] [blame] | 222 | yield references to the same object. \emph{Warning}: this is intended |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 223 | for pickling multiple objects without intervening modifications to the |
| 224 | objects or their parts. If you modify an object and then pickle it |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 225 | again using the same \class{Pickler} instance, the object is not |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 226 | pickled again --- a reference to it is pickled and the |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 227 | \class{Unpickler} will return the old value, not the modified one. |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 228 | (There are two problems here: (a) detecting changes, and (b) |
| 229 | marshalling a minimal set of changes. I have no answers. Garbage |
| 230 | Collection may also become a problem here.) |
| 231 | |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 232 | Apart from the \class{Pickler} and \class{Unpickler} classes, the |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 233 | module defines the following functions, and an exception: |
| 234 | |
Fred Drake | cce1090 | 1998-03-17 06:33:25 +0000 | [diff] [blame] | 235 | \begin{funcdesc}{dump}{object, file\optional{, bin}} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 236 | Write a pickled representation of \var{obect} to the open file object |
Guido van Rossum | 736fe5e | 1997-12-09 20:45:08 +0000 | [diff] [blame] | 237 | \var{file}. This is equivalent to |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 238 | \samp{Pickler(\var{file}, \var{bin}).dump(\var{object})}. |
Guido van Rossum | 736fe5e | 1997-12-09 20:45:08 +0000 | [diff] [blame] | 239 | If the optional \var{bin} argument is present and nonzero, the binary |
| 240 | pickle format is used; if it is zero or absent, the (less efficient) |
| 241 | text pickle format is used. |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 242 | \end{funcdesc} |
| 243 | |
| 244 | \begin{funcdesc}{load}{file} |
| 245 | Read a pickled object from the open file object \var{file}. This is |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 246 | equivalent to \samp{Unpickler(\var{file}).load()}. |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 247 | \end{funcdesc} |
| 248 | |
Guido van Rossum | 736fe5e | 1997-12-09 20:45:08 +0000 | [diff] [blame] | 249 | \begin{funcdesc}{dumps}{object\optional{, bin}} |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 250 | Return the pickled representation of the object as a string, instead |
Guido van Rossum | 736fe5e | 1997-12-09 20:45:08 +0000 | [diff] [blame] | 251 | of writing it to a file. If the optional \var{bin} argument is |
| 252 | present and nonzero, the binary pickle format is used; if it is zero |
| 253 | or absent, the (less efficient) text pickle format is used. |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 254 | \end{funcdesc} |
| 255 | |
| 256 | \begin{funcdesc}{loads}{string} |
| 257 | Read a pickled object from a string instead of a file. Characters in |
| 258 | the string past the pickled object's representation are ignored. |
| 259 | \end{funcdesc} |
| 260 | |
| 261 | \begin{excdesc}{PicklingError} |
| 262 | This exception is raised when an unpicklable object is passed to |
Fred Drake | 4179691 | 1999-07-02 14:25:37 +0000 | [diff] [blame] | 263 | \method{Pickler.dump()}. |
Guido van Rossum | 470be14 | 1995-03-17 16:07:09 +0000 | [diff] [blame] | 264 | \end{excdesc} |
Fred Drake | 4074896 | 1998-03-06 21:27:14 +0000 | [diff] [blame] | 265 | |
| 266 | |
| 267 | \begin{seealso} |
Fred Drake | ffbe687 | 1999-04-22 21:23:22 +0000 | [diff] [blame] | 268 | \seemodule[copyreg]{copy_reg}{pickle interface constructor |
| 269 | registration} |
Fred Drake | 9b28fe2 | 1998-04-04 06:20:28 +0000 | [diff] [blame] | 270 | |
Fred Drake | ffbe687 | 1999-04-22 21:23:22 +0000 | [diff] [blame] | 271 | \seemodule{shelve}{indexed databases of objects; uses \module{pickle}} |
Fred Drake | 17e5640 | 1998-04-11 20:43:51 +0000 | [diff] [blame] | 272 | |
Fred Drake | ffbe687 | 1999-04-22 21:23:22 +0000 | [diff] [blame] | 273 | \seemodule{copy}{shallow and deep object copying} |
Fred Drake | 17e5640 | 1998-04-11 20:43:51 +0000 | [diff] [blame] | 274 | |
Fred Drake | ffbe687 | 1999-04-22 21:23:22 +0000 | [diff] [blame] | 275 | \seemodule{marshal}{high-performance serialization of built-in types} |
Fred Drake | 4074896 | 1998-03-06 21:27:14 +0000 | [diff] [blame] | 276 | \end{seealso} |
Fred Drake | 9463de2 | 1998-04-11 20:05:43 +0000 | [diff] [blame] | 277 | |
| 278 | |
Fred Drake | 295da24 | 1998-08-10 19:42:37 +0000 | [diff] [blame] | 279 | \section{\module{cPickle} --- |
Fred Drake | ffbe687 | 1999-04-22 21:23:22 +0000 | [diff] [blame] | 280 | Alternate implementation of \module{pickle}} |
| 281 | |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 282 | \declaremodule{builtin}{cPickle} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 283 | \modulesynopsis{Faster version of \module{pickle}, but not subclassable.} |
Fred Drake | ffbe687 | 1999-04-22 21:23:22 +0000 | [diff] [blame] | 284 | \moduleauthor{Jim Fulton}{jfulton@digicool.com} |
| 285 | \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
Fred Drake | b91e934 | 1998-07-23 17:59:49 +0000 | [diff] [blame] | 286 | |
Fred Drake | 9463de2 | 1998-04-11 20:05:43 +0000 | [diff] [blame] | 287 | |
Fred Drake | 9463de2 | 1998-04-11 20:05:43 +0000 | [diff] [blame] | 288 | The \module{cPickle} module provides a similar interface and identical |
Fred Drake | 4179691 | 1999-07-02 14:25:37 +0000 | [diff] [blame] | 289 | functionality as the \refmodule{pickle}\refstmodindex{pickle} module, |
| 290 | but can be up to 1000 times faster since it is implemented in C. The |
| 291 | only other important difference to note is that \function{Pickler()} |
| 292 | and \function{Unpickler()} are functions and not classes, and so |
| 293 | cannot be subclassed. This should not be an issue in most cases. |
Fred Drake | 9463de2 | 1998-04-11 20:05:43 +0000 | [diff] [blame] | 294 | |
| 295 | The format of the pickle data is identical to that produced using the |
Fred Drake | ffbe687 | 1999-04-22 21:23:22 +0000 | [diff] [blame] | 296 | \refmodule{pickle} module, so it is possible to use \refmodule{pickle} and |
Fred Drake | 9463de2 | 1998-04-11 20:05:43 +0000 | [diff] [blame] | 297 | \module{cPickle} interchangably with existing pickles. |
Guido van Rossum | cf3ce92 | 1999-01-06 23:34:39 +0000 | [diff] [blame] | 298 | |
| 299 | (Since the pickle data format is actually a tiny stack-oriented |
| 300 | programming language, and there are some freedoms in the encodings of |
| 301 | certain objects, it's possible that the two modules produce different |
| 302 | pickled data for the same input objects; however they will always be |
| 303 | able to read each others pickles back in.) |