Lines Matching refs:pickle
1 :mod:`pickle` --- Python object serialization
4 .. module:: pickle
10 **Source code:** :source:`Lib/pickle.py`
22 The :mod:`pickle` module implements binary protocols for serializing and
33 The ``pickle`` module **is not secure**. Only unpickle data you trust.
35 It is possible to construct malicious pickle data which will **execute
53 general :mod:`pickle` should always be the preferred way to serialize Python
57 The :mod:`pickle` module differs from :mod:`marshal` in several significant ways:
59 * The :mod:`pickle` module keeps track of the objects it has already serialized,
68 serialized. :mod:`pickle` stores such objects only once, and ensures that all
73 instances. :mod:`pickle` can save and restore class instances transparently,
81 The :mod:`pickle` serialization format is guaranteed to be backwards compatible
82 across Python releases provided a compatible pickle protocol is chosen and
92 There are fundamental differences between the pickle protocols and
96 most of the time it is then encoded to ``utf-8``), while pickle is
99 * JSON is human-readable, while pickle is not;
102 while pickle is Python-specific;
105 types, and no custom classes; pickle can represent an extremely large
108 implementing :ref:`specific object APIs <pickle-inst>`);
110 * Unlike pickle, deserializing untrusted JSON does not in itself create an
126 The data format used by :mod:`pickle` is Python-specific. This has the
131 By default, the :mod:`pickle` data format uses a relatively compact binary
136 generated by :mod:`pickle`. :mod:`pickletools` source code has extensive
137 comments about opcodes used by pickle protocols.
141 to read the pickle produced.
169 :mod:`pickle` reads and writes file objects, it does not handle the issue of
171 access to persistent objects. The :mod:`pickle` module can transform a complex
176 module provides a simple interface to pickle and unpickle objects on
188 The :mod:`pickle` module provides the following constants:
193 An integer, the highest :ref:`protocol version <pickle-protocols>`
200 An integer, the default :ref:`protocol version <pickle-protocols>` used
213 The :mod:`pickle` module provides the following functions to make the pickling
245 The protocol version of the pickle is detected automatically, so no
260 The protocol version of the pickle is detected automatically, so no
271 The :mod:`pickle` module defines three exceptions:
283 Refer to :ref:`pickle-picklable` to learn what kinds of objects can be
296 The :mod:`pickle` module exports three classes, :class:`Pickler`,
301 This takes a binary file for writing a pickle data stream.
313 If *fix_imports* is true and *protocol* is less than 3, pickle will try to
315 that the pickle data stream is readable with Python 2.
318 serialized into *file* as part of the pickle stream.
322 (such as None), the given buffer is :ref:`out-of-band <pickle-oob>`;
323 otherwise the buffer is serialized in-band, i.e. inside the pickle stream.
346 See :ref:`pickle-persistent` for details and examples of uses.
352 :func:`copyreg.pickle`. It is a mapping whose keys are classes
367 See :ref:`pickle-dispatch` for usage examples.
377 :attr:`dispatch_table`-registered reducers to pickle ``obj``.
396 This takes a binary file for reading a pickle data stream.
398 The protocol version of the pickle is detected automatically, so no
409 to control compatibility support for pickle stream generated by Python 2.
410 If *fix_imports* is true, pickle will try to map the old Python 2 names
412 pickle how to decode 8-bit string instances pickled by Python 2;
420 deserialization must be contained in the pickle stream. This means
425 objects that is consumed each time the pickle stream references
426 an :ref:`out-of-band <pickle-oob>` buffer view. Such buffers have been
447 See :ref:`pickle-persistent` for details and examples of uses.
458 :ref:`pickle-restrict` for details.
460 .. audit-event:: pickle.find_class module,name pickle.Unpickler.find_class
472 :class:`PickleBuffer` objects can only be serialized using pickle
474 :ref:`out-of-band serialization <pickle-oob>`.
513 calling :meth:`__getstate__` is picklable (see section :ref:`pickle-inst` for
516 Attempts to pickle unpicklable objects will raise the :exc:`PicklingError`
518 been written to the underlying file. Trying to pickle a highly recursive data
538 picklestring = pickle.dumps(Foo)
563 default, pickle will retrieve the class and the attributes of an instance via
634 Refer to the section :ref:`pickle-state` for more information about how to use
648 As we shall see, pickle does not use directly the methods described above. In
669 module; the pickle module searches the module namespace to determine the
695 used depends on which pickle protocol version is used as well as the number
717 version. When defined, pickle will prefer it over the :meth:`__reduce__`
722 .. currentmodule:: pickle
730 single: persistent_id (pickle protocol)
731 single: persistent_load (pickle protocol)
733 For the benefit of object persistence, the :mod:`pickle` module supports the
739 The resolution of such persistent IDs is not defined by the :mod:`pickle`
744 To pickle objects that have an external persistent ID, the pickler must have a
748 When a persistent ID string is returned, the pickler will pickle that object,
756 pickle external objects by reference.
777 p = pickle.Pickler(f)
781 creates an instance of :class:`pickle.Pickler` with a private dispatch
785 class MyPickler(pickle.Pickler):
795 copyreg.pickle(SomeClass, reduce_SomeClass)
797 p = pickle.Pickler(f)
861 >>> new_reader = pickle.loads(pickle.dumps(reader))
897 import pickle
902 class MyPickler(pickle.Pickler):
918 unpickled_class = pickle.loads(f.getvalue())
932 In some contexts, the :mod:`pickle` module is used to transfer massive amounts
935 operation of the :mod:`pickle` module, as it transforms a graph-like structure
937 data to and from the pickle stream.
942 provided by pickle protocol 5 and higher.
954 with normal usage of the :mod:`pickle` module. However, consumers can also
955 opt-in to tell :mod:`pickle` that they will handle those buffers by
968 see their data copied into the pickle stream, only a cheap marker will be
996 # PickleBuffer is forbidden with pickle protocols <= 4.
1015 On the consumer side, we can pickle those objects the usual way, which
1019 data = pickle.dumps(b, protocol=5)
1020 new_b = pickle.loads(data)
1029 data = pickle.dumps(b, protocol=5, buffer_callback=buffers.append)
1030 new_b = pickle.loads(data, buffers=buffers)
1050 single: find_class() (pickle protocol)
1053 pickle data. For many applications, this behaviour is unacceptable as it
1055 this hand-crafted pickle data stream does when loaded::
1057 >>> import pickle
1058 >>> pickle.loads(b"cos\nsystem\n(S'echo hello world'\ntR.")
1077 import pickle
1087 class RestrictedUnpickler(pickle.Unpickler):
1094 raise pickle.UnpicklingError("global '%s.%s' is forbidden" %
1098 """Helper function analogous to pickle.loads()."""
1103 >>> restricted_loads(pickle.dumps([1, 2, range(15)]))
1108 pickle.UnpicklingError: global 'os.system' is forbidden
1114 pickle.UnpicklingError: global 'builtins.eval' is forbidden
1129 Recent versions of the pickle protocol (from protocol 2 and upwards) feature
1131 Also, the :mod:`pickle` module has a transparent optimizer written in C.
1141 import pickle
1143 # An arbitrary collection of objects supported by pickle.
1150 with open('data.pickle', 'wb') as f:
1152 pickle.dump(data, f, pickle.HIGHEST_PROTOCOL)
1157 import pickle
1159 with open('data.pickle', 'rb') as f:
1162 data = pickle.load(f)
1178 Indexed databases of objects; uses :mod:`pickle`.
1203 persistent IDs, the resulting pickle will become unreadable.