traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

#2558: document pickle protocol version 3. Thanks to Guilherme Polo.

This commit is contained in:
Georg Brandl 2008-04-06 08:39:37 +00:00
parent 790465fd90
commit 42f2ae0f69
1 changed files with 16 additions and 13 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
Doc/library/pickle.rst
View File

@ -110,7 +110,7 @@ advantage of using printable ASCII (and of some other characteristics of
:mod:`pickle`'s representation) is that for debugging or recovery purposes it is :mod:`pickle`'s representation) is that for debugging or recovery purposes it is
possible for a human to read the pickled file with a standard text editor. possible for a human to read the pickled file with a standard text editor.
There are currently 3 different protocols which can be used for pickling. There are currently 4 different protocols which can be used for pickling.
* Protocol version 0 is the original ASCII protocol and is backwards compatible * Protocol version 0 is the original ASCII protocol and is backwards compatible
with earlier versions of Python. with earlier versions of Python.
@ -121,11 +121,14 @@ There are currently 3 different protocols which can be used for pickling.
* Protocol version 2 was introduced in Python 2.3. It provides much more * 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.
* 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.
Refer to :pep:`307` for more information. Refer to :pep:`307` for more information.
If a *protocol* is not specified, protocol 0 is used. If *protocol* is specified If a *protocol* is not specified, protocol 3 is used. If *protocol* is
as a negative value or :const:`HIGHEST_PROTOCOL`, the highest protocol version specified as a negative value or :const:`HIGHEST_PROTOCOL`, the highest
available will be used. protocol version available will be used.
A binary format, which is slightly more efficient, can be chosen by specifying a A binary format, which is slightly more efficient, can be chosen by specifying a
*protocol* version >= 1. *protocol* version >= 1.
@ -164,9 +167,9 @@ process more convenient:
Write a pickled representation of *obj* to the open file object *file*. This is Write a pickled representation of *obj* to the open file object *file*. This is
equivalent to ``Pickler(file, protocol).dump(obj)``. equivalent to ``Pickler(file, protocol).dump(obj)``.
If the *protocol* parameter is omitted, protocol 0 is used. If *protocol* is If the *protocol* parameter is omitted, protocol 3 is used. If *protocol* is
specified as a negative value or :const:`HIGHEST_PROTOCOL`, the highest protocol specified as a negative value or :const:`HIGHEST_PROTOCOL`, the highest
version will be used. protocol version will be used.
*file* must have a :meth:`write` method that accepts a single string argument. *file* must have a :meth:`write` method that accepts a single string argument.
It can thus be a file object opened for writing, a :mod:`StringIO` object, or It can thus be a file object opened for writing, a :mod:`StringIO` object, or
@ -194,9 +197,9 @@ process more convenient:
Return the pickled representation of the object as a string, instead of writing Return the pickled representation of the object as a string, instead of writing
it to a file. it to a file.
If the *protocol* parameter is omitted, protocol 0 is used. If *protocol* is If the *protocol* parameter is omitted, protocol 3 is used. If *protocol*
specified as a negative value or :const:`HIGHEST_PROTOCOL`, the highest protocol is specified as a negative value or :const:`HIGHEST_PROTOCOL`, the highest
version will be used. protocol version will be used.
.. function:: loads(string) .. function:: loads(string)
@ -234,7 +237,7 @@ The :mod:`pickle` module also exports two callables [#]_, :class:`Pickler` and
This takes a file-like object to which it will write a pickle data stream. This takes a file-like object to which it will write a pickle data stream.
If the *protocol* parameter is omitted, protocol 0 is used. If *protocol* is If the *protocol* parameter is omitted, protocol 3 is used. If *protocol* is
specified as a negative value or :const:`HIGHEST_PROTOCOL`, the highest specified as a negative value or :const:`HIGHEST_PROTOCOL`, the highest
protocol version will be used. protocol version will be used.
@ -681,8 +684,8 @@ that a self-referencing list is pickled and restored correctly. ::
output = open('data.pkl', 'wb') output = open('data.pkl', 'wb')
# Pickle dictionary using protocol 0. # Pickle dictionary using protocol 2.
pickle.dump(data1, output) pickle.dump(data1, output, 2)
# Pickle the list using the highest protocol available. # Pickle the list using the highest protocol available.
pickle.dump(selfref_list, output, -1) pickle.dump(selfref_list, output, -1)