From a9494f6c53b9b69063f0f304062a6a6bf013e47a Mon Sep 17 00:00:00 2001 From: Antoine Pitrou Date: Thu, 10 May 2012 15:38:30 +0200 Subject: [PATCH] Some nits in the pickle docs. --- Doc/library/pickle.rst | 44 ++++++++++++++++++++++-------------------- 1 file changed, 23 insertions(+), 21 deletions(-) diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst index bf0a72e8765..a1f9af23be1 100644 --- a/Doc/library/pickle.rst +++ b/Doc/library/pickle.rst @@ -85,45 +85,48 @@ Data stream format ------------------ .. index:: - single: XDR single: External Data Representation The data format used by :mod:`pickle` is Python-specific. This has the advantage that there are no restrictions imposed by external standards such as -XDR (which can't represent pointer sharing); however it means that non-Python -programs may not be able to reconstruct pickled Python objects. +JSON or XDR (which can't represent pointer sharing); however it means that +non-Python programs may not be able to reconstruct pickled Python objects. + +By default, the :mod:`pickle` data format uses a relatively compact binary +representation. If you need optimal size characteristics, you can efficiently +:doc:`compress ` pickled data. -By default, the :mod:`pickle` data format uses a compact binary representation. The module :mod:`pickletools` contains tools for analyzing data streams -generated by :mod:`pickle`. +generated by :mod:`pickle`. :mod:`pickletools` source code has extensive +comments about opcodes used by pickle protocols. There are currently 4 different protocols which can be used for pickling. -* Protocol version 0 is the original human-readable protocol and is +* Protocol version 0 is the original "human-readable" protocol and is backwards compatible with earlier versions of Python. -* Protocol version 1 is the old binary format which is also compatible with +* Protocol version 1 is an old binary format which is also compatible with earlier versions of Python. * Protocol version 2 was introduced in Python 2.3. It provides much more - efficient pickling of :term:`new-style class`\es. + 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.0. It has explicit support for - bytes and cannot be unpickled by Python 2.x pickle modules. This is - the current recommended protocol, use it whenever it is possible. - -Refer to :pep:`307` for information about improvements brought by -protocol 2. See :mod:`pickletools`'s source code for extensive -comments about opcodes used by pickle protocols. +* Protocol version 3 was added in Python 3. 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. Module Interface ---------------- -To serialize an object hierarchy, you first create a pickler, then you call the -pickler's :meth:`dump` method. To de-serialize a data stream, you first create -an unpickler, then you call the unpickler's :meth:`load` method. The -:mod:`pickle` module provides the following constant: +To serialize an object hierarchy, you simply call the :func:`dumps` function. +Similarly, to de-serialize a data stream, you call the :func:`loads` function. +However, if you want more control over serialization and de-serialization, +you can create a :class:`Pickler` or an :class:`Unpickler` object, respectively. + +The :mod:`pickle` module provides the following constants: .. data:: HIGHEST_PROTOCOL @@ -134,8 +137,7 @@ an unpickler, then you call the unpickler's :meth:`load` method. The .. data:: DEFAULT_PROTOCOL The default protocol used for pickling. May be less than HIGHEST_PROTOCOL. - Currently the default protocol is 3; a backward-incompatible protocol - designed for Python 3.0. + 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