Changeset 391 for python/trunk/Doc/library/pickle.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/library/pickle.rst (modified) (11 diffs)

python/trunk/Doc/library/pickle.rst

@@ -25 +25 @@
 This documentation describes both the :mod:`pickle` module and the
 :mod:`cPickle` module.
+
+.. warning::
+
+   The :mod:`pickle` module is not intended to be secure against erroneous or
+   maliciously constructed data.  Never unpickle data received from an untrusted
+   or unauthenticated source.
 
 
@@ -48 +54 @@
 files.
 
-The :mod:`pickle` module differs from :mod:`marshal` several significant ways:
+The :mod:`pickle` module differs from :mod:`marshal` in several significant ways:
 
 * The :mod:`pickle` module keeps track of the objects it has already serialized,
@@ -74 +80 @@
   The :mod:`pickle` serialization format is guaranteed to be backwards compatible
   across Python releases.
-
-.. warning::
-
-   The :mod:`pickle` module is not intended to be secure against erroneous or
-   maliciously constructed data.  Never unpickle data received from an untrusted
-   or unauthenticated source.
 
 Note that serialization is a more primitive notion than persistence; although
@@ -353 +353 @@
 * classes that are defined at the top level of a module
 
-* instances of such classes whose :attr:`__dict__` or :meth:`__setstate__` is
-  picklable  (see section :ref:`pickle-protocol` for details)
+* instances of such classes whose :attr:`~object.__dict__` or the result of
+  calling :meth:`__getstate__` is picklable  (see section :ref:`pickle-protocol`
+  for details).
 
 Attempts to pickle unpicklable objects will raise the :exc:`PicklingError`
@@ -365 +366 @@
 Note that functions (built-in and user-defined) are pickled by "fully qualified"
 name reference, not by value.  This means that only the function name is
-pickled, along with the name of module the function is defined in.  Neither the
-function's code, nor any of its function attributes are pickled.  Thus the
+pickled, along with the name of the module the function is defined in.  Neither
+the function's code, nor any of its function attributes are pickled.  Thus the
 defining module must be importable in the unpickling environment, and the module
 must contain the named object, otherwise an exception will be raised. [#]_
@@ -443 +444 @@
    pickled as the contents for the instance, instead of the contents of the
    instance's dictionary.  If there is no :meth:`__getstate__` method, the
-   instance's :attr:`__dict__` is pickled.
-
-.. method:: object.__setstate__()
+   instance's :attr:`~object.__dict__` is pickled.
+
+.. method:: object.__setstate__(state)
 
    Upon unpickling, if the class also defines the method :meth:`__setstate__`,
@@ -511 +512 @@
      :meth:`__setstate__` method as described in section :ref:`pickle-inst`.  If
      the object has no :meth:`__setstate__` method, then, as above, the value
-     must be a dictionary and it will be added to the object's :attr:`__dict__`.
+     must be a dictionary and it will be added to the object's
+     :attr:`~object.__dict__`.
 
    * Optionally, an iterator (and not a sequence) yielding successive list
@@ -569 +571 @@
 
 To define external persistent id resolution, you need to set the
-:attr:`persistent_id` attribute of the pickler object and the
-:attr:`persistent_load` attribute of the unpickler object.
+:attr:`~Pickler.persistent_id` attribute of the pickler object and the
+:attr:`~Unpickler.persistent_load` attribute of the unpickler object.
 
 To pickle objects that have an external persistent id, the pickler must have a
-custom :func:`persistent_id` method that takes an object as an argument and
-returns either ``None`` or the persistent id for that object.  When ``None`` is
-returned, the pickler simply pickles the object as normal.  When a persistent id
-string is returned, the pickler will pickle that string, along with a marker so
-that the unpickler will recognize the string as a persistent id.
+custom :func:`~Pickler.persistent_id` method that takes an object as an
+argument and returns either ``None`` or the persistent id for that object.
+When ``None`` is returned, the pickler simply pickles the object as normal.
+When a persistent id string is returned, the pickler will pickle that string,
+along with a marker so that the unpickler will recognize the string as a
+persistent id.
 
 To unpickle external objects, the unpickler must have a custom
-:func:`persistent_load` function that takes a persistent id string and returns
-the referenced object.
+:func:`~Unpickler.persistent_load` function that takes a persistent id string
+and returns the referenced object.
 
 Here's a silly example that *might* shed more light::
@@ -631 +634 @@
    print j
 
-In the :mod:`cPickle` module, the unpickler's :attr:`persistent_load` attribute
-can also be set to a Python list, in which case, when the unpickler reaches a
-persistent id, the persistent id string will simply be appended to this list.
-This functionality exists so that a pickle data stream can be "sniffed" for
-object references without actually instantiating all the objects in a pickle.
-[#]_  Setting :attr:`persistent_load` to a list is usually used in conjunction
-with the :meth:`noload` method on the Unpickler.
+In the :mod:`cPickle` module, the unpickler's :attr:`~Unpickler.persistent_load`
+attribute can also be set to a Python list, in which case, when the unpickler
+reaches a persistent id, the persistent id string will simply be appended to
+this list.  This functionality exists so that a pickle data stream can be
+"sniffed" for object references without actually instantiating all the objects
+in a pickle.
+[#]_  Setting :attr:`~Unpickler.persistent_load` to a list is usually used in
+conjunction with the :meth:`~Unpickler.noload` method on the Unpickler.
 
 .. BAW: Both pickle and cPickle support something called inst_persistent_id()
@@ -675 +679 @@
 
 Things are a little cleaner with :mod:`cPickle`, but not by much. To control
-what gets unpickled, you can set the unpickler's :attr:`find_global` attribute
-to a function or ``None``.  If it is ``None`` then any attempts to unpickle
-instances will raise an :exc:`UnpicklingError`.  If it is a function, then it
-should accept a module name and a class name, and return the corresponding class
-object.  It is responsible for looking up the class and performing any necessary
-imports, and it may raise an error to prevent instances of the class from being
-unpickled.
+what gets unpickled, you can set the unpickler's :attr:`~Unpickler.find_global`
+attribute to a function or ``None``.  If it is ``None`` then any attempts to
+unpickle instances will raise an :exc:`UnpicklingError`.  If it is a function,
+then it should accept a module name and a class name, and return the
+corresponding class object.  It is responsible for looking up the class and
+performing any necessary imports, and it may raise an error to prevent
+instances of the class from being unpickled.
 
 The moral of the story is that you should be really careful about the source of
@@ -732 +736 @@
 Here's a larger example that shows how to modify pickling behavior for a class.
 The :class:`TextReader` class opens a text file, and returns the line number and
-line contents each time its :meth:`readline` method is called. If a
+line contents each time its :meth:`!readline` method is called. If a
 :class:`TextReader` instance is pickled, all attributes *except* the file object
 member are saved. When the instance is unpickled, the file is reopened, and