From 9bcb1127f1d1305cc8071f8b4460af3b34f3ec74 Mon Sep 17 00:00:00 2001 From: Antoine Pitrou Date: Sat, 7 Dec 2013 01:05:57 +0100 Subject: [PATCH] Mention pickle protocol 4, and some tweaks. --- Doc/library/pickle.rst | 25 ++++++++++++++++++------- 1 file changed, 18 insertions(+), 7 deletions(-) diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst index cfd5f791ec..1f35b606c1 100644 --- 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 ` + 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 ` 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 -- 2.40.0