Mention pickle protocol 4, and some tweaks.

diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst
index cfd5f791ec7c232606b5f7a219e7e0fde2d43a20..1f35b606c1990f86b1e377ba10f5f06b17538551 100644 (file)
--- a/Doc/library/pickle.rst
+++ b/Doc/library/pickle.rst
@@ -94,6 +94,9 @@ There are fundamental differences between the pickle protocols and
    The :mod:`json` module: a standard library module allowing JSON
    serialization and deserialization.
 
+
+.. _pickle-protocols:
+
 Data stream format
 ------------------
 
@@ -125,10 +128,15 @@ There are currently 4 different protocols which can be used for pickling.
   efficient pickling of :term:`new-style class`\es.  Refer to :pep:`307` for
   information about improvements brought by protocol 2.
 
-* Protocol version 3 was added in Python 3.  It has explicit support for
+* Protocol version 3 was added in Python 3.0.  It has explicit support for
   :class:`bytes` objects and cannot be unpickled by Python 2.x.  This is
-  the default as well as the current recommended protocol; use it whenever
-  possible.
+  the default protocol, and the recommended protocol when compatibility with
+  other Python 3 versions is required.
+
+* Protocol version 4 was added in Python 3.4.  It adds support for very large
+  objects, pickling more kinds of objects, and some data format
+  optimizations.  Refer to :pep:`3154` for information about improvements
+  brought by protocol 4.
 
 .. note::
    Serialization is a more primitive notion than persistence; although
@@ -156,13 +164,16 @@ The :mod:`pickle` module provides the following constants:
 
 .. data:: HIGHEST_PROTOCOL
 
-   The highest protocol version available.  This value can be passed as a
-   *protocol* value.
+   An integer, the highest :ref:`protocol version <pickle-protocols>`
+   available.  This value can be passed as a *protocol* value to functions
+   :func:`dump` and :func:`dumps` as well as the :class:`Pickler`
+   constructor.
 
 .. data:: DEFAULT_PROTOCOL
 
-   The default protocol used for pickling.  May be less than HIGHEST_PROTOCOL.
-   Currently the default protocol is 3, a new protocol designed for Python 3.0.
+   An integer, the default :ref:`protocol version <pickle-protocols>` used
+   for pickling.  May be less than :data:`HIGHEST_PROTOCOL`.  Currently the
+   default protocol is 3, a new protocol designed for Python 3.0.
 
 
 The :mod:`pickle` module provides the following functions to make the pickling