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