Issue #6137: The pickle module now translates module names when loading

or dumping pickles with a 2.x-compatible protocol, in order to make data
sharing and migration easier. This behaviour can be disabled using the
new `fix_imports` optional argument.

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()