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 :mod:`pickle` module is not secure against erroneous or maliciously
45 general :mod:`pickle` should always be the preferred way to serialize Python
49 The :mod:`pickle` module differs from :mod:`marshal` in several significant ways:
51 * The :mod:`pickle` module keeps track of the objects it has already serialized,
60 serialized. :mod:`pickle` stores such objects only once, and ensures that all
65 instances. :mod:`pickle` can save and restore class instances transparently,
73 The :mod:`pickle` serialization format is guaranteed to be backwards compatible
74 across Python releases provided a compatible pickle protocol is chosen and
81 There are fundamental differences between the pickle protocols and
85 most of the time it is then encoded to ``utf-8``), while pickle is
88 * JSON is human-readable, while pickle is not;
91 while pickle is Python-specific;
94 types, and no custom classes; pickle can represent an extremely large
97 implementing :ref:`specific object APIs <pickle-inst>`).
112 The data format used by :mod:`pickle` is Python-specific. This has the
117 By default, the :mod:`pickle` data format uses a relatively compact binary
122 generated by :mod:`pickle`. :mod:`pickletools` source code has extensive
123 comments about opcodes used by pickle protocols.
127 to read the pickle produced.
151 :mod:`pickle` reads and writes file objects, it does not handle the issue of
153 access to persistent objects. The :mod:`pickle` module can transform a complex
158 module provides a simple interface to pickle and unpickle objects on
170 The :mod:`pickle` module provides the following constants:
175 An integer, the highest :ref:`protocol version <pickle-protocols>`
182 An integer, the default :ref:`protocol version <pickle-protocols>` used
187 The :mod:`pickle` module provides the following functions to make the pickling
205 If *fix_imports* is true and *protocol* is less than 3, pickle will try to
207 that the pickle data stream is readable with Python 2.
223 The protocol version of the pickle is detected automatically, so no
234 which are used to control compatibility support for pickle stream generated
235 by Python 2. If *fix_imports* is true, pickle will try to map the old
237 *errors* tell pickle how to decode 8-bit string instances pickled by Python
249 The protocol version of the pickle is detected automatically, so no
254 which are used to control compatibility support for pickle stream generated
255 by Python 2. If *fix_imports* is true, pickle will try to map the old
257 *errors* tell pickle how to decode 8-bit string instances pickled by Python
265 The :mod:`pickle` module defines three exceptions:
277 Refer to :ref:`pickle-picklable` to learn what kinds of objects can be
290 The :mod:`pickle` module exports two classes, :class:`Pickler` and
295 This takes a binary file for writing a pickle data stream.
307 If *fix_imports* is true and *protocol* is less than 3, pickle will try to
309 that the pickle data stream is readable with Python 2.
326 See :ref:`pickle-persistent` for details and examples of uses.
332 :func:`copyreg.pickle`. It is a mapping whose keys are classes
347 See :ref:`pickle-dispatch` for usage examples.
364 This takes a binary file for reading a pickle data stream.
366 The protocol version of the pickle is detected automatically, so no
376 which are used to control compatibility support for pickle stream generated
377 by Python 2. If *fix_imports* is true, pickle will try to map the old
379 *errors* tell pickle how to decode 8-bit string instances pickled by Python
397 See :ref:`pickle-persistent` for details and examples of uses.
408 :ref:`pickle-restrict` for details.
434 calling :meth:`__getstate__` is picklable (see section :ref:`pickle-inst` for
437 Attempts to pickle unpicklable objects will raise the :exc:`PicklingError`
439 been written to the underlying file. Trying to pickle a highly recursive data
459 picklestring = pickle.dumps(Foo)
484 default, pickle will retrieve the class and the attributes of an instance via
555 Refer to the section :ref:`pickle-state` for more information about how to use
569 As we shall see, pickle does not use directly the methods described above. In
590 module; the pickle module searches the module namespace to determine the
616 used depends on which pickle protocol version is used as well as the number
629 version. When defined, pickle will prefer it over the :meth:`__reduce__`
634 .. currentmodule:: pickle
642 single: persistent_id (pickle protocol)
643 single: persistent_load (pickle protocol)
645 For the benefit of object persistence, the :mod:`pickle` module supports the
651 The resolution of such persistent IDs is not defined by the :mod:`pickle`
656 To pickle objects that have an external persistent id, the pickler must have a
660 When a persistent ID string is returned, the pickler will pickle that object,
668 pickle external objects by reference.
689 p = pickle.Pickler(f)
693 creates an instance of :class:`pickle.Pickler` with a private dispatch
697 class MyPickler(pickle.Pickler):
707 copyreg.pickle(SomeClass, reduce_SomeClass)
709 p = pickle.Pickler(f)
773 >>> new_reader = pickle.loads(pickle.dumps(reader))
784 single: find_class() (pickle protocol)
787 pickle data. For many applications, this behaviour is unacceptable as it
789 this hand-crafted pickle data stream does when loaded::
791 >>> import pickle
792 >>> pickle.loads(b"cos\nsystem\n(S'echo hello world'\ntR.")
811 import pickle
821 class RestrictedUnpickler(pickle.Unpickler):
828 raise pickle.UnpicklingError("global '%s.%s' is forbidden" %
832 """Helper function analogous to pickle.loads()."""
837 >>> restricted_loads(pickle.dumps([1, 2, range(15)]))
842 pickle.UnpicklingError: global 'os.system' is forbidden
848 pickle.UnpicklingError: global 'builtins.eval' is forbidden
863 Recent versions of the pickle protocol (from protocol 2 and upwards) feature
865 Also, the :mod:`pickle` module has a transparent optimizer written in C.
875 import pickle
877 # An arbitrary collection of objects supported by pickle.
884 with open('data.pickle', 'wb') as f:
886 pickle.dump(data, f, pickle.HIGHEST_PROTOCOL)
891 import pickle
893 with open('data.pickle', 'rb') as f:
896 data = pickle.load(f)
912 Indexed databases of objects; uses :mod:`pickle`.
937 persistent IDs, the resulting pickle will become unreadable.