Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libpickle.tex @ 5817:48b94de85bf3 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Extensive changes by AMK.
author Guido van Rossum <guido@python.org>
date Thu, 17 Jul 1997 16:29:42 +0000
parents 6414ffb7f285
children 3468ea8645ca
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
1 \section{Standard Module \sectcode{pickle}}
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
2 \stmodindex{pickle}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
3 \index{persistency}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
4 \indexii{persistent}{objects}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
5 \indexii{serializing}{objects}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
6 \indexii{marshalling}{objects}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
7 \indexii{flattening}{objects}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
8 \indexii{pickling}{objects}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
9
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
10 \renewcommand{\indexsubitem}{(in module pickle)}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
11
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
12 The \code{pickle} module implements a basic but powerful algorithm for
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2347
diff changeset
13 ``pickling'' (a.k.a.\ serializing, marshalling or flattening) nearly
2609
7ef72873e4d6 restructured library manual accordiung to functional group
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
14 arbitrary Python objects. This is the act of converting objects to a
7ef72873e4d6 restructured library manual accordiung to functional group
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
15 stream of bytes (and back: ``unpickling'').
7ef72873e4d6 restructured library manual accordiung to functional group
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
16 This is a more primitive notion than
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 persistency --- although \code{pickle} reads and writes file objects,
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 it does not handle the issue of naming persistent objects, nor the
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
19 (even more complicated) area of concurrent access to persistent
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 objects. The \code{pickle} module can transform a complex object into
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
21 a byte stream and it can transform the byte stream into an object with
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 the same internal structure. The most obvious thing to do with these
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 byte streams is to write them onto a file, but it is also conceivable
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
24 to send them across a network or store them in a database. The module
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
25 \code{shelve} provides a simple interface to pickle and unpickle
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
26 objects on ``dbm''-style database files.
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 \stmodindex{shelve}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
28
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 Unlike the built-in module \code{marshal}, \code{pickle} handles the
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
30 following correctly:
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 \stmodindex{marshal}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
32
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
33 \begin{itemize}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
34
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
35 \item recursive objects (objects containing references to themselves)
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
36
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
37 \item object sharing (references to the same object in different places)
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
38
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
39 \item user-defined classes and their instances
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
40
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
41 \end{itemize}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
42
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
43 The data format used by \code{pickle} is Python-specific. This has
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
44 the advantage that there are no restrictions imposed by external
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
45 standards such as CORBA (which probably can't represent pointer
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
46 sharing or recursive objects); however it means that non-Python
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
47 programs may not be able to reconstruct pickled Python objects.
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
48
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
49 The \code{pickle} data format uses a printable \ASCII{} representation.
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
50 This is slightly more voluminous than a binary representation.
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
51 However, small integers actually take {\em less} space when
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
52 represented as minimal-size decimal strings than when represented as
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
53 32-bit binary numbers, and strings are only much longer if they
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
54 contain many control characters or 8-bit characters. The big
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
55 advantage of using printable \ASCII{} (and of some other characteristics
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
56 of \code{pickle}'s representation) is that for debugging or recovery
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
57 purposes it is possible for a human to read the pickled file with a
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
58 standard text editor. (I could have gone a step further and used a
2609
7ef72873e4d6 restructured library manual accordiung to functional group
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
59 notation like S-expressions, but the parser
7ef72873e4d6 restructured library manual accordiung to functional group
Guido van Rossum <guido@python.org>
parents: 2576
diff changeset
60 (currently written in Python) would have been
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
61 considerably more complicated and slower, and the files would probably
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
62 have become much larger.)
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
63
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
64 The \code{pickle} module doesn't handle code objects, which the
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
65 \code{marshal} module does. I suppose \code{pickle} could, and maybe
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
66 it should, but there's probably no great need for it right now (as
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
67 long as \code{marshal} continues to be used for reading and writing
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
68 code objects), and at least this avoids the possibility of smuggling
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
69 Trojan horses into a program.
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
70 \stmodindex{marshal}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
71
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
72 For the benefit of persistency modules written using \code{pickle}, it
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
73 supports the notion of a reference to an object outside the pickled
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
74 data stream. Such objects are referenced by a name, which is an
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
75 arbitrary string of printable \ASCII{} characters. The resolution of
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
76 such names is not defined by the \code{pickle} module --- the
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
77 persistent object module will have to implement a method
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
78 \code{persistent_load}. To write references to persistent objects,
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
79 the persistent module must define a method \code{persistent_id} which
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
80 returns either \code{None} or the persistent ID of the object.
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
81
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
82 There are some restrictions on the pickling of class instances.
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
83
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
84 First of all, the class must be defined at the top level in a module.
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
85
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
86 \renewcommand{\indexsubitem}{(pickle protocol)}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
87
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
88 Next, it must normally be possible to create class instances by
3993
6414ffb7f285 Suggest using default values for __init__ arguments to make classes
Guido van Rossum <guido@python.org>
parents: 2647
diff changeset
89 calling the class without arguments. Usually, this is best
6414ffb7f285 Suggest using default values for __init__ arguments to make classes
Guido van Rossum <guido@python.org>
parents: 2647
diff changeset
90 accomplished by providing default values for all arguments to its
6414ffb7f285 Suggest using default values for __init__ arguments to make classes
Guido van Rossum <guido@python.org>
parents: 2647
diff changeset
91 \code{__init__} method (if it has one). If this is undesirable, the
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
92 class can define a method \code{__getinitargs__()}, which should
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
93 return a {\em tuple} containing the arguments to be passed to the
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
94 class constructor (\code{__init__()}).
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
95 \ttindex{__getinitargs__}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
96 \ttindex{__init__}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
97
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
98 Classes can further influence how their instances are pickled --- if the class
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
99 defines the method \code{__getstate__()}, it is called and the return
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
100 state is pickled as the contents for the instance, and if the class
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
101 defines the method \code{__setstate__()}, it is called with the
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
102 unpickled state. (Note that these methods can also be used to
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
103 implement copying class instances.) If there is no
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
104 \code{__getstate__()} method, the instance's \code{__dict__} is
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
105 pickled. If there is no \code{__setstate__()} method, the pickled
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
106 object must be a dictionary and its items are assigned to the new
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
107 instance's dictionary. (If a class defines both \code{__getstate__()}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
108 and \code{__setstate__()}, the state object needn't be a dictionary
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
109 --- these methods can do what they want.) This protocol is also used
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
110 by the shallow and deep copying operations defined in the \code{copy}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
111 module.
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
112 \ttindex{__getstate__}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
113 \ttindex{__setstate__}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
114 \ttindex{__dict__}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
115
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
116 Note that when class instances are pickled, their class's code and
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2347
diff changeset
117 data are not pickled along with them. Only the instance data are
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
118 pickled. This is done on purpose, so you can fix bugs in a class or
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
119 add methods and still load objects that were created with an earlier
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
120 version of the class. If you plan to have long-lived objects that
2527
815dfaa6a778 small changes by Soren Larsen
Guido van Rossum <guido@python.org>
parents: 2347
diff changeset
121 will see many versions of a class, it may be worthwhile to put a version
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
122 number in the objects so that suitable conversions can be made by the
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
123 class's \code{__setstate__()} method.
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
124
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
125 When a class itself is pickled, only its name is pickled --- the class
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
126 definition is not pickled, but re-imported by the unpickling process.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
127 Therefore, the restriction that the class must be defined at the top
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
128 level in a module applies to pickled classes as well.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
129
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
130 \renewcommand{\indexsubitem}{(in module pickle)}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
131
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
132 The interface can be summarized as follows.
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
133
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
134 To pickle an object \code{x} onto a file \code{f}, open for writing:
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
135
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
136 \begin{verbatim}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
137 p = pickle.Pickler(f)
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
138 p.dump(x)
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
139 \end{verbatim}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
140
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
141 A shorthand for this is:
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
142
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
143 \begin{verbatim}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
144 pickle.dump(x, f)
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
145 \end{verbatim}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
146
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
147 To unpickle an object \code{x} from a file \code{f}, open for reading:
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
148
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
149 \begin{verbatim}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
150 u = pickle.Unpickler(f)
2647
9b7e6d9a528d typos, layout and other small things
Guido van Rossum <guido@python.org>
parents: 2609
diff changeset
151 x = u.load()
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
152 \end{verbatim}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
153
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
154 A shorthand is:
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
155
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
156 \begin{verbatim}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
157 x = pickle.load(f)
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
158 \end{verbatim}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
159
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
160 The \code{Pickler} class only calls the method \code{f.write} with a
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
161 string argument. The \code{Unpickler} calls the methods \code{f.read}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
162 (with an integer argument) and \code{f.readline} (without argument),
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
163 both returning a string. It is explicitly allowed to pass non-file
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
164 objects here, as long as they have the right methods.
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
165 \ttindex{Unpickler}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
166 \ttindex{Pickler}
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
167
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
168 The following types can be pickled:
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
169 \begin{itemize}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
170
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
171 \item \code{None}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
172
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
173 \item integers, long integers, floating point numbers
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
174
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
175 \item strings
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
176
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
177 \item tuples, lists and dictionaries containing only picklable objects
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
178
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
179 \item classes that are defined at the top level in a module
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
180
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
181 \item instances of such classes whose \code{__dict__} or
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
182 \code{__setstate__()} is picklable
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
183
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
184 \end{itemize}
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
185
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
186 Attempts to pickle unpicklable objects will raise the
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
187 \code{PicklingError} exception; when this happens, an unspecified
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
188 number of bytes may have been written to the file.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
189
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
190 It is possible to make multiple calls to the \code{dump()} method of
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
191 the same \code{Pickler} instance. These must then be matched to the
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
192 same number of calls to the \code{load()} instance of the
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
193 corresponding \code{Unpickler} instance. If the same object is
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
194 pickled by multiple \code{dump()} calls, the \code{load()} will all
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
195 yield references to the same object. {\em Warning}: this is intended
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
196 for pickling multiple objects without intervening modifications to the
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
197 objects or their parts. If you modify an object and then pickle it
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
198 again using the same \code{Pickler} instance, the object is not
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
199 pickled again --- a reference to it is pickled and the
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
200 \code{Unpickler} will return the old value, not the modified one.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
201 (There are two problems here: (a) detecting changes, and (b)
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
202 marshalling a minimal set of changes. I have no answers. Garbage
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
203 Collection may also become a problem here.)
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
204
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
205 Apart from the \code{Pickler} and \code{Unpickler} classes, the
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
206 module defines the following functions, and an exception:
2347
d05685993476 added docs for pickle, shelve and copy
Guido van Rossum <guido@python.org>
parents:
diff changeset
207
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
208 \begin{funcdesc}{dump}{object\, file}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
209 Write a pickled representation of \var{obect} to the open file object
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
210 \var{file}. This is equivalent to \code{Pickler(file).dump(object)}.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
211 \end{funcdesc}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
212
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
213 \begin{funcdesc}{load}{file}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
214 Read a pickled object from the open file object \var{file}. This is
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
215 equivalent to \code{Unpickler(file).load()}.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
216 \end{funcdesc}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
217
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
218 \begin{funcdesc}{dumps}{object}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
219 Return the pickled representation of the object as a string, instead
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
220 of writing it to a file.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
221 \end{funcdesc}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
222
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
223 \begin{funcdesc}{loads}{string}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
224 Read a pickled object from a string instead of a file. Characters in
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
225 the string past the pickled object's representation are ignored.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
226 \end{funcdesc}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
227
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
228 \begin{excdesc}{PicklingError}
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
229 This exception is raised when an unpicklable object is passed to
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
230 \code{Pickler.dump()}.
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2527
diff changeset
231 \end{excdesc}