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