Merged revisions 85572-85573,85606,85609-85622,85624,85626-85627,85629,85631,85633,85635-85636,85638-85639,85641-85642 via svnmerge from

svn+ssh://svn.python.org/python/branches/py3k

........
  r85572 | georg.brandl | 2010-10-16 20:51:05 +0200 (Sa, 16 Okt 2010) | 1 line

  #10122: typo fix.
........
  r85573 | georg.brandl | 2010-10-16 20:53:08 +0200 (Sa, 16 Okt 2010) | 1 line

  #10124: typo fix.
........
  r85606 | georg.brandl | 2010-10-17 08:32:59 +0200 (So, 17 Okt 2010) | 1 line

  #10058: tweak wording about exception returns.
........
  r85609 | georg.brandl | 2010-10-17 11:19:03 +0200 (So, 17 Okt 2010) | 1 line

  #8556: use less confusing mapping key in example.
........
  r85610 | georg.brandl | 2010-10-17 11:23:05 +0200 (So, 17 Okt 2010) | 1 line

  #8686: remove potentially confusing wording that does not add any value.
........
  r85611 | georg.brandl | 2010-10-17 11:33:24 +0200 (So, 17 Okt 2010) | 1 line

  #8811: small fixes to sqlite3 docs.
........
  r85612 | georg.brandl | 2010-10-17 11:37:54 +0200 (So, 17 Okt 2010) | 1 line

  #8855: add shelve security warning.
........
  r85613 | georg.brandl | 2010-10-17 11:43:35 +0200 (So, 17 Okt 2010) | 1 line

  Fix hmac docs: it takes and returns bytes, except for hexdigest().
........
  r85614 | georg.brandl | 2010-10-17 11:46:11 +0200 (So, 17 Okt 2010) | 1 line

  #8968: add actual name of token constants.
........
  r85615 | georg.brandl | 2010-10-17 12:05:13 +0200 (So, 17 Okt 2010) | 1 line

  #459007: merge info from PC/getpathp.c and using/windows.rst to document the forming of sys.path under Windows.
........
  r85616 | georg.brandl | 2010-10-17 12:07:29 +0200 (So, 17 Okt 2010) | 1 line

  Fix copy-paste error in example.
........
  r85617 | georg.brandl | 2010-10-17 12:09:06 +0200 (So, 17 Okt 2010) | 1 line

  #5212: md5 weaknesses do not affect hmac, so remove the note about that.
........
  r85618 | georg.brandl | 2010-10-17 12:14:38 +0200 (So, 17 Okt 2010) | 1 line

  #9086: correct wrong terminology about linking with pythonXY.dll.
........
  r85619 | georg.brandl | 2010-10-17 12:15:50 +0200 (So, 17 Okt 2010) | 1 line

  Make file names consistent.
........
  r85620 | georg.brandl | 2010-10-17 12:22:28 +0200 (So, 17 Okt 2010) | 1 line

  Remove second parser module example; it referred to non-readily-available example files, and this kind of discovery is much better done with the AST nowadays anyway.
........
  r85621 | georg.brandl | 2010-10-17 12:24:54 +0200 (So, 17 Okt 2010) | 1 line

  #9105: move pickle warning to a bit more prominent location.
........
  r85622 | georg.brandl | 2010-10-17 12:28:04 +0200 (So, 17 Okt 2010) | 1 line

  #9112: document error() and exit() methods of ArgumentParser.
........
  r85624 | georg.brandl | 2010-10-17 12:34:28 +0200 (So, 17 Okt 2010) | 1 line

  Some markup and style fixes in argparse docs.
........
  r85626 | georg.brandl | 2010-10-17 12:38:20 +0200 (So, 17 Okt 2010) | 1 line

  #9117: fix syntax for class definition.
........
  r85627 | georg.brandl | 2010-10-17 12:44:11 +0200 (So, 17 Okt 2010) | 1 line

  #9138: reword introduction to classes in Python.
........
  r85629 | georg.brandl | 2010-10-17 12:51:45 +0200 (So, 17 Okt 2010) | 1 line

  #5962: clarify sys.exit() vs. threads.
........
  r85631 | georg.brandl | 2010-10-17 12:53:54 +0200 (So, 17 Okt 2010) | 1 line

  Fix capitalization.
........
  r85633 | georg.brandl | 2010-10-17 12:59:41 +0200 (So, 17 Okt 2010) | 1 line

  #9204: remove mentions of removed types in the types module.
........
  r85635 | georg.brandl | 2010-10-17 13:03:22 +0200 (So, 17 Okt 2010) | 1 line

  #5121: fix claims about default values leading to segfaults.
........
  r85636 | georg.brandl | 2010-10-17 13:06:14 +0200 (So, 17 Okt 2010) | 1 line

  #9237: document sys.call_tracing().
........
  r85638 | georg.brandl | 2010-10-17 13:13:37 +0200 (So, 17 Okt 2010) | 1 line

  Port changes to pickle docs apparently lost in py3k.
