Give the pickle special methods a signature.

1 files changed, 117 insertions, 118 deletions

diff --git a/Doc/library/pickle.rst b/Doc/library/pickle.rst
index f197261..cc3c036 100644
--- a/Doc/library/pickle.rst
+++ b/Doc/library/pickle.rst
@@ -396,6 +396,8 @@ conversions can be made by the class's :meth:`__setstate__` method.
 The pickle protocol
 -------------------
 
+.. currentmodule:: None
+
 This section describes the "pickling protocol" that defines the interface
 between the pickler/unpickler and the objects that are being serialized.  This
 protocol provides a standard way for you to define, customize, and control how
@@ -410,129 +412,126 @@ environment slightly safer from untrusted pickle data streams; see section
 Pickling and unpickling normal class instances
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. index::
-   single: __getinitargs__() (copy protocol)
-   single: __init__() (instance constructor)
-
-When a pickled class instance is unpickled, its :meth:`__init__` method is
-normally *not* invoked.  If it is desirable that the :meth:`__init__` method be
-called on unpickling, an old-style class can define a method
-:meth:`__getinitargs__`, which should return a *tuple* containing the arguments
-to be passed to the class constructor (:meth:`__init__` for example).  The
-:meth:`__getinitargs__` method is called at pickle time; the tuple it returns is
-incorporated in the pickle for the instance.
-
-.. index:: single: __getnewargs__() (copy protocol)
-
-New-style types can provide a :meth:`__getnewargs__` method that is used for
-protocol 2.  Implementing this method is needed if the type establishes some
-internal invariants when the instance is created, or if the memory allocation is
-affected by the values passed to the :meth:`__new__` method for the type (as it
-is for tuples and strings).  Instances of a :term:`new-style class` :class:`C`
-are created using ::
-
-   obj = C.__new__(C, *args)
-
-
-where *args* is the result of calling :meth:`__getnewargs__` on the original
-object; if there is no :meth:`__getnewargs__`, an empty tuple is assumed.
-
-.. index::
-   single: __getstate__() (copy protocol)
-   single: __setstate__() (copy protocol)
-   single: __dict__ (instance attribute)
-
-Classes can further influence how their instances are pickled; if the class
-defines the method :meth:`__getstate__`, it is called and the return state is
-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.
-
-Upon unpickling, if the class also defines the method :meth:`__setstate__`, it
-is called with the unpickled state. [#]_  If there is no :meth:`__setstate__`
-method, the pickled state must be a dictionary and its items are assigned to the
-new instance's dictionary.  If a class defines both :meth:`__getstate__` and
-:meth:`__setstate__`, the state object needn't be a dictionary and these methods
-can do what they want. [#]_
-
-.. warning::
-
-   For :term:`new-style class`\es, if :meth:`__getstate__` returns a false
-   value, the :meth:`__setstate__` method will not be called.
+.. method:: object.__getinitargs__()
+   
+   When a pickled class instance is unpickled, its :meth:`__init__` method is
+   normally *not* invoked.  If it is desirable that the :meth:`__init__` method
+   be called on unpickling, an old-style class can define a method
+   :meth:`__getinitargs__`, which should return a *tuple* containing the
+   arguments to be passed to the class constructor (:meth:`__init__` for
+   example).  The :meth:`__getinitargs__` method is called at pickle time; the
+   tuple it returns is incorporated in the pickle for the instance.
+
+.. method:: object.__getnewargs__()
+
+   New-style types can provide a :meth:`__getnewargs__` method that is used for
+   protocol 2.  Implementing this method is needed if the type establishes some
+   internal invariants when the instance is created, or if the memory allocation
+   is affected by the values passed to the :meth:`__new__` method for the type
+   (as it is for tuples and strings).  Instances of a :term:`new-style class`
+   ``C`` are created using ::
+    
+      obj = C.__new__(C, *args)
+    
+   where *args* is the result of calling :meth:`__getnewargs__` on the original
+   object; if there is no :meth:`__getnewargs__`, an empty tuple is assumed.
+
+.. method:: object.__getstate__()
+   
+   Classes can further influence how their instances are pickled; if the class
+   defines the method :meth:`__getstate__`, it is called and the return state is
+   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__() 
+   
+   Upon unpickling, if the class also defines the method :meth:`__setstate__`,
+   it is called with the unpickled state. [#]_ If there is no
+   :meth:`__setstate__` method, the pickled state must be a dictionary and its
+   items are assigned to the new instance's dictionary.  If a class defines both
+   :meth:`__getstate__` and :meth:`__setstate__`, the state object needn't be a
+   dictionary and these methods can do what they want. [#]_
+    
+   .. warning::
+    
+      For :term:`new-style class`\es, if :meth:`__getstate__` returns a false
+      value, the :meth:`__setstate__` method will not be called.
 
 
 Pickling and unpickling extension types
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-.. index::
-   single: __reduce__() (pickle protocol)
-   single: __reduce_ex__() (pickle protocol)
-   single: __safe_for_unpickling__ (pickle protocol)
-
-When the :class:`Pickler` encounters an object of a type it knows nothing about
---- such as an extension type --- it looks in two places for a hint of how to
-pickle it.  One alternative is for the object to implement a :meth:`__reduce__`
-method.  If provided, at pickling time :meth:`__reduce__` will be called with no
-arguments, and it must return either a string or a tuple.
-
-If a string is returned, it names a global variable whose contents are pickled
-as normal.  The string returned by :meth:`__reduce__` should be the object's
-local name relative to its module; the pickle module searches the module
-namespace to determine the object's module.
-
-When a tuple is returned, it must be between two and five elements long.
-Optional elements can either be omitted, or ``None`` can be provided as their
-value.  The contents of this tuple are pickled as normal and used to
-reconstruct the object at unpickling time.  The semantics of each element are:
-
-* A callable object that will be called to create the initial version of the
-  object.  The next element of the tuple will provide arguments for this callable,
-  and later elements provide additional state information that will subsequently
-  be used to fully reconstruct the pickled data.
-
-  In the unpickling environment this object must be either a class, a callable
-  registered as a "safe constructor" (see below), or it must have an attribute
-  :attr:`__safe_for_unpickling__` with a true value. Otherwise, an
-  :exc:`UnpicklingError` will be raised in the unpickling environment.  Note that
-  as usual, the callable itself is pickled by name.
-
-* A tuple of arguments for the callable object.
-
-  .. versionchanged:: 2.5
-     Formerly, this argument could also be ``None``.
-
-* Optionally, the object's state, which will be passed to the object's
-  :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__`.
-
-* Optionally, an iterator (and not a sequence) yielding successive list items.
-  These list items will be pickled, and appended to the object using either
-  ``obj.append(item)`` or ``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 dictionary items,
-  which should be tuples of the form ``(key, value)``.  These items will be
-  pickled and 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__`.
-
-It is sometimes useful to know the protocol version when implementing
-:meth:`__reduce__`.  This can be done by implementing a method named
-:meth:`__reduce_ex__` instead of :meth:`__reduce__`. :meth:`__reduce_ex__`, when
-it exists, is called in preference over :meth:`__reduce__` (you may still
-provide :meth:`__reduce__` for backwards compatibility).  The
-:meth:`__reduce_ex__` method will be called with a single integer argument, the
-protocol version.
-
-The :class:`object` class implements both :meth:`__reduce__` and
-:meth:`__reduce_ex__`; however, if a subclass overrides :meth:`__reduce__` but
-not :meth:`__reduce_ex__`, the :meth:`__reduce_ex__` implementation detects this
-and calls :meth:`__reduce__`.
+.. method:: object.__reduce__()
+   
+   When the :class:`Pickler` encounters an object of a type it knows nothing
+   about --- such as an extension type --- it looks in two places for a hint of
+   how to pickle it.  One alternative is for the object to implement a
+   :meth:`__reduce__` method.  If provided, at pickling time :meth:`__reduce__`
+   will be called with no arguments, and it must return either a string or a
+   tuple.
+
+   If a string is returned, it names a global variable whose contents are
+   pickled as normal.  The string returned by :meth:`__reduce__` should be the
+   object's local name relative to its module; the pickle module searches the
+   module namespace to determine the object's module.
+
+   When a tuple is returned, it must be between two and five elements long.
+   Optional elements can either be omitted, or ``None`` can be provided as their
+   value.  The contents of this tuple are pickled as normal and used to
+   reconstruct the object at unpickling time.  The semantics of each element
+   are:
+
+   * A callable object that will be called to create the initial version of the
+     object.  The next element of the tuple will provide arguments for this
+     callable, and later elements provide additional state information that will
+     subsequently be used to fully reconstruct the pickled data.
+
+     In the unpickling environment this object must be either a class, a
+     callable registered as a "safe constructor" (see below), or it must have an
+     attribute :attr:`__safe_for_unpickling__` with a true value. Otherwise, an
+     :exc:`UnpicklingError` will be raised in the unpickling environment.  Note
+     that as usual, the callable itself is pickled by name.
+
+   * A tuple of arguments for the callable object.
+
+     .. versionchanged:: 2.5
+        Formerly, this argument could also be ``None``.
+
+   * Optionally, the object's state, which will be passed to the object's
+     :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__`.
+
+   * Optionally, an iterator (and not a sequence) yielding successive list
+     items.  These list items will be pickled, and appended to the object using
+     either ``obj.append(item)`` or ``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 dictionary
+     items, which should be tuples of the form ``(key, value)``.  These items
+     will be pickled and 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) 
+
+   It is sometimes useful to know the protocol version when implementing
+   :meth:`__reduce__`.  This can be done by implementing a method named
+   :meth:`__reduce_ex__` instead of :meth:`__reduce__`. :meth:`__reduce_ex__`,
+   when it exists, is called in preference over :meth:`__reduce__` (you may
+   still provide :meth:`__reduce__` for backwards compatibility).  The
+   :meth:`__reduce_ex__` method will be called with a single integer argument,
+   the protocol version.
+
+   The :class:`object` class implements both :meth:`__reduce__` and
+   :meth:`__reduce_ex__`; however, if a subclass overrides :meth:`__reduce__`
+   but not :meth:`__reduce_ex__`, the :meth:`__reduce_ex__` implementation
+   detects this and calls :meth:`__reduce__`.
 
 An alternative to implementing a :meth:`__reduce__` method on the object to be
 pickled, is to register the callable with the :mod:`copy_reg` module.  This