[Python-checkins] cpython (3.2): Some nits in the pickle docs.

[antoine.pitrou]

http://hg.python.org/cpython/rev/1b5429e835e0
changeset:   76860:1b5429e835e0
branch:      3.2
parent:      76858:b058f22b5723
user:        Antoine Pitrou <solipsis at pitrou.net>
date:        Thu May 10 15:38:30 2012 +0200
summary:
  Some nits in the pickle docs.

files:
  Doc/library/pickle.rst |  44 +++++++++++++++--------------
  1 files changed, 23 insertions(+), 21 deletions(-)


diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst
--- a/Doc/library/pickle.rst
+++ b/Doc/library/pickle.rst
@@ -85,45 +85,48 @@
 ------------------
 
 .. 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 compact binary representation.
+By default, the :mod:`pickle` data format uses a relatively compact binary
+representation.  If you need optimal size characteristics, you can efficiently
+:doc:`compress <archiving>` pickled data.
+
 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 @@
 .. 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

-- 
Repository URL: http://hg.python.org/cpython