Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

Some nits in the pickle docs.

This commit is contained in:
Antoine Pitrou 2012-05-10 15:38:47 +02:00
parent b2eeced5ea a9494f6c53
commit fda08b0860
1 changed files with 23 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

44
Doc/library/pickle.rst
View File

@ -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 <archiving>` 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