merge 3.2

Doc/library/2to3.rst

@@ -23,7 +23,7 @@ Using 2to3
 also located in the :file:`Tools/scripts` directory of the Python root.
 
 2to3's basic arguments are a list of files or directories to transform.  The
-directories are to recursively traversed for Python sources.
+directories are recursively traversed for Python sources.
 
 Here is a sample Python 2.x source file, :file:`example.py`::
 

Doc/library/concurrent.futures.rst

@@ -42,12 +42,13 @@ Executor Objects
 
        Equivalent to ``map(func, *iterables)`` except *func* is executed
        asynchronously and several calls to *func* may be made concurrently.  The
-       returned iterator raises a :exc:`TimeoutError` if :meth:`__next__()` is
-       called and the result isn't available after *timeout* seconds from the
-       original call to :meth:`Executor.map`. *timeout* can be an int or a
-       float.  If *timeout* is not specified or ``None``, there is no limit to
-       the wait time.  If a call raises an exception, then that exception will
-       be raised when its value is retrieved from the iterator.
+       returned iterator raises a :exc:`TimeoutError` if
+       :meth:`~iterator.__next__` is called and the result isn't available
+       after *timeout* seconds from the original call to :meth:`Executor.map`.
+       *timeout* can be an int or a float.  If *timeout* is not specified or
+       ``None``, there is no limit to the wait time.  If a call raises an
+       exception, then that exception will be raised when its value is
+       retrieved from the iterator.
 
     .. method:: shutdown(wait=True)
 
@@ -364,10 +365,11 @@ Module Functions
    different :class:`Executor` instances) given by *fs* that yields futures as
    they complete (finished or were cancelled).  Any futures that completed
    before :func:`as_completed` is called will be yielded first.  The returned
-   iterator raises a :exc:`TimeoutError` if :meth:`__next__` is called and the
-   result isn't available after *timeout* seconds from the original call to
-   :func:`as_completed`.  *timeout* can be an int or float.  If *timeout* is not
-   specified or ``None``, there is no limit to the wait time.
+   iterator raises a :exc:`TimeoutError` if :meth:`~iterator.__next__` is
+   called and the result isn't available after *timeout* seconds from the
+   original call to :func:`as_completed`.  *timeout* can be an int or float.
+   If *timeout* is not specified or ``None``, there is no limit to the wait
+   time.
 
 
 .. seealso::

Doc/library/dis.rst

@@ -660,10 +660,10 @@ the more significant byte last.
 
 .. opcode:: FOR_ITER (delta)
 
-   ``TOS`` is an :term:`iterator`.  Call its :meth:`__next__` method.  If this
-   yields a new value, push it on the stack (leaving the iterator below it).  If
-   the iterator indicates it is exhausted ``TOS`` is popped, and the byte code
-   counter is incremented by *delta*.
+   ``TOS`` is an :term:`iterator`.  Call its :meth:`~iterator.__next__` method.
+   If this yields a new value, push it on the stack (leaving the iterator below
+   it).  If the iterator indicates it is exhausted ``TOS`` is popped, and the
+   byte code counter is incremented by *delta*.
 
 
 .. opcode:: LOAD_GLOBAL (namei)

Doc/library/functions.rst

@@ -348,10 +348,10 @@ are always available.  They are listed here in alphabetical order.
 .. function:: enumerate(iterable, start=0)
 
    Return an enumerate object. *iterable* must be a sequence, an
-   :term:`iterator`, or some other object which supports iteration.  The
-   :meth:`__next__` method of the iterator returned by :func:`enumerate` returns a
-   tuple containing a count (from *start* which defaults to 0) and the
-   values obtained from iterating over *iterable*.
+   :term:`iterator`, or some other object which supports iteration.
+   The :meth:`~iterator.__next__` method of the iterator returned by
+   :func:`enumerate` returns a tuple containing a count (from *start* which
+   defaults to 0) and the values obtained from iterating over *iterable*.
 
       >>> seasons = ['Spring', 'Summer', 'Fall', 'Winter']
       >>> list(enumerate(seasons))
@@ -683,9 +683,10 @@ are always available.  They are listed here in alphabetical order.
    starting at ``0``).  If it does not support either of those protocols,
    :exc:`TypeError` is raised. If the second argument, *sentinel*, is given,
    then *object* must be a callable object.  The iterator created in this case
-   will call *object* with no arguments for each call to its :meth:`__next__`
-   method; if the value returned is equal to *sentinel*, :exc:`StopIteration`
-   will be raised, otherwise the value will be returned.
+   will call *object* with no arguments for each call to its
+   :meth:`~iterator.__next__` method; if the value returned is equal to
+   *sentinel*, :exc:`StopIteration` will be raised, otherwise the value will
+   be returned.
 
    One useful application of the second form of :func:`iter` is to read lines of
    a file until a certain line is reached.  The following example reads a file
@@ -779,9 +780,9 @@ are always available.  They are listed here in alphabetical order.
 
 .. function:: next(iterator[, default])
 
-   Retrieve the next item from the *iterator* by calling its :meth:`__next__`
-   method.  If *default* is given, it is returned if the iterator is exhausted,
-   otherwise :exc:`StopIteration` is raised.
+   Retrieve the next item from the *iterator* by calling its
+   :meth:`~iterator.__next__` method.  If *default* is given, it is returned
+   if the iterator is exhausted, otherwise :exc:`StopIteration` is raised.
 
 
 .. function:: object()

Doc/library/stdtypes.rst

@@ -779,9 +779,9 @@ specific sequence types, dictionaries, and other more specialized forms.  The
 specific types are not important beyond their implementation of the iterator
 protocol.
 
-Once an iterator's :meth:`__next__` method raises :exc:`StopIteration`, it must
-continue to do so on subsequent calls.  Implementations that do not obey this
-property are deemed broken.
+Once an iterator's :meth:`~iterator.__next__` method raises
+:exc:`StopIteration`, it must continue to do so on subsequent calls.
+Implementations that do not obey this property are deemed broken.
 
 
 .. _generator-types:
@@ -792,7 +792,8 @@ Generator Types
 Python's :term:`generator`\s provide a convenient way to implement the iterator
 protocol.  If a container object's :meth:`__iter__` method is implemented as a
 generator, it will automatically return an iterator object (technically, a
-generator object) supplying the :meth:`__iter__` and :meth:`__next__` methods.
+generator object) supplying the :meth:`__iter__` and :meth:`~generator.__next__`
+methods.
 More information about generators can be found in :ref:`the documentation for
 the yield expression <yieldexpr>`.