........
  r85639 | georg.brandl | 2010-10-17 13:23:56 +0200 (So, 17 Okt 2010) | 1 line

  Make twisted example a bit more logical.
........
  r85641 | georg.brandl | 2010-10-17 13:29:07 +0200 (So, 17 Okt 2010) | 1 line

  Fix documentation of dis.opmap direction.
........
  r85642 | georg.brandl | 2010-10-17 13:36:28 +0200 (So, 17 Okt 2010) | 1 line

  #9730: fix example.
........

1 files changed, 91 insertions, 85 deletions

diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst
index 3358053..8a671a7 100644
--- a/Doc/library/pickle.rst
+++ b/Doc/library/pickle.rst
@@ -23,6 +23,12 @@ into an object hierarchy.  Pickling (and unpickling) is alternatively known as
 "serialization", "marshalling," [#]_ or "flattening", however, to avoid
 confusion, the terms used here are "pickling" and "unpickling"..
 
+.. 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.
+
 
 Relationship to other Python modules
 ------------------------------------
@@ -63,12 +69,6 @@ The :mod:`pickle` module differs from :mod:`marshal` several significant ways:
   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
 :mod:`pickle` reads and writes file objects, it does not handle the issue of
 naming persistent objects, nor the (even more complicated) issue of concurrent
@@ -427,33 +427,38 @@ implementation of this behaviour::
        obj.__dict__.update(attributes)
        return obj
 
-.. index:: single: __getnewargs__() (copy protocol)
-
 Classes can alter the default behaviour by providing one or several special
-methods.  In protocol 2 and newer, classes that implements the
-:meth:`__getnewargs__` method can dictate the values passed to the
-:meth:`__new__` method upon unpickling.  This is often needed for classes
-whose :meth:`__new__` method requires arguments.
+methods:
 
-.. index:: single: __getstate__() (copy protocol)
+.. method:: object.__getnewargs__()
 
-Classes can further influence how their instances are pickled; if the class
-defines the method :meth:`__getstate__`, it is called and the returned object is
-pickled as the contents for the instance, instead of the contents of the
-instance's dictionary.  If the :meth:`__getstate__` method is absent, the
-instance's :attr:`__dict__` is pickled as usual.
+   In protocol 2 and newer, classes that implements the :meth:`__getnewargs__`
+   method can dictate the values passed to the :meth:`__new__` method upon
+   unpickling.  This is often needed for classes whose :meth:`__new__` method
+   requires arguments.
 
-.. index:: single: __setstate__() (copy protocol)
 
-Upon unpickling, if the class defines :meth:`__setstate__`, it is called with
-the unpickled state.  In that case, there is no requirement for the state object
-to be a dictionary. Otherwise, the pickled state must be a dictionary and its
-items are assigned to the new instance's dictionary.
+.. method:: object.__getstate__()
 
-.. note::
+   Classes can further influence how their instances are pickled; if the class
+   defines the method :meth:`__getstate__`, it is called and the returned object
+   is pickled as the contents for the instance, instead of the contents of the
+   instance's dictionary.  If the :meth:`__getstate__` method is absent, the
+   instance's :attr:`__dict__` is pickled as usual.
+
+
+.. method:: object.__setstate__(state)
+
+   Upon unpickling, if the class defines :meth:`__setstate__`, it is called with
+   the unpickled state.  In that case, there is no requirement for the state
+   object to be a dictionary.  Otherwise, the pickled state must be a dictionary
+   and its items are assigned to the new instance's dictionary.
+
+   .. note::
+
+      If :meth:`__getstate__` returns a false value, the :meth:`__setstate__`
+      method will not be called upon unpickling.
 
-   If :meth:`__getstate__` returns a false value, the :meth:`__setstate__`
-   method will not be called.
 
 Refer to the section :ref:`pickle-state` for more information about how to use
 the methods :meth:`__getstate__` and :meth:`__setstate__`.
@@ -462,14 +467,12 @@ the methods :meth:`__getstate__` and :meth:`__setstate__`.
 
    At unpickling time, some methods like :meth:`__getattr__`,
    :meth:`__getattribute__`, or :meth:`__setattr__` may be called upon the
-   instance.  In case those methods rely on some internal invariant being
-   true, the type should implement either :meth:`__getinitargs__` or
-   :meth:`__getnewargs__` to establish such an invariant; otherwise, neither
-   :meth:`__new__` nor :meth:`__init__` will be called.
+   instance.  In case those methods rely on some internal invariant being true,
+   the type should implement :meth:`__getnewargs__` to establish such an
+   invariant; otherwise, neither :meth:`__new__` nor :meth:`__init__` will be
+   called.
 
-.. index::
-   pair: copy; protocol
-   single: __reduce__() (copy protocol)
+.. index:: pair: copy; protocol
 
 As we shall see, pickle does not use directly the methods described above.  In
 fact, these methods are part of the copy protocol which implements the
@@ -480,58 +483,61 @@ objects. [#]_
 Although powerful, implementing :meth:`__reduce__` directly in your classes is
 error prone.  For this reason, class designers should use the high-level
 interface (i.e., :meth:`__getnewargs__`, :meth:`__getstate__` and
-:meth:`__setstate__`) whenever possible.  We will show, however, cases where using
-:meth:`__reduce__` is the only option or leads to more efficient pickling or
-both.
-
-The interface is currently defined as follows. The :meth:`__reduce__` method
-takes no argument and shall return either a string or preferably a tuple (the
-returned object is often referred to as the "reduce value").
-
-If a string is returned, the string should be interpreted as the name of a
-global variable.  It should be the object's local name relative to its module;
-the pickle module searches the module namespace to determine the object's
-module.  This behaviour is typically useful for singletons.
-
-When a tuple is returned, it must be between two and five items long.  Optional
-items can either be omitted, or ``None`` can be provided as their value.  The
-semantics of each item are in order:
-
-.. XXX Mention __newobj__ special-case?
-
-* A callable object that will be called to create the initial version of the
-  object.
-
-* A tuple of arguments for the callable object. An empty tuple must be given if
-  the callable does not accept any argument.
-
-* Optionally, the object's state, which will be passed to the object's
-  :meth:`__setstate__` method as previously described.  If the object has no
-  such method then, the value must be a dictionary and it will be added to the
-  object's :attr:`__dict__` attribute.
-
-* Optionally, an iterator (and not a sequence) yielding successive items.  These
-  items will be appended to the object either using ``obj.append(item)`` or, in
-  batch, using ``obj.extend(list_of_items)``.  This is primarily used for list
-  subclasses, but may be used by other classes as long as they have
-  :meth:`append` and :meth:`extend` methods with the appropriate signature.
-  (Whether :meth:`append` or :meth:`extend` is used depends on which pickle
-  protocol version is used as well as the number of items to append, so both
-  must be supported.)
-
-* Optionally, an iterator (not a sequence) yielding successive key-value pairs.
-  These items will be stored to the object using ``obj[key] = value``.  This is
-  primarily used for dictionary subclasses, but may be used by other classes as
-  long as they implement :meth:`__setitem__`.
-
-.. index:: single: __reduce_ex__() (copy protocol)
-
-Alternatively, a :meth:`__reduce_ex__` method may be defined.  The only
-difference is this method should take a single integer argument, the protocol
-version.  When defined, pickle will prefer it over the :meth:`__reduce__`
-method.  In addition, :meth:`__reduce__` automatically becomes a synonym for the
-extended version.  The main use for this method is to provide
-backwards-compatible reduce values for older Python releases.
+:meth:`__setstate__`) whenever possible.  We will show, however, cases where
+using :meth:`__reduce__` is the only option or leads to more efficient pickling
+or both.
+
+.. method:: object.__reduce__()
+
+   The interface is currently defined as follows.  The :meth:`__reduce__` method
+   takes no argument and shall return either a string or preferably a tuple (the
+   returned object is often referred to as the "reduce value").
+
+   If a string is returned, the string should be interpreted as the name of a
+   global variable.  It should be the object's local name relative to its
+   module; the pickle module searches the module namespace to determine the
+   object's module.  This behaviour is typically useful for singletons.
+
+   When a tuple is returned, it must be between two and five items long.
+   Optional items can either be omitted, or ``None`` can be provided as their
+   value.  The semantics of each item are in order:
+
+   .. XXX Mention __newobj__ special-case?
+
+   * A callable object that will be called to create the initial version of the
+     object.
+
+   * A tuple of arguments for the callable object.  An empty tuple must be given
+     if the callable does not accept any argument.
+
+   * Optionally, the object's state, which will be passed to the object's
+     :meth:`__setstate__` method as previously described.  If the object has no
+     such method then, the value must be a dictionary and it will be added to
+     the object's :attr:`__dict__` attribute.
+
+   * Optionally, an iterator (and not a sequence) yielding successive items.
+     These items will be appended to the object either using
+     ``obj.append(item)`` or, in batch, using ``obj.extend(list_of_items)``.
+     This is primarily used for list subclasses, but may be used by other
+     classes as long as they have :meth:`append` and :meth:`extend` methods with
+     the appropriate signature.  (Whether :meth:`append` or :meth:`extend` is
+     used depends on which pickle protocol version is used as well as the number
+     of items to append, so both must be supported.)
+
+   * Optionally, an iterator (not a sequence) yielding successive key-value
+     pairs.  These items will be stored to the object using ``obj[key] =
+     value``.  This is primarily used for dictionary subclasses, but may be used
+     by other classes as long as they implement :meth:`__setitem__`.
+
+
+.. method:: object.__reduce_ex__(protocol)
+
+   Alternatively, a :meth:`__reduce_ex__` method may be defined.  The only
+   difference is this method should take a single integer argument, the protocol
+   version.  When defined, pickle will prefer it over the :meth:`__reduce__`
+   method.  In addition, :meth:`__reduce__` automatically becomes a synonym for
+   the extended version.  The main use for this method is to provide
+   backwards-compatible reduce values for older Python releases.
 
 .. _pickle-persistent: