diff options
Diffstat (limited to 'Doc/library/pickle.rst')
| -rw-r--r-- | Doc/library/pickle.rst | 51 |
1 files changed, 36 insertions, 15 deletions
diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst index 1c70196..21e4001 100644 --- a/Doc/library/pickle.rst +++ b/Doc/library/pickle.rst @@ -141,7 +141,7 @@ an unpickler, then you call the unpickler's :meth:`load` method. The The :mod:`pickle` module provides the following functions to make the pickling process more convenient: -.. function:: dump(obj, file[, protocol]) +.. function:: dump(obj, file[, protocol, \*, fix_imports=True]) Write a pickled representation of *obj* to the open file object *file*. This is equivalent to ``Pickler(file, protocol).dump(obj)``. @@ -158,7 +158,11 @@ process more convenient: argument. It can thus be a file object opened for binary writing, a io.BytesIO instance, or any other custom object that meets this interface. -.. function:: dumps(obj[, protocol]) + If *fix_imports* is True and *protocol* is less than 3, pickle will try to + map the new Python 3.x names to the old module names used in Python 2.x, + so that the pickle data stream is readable with Python 2.x. + +.. function:: dumps(obj[, protocol, \*, fix_imports=True]) Return the pickled representation of the object as a :class:`bytes` object, instead of writing it to a file. @@ -171,7 +175,11 @@ process more convenient: supported. The higher the protocol used, the more recent the version of Python needed to read the pickle produced. -.. function:: load(file, [\*, encoding="ASCII", errors="strict"]) + If *fix_imports* is True and *protocol* is less than 3, pickle will try to + map the new Python 3.x names to the old module names used in Python 2.x, + so that the pickle data stream is readable with Python 2.x. + +.. function:: load(file, [\*, fix_imports=True, encoding="ASCII", errors="strict"]) Read a pickled object representation from the open file object *file* and return the reconstituted object hierarchy specified therein. This is @@ -187,11 +195,14 @@ process more convenient: for reading, a BytesIO object, or any other custom object that meets this interface. - Optional keyword arguments are encoding and errors, which are used to decode - 8-bit string instances pickled by Python 2.x. These default to 'ASCII' and - 'strict', respectively. + Optional keyword arguments are *fix_imports*, *encoding* and *errors*, + which are used to control compatiblity support for pickle stream generated + by Python 2.x. If *fix_imports* is True, pickle will try to map the old + Python 2.x names to the new names used in Python 3.x. The *encoding* and + *errors* tell pickle how to decode 8-bit string instances pickled by Python + 2.x; these default to 'ASCII' and 'strict', respectively. -.. function:: loads(bytes_object, [\*, encoding="ASCII", errors="strict"]) +.. function:: loads(bytes_object, [\*, fix_imports=True, encoding="ASCII", errors="strict"]) Read a pickled object hierarchy from a :class:`bytes` object and return the reconstituted object hierarchy specified therein @@ -200,9 +211,12 @@ process more convenient: argument is needed. Bytes past the pickled object's representation are ignored. - Optional keyword arguments are encoding and errors, which are used to decode - 8-bit string instances pickled by Python 2.x. These default to 'ASCII' and - 'strict', respectively. + Optional keyword arguments are *fix_imports*, *encoding* and *errors*, + which are used to control compatiblity support for pickle stream generated + by Python 2.x. If *fix_imports* is True, pickle will try to map the old + Python 2.x names to the new names used in Python 3.x. The *encoding* and + *errors* tell pickle how to decode 8-bit string instances pickled by Python + 2.x; these default to 'ASCII' and 'strict', respectively. The :mod:`pickle` module defines three exceptions: @@ -233,7 +247,7 @@ The :mod:`pickle` module defines three exceptions: The :mod:`pickle` module exports two classes, :class:`Pickler` and :class:`Unpickler`: -.. class:: Pickler(file[, protocol]) +.. class:: Pickler(file[, protocol, \*, fix_imports=True]) This takes a binary file for writing a pickle data stream. @@ -249,6 +263,10 @@ The :mod:`pickle` module exports two classes, :class:`Pickler` and argument. It can thus be a file object opened for binary writing, a io.BytesIO instance, or any other custom object that meets this interface. + If *fix_imports* is True and *protocol* is less than 3, pickle will try to + map the new Python 3.x names to the old module names used in Python 2.x, + so that the pickle data stream is readable with Python 2.x. + .. method:: dump(obj) Write a pickled representation of *obj* to the open file object given in @@ -277,7 +295,7 @@ The :mod:`pickle` module exports two classes, :class:`Pickler` and Use :func:`pickletools.optimize` if you need more compact pickles. -.. class:: Unpickler(file, [\*, encoding="ASCII", errors="strict"]) +.. class:: Unpickler(file, [\*, fix_imports=True, encoding="ASCII", errors="strict"]) This takes a binary file for reading a pickle data stream. @@ -290,9 +308,12 @@ The :mod:`pickle` module exports two classes, :class:`Pickler` and for reading, a BytesIO object, or any other custom object that meets this interface. - Optional keyword arguments are encoding and errors, which are used to decode - 8-bit string instances pickled by Python 2.x. These default to 'ASCII' and - 'strict', respectively. + Optional keyword arguments are *fix_imports*, *encoding* and *errors*, + which are used to control compatiblity support for pickle stream generated + by Python 2.x. If *fix_imports* is True, pickle will try to map the old + Python 2.x names to the new names used in Python 3.x. The *encoding* and + *errors* tell pickle how to decode 8-bit string instances pickled by Python + 2.x; these default to 'ASCII' and 'strict', respectively. .. method:: load() |