diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst index 520c24b8eea..a9877ff1ed6 100644 --- a/Doc/library/pickle.rst +++ b/Doc/library/pickle.rst @@ -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 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 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 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. -If a *protocol* is not specified, protocol 0 is used. If *protocol* is specified -as a negative value or :const:`HIGHEST_PROTOCOL`, the highest protocol version -available will be used. +If a *protocol* is not specified, protocol 3 is used. If *protocol* is +specified as a negative value or :const:`HIGHEST_PROTOCOL`, the highest +protocol version available will be used. A binary format, which is slightly more efficient, can be chosen by specifying a *protocol* version >= 1. @@ -164,9 +167,9 @@ process more convenient: Write a pickled representation of *obj* to the open file object *file*. This is equivalent to ``Pickler(file, protocol).dump(obj)``. - If the *protocol* parameter is omitted, protocol 0 is used. If *protocol* is - specified as a negative value or :const:`HIGHEST_PROTOCOL`, the highest protocol - version will be used. + 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 version will be used. *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 @@ -194,9 +197,9 @@ process more convenient: Return the pickled representation of the object as a string, instead of writing it to a file. - If the *protocol* parameter is omitted, protocol 0 is used. If *protocol* is - specified as a negative value or :const:`HIGHEST_PROTOCOL`, the highest protocol - version will be used. + 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 version will be used. .. 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. - 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 version will be used. @@ -681,8 +684,8 @@ that a self-referencing list is pickled and restored correctly. :: output = open('data.pkl', 'wb') - # Pickle dictionary using protocol 0. - pickle.dump(data1, output) + # Pickle dictionary using protocol 2. + pickle.dump(data1, output, 2) # Pickle the list using the highest protocol available. pickle.dump(selfref_list, output, -1)