#2558: document pickle protocol version 3. Thanks to Guilherme Polo.
diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst
index 520c24b..a9877ff 100644
--- a/Doc/library/pickle.rst
+++ b/Doc/library/pickle.rst
@@ -110,7 +110,7 @@
:mod:`pickle`'s representation) is that for debugging or recovery purposes it is
possible for a human to read the pickled file with a standard text editor.
-There are currently 3 different protocols which can be used for pickling.
+There are currently 4 different protocols which can be used for pickling.
* Protocol version 0 is the original ASCII protocol and is backwards compatible
with earlier versions of Python.
@@ -121,11 +121,14 @@
* Protocol version 2 was introduced in Python 2.3. It provides much more
efficient pickling of :term:`new-style class`\es.
+* Protocol version 3 was added in Python 3.0. It has explicit support for
+ bytes and cannot be unpickled by Python 2.x pickle modules.
+
Refer to :pep:`307` for more information.
-If a *protocol* is not specified, protocol 0 is used. If *protocol* is specified
-as a negative value or :const:`HIGHEST_PROTOCOL`, the highest protocol version
-available will be used.
+If a *protocol* is not specified, protocol 3 is used. If *protocol* is
+specified as a negative value or :const:`HIGHEST_PROTOCOL`, the highest
+protocol version available will be used.
A binary format, which is slightly more efficient, can be chosen by specifying a
*protocol* version >= 1.
@@ -164,9 +167,9 @@
Write a pickled representation of *obj* to the open file object *file*. This is
equivalent to ``Pickler(file, protocol).dump(obj)``.
- If the *protocol* parameter is omitted, protocol 0 is used. If *protocol* is
- specified as a negative value or :const:`HIGHEST_PROTOCOL`, the highest protocol
- version will be used.
+ If the *protocol* parameter is omitted, protocol 3 is used. If *protocol* is
+ specified as a negative value or :const:`HIGHEST_PROTOCOL`, the highest
+ protocol version will be used.
*file* must have a :meth:`write` method that accepts a single string argument.
It can thus be a file object opened for writing, a :mod:`StringIO` object, or
@@ -194,9 +197,9 @@
Return the pickled representation of the object as a string, instead of writing
it to a file.
- If the *protocol* parameter is omitted, protocol 0 is used. If *protocol* is
- specified as a negative value or :const:`HIGHEST_PROTOCOL`, the highest protocol
- version will be used.
+ If the *protocol* parameter is omitted, protocol 3 is used. If *protocol*
+ is specified as a negative value or :const:`HIGHEST_PROTOCOL`, the highest
+ protocol version will be used.
.. function:: loads(string)
@@ -234,7 +237,7 @@
This takes a file-like object to which it will write a pickle data stream.
- If the *protocol* parameter is omitted, protocol 0 is used. If *protocol* is
+ If the *protocol* parameter is omitted, protocol 3 is used. If *protocol* is
specified as a negative value or :const:`HIGHEST_PROTOCOL`, the highest
protocol version will be used.
@@ -681,8 +684,8 @@
output = open('data.pkl', 'wb')
- # Pickle dictionary using protocol 0.
- pickle.dump(data1, output)
+ # Pickle dictionary using protocol 2.
+ pickle.dump(data1, output, 2)
# Pickle the list using the highest protocol available.
pickle.dump(selfref_list, output, -1)