Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`pickle` --- Python object serialization |
| 2 | ============================================= |
| 3 | |
| 4 | .. index:: |
| 5 | single: persistence |
| 6 | pair: persistent; objects |
| 7 | pair: serializing; objects |
| 8 | pair: marshalling; objects |
| 9 | pair: flattening; objects |
| 10 | pair: pickling; objects |
| 11 | |
| 12 | .. module:: pickle |
| 13 | :synopsis: Convert Python objects to streams of bytes and back. |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 14 | .. sectionauthor:: Jim Kerr <jbkerr@sr.hp.com>. |
Andrew Kuchling | 587e970 | 2013-11-12 10:02:35 -0500 | [diff] [blame] | 15 | .. sectionauthor:: Barry Warsaw <barry@python.org> |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 16 | |
Alexandre Vassalotti | 9d7665d | 2009-04-03 06:13:29 +0000 | [diff] [blame] | 17 | |
Antoine Pitrou | d4d6055 | 2013-12-07 00:56:59 +0100 | [diff] [blame] | 18 | The :mod:`pickle` module implements binary protocols for serializing and |
| 19 | de-serializing a Python object structure. *"Pickling"* is the process |
| 20 | whereby a Python object hierarchy is converted into a byte stream, and |
| 21 | *"unpickling"* is the inverse operation, whereby a byte stream |
| 22 | (from a :term:`binary file` or :term:`bytes-like object`) is converted |
| 23 | back into an object hierarchy. Pickling (and unpickling) is alternatively |
| 24 | known as "serialization", "marshalling," [#]_ or "flattening"; however, to |
| 25 | avoid confusion, the terms used here are "pickling" and "unpickling". |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 26 | |
Georg Brandl | 0036bcf | 2010-10-17 10:24:54 +0000 | [diff] [blame] | 27 | .. warning:: |
| 28 | |
| 29 | The :mod:`pickle` module is not intended to be secure against erroneous or |
| 30 | maliciously constructed data. Never unpickle data received from an untrusted |
| 31 | or unauthenticated source. |
| 32 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 33 | |
| 34 | Relationship to other Python modules |
| 35 | ------------------------------------ |
| 36 | |
Antoine Pitrou | d4d6055 | 2013-12-07 00:56:59 +0100 | [diff] [blame] | 37 | Comparison with ``marshal`` |
| 38 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 39 | |
| 40 | Python has a more primitive serialization module called :mod:`marshal`, but in |
| 41 | general :mod:`pickle` should always be the preferred way to serialize Python |
| 42 | objects. :mod:`marshal` exists primarily to support Python's :file:`.pyc` |
| 43 | files. |
| 44 | |
Georg Brandl | 5aa580f | 2010-11-30 14:57:54 +0000 | [diff] [blame] | 45 | The :mod:`pickle` module differs from :mod:`marshal` in several significant ways: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 46 | |
| 47 | * The :mod:`pickle` module keeps track of the objects it has already serialized, |
| 48 | so that later references to the same object won't be serialized again. |
| 49 | :mod:`marshal` doesn't do this. |
| 50 | |
| 51 | This has implications both for recursive objects and object sharing. Recursive |
| 52 | objects are objects that contain references to themselves. These are not |
| 53 | handled by marshal, and in fact, attempting to marshal recursive objects will |
| 54 | crash your Python interpreter. Object sharing happens when there are multiple |
| 55 | references to the same object in different places in the object hierarchy being |
| 56 | serialized. :mod:`pickle` stores such objects only once, and ensures that all |
| 57 | other references point to the master copy. Shared objects remain shared, which |
| 58 | can be very important for mutable objects. |
| 59 | |
| 60 | * :mod:`marshal` cannot be used to serialize user-defined classes and their |
| 61 | instances. :mod:`pickle` can save and restore class instances transparently, |
| 62 | however the class definition must be importable and live in the same module as |
| 63 | when the object was stored. |
| 64 | |
| 65 | * The :mod:`marshal` serialization format is not guaranteed to be portable |
| 66 | across Python versions. Because its primary job in life is to support |
| 67 | :file:`.pyc` files, the Python implementers reserve the right to change the |
| 68 | serialization format in non-backwards compatible ways should the need arise. |
| 69 | The :mod:`pickle` serialization format is guaranteed to be backwards compatible |
| 70 | across Python releases. |
| 71 | |
Antoine Pitrou | d4d6055 | 2013-12-07 00:56:59 +0100 | [diff] [blame] | 72 | Comparison with ``json`` |
| 73 | ^^^^^^^^^^^^^^^^^^^^^^^^ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 74 | |
Antoine Pitrou | d4d6055 | 2013-12-07 00:56:59 +0100 | [diff] [blame] | 75 | There are fundamental differences between the pickle protocols and |
| 76 | `JSON (JavaScript Object Notation) <http://json.org>`_: |
| 77 | |
| 78 | * JSON is a text serialization format (it outputs unicode text, although |
| 79 | most of the time it is then encoded to ``utf-8``), while pickle is |
| 80 | a binary serialization format; |
| 81 | |
| 82 | * JSON is human-readable, while pickle is not; |
| 83 | |
| 84 | * JSON is interoperable and widely used outside of the Python ecosystem, |
| 85 | while pickle is Python-specific; |
| 86 | |
| 87 | * JSON, by default, can only represent a subset of the Python built-in |
| 88 | types, and no custom classes; pickle can represent an extremely large |
| 89 | number of Python types (many of them automatically, by clever usage |
| 90 | of Python's introspection facilities; complex cases can be tackled by |
| 91 | implementing :ref:`specific object APIs <pickle-inst>`). |
| 92 | |
| 93 | .. seealso:: |
| 94 | The :mod:`json` module: a standard library module allowing JSON |
| 95 | serialization and deserialization. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 96 | |
Antoine Pitrou | 9bcb112 | 2013-12-07 01:05:57 +0100 | [diff] [blame] | 97 | |
| 98 | .. _pickle-protocols: |
| 99 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 100 | Data stream format |
| 101 | ------------------ |
| 102 | |
| 103 | .. index:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 104 | single: External Data Representation |
| 105 | |
| 106 | The data format used by :mod:`pickle` is Python-specific. This has the |
| 107 | advantage that there are no restrictions imposed by external standards such as |
Antoine Pitrou | a9494f6 | 2012-05-10 15:38:30 +0200 | [diff] [blame] | 108 | JSON or XDR (which can't represent pointer sharing); however it means that |
| 109 | non-Python programs may not be able to reconstruct pickled Python objects. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 110 | |
Antoine Pitrou | a9494f6 | 2012-05-10 15:38:30 +0200 | [diff] [blame] | 111 | By default, the :mod:`pickle` data format uses a relatively compact binary |
| 112 | representation. If you need optimal size characteristics, you can efficiently |
| 113 | :doc:`compress <archiving>` pickled data. |
| 114 | |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 115 | The module :mod:`pickletools` contains tools for analyzing data streams |
Antoine Pitrou | a9494f6 | 2012-05-10 15:38:30 +0200 | [diff] [blame] | 116 | generated by :mod:`pickle`. :mod:`pickletools` source code has extensive |
| 117 | comments about opcodes used by pickle protocols. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 118 | |
Georg Brandl | 42f2ae0 | 2008-04-06 08:39:37 +0000 | [diff] [blame] | 119 | There are currently 4 different protocols which can be used for pickling. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 120 | |
Antoine Pitrou | a9494f6 | 2012-05-10 15:38:30 +0200 | [diff] [blame] | 121 | * Protocol version 0 is the original "human-readable" protocol and is |
Alexandre Vassalotti | f7d08c7 | 2009-01-23 04:50:05 +0000 | [diff] [blame] | 122 | backwards compatible with earlier versions of Python. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 123 | |
Antoine Pitrou | a9494f6 | 2012-05-10 15:38:30 +0200 | [diff] [blame] | 124 | * Protocol version 1 is an old binary format which is also compatible with |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 125 | earlier versions of Python. |
| 126 | |
| 127 | * Protocol version 2 was introduced in Python 2.3. It provides much more |
Antoine Pitrou | a9494f6 | 2012-05-10 15:38:30 +0200 | [diff] [blame] | 128 | efficient pickling of :term:`new-style class`\es. Refer to :pep:`307` for |
| 129 | information about improvements brought by protocol 2. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 130 | |
Antoine Pitrou | 9bcb112 | 2013-12-07 01:05:57 +0100 | [diff] [blame] | 131 | * Protocol version 3 was added in Python 3.0. It has explicit support for |
Antoine Pitrou | a9494f6 | 2012-05-10 15:38:30 +0200 | [diff] [blame] | 132 | :class:`bytes` objects and cannot be unpickled by Python 2.x. This is |
Antoine Pitrou | 9bcb112 | 2013-12-07 01:05:57 +0100 | [diff] [blame] | 133 | the default protocol, and the recommended protocol when compatibility with |
| 134 | other Python 3 versions is required. |
| 135 | |
| 136 | * Protocol version 4 was added in Python 3.4. It adds support for very large |
| 137 | objects, pickling more kinds of objects, and some data format |
| 138 | optimizations. Refer to :pep:`3154` for information about improvements |
| 139 | brought by protocol 4. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 140 | |
Antoine Pitrou | d4d6055 | 2013-12-07 00:56:59 +0100 | [diff] [blame] | 141 | .. note:: |
| 142 | Serialization is a more primitive notion than persistence; although |
| 143 | :mod:`pickle` reads and writes file objects, it does not handle the issue of |
| 144 | naming persistent objects, nor the (even more complicated) issue of concurrent |
| 145 | access to persistent objects. The :mod:`pickle` module can transform a complex |
| 146 | object into a byte stream and it can transform the byte stream into an object |
| 147 | with the same internal structure. Perhaps the most obvious thing to do with |
| 148 | these byte streams is to write them onto a file, but it is also conceivable to |
| 149 | send them across a network or store them in a database. The :mod:`shelve` |
| 150 | module provides a simple interface to pickle and unpickle objects on |
| 151 | DBM-style database files. |
| 152 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 153 | |
Alexandre Vassalotti | d039286 | 2008-10-24 01:32:40 +0000 | [diff] [blame] | 154 | Module Interface |
| 155 | ---------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 156 | |
Antoine Pitrou | a9494f6 | 2012-05-10 15:38:30 +0200 | [diff] [blame] | 157 | To serialize an object hierarchy, you simply call the :func:`dumps` function. |
| 158 | Similarly, to de-serialize a data stream, you call the :func:`loads` function. |
| 159 | However, if you want more control over serialization and de-serialization, |
| 160 | you can create a :class:`Pickler` or an :class:`Unpickler` object, respectively. |
| 161 | |
| 162 | The :mod:`pickle` module provides the following constants: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 163 | |
| 164 | |
| 165 | .. data:: HIGHEST_PROTOCOL |
| 166 | |
Antoine Pitrou | 9bcb112 | 2013-12-07 01:05:57 +0100 | [diff] [blame] | 167 | An integer, the highest :ref:`protocol version <pickle-protocols>` |
| 168 | available. This value can be passed as a *protocol* value to functions |
| 169 | :func:`dump` and :func:`dumps` as well as the :class:`Pickler` |
| 170 | constructor. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 171 | |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 172 | .. data:: DEFAULT_PROTOCOL |
| 173 | |
Antoine Pitrou | 9bcb112 | 2013-12-07 01:05:57 +0100 | [diff] [blame] | 174 | An integer, the default :ref:`protocol version <pickle-protocols>` used |
| 175 | for pickling. May be less than :data:`HIGHEST_PROTOCOL`. Currently the |
Alexandre Vassalotti | d05c9ff | 2013-12-07 01:09:27 -0800 | [diff] [blame^] | 176 | default protocol is 3, a new protocol designed for Python 3. |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 177 | |
| 178 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 179 | The :mod:`pickle` module provides the following functions to make the pickling |
| 180 | process more convenient: |
| 181 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 182 | .. function:: dump(obj, file, protocol=None, \*, fix_imports=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 183 | |
Antoine Pitrou | 11cb961 | 2010-09-15 11:11:28 +0000 | [diff] [blame] | 184 | Write a pickled representation of *obj* to the open :term:`file object` *file*. |
| 185 | This is equivalent to ``Pickler(file, protocol).dump(obj)``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 186 | |
Alexandre Vassalotti | d05c9ff | 2013-12-07 01:09:27 -0800 | [diff] [blame^] | 187 | The optional *protocol* argument tells the pickler to use the given |
| 188 | protocol; supported protocols are 0, 1, 2, 3. The default protocol is 3; a |
| 189 | backward-incompatible protocol designed for Python 3. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 190 | |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 191 | Specifying a negative protocol version selects the highest protocol version |
| 192 | supported. The higher the protocol used, the more recent the version of |
| 193 | Python needed to read the pickle produced. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 194 | |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 195 | The *file* argument must have a write() method that accepts a single bytes |
Antoine Pitrou | 11cb961 | 2010-09-15 11:11:28 +0000 | [diff] [blame] | 196 | argument. It can thus be an on-disk file opened for binary writing, a |
| 197 | :class:`io.BytesIO` instance, or any other custom object that meets this |
| 198 | interface. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 199 | |
Serhiy Storchaka | fbc1c26 | 2013-11-29 12:17:13 +0200 | [diff] [blame] | 200 | If *fix_imports* is true and *protocol* is less than 3, pickle will try to |
Alexandre Vassalotti | d05c9ff | 2013-12-07 01:09:27 -0800 | [diff] [blame^] | 201 | map the new Python 3 names to the old module names used in Python 2, so |
| 202 | that the pickle data stream is readable with Python 2. |
Antoine Pitrou | d9dfaa9 | 2009-06-04 20:32:06 +0000 | [diff] [blame] | 203 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 204 | .. function:: dumps(obj, protocol=None, \*, fix_imports=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 205 | |
Alexandre Vassalotti | d05c9ff | 2013-12-07 01:09:27 -0800 | [diff] [blame^] | 206 | Return the pickled representation of the object as a :class:`bytes` object, |
| 207 | instead of writing it to a file. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 208 | |
Alexandre Vassalotti | d05c9ff | 2013-12-07 01:09:27 -0800 | [diff] [blame^] | 209 | The optional *protocol* argument tells the pickler to use the given |
| 210 | protocol; supported protocols are 0, 1, 2, 3 and 4. The default protocol |
| 211 | is 3; a backward-incompatible protocol designed for Python 3. |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 212 | |
| 213 | Specifying a negative protocol version selects the highest protocol version |
| 214 | supported. The higher the protocol used, the more recent the version of |
| 215 | Python needed to read the pickle produced. |
| 216 | |
Serhiy Storchaka | fbc1c26 | 2013-11-29 12:17:13 +0200 | [diff] [blame] | 217 | If *fix_imports* is true and *protocol* is less than 3, pickle will try to |
Alexandre Vassalotti | d05c9ff | 2013-12-07 01:09:27 -0800 | [diff] [blame^] | 218 | map the new Python 3 names to the old module names used in Python 2, so |
| 219 | that the pickle data stream is readable with Python 2. |
Antoine Pitrou | d9dfaa9 | 2009-06-04 20:32:06 +0000 | [diff] [blame] | 220 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 221 | .. function:: load(file, \*, fix_imports=True, encoding="ASCII", errors="strict") |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 222 | |
Alexandre Vassalotti | d05c9ff | 2013-12-07 01:09:27 -0800 | [diff] [blame^] | 223 | Read a pickled object representation from the open :term:`file object` |
| 224 | *file* and return the reconstituted object hierarchy specified therein. |
| 225 | This is equivalent to ``Unpickler(file).load()``. |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 226 | |
Alexandre Vassalotti | d05c9ff | 2013-12-07 01:09:27 -0800 | [diff] [blame^] | 227 | The protocol version of the pickle is detected automatically, so no |
| 228 | protocol argument is needed. Bytes past the pickled object's |
| 229 | representation are ignored. |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 230 | |
| 231 | The argument *file* must have two methods, a read() method that takes an |
| 232 | integer argument, and a readline() method that requires no arguments. Both |
Alexandre Vassalotti | d05c9ff | 2013-12-07 01:09:27 -0800 | [diff] [blame^] | 233 | methods should return bytes. Thus *file* can be an on-disk file opened for |
| 234 | binary reading, a :class:`io.BytesIO` object, or any other custom object |
Antoine Pitrou | 11cb961 | 2010-09-15 11:11:28 +0000 | [diff] [blame] | 235 | that meets this interface. |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 236 | |
Antoine Pitrou | d9dfaa9 | 2009-06-04 20:32:06 +0000 | [diff] [blame] | 237 | Optional keyword arguments are *fix_imports*, *encoding* and *errors*, |
Georg Brandl | 6faee4e | 2010-09-21 14:48:28 +0000 | [diff] [blame] | 238 | which are used to control compatibility support for pickle stream generated |
Alexandre Vassalotti | d05c9ff | 2013-12-07 01:09:27 -0800 | [diff] [blame^] | 239 | by Python 2. If *fix_imports* is true, pickle will try to map the old |
| 240 | Python 2 names to the new names used in Python 3. The *encoding* and |
Antoine Pitrou | d9dfaa9 | 2009-06-04 20:32:06 +0000 | [diff] [blame] | 241 | *errors* tell pickle how to decode 8-bit string instances pickled by Python |
Alexandre Vassalotti | d05c9ff | 2013-12-07 01:09:27 -0800 | [diff] [blame^] | 242 | 2; these default to 'ASCII' and 'strict', respectively. The *encoding* can |
| 243 | be 'bytes' to read these 8-bit string instances as bytes objects. |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 244 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 245 | .. function:: loads(bytes_object, \*, fix_imports=True, encoding="ASCII", errors="strict") |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 246 | |
| 247 | Read a pickled object hierarchy from a :class:`bytes` object and return the |
| 248 | reconstituted object hierarchy specified therein |
| 249 | |
Alexandre Vassalotti | d05c9ff | 2013-12-07 01:09:27 -0800 | [diff] [blame^] | 250 | The protocol version of the pickle is detected automatically, so no |
| 251 | protocol argument is needed. Bytes past the pickled object's |
| 252 | representation are ignored. |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 253 | |
Antoine Pitrou | d9dfaa9 | 2009-06-04 20:32:06 +0000 | [diff] [blame] | 254 | Optional keyword arguments are *fix_imports*, *encoding* and *errors*, |
Georg Brandl | 6faee4e | 2010-09-21 14:48:28 +0000 | [diff] [blame] | 255 | which are used to control compatibility support for pickle stream generated |
Alexandre Vassalotti | d05c9ff | 2013-12-07 01:09:27 -0800 | [diff] [blame^] | 256 | by Python 2. If *fix_imports* is true, pickle will try to map the old |
| 257 | Python 2 names to the new names used in Python 3. The *encoding* and |
Antoine Pitrou | d9dfaa9 | 2009-06-04 20:32:06 +0000 | [diff] [blame] | 258 | *errors* tell pickle how to decode 8-bit string instances pickled by Python |
Alexandre Vassalotti | d05c9ff | 2013-12-07 01:09:27 -0800 | [diff] [blame^] | 259 | 2; these default to 'ASCII' and 'strict', respectively. The *encoding* can |
| 260 | be 'bytes' to read these 8-bit string instances as bytes objects. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 261 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 262 | |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 263 | The :mod:`pickle` module defines three exceptions: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 264 | |
| 265 | .. exception:: PickleError |
| 266 | |
Alexandre Vassalotti | 5f3b63a | 2008-10-18 20:47:58 +0000 | [diff] [blame] | 267 | Common base class for the other pickling exceptions. It inherits |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 268 | :exc:`Exception`. |
| 269 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 270 | .. exception:: PicklingError |
| 271 | |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 272 | Error raised when an unpicklable object is encountered by :class:`Pickler`. |
| 273 | It inherits :exc:`PickleError`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 274 | |
Alexandre Vassalotti | 5f3b63a | 2008-10-18 20:47:58 +0000 | [diff] [blame] | 275 | Refer to :ref:`pickle-picklable` to learn what kinds of objects can be |
| 276 | pickled. |
| 277 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 278 | .. exception:: UnpicklingError |
| 279 | |
Ezio Melotti | e62aad3 | 2011-11-18 13:51:10 +0200 | [diff] [blame] | 280 | Error raised when there is a problem unpickling an object, such as a data |
Alexandre Vassalotti | 5f3b63a | 2008-10-18 20:47:58 +0000 | [diff] [blame] | 281 | corruption or a security violation. It inherits :exc:`PickleError`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 282 | |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 283 | Note that other exceptions may also be raised during unpickling, including |
| 284 | (but not necessarily limited to) AttributeError, EOFError, ImportError, and |
| 285 | IndexError. |
| 286 | |
| 287 | |
| 288 | The :mod:`pickle` module exports two classes, :class:`Pickler` and |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 289 | :class:`Unpickler`: |
| 290 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 291 | .. class:: Pickler(file, protocol=None, \*, fix_imports=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 292 | |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 293 | This takes a binary file for writing a pickle data stream. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 294 | |
Alexandre Vassalotti | d05c9ff | 2013-12-07 01:09:27 -0800 | [diff] [blame^] | 295 | The optional *protocol* argument tells the pickler to use the given |
| 296 | protocol; supported protocols are 0, 1, 2, 3 and 4. The default protocol |
| 297 | is 3; a backward-incompatible protocol designed for Python 3. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 298 | |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 299 | Specifying a negative protocol version selects the highest protocol version |
| 300 | supported. The higher the protocol used, the more recent the version of |
| 301 | Python needed to read the pickle produced. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 302 | |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 303 | The *file* argument must have a write() method that accepts a single bytes |
Antoine Pitrou | 11cb961 | 2010-09-15 11:11:28 +0000 | [diff] [blame] | 304 | argument. It can thus be an on-disk file opened for binary writing, a |
Alexandre Vassalotti | d05c9ff | 2013-12-07 01:09:27 -0800 | [diff] [blame^] | 305 | :class:`io.BytesIO` instance, or any other custom object that meets this |
| 306 | interface. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 307 | |
Serhiy Storchaka | fbc1c26 | 2013-11-29 12:17:13 +0200 | [diff] [blame] | 308 | If *fix_imports* is true and *protocol* is less than 3, pickle will try to |
Alexandre Vassalotti | d05c9ff | 2013-12-07 01:09:27 -0800 | [diff] [blame^] | 309 | map the new Python 3 names to the old module names used in Python 2, so |
| 310 | that the pickle data stream is readable with Python 2. |
Antoine Pitrou | d9dfaa9 | 2009-06-04 20:32:06 +0000 | [diff] [blame] | 311 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 312 | .. method:: dump(obj) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 313 | |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 314 | Write a pickled representation of *obj* to the open file object given in |
| 315 | the constructor. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 316 | |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 317 | .. method:: persistent_id(obj) |
| 318 | |
| 319 | Do nothing by default. This exists so a subclass can override it. |
| 320 | |
| 321 | If :meth:`persistent_id` returns ``None``, *obj* is pickled as usual. Any |
| 322 | other value causes :class:`Pickler` to emit the returned value as a |
| 323 | persistent ID for *obj*. The meaning of this persistent ID should be |
| 324 | defined by :meth:`Unpickler.persistent_load`. Note that the value |
| 325 | returned by :meth:`persistent_id` cannot itself have a persistent ID. |
| 326 | |
| 327 | See :ref:`pickle-persistent` for details and examples of uses. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 328 | |
Antoine Pitrou | 8d3c290 | 2012-03-04 18:31:48 +0100 | [diff] [blame] | 329 | .. attribute:: dispatch_table |
| 330 | |
| 331 | A pickler object's dispatch table is a registry of *reduction |
| 332 | functions* of the kind which can be declared using |
| 333 | :func:`copyreg.pickle`. It is a mapping whose keys are classes |
| 334 | and whose values are reduction functions. A reduction function |
| 335 | takes a single argument of the associated class and should |
Serhiy Storchaka | 5bbbc94 | 2013-10-14 10:43:46 +0300 | [diff] [blame] | 336 | conform to the same interface as a :meth:`__reduce__` |
Antoine Pitrou | 8d3c290 | 2012-03-04 18:31:48 +0100 | [diff] [blame] | 337 | method. |
| 338 | |
| 339 | By default, a pickler object will not have a |
| 340 | :attr:`dispatch_table` attribute, and it will instead use the |
| 341 | global dispatch table managed by the :mod:`copyreg` module. |
| 342 | However, to customize the pickling for a specific pickler object |
| 343 | one can set the :attr:`dispatch_table` attribute to a dict-like |
| 344 | object. Alternatively, if a subclass of :class:`Pickler` has a |
| 345 | :attr:`dispatch_table` attribute then this will be used as the |
| 346 | default dispatch table for instances of that class. |
| 347 | |
| 348 | See :ref:`pickle-dispatch` for usage examples. |
| 349 | |
| 350 | .. versionadded:: 3.3 |
| 351 | |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 352 | .. attribute:: fast |
| 353 | |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 354 | Deprecated. Enable fast mode if set to a true value. The fast mode |
| 355 | disables the usage of memo, therefore speeding the pickling process by not |
| 356 | generating superfluous PUT opcodes. It should not be used with |
| 357 | self-referential objects, doing otherwise will cause :class:`Pickler` to |
| 358 | recurse infinitely. |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 359 | |
| 360 | Use :func:`pickletools.optimize` if you need more compact pickles. |
| 361 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 362 | |
Georg Brandl | 1824415 | 2009-09-02 20:34:52 +0000 | [diff] [blame] | 363 | .. class:: Unpickler(file, \*, fix_imports=True, encoding="ASCII", errors="strict") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 364 | |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 365 | This takes a binary file for reading a pickle data stream. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 366 | |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 367 | The protocol version of the pickle is detected automatically, so no |
| 368 | protocol argument is needed. |
| 369 | |
| 370 | The argument *file* must have two methods, a read() method that takes an |
| 371 | integer argument, and a readline() method that requires no arguments. Both |
Alexandre Vassalotti | d05c9ff | 2013-12-07 01:09:27 -0800 | [diff] [blame^] | 372 | methods should return bytes. Thus *file* can be an on-disk file object |
| 373 | opened for binary reading, a :class:`io.BytesIO` object, or any other |
| 374 | custom object that meets this interface. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 375 | |
Antoine Pitrou | d9dfaa9 | 2009-06-04 20:32:06 +0000 | [diff] [blame] | 376 | Optional keyword arguments are *fix_imports*, *encoding* and *errors*, |
Georg Brandl | 6faee4e | 2010-09-21 14:48:28 +0000 | [diff] [blame] | 377 | which are used to control compatibility support for pickle stream generated |
Alexandre Vassalotti | d05c9ff | 2013-12-07 01:09:27 -0800 | [diff] [blame^] | 378 | by Python 2. If *fix_imports* is true, pickle will try to map the old |
| 379 | Python 2 names to the new names used in Python 3. The *encoding* and |
Antoine Pitrou | d9dfaa9 | 2009-06-04 20:32:06 +0000 | [diff] [blame] | 380 | *errors* tell pickle how to decode 8-bit string instances pickled by Python |
Alexandre Vassalotti | d05c9ff | 2013-12-07 01:09:27 -0800 | [diff] [blame^] | 381 | 2; these default to 'ASCII' and 'strict', respectively. The *encoding* can |
| 382 | be 'bytes' to read these ß8-bit string instances as bytes objects. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 383 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 384 | .. method:: load() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 385 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 386 | Read a pickled object representation from the open file object given in |
| 387 | the constructor, and return the reconstituted object hierarchy specified |
Alexandre Vassalotti | 5f3b63a | 2008-10-18 20:47:58 +0000 | [diff] [blame] | 388 | therein. Bytes past the pickled object's representation are ignored. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 389 | |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 390 | .. method:: persistent_load(pid) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 391 | |
Ezio Melotti | e62aad3 | 2011-11-18 13:51:10 +0200 | [diff] [blame] | 392 | Raise an :exc:`UnpicklingError` by default. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 393 | |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 394 | If defined, :meth:`persistent_load` should return the object specified by |
Alexandre Vassalotti | 5f3b63a | 2008-10-18 20:47:58 +0000 | [diff] [blame] | 395 | the persistent ID *pid*. If an invalid persistent ID is encountered, an |
Ezio Melotti | e62aad3 | 2011-11-18 13:51:10 +0200 | [diff] [blame] | 396 | :exc:`UnpicklingError` should be raised. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 397 | |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 398 | See :ref:`pickle-persistent` for details and examples of uses. |
| 399 | |
| 400 | .. method:: find_class(module, name) |
| 401 | |
Alexandre Vassalotti | 5f3b63a | 2008-10-18 20:47:58 +0000 | [diff] [blame] | 402 | Import *module* if necessary and return the object called *name* from it, |
Alexandre Vassalotti | d039286 | 2008-10-24 01:32:40 +0000 | [diff] [blame] | 403 | where the *module* and *name* arguments are :class:`str` objects. Note, |
| 404 | unlike its name suggests, :meth:`find_class` is also used for finding |
| 405 | functions. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 406 | |
Alexandre Vassalotti | 5f3b63a | 2008-10-18 20:47:58 +0000 | [diff] [blame] | 407 | Subclasses may override this to gain control over what type of objects and |
Alexandre Vassalotti | d039286 | 2008-10-24 01:32:40 +0000 | [diff] [blame] | 408 | how they can be loaded, potentially reducing security risks. Refer to |
| 409 | :ref:`pickle-restrict` for details. |
Alexandre Vassalotti | 5f3b63a | 2008-10-18 20:47:58 +0000 | [diff] [blame] | 410 | |
| 411 | |
| 412 | .. _pickle-picklable: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 413 | |
| 414 | What can be pickled and unpickled? |
| 415 | ---------------------------------- |
| 416 | |
| 417 | The following types can be pickled: |
| 418 | |
| 419 | * ``None``, ``True``, and ``False`` |
| 420 | |
Georg Brandl | ba956ae | 2007-11-29 17:24:34 +0000 | [diff] [blame] | 421 | * integers, floating point numbers, complex numbers |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 422 | |
Georg Brandl | f694518 | 2008-02-01 11:56:49 +0000 | [diff] [blame] | 423 | * strings, bytes, bytearrays |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 424 | |
| 425 | * tuples, lists, sets, and dictionaries containing only picklable objects |
| 426 | |
Ethan Furman | 2498d9e | 2013-10-18 00:45:40 -0700 | [diff] [blame] | 427 | * functions defined at the top level of a module (using :keyword:`def`, not |
| 428 | :keyword:`lambda`) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 429 | |
| 430 | * built-in functions defined at the top level of a module |
| 431 | |
| 432 | * classes that are defined at the top level of a module |
| 433 | |
Serhiy Storchaka | 5bbbc94 | 2013-10-14 10:43:46 +0300 | [diff] [blame] | 434 | * instances of such classes whose :attr:`~object.__dict__` or the result of |
| 435 | calling :meth:`__getstate__` is picklable (see section :ref:`pickle-inst` for |
Eli Bendersky | 78f3ce5 | 2013-01-02 05:53:59 -0800 | [diff] [blame] | 436 | details). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 437 | |
| 438 | Attempts to pickle unpicklable objects will raise the :exc:`PicklingError` |
| 439 | exception; when this happens, an unspecified number of bytes may have already |
Alexandre Vassalotti | 5f3b63a | 2008-10-18 20:47:58 +0000 | [diff] [blame] | 440 | been written to the underlying file. Trying to pickle a highly recursive data |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 441 | structure may exceed the maximum recursion depth, a :exc:`RuntimeError` will be |
Alexandre Vassalotti | 5f3b63a | 2008-10-18 20:47:58 +0000 | [diff] [blame] | 442 | raised in this case. You can carefully raise this limit with |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 443 | :func:`sys.setrecursionlimit`. |
| 444 | |
| 445 | Note that functions (built-in and user-defined) are pickled by "fully qualified" |
Ethan Furman | 2498d9e | 2013-10-18 00:45:40 -0700 | [diff] [blame] | 446 | name reference, not by value. [#]_ This means that only the function name is |
Eli Bendersky | 78f3ce5 | 2013-01-02 05:53:59 -0800 | [diff] [blame] | 447 | pickled, along with the name of the module the function is defined in. Neither |
| 448 | the function's code, nor any of its function attributes are pickled. Thus the |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 449 | defining module must be importable in the unpickling environment, and the module |
| 450 | must contain the named object, otherwise an exception will be raised. [#]_ |
| 451 | |
| 452 | Similarly, classes are pickled by named reference, so the same restrictions in |
| 453 | the unpickling environment apply. Note that none of the class's code or data is |
| 454 | pickled, so in the following example the class attribute ``attr`` is not |
| 455 | restored in the unpickling environment:: |
| 456 | |
| 457 | class Foo: |
Alexandre Vassalotti | 5f3b63a | 2008-10-18 20:47:58 +0000 | [diff] [blame] | 458 | attr = 'A class attribute' |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 459 | |
| 460 | picklestring = pickle.dumps(Foo) |
| 461 | |
| 462 | These restrictions are why picklable functions and classes must be defined in |
| 463 | the top level of a module. |
| 464 | |
| 465 | Similarly, when class instances are pickled, their class's code and data are not |
| 466 | pickled along with them. Only the instance data are pickled. This is done on |
| 467 | purpose, so you can fix bugs in a class or add methods to the class and still |
| 468 | load objects that were created with an earlier version of the class. If you |
| 469 | plan to have long-lived objects that will see many versions of a class, it may |
| 470 | be worthwhile to put a version number in the objects so that suitable |
| 471 | conversions can be made by the class's :meth:`__setstate__` method. |
| 472 | |
| 473 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 474 | .. _pickle-inst: |
| 475 | |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 476 | Pickling Class Instances |
| 477 | ------------------------ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 478 | |
Serhiy Storchaka | 5bbbc94 | 2013-10-14 10:43:46 +0300 | [diff] [blame] | 479 | .. currentmodule:: None |
| 480 | |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 481 | In this section, we describe the general mechanisms available to you to define, |
| 482 | customize, and control how class instances are pickled and unpickled. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 483 | |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 484 | In most cases, no additional code is needed to make instances picklable. By |
| 485 | default, pickle will retrieve the class and the attributes of an instance via |
| 486 | introspection. When a class instance is unpickled, its :meth:`__init__` method |
| 487 | is usually *not* invoked. The default behaviour first creates an uninitialized |
| 488 | instance and then restores the saved attributes. The following code shows an |
| 489 | implementation of this behaviour:: |
Georg Brandl | 85eb8c1 | 2007-08-31 16:33:38 +0000 | [diff] [blame] | 490 | |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 491 | def save(obj): |
| 492 | return (obj.__class__, obj.__dict__) |
| 493 | |
| 494 | def load(cls, attributes): |
| 495 | obj = cls.__new__(cls) |
| 496 | obj.__dict__.update(attributes) |
| 497 | return obj |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 498 | |
Georg Brandl | 6faee4e | 2010-09-21 14:48:28 +0000 | [diff] [blame] | 499 | Classes can alter the default behaviour by providing one or several special |
Georg Brandl | c814826 | 2010-10-17 11:13:37 +0000 | [diff] [blame] | 500 | methods: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 501 | |
Antoine Pitrou | c9dc4a2 | 2013-11-23 18:59:12 +0100 | [diff] [blame] | 502 | .. method:: object.__getnewargs_ex__() |
| 503 | |
| 504 | In protocols 4 and newer, classes that implements the |
| 505 | :meth:`__getnewargs_ex__` method can dictate the values passed to the |
| 506 | :meth:`__new__` method upon unpickling. The method must return a pair |
| 507 | ``(args, kwargs)`` where *args* is a tuple of positional arguments |
| 508 | and *kwargs* a dictionary of named arguments for constructing the |
| 509 | object. Those will be passed to the :meth:`__new__` method upon |
| 510 | unpickling. |
| 511 | |
| 512 | You should implement this method if the :meth:`__new__` method of your |
| 513 | class requires keyword-only arguments. Otherwise, it is recommended for |
| 514 | compatibility to implement :meth:`__getnewargs__`. |
| 515 | |
| 516 | |
Georg Brandl | c814826 | 2010-10-17 11:13:37 +0000 | [diff] [blame] | 517 | .. method:: object.__getnewargs__() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 518 | |
Antoine Pitrou | c9dc4a2 | 2013-11-23 18:59:12 +0100 | [diff] [blame] | 519 | This method serve a similar purpose as :meth:`__getnewargs_ex__` but |
| 520 | for protocols 2 and newer. It must return a tuple of arguments `args` |
| 521 | which will be passed to the :meth:`__new__` method upon unpickling. |
| 522 | |
| 523 | In protocols 4 and newer, :meth:`__getnewargs__` will not be called if |
| 524 | :meth:`__getnewargs_ex__` is defined. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 525 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 526 | |
Georg Brandl | c814826 | 2010-10-17 11:13:37 +0000 | [diff] [blame] | 527 | .. method:: object.__getstate__() |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 528 | |
Georg Brandl | c814826 | 2010-10-17 11:13:37 +0000 | [diff] [blame] | 529 | Classes can further influence how their instances are pickled; if the class |
| 530 | defines the method :meth:`__getstate__`, it is called and the returned object |
| 531 | is pickled as the contents for the instance, instead of the contents of the |
| 532 | instance's dictionary. If the :meth:`__getstate__` method is absent, the |
Serhiy Storchaka | 5bbbc94 | 2013-10-14 10:43:46 +0300 | [diff] [blame] | 533 | instance's :attr:`~object.__dict__` is pickled as usual. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 534 | |
Georg Brandl | c814826 | 2010-10-17 11:13:37 +0000 | [diff] [blame] | 535 | |
| 536 | .. method:: object.__setstate__(state) |
| 537 | |
| 538 | Upon unpickling, if the class defines :meth:`__setstate__`, it is called with |
| 539 | the unpickled state. In that case, there is no requirement for the state |
| 540 | object to be a dictionary. Otherwise, the pickled state must be a dictionary |
| 541 | and its items are assigned to the new instance's dictionary. |
| 542 | |
| 543 | .. note:: |
| 544 | |
| 545 | If :meth:`__getstate__` returns a false value, the :meth:`__setstate__` |
| 546 | method will not be called upon unpickling. |
| 547 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 548 | |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 549 | Refer to the section :ref:`pickle-state` for more information about how to use |
| 550 | the methods :meth:`__getstate__` and :meth:`__setstate__`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 551 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 552 | .. note:: |
Georg Brandl | e720c0a | 2009-04-27 16:20:50 +0000 | [diff] [blame] | 553 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 554 | At unpickling time, some methods like :meth:`__getattr__`, |
| 555 | :meth:`__getattribute__`, or :meth:`__setattr__` may be called upon the |
Antoine Pitrou | c9dc4a2 | 2013-11-23 18:59:12 +0100 | [diff] [blame] | 556 | instance. In case those methods rely on some internal invariant being |
| 557 | true, the type should implement :meth:`__getnewargs__` or |
| 558 | :meth:`__getnewargs_ex__` to establish such an invariant; otherwise, |
| 559 | neither :meth:`__new__` nor :meth:`__init__` will be called. |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 560 | |
Georg Brandl | c814826 | 2010-10-17 11:13:37 +0000 | [diff] [blame] | 561 | .. index:: pair: copy; protocol |
Christian Heimes | 05e8be1 | 2008-02-23 18:30:17 +0000 | [diff] [blame] | 562 | |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 563 | As we shall see, pickle does not use directly the methods described above. In |
| 564 | fact, these methods are part of the copy protocol which implements the |
| 565 | :meth:`__reduce__` special method. The copy protocol provides a unified |
| 566 | interface for retrieving the data necessary for pickling and copying |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 567 | objects. [#]_ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 568 | |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 569 | Although powerful, implementing :meth:`__reduce__` directly in your classes is |
| 570 | error prone. For this reason, class designers should use the high-level |
Antoine Pitrou | c9dc4a2 | 2013-11-23 18:59:12 +0100 | [diff] [blame] | 571 | interface (i.e., :meth:`__getnewargs_ex__`, :meth:`__getstate__` and |
Georg Brandl | c814826 | 2010-10-17 11:13:37 +0000 | [diff] [blame] | 572 | :meth:`__setstate__`) whenever possible. We will show, however, cases where |
| 573 | using :meth:`__reduce__` is the only option or leads to more efficient pickling |
| 574 | or both. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 575 | |
Georg Brandl | c814826 | 2010-10-17 11:13:37 +0000 | [diff] [blame] | 576 | .. method:: object.__reduce__() |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 577 | |
Georg Brandl | c814826 | 2010-10-17 11:13:37 +0000 | [diff] [blame] | 578 | The interface is currently defined as follows. The :meth:`__reduce__` method |
| 579 | takes no argument and shall return either a string or preferably a tuple (the |
| 580 | returned object is often referred to as the "reduce value"). |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 581 | |
Georg Brandl | c814826 | 2010-10-17 11:13:37 +0000 | [diff] [blame] | 582 | If a string is returned, the string should be interpreted as the name of a |
| 583 | global variable. It should be the object's local name relative to its |
| 584 | module; the pickle module searches the module namespace to determine the |
| 585 | object's module. This behaviour is typically useful for singletons. |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 586 | |
Georg Brandl | c814826 | 2010-10-17 11:13:37 +0000 | [diff] [blame] | 587 | When a tuple is returned, it must be between two and five items long. |
| 588 | Optional items can either be omitted, or ``None`` can be provided as their |
| 589 | value. The semantics of each item are in order: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 590 | |
Georg Brandl | c814826 | 2010-10-17 11:13:37 +0000 | [diff] [blame] | 591 | .. XXX Mention __newobj__ special-case? |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 592 | |
Georg Brandl | c814826 | 2010-10-17 11:13:37 +0000 | [diff] [blame] | 593 | * A callable object that will be called to create the initial version of the |
| 594 | object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 595 | |
Georg Brandl | c814826 | 2010-10-17 11:13:37 +0000 | [diff] [blame] | 596 | * A tuple of arguments for the callable object. An empty tuple must be given |
| 597 | if the callable does not accept any argument. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 598 | |
Georg Brandl | c814826 | 2010-10-17 11:13:37 +0000 | [diff] [blame] | 599 | * Optionally, the object's state, which will be passed to the object's |
| 600 | :meth:`__setstate__` method as previously described. If the object has no |
| 601 | such method then, the value must be a dictionary and it will be added to |
Serhiy Storchaka | 5bbbc94 | 2013-10-14 10:43:46 +0300 | [diff] [blame] | 602 | the object's :attr:`~object.__dict__` attribute. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 603 | |
Georg Brandl | c814826 | 2010-10-17 11:13:37 +0000 | [diff] [blame] | 604 | * Optionally, an iterator (and not a sequence) yielding successive items. |
| 605 | These items will be appended to the object either using |
| 606 | ``obj.append(item)`` or, in batch, using ``obj.extend(list_of_items)``. |
| 607 | This is primarily used for list subclasses, but may be used by other |
| 608 | classes as long as they have :meth:`append` and :meth:`extend` methods with |
| 609 | the appropriate signature. (Whether :meth:`append` or :meth:`extend` is |
| 610 | used depends on which pickle protocol version is used as well as the number |
| 611 | of items to append, so both must be supported.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 612 | |
Georg Brandl | c814826 | 2010-10-17 11:13:37 +0000 | [diff] [blame] | 613 | * Optionally, an iterator (not a sequence) yielding successive key-value |
| 614 | pairs. These items will be stored to the object using ``obj[key] = |
| 615 | value``. This is primarily used for dictionary subclasses, but may be used |
| 616 | by other classes as long as they implement :meth:`__setitem__`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 617 | |
Georg Brandl | c814826 | 2010-10-17 11:13:37 +0000 | [diff] [blame] | 618 | |
| 619 | .. method:: object.__reduce_ex__(protocol) |
| 620 | |
| 621 | Alternatively, a :meth:`__reduce_ex__` method may be defined. The only |
| 622 | difference is this method should take a single integer argument, the protocol |
| 623 | version. When defined, pickle will prefer it over the :meth:`__reduce__` |
| 624 | method. In addition, :meth:`__reduce__` automatically becomes a synonym for |
| 625 | the extended version. The main use for this method is to provide |
| 626 | backwards-compatible reduce values for older Python releases. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 627 | |
Serhiy Storchaka | 5bbbc94 | 2013-10-14 10:43:46 +0300 | [diff] [blame] | 628 | .. currentmodule:: pickle |
| 629 | |
Alexandre Vassalotti | 758bca6 | 2008-10-18 19:25:07 +0000 | [diff] [blame] | 630 | .. _pickle-persistent: |
| 631 | |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 632 | Persistence of External Objects |
| 633 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 634 | |
Christian Heimes | 05e8be1 | 2008-02-23 18:30:17 +0000 | [diff] [blame] | 635 | .. index:: |
| 636 | single: persistent_id (pickle protocol) |
| 637 | single: persistent_load (pickle protocol) |
| 638 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 639 | For the benefit of object persistence, the :mod:`pickle` module supports the |
| 640 | notion of a reference to an object outside the pickled data stream. Such |
Alexandre Vassalotti | 5f3b63a | 2008-10-18 20:47:58 +0000 | [diff] [blame] | 641 | objects are referenced by a persistent ID, which should be either a string of |
| 642 | alphanumeric characters (for protocol 0) [#]_ or just an arbitrary object (for |
| 643 | any newer protocol). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 644 | |
Alexandre Vassalotti | 5f3b63a | 2008-10-18 20:47:58 +0000 | [diff] [blame] | 645 | The resolution of such persistent IDs is not defined by the :mod:`pickle` |
| 646 | module; it will delegate this resolution to the user defined methods on the |
Serhiy Storchaka | 5bbbc94 | 2013-10-14 10:43:46 +0300 | [diff] [blame] | 647 | pickler and unpickler, :meth:`~Pickler.persistent_id` and |
| 648 | :meth:`~Unpickler.persistent_load` respectively. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 649 | |
| 650 | To pickle objects that have an external persistent id, the pickler must have a |
Serhiy Storchaka | 5bbbc94 | 2013-10-14 10:43:46 +0300 | [diff] [blame] | 651 | custom :meth:`~Pickler.persistent_id` method that takes an object as an |
| 652 | argument and returns either ``None`` or the persistent id for that object. |
| 653 | When ``None`` is returned, the pickler simply pickles the object as normal. |
| 654 | When a persistent ID string is returned, the pickler will pickle that object, |
| 655 | along with a marker so that the unpickler will recognize it as a persistent ID. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 656 | |
| 657 | To unpickle external objects, the unpickler must have a custom |
Serhiy Storchaka | 5bbbc94 | 2013-10-14 10:43:46 +0300 | [diff] [blame] | 658 | :meth:`~Unpickler.persistent_load` method that takes a persistent ID object and |
| 659 | returns the referenced object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 660 | |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 661 | Here is a comprehensive example presenting how persistent ID can be used to |
| 662 | pickle external objects by reference. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 663 | |
Alexandre Vassalotti | 5f3b63a | 2008-10-18 20:47:58 +0000 | [diff] [blame] | 664 | .. literalinclude:: ../includes/dbpickle.py |
Alexandre Vassalotti | bcd1e3a | 2009-01-23 05:28:16 +0000 | [diff] [blame] | 665 | |
Antoine Pitrou | 8d3c290 | 2012-03-04 18:31:48 +0100 | [diff] [blame] | 666 | .. _pickle-dispatch: |
| 667 | |
| 668 | Dispatch Tables |
| 669 | ^^^^^^^^^^^^^^^ |
| 670 | |
| 671 | If one wants to customize pickling of some classes without disturbing |
| 672 | any other code which depends on pickling, then one can create a |
| 673 | pickler with a private dispatch table. |
| 674 | |
| 675 | The global dispatch table managed by the :mod:`copyreg` module is |
| 676 | available as :data:`copyreg.dispatch_table`. Therefore, one may |
| 677 | choose to use a modified copy of :data:`copyreg.dispatch_table` as a |
| 678 | private dispatch table. |
| 679 | |
| 680 | For example :: |
| 681 | |
| 682 | f = io.BytesIO() |
| 683 | p = pickle.Pickler(f) |
| 684 | p.dispatch_table = copyreg.dispatch_table.copy() |
| 685 | p.dispatch_table[SomeClass] = reduce_SomeClass |
| 686 | |
| 687 | creates an instance of :class:`pickle.Pickler` with a private dispatch |
| 688 | table which handles the ``SomeClass`` class specially. Alternatively, |
| 689 | the code :: |
| 690 | |
| 691 | class MyPickler(pickle.Pickler): |
| 692 | dispatch_table = copyreg.dispatch_table.copy() |
| 693 | dispatch_table[SomeClass] = reduce_SomeClass |
| 694 | f = io.BytesIO() |
| 695 | p = MyPickler(f) |
| 696 | |
| 697 | does the same, but all instances of ``MyPickler`` will by default |
| 698 | share the same dispatch table. The equivalent code using the |
| 699 | :mod:`copyreg` module is :: |
| 700 | |
| 701 | copyreg.pickle(SomeClass, reduce_SomeClass) |
| 702 | f = io.BytesIO() |
| 703 | p = pickle.Pickler(f) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 704 | |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 705 | .. _pickle-state: |
| 706 | |
| 707 | Handling Stateful Objects |
| 708 | ^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 709 | |
| 710 | .. index:: |
| 711 | single: __getstate__() (copy protocol) |
| 712 | single: __setstate__() (copy protocol) |
| 713 | |
| 714 | Here's an example that shows how to modify pickling behavior for a class. |
| 715 | The :class:`TextReader` class opens a text file, and returns the line number and |
Serhiy Storchaka | 5bbbc94 | 2013-10-14 10:43:46 +0300 | [diff] [blame] | 716 | line contents each time its :meth:`!readline` method is called. If a |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 717 | :class:`TextReader` instance is pickled, all attributes *except* the file object |
| 718 | member are saved. When the instance is unpickled, the file is reopened, and |
| 719 | reading resumes from the last location. The :meth:`__setstate__` and |
| 720 | :meth:`__getstate__` methods are used to implement this behavior. :: |
| 721 | |
| 722 | class TextReader: |
| 723 | """Print and number lines in a text file.""" |
| 724 | |
| 725 | def __init__(self, filename): |
| 726 | self.filename = filename |
| 727 | self.file = open(filename) |
| 728 | self.lineno = 0 |
| 729 | |
| 730 | def readline(self): |
| 731 | self.lineno += 1 |
| 732 | line = self.file.readline() |
| 733 | if not line: |
| 734 | return None |
Alexandre Vassalotti | 9d7665d | 2009-04-03 06:13:29 +0000 | [diff] [blame] | 735 | if line.endswith('\n'): |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 736 | line = line[:-1] |
| 737 | return "%i: %s" % (self.lineno, line) |
| 738 | |
| 739 | def __getstate__(self): |
| 740 | # Copy the object's state from self.__dict__ which contains |
| 741 | # all our instance attributes. Always use the dict.copy() |
| 742 | # method to avoid modifying the original state. |
| 743 | state = self.__dict__.copy() |
| 744 | # Remove the unpicklable entries. |
| 745 | del state['file'] |
| 746 | return state |
| 747 | |
| 748 | def __setstate__(self, state): |
| 749 | # Restore instance attributes (i.e., filename and lineno). |
| 750 | self.__dict__.update(state) |
| 751 | # Restore the previously opened file's state. To do so, we need to |
| 752 | # reopen it and read from it until the line count is restored. |
| 753 | file = open(self.filename) |
| 754 | for _ in range(self.lineno): |
| 755 | file.readline() |
| 756 | # Finally, save the file. |
| 757 | self.file = file |
| 758 | |
| 759 | |
| 760 | A sample usage might be something like this:: |
| 761 | |
| 762 | >>> reader = TextReader("hello.txt") |
| 763 | >>> reader.readline() |
| 764 | '1: Hello world!' |
| 765 | >>> reader.readline() |
| 766 | '2: I am line number two.' |
| 767 | >>> new_reader = pickle.loads(pickle.dumps(reader)) |
| 768 | >>> new_reader.readline() |
| 769 | '3: Goodbye!' |
| 770 | |
| 771 | |
Alexandre Vassalotti | d039286 | 2008-10-24 01:32:40 +0000 | [diff] [blame] | 772 | .. _pickle-restrict: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 773 | |
Alexandre Vassalotti | d039286 | 2008-10-24 01:32:40 +0000 | [diff] [blame] | 774 | Restricting Globals |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 775 | ------------------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 776 | |
Christian Heimes | 05e8be1 | 2008-02-23 18:30:17 +0000 | [diff] [blame] | 777 | .. index:: |
Alexandre Vassalotti | d039286 | 2008-10-24 01:32:40 +0000 | [diff] [blame] | 778 | single: find_class() (pickle protocol) |
Christian Heimes | 05e8be1 | 2008-02-23 18:30:17 +0000 | [diff] [blame] | 779 | |
Alexandre Vassalotti | d039286 | 2008-10-24 01:32:40 +0000 | [diff] [blame] | 780 | By default, unpickling will import any class or function that it finds in the |
| 781 | pickle data. For many applications, this behaviour is unacceptable as it |
| 782 | permits the unpickler to import and invoke arbitrary code. Just consider what |
| 783 | this hand-crafted pickle data stream does when loaded:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 784 | |
Alexandre Vassalotti | d039286 | 2008-10-24 01:32:40 +0000 | [diff] [blame] | 785 | >>> import pickle |
| 786 | >>> pickle.loads(b"cos\nsystem\n(S'echo hello world'\ntR.") |
| 787 | hello world |
| 788 | 0 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 789 | |
Alexandre Vassalotti | d039286 | 2008-10-24 01:32:40 +0000 | [diff] [blame] | 790 | In this example, the unpickler imports the :func:`os.system` function and then |
| 791 | apply the string argument "echo hello world". Although this example is |
| 792 | inoffensive, it is not difficult to imagine one that could damage your system. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 793 | |
Alexandre Vassalotti | d039286 | 2008-10-24 01:32:40 +0000 | [diff] [blame] | 794 | For this reason, you may want to control what gets unpickled by customizing |
Serhiy Storchaka | 5bbbc94 | 2013-10-14 10:43:46 +0300 | [diff] [blame] | 795 | :meth:`Unpickler.find_class`. Unlike its name suggests, |
| 796 | :meth:`Unpickler.find_class` is called whenever a global (i.e., a class or |
| 797 | a function) is requested. Thus it is possible to either completely forbid |
| 798 | globals or restrict them to a safe subset. |
Alexandre Vassalotti | d039286 | 2008-10-24 01:32:40 +0000 | [diff] [blame] | 799 | |
| 800 | Here is an example of an unpickler allowing only few safe classes from the |
| 801 | :mod:`builtins` module to be loaded:: |
| 802 | |
| 803 | import builtins |
| 804 | import io |
| 805 | import pickle |
| 806 | |
| 807 | safe_builtins = { |
| 808 | 'range', |
| 809 | 'complex', |
| 810 | 'set', |
| 811 | 'frozenset', |
| 812 | 'slice', |
| 813 | } |
| 814 | |
| 815 | class RestrictedUnpickler(pickle.Unpickler): |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 816 | |
Alexandre Vassalotti | d039286 | 2008-10-24 01:32:40 +0000 | [diff] [blame] | 817 | def find_class(self, module, name): |
| 818 | # Only allow safe classes from builtins. |
| 819 | if module == "builtins" and name in safe_builtins: |
| 820 | return getattr(builtins, name) |
| 821 | # Forbid everything else. |
| 822 | raise pickle.UnpicklingError("global '%s.%s' is forbidden" % |
| 823 | (module, name)) |
| 824 | |
| 825 | def restricted_loads(s): |
| 826 | """Helper function analogous to pickle.loads().""" |
| 827 | return RestrictedUnpickler(io.BytesIO(s)).load() |
| 828 | |
| 829 | A sample usage of our unpickler working has intended:: |
| 830 | |
| 831 | >>> restricted_loads(pickle.dumps([1, 2, range(15)])) |
| 832 | [1, 2, range(0, 15)] |
| 833 | >>> restricted_loads(b"cos\nsystem\n(S'echo hello world'\ntR.") |
| 834 | Traceback (most recent call last): |
| 835 | ... |
| 836 | pickle.UnpicklingError: global 'os.system' is forbidden |
| 837 | >>> restricted_loads(b'cbuiltins\neval\n' |
| 838 | ... b'(S\'getattr(__import__("os"), "system")' |
| 839 | ... b'("echo hello world")\'\ntR.') |
| 840 | Traceback (most recent call last): |
| 841 | ... |
| 842 | pickle.UnpicklingError: global 'builtins.eval' is forbidden |
| 843 | |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 844 | |
| 845 | .. XXX Add note about how extension codes could evade our protection |
Georg Brandl | 48310cd | 2009-01-03 21:18:54 +0000 | [diff] [blame] | 846 | mechanism (e.g. cached classes do not invokes find_class()). |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 847 | |
| 848 | As our examples shows, you have to be careful with what you allow to be |
| 849 | unpickled. Therefore if security is a concern, you may want to consider |
Alexandre Vassalotti | 9d7665d | 2009-04-03 06:13:29 +0000 | [diff] [blame] | 850 | alternatives such as the marshalling API in :mod:`xmlrpc.client` or |
| 851 | third-party solutions. |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 852 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 853 | |
Antoine Pitrou | d4d6055 | 2013-12-07 00:56:59 +0100 | [diff] [blame] | 854 | Performance |
| 855 | ----------- |
| 856 | |
| 857 | Recent versions of the pickle protocol (from protocol 2 and upwards) feature |
| 858 | efficient binary encodings for several common features and built-in types. |
| 859 | Also, the :mod:`pickle` module has a transparent optimizer written in C. |
| 860 | |
| 861 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 862 | .. _pickle-example: |
| 863 | |
Alexandre Vassalotti | 9d7665d | 2009-04-03 06:13:29 +0000 | [diff] [blame] | 864 | Examples |
| 865 | -------- |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 866 | |
Alexandre Vassalotti | 9d7665d | 2009-04-03 06:13:29 +0000 | [diff] [blame] | 867 | For the simplest code, use the :func:`dump` and :func:`load` functions. :: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 868 | |
| 869 | import pickle |
| 870 | |
Alexandre Vassalotti | bcd1e3a | 2009-01-23 05:28:16 +0000 | [diff] [blame] | 871 | # An arbitrary collection of objects supported by pickle. |
| 872 | data = { |
Alexandre Vassalotti | 9d7665d | 2009-04-03 06:13:29 +0000 | [diff] [blame] | 873 | 'a': [1, 2.0, 3, 4+6j], |
| 874 | 'b': ("character string", b"byte string"), |
| 875 | 'c': set([None, True, False]) |
Alexandre Vassalotti | bcd1e3a | 2009-01-23 05:28:16 +0000 | [diff] [blame] | 876 | } |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 877 | |
Alexandre Vassalotti | bcd1e3a | 2009-01-23 05:28:16 +0000 | [diff] [blame] | 878 | with open('data.pickle', 'wb') as f: |
| 879 | # Pickle the 'data' dictionary using the highest protocol available. |
| 880 | pickle.dump(data, f, pickle.HIGHEST_PROTOCOL) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 881 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 882 | |
Alexandre Vassalotti | bcd1e3a | 2009-01-23 05:28:16 +0000 | [diff] [blame] | 883 | The following example reads the resulting pickled data. :: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 884 | |
Alexandre Vassalotti | bcd1e3a | 2009-01-23 05:28:16 +0000 | [diff] [blame] | 885 | import pickle |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 886 | |
Alexandre Vassalotti | bcd1e3a | 2009-01-23 05:28:16 +0000 | [diff] [blame] | 887 | with open('data.pickle', 'rb') as f: |
| 888 | # The protocol version used is detected automatically, so we do not |
| 889 | # have to specify it. |
| 890 | data = pickle.load(f) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 891 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 892 | |
Alexandre Vassalotti | 9d7665d | 2009-04-03 06:13:29 +0000 | [diff] [blame] | 893 | .. XXX: Add examples showing how to optimize pickles for size (like using |
| 894 | .. pickletools.optimize() or the gzip module). |
| 895 | |
| 896 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 897 | .. seealso:: |
| 898 | |
Alexandre Vassalotti | f7fa63d | 2008-05-11 08:55:36 +0000 | [diff] [blame] | 899 | Module :mod:`copyreg` |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 900 | Pickle interface constructor registration for extension types. |
| 901 | |
Alexandre Vassalotti | 9d7665d | 2009-04-03 06:13:29 +0000 | [diff] [blame] | 902 | Module :mod:`pickletools` |
| 903 | Tools for working with and analyzing pickled data. |
| 904 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 905 | Module :mod:`shelve` |
| 906 | Indexed databases of objects; uses :mod:`pickle`. |
| 907 | |
| 908 | Module :mod:`copy` |
| 909 | Shallow and deep object copying. |
| 910 | |
| 911 | Module :mod:`marshal` |
| 912 | High-performance serialization of built-in types. |
| 913 | |
| 914 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 915 | .. rubric:: Footnotes |
| 916 | |
| 917 | .. [#] Don't confuse this with the :mod:`marshal` module |
| 918 | |
Ethan Furman | 2498d9e | 2013-10-18 00:45:40 -0700 | [diff] [blame] | 919 | .. [#] This is why :keyword:`lambda` functions cannot be pickled: all |
| 920 | :keyword:`lambda` functions share the same name: ``<lambda>``. |
| 921 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 922 | .. [#] The exception raised will likely be an :exc:`ImportError` or an |
| 923 | :exc:`AttributeError` but it could be something else. |
| 924 | |
Alexandre Vassalotti | 73b90a8 | 2008-10-29 23:32:33 +0000 | [diff] [blame] | 925 | .. [#] The :mod:`copy` module uses this protocol for shallow and deep copying |
| 926 | operations. |
Alexandre Vassalotti | 5f3b63a | 2008-10-18 20:47:58 +0000 | [diff] [blame] | 927 | |
Alexandre Vassalotti | d039286 | 2008-10-24 01:32:40 +0000 | [diff] [blame] | 928 | .. [#] The limitation on alphanumeric characters is due to the fact |
| 929 | the persistent IDs, in protocol 0, are delimited by the newline |
| 930 | character. Therefore if any kind of newline characters occurs in |
Alexandre Vassalotti | 5f3b63a | 2008-10-18 20:47:58 +0000 | [diff] [blame] | 931 | persistent IDs, the resulting pickle will become unreadable. |