Edit concurrent docs, add versionadded and see also reference to the PEP.

Doc/library/concurrent.futures.rst

@@ -4,6 +4,8 @@
 .. module:: concurrent.futures
    :synopsis: Execute computations concurrently using threads or processes.
 
+.. versionadded:: 3.2
+
 The :mod:`concurrent.futures` module provides a high-level interface for
 asynchronously executing callables.
 
@@ -12,8 +14,9 @@ The asynchronous execution can be be performed with threads, using
 :class:`ProcessPoolExecutor`.  Both implement the same interface, which is
 defined by the abstract :class:`Executor` class.
 
+
 Executor Objects
-^^^^^^^^^^^^^^^^
+----------------
 
 .. class:: Executor
 
@@ -24,9 +27,7 @@ Executor Objects
 
        Schedules the callable, *fn*, to be executed as ``fn(*args **kwargs)``
        and returns a :class:`Future` object representing the execution of the
-       callable.
-
-       ::
+       callable. ::
 
           with ThreadPoolExecutor(max_workers=1) as executor:
               future = executor.submit(pow, 323, 1235)
@@ -40,8 +41,8 @@ Executor Objects
        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.
+       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)
 
@@ -58,11 +59,10 @@ Executor Objects
        value of *wait*, the entire Python program will not exit until all
        pending futures are done executing.
 
-       You can avoid having to call this method explicitly if you use the `with`
-       statement, which will shutdown the `Executor` (waiting as if
-       `Executor.shutdown` were called with *wait* set to `True`):
-
-       ::
+       You can avoid having to call this method explicitly if you use the
+       :keyword:`with` statement, which will shutdown the :class:`Executor`
+       (waiting as if :meth:`Executor.shutdown` were called with *wait* set to
+       ``True``)::
 
           import shutil
           with ThreadPoolExecutor(max_workers=4) as e:
@@ -71,16 +71,15 @@ Executor Objects
               e.submit(shutil.copy, 'src3.txt', 'dest3.txt')
               e.submit(shutil.copy, 'src3.txt', 'dest4.txt')
 
+
 ThreadPoolExecutor
-^^^^^^^^^^^^^^^^^^
+------------------
 
 :class:`ThreadPoolExecutor` is a :class:`Executor` subclass that uses a pool of
 threads to execute calls asynchronously.
 
 Deadlocks can occur when the callable associated with a :class:`Future` waits on
-the results of another :class:`Future`. For example:
-
-::
+the results of another :class:`Future`.  For example::
 
    import time
    def wait_on_b():
@@ -98,9 +97,7 @@ the results of another :class:`Future`. For example:
    a = executor.submit(wait_on_b)
    b = executor.submit(wait_on_a)
 
-And:
-
-::
+And::
 
    def wait_on_future():
        f = executor.submit(pow, 5, 2)
@@ -117,10 +114,11 @@ And:
    An :class:`Executor` subclass that uses a pool of at most *max_workers*
    threads to execute calls asynchronously.
 
+
 .. _threadpoolexecutor-example:
 
 ThreadPoolExecutor Example
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~
 ::
 
    import concurrent.futures
@@ -149,7 +147,7 @@ ThreadPoolExecutor Example
 
 
 ProcessPoolExecutor
-^^^^^^^^^^^^^^^^^^^
+-------------------
 
 The :class:`ProcessPoolExecutor` class is an :class:`Executor` subclass that
 uses a pool of processes to execute calls asynchronously.
@@ -166,10 +164,11 @@ to a :class:`ProcessPoolExecutor` will result in deadlock.
    of at most *max_workers* processes.  If *max_workers* is ``None`` or not
    given, it will default to the number of processors on the machine.
 
+
 .. _processpoolexecutor-example:
 
 ProcessPoolExecutor Example
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 ::
 
    import concurrent.futures
@@ -201,8 +200,9 @@ ProcessPoolExecutor Example
    if __name__ == '__main__':
        main()
 
+
 Future Objects
-^^^^^^^^^^^^^^
+--------------
 
 The :class:`Future` class encapulates the asynchronous execution of a callable.
 :class:`Future` instances are created by :meth:`Executor.submit`.
@@ -248,11 +248,11 @@ The :class:`Future` class encapulates the asynchronous execution of a callable.
 
     .. method:: exception(timeout=None)
 
-       Return the exception raised by the call. If the call hasn't yet completed
-       then this method will wait up to *timeout* seconds. If the call hasn't
-       completed in *timeout* seconds, then a :exc:`TimeoutError` will be
-       raised.  *timeout* can be an int or float. If *timeout* is not specified
-       or ``None``, there is no limit to the wait time.
+       Return the exception raised by the call.  If the call hasn't yet
+       completed then this method will wait up to *timeout* seconds.  If the
+       call hasn't completed in *timeout* seconds, then a :exc:`TimeoutError`
+       will be raised.  *timeout* can be an int or float.  If *timeout* is not
+       specified or ``None``, there is no limit to the wait time.
 
        If the future is cancelled before completing then :exc:`CancelledError`
        will be raised.
@@ -280,16 +280,16 @@ The :class:`Future` class encapulates the asynchronous execution of a callable.
     .. method:: set_running_or_notify_cancel()
 
        This method should only be called by :class:`Executor` implementations
-       before executing the work associated with the :class:`Future` and by
-       unit tests.
+       before executing the work associated with the :class:`Future` and by unit
+       tests.
 
-       If the method returns `False` then the :class:`Future` was cancelled i.e.
-       :meth:`Future.cancel` was called and returned `True`. Any threads waiting
-       on the :class:`Future` completing (i.e. through :func:`as_completed` or
-       :func:`wait`) will be woken up.
+       If the method returns `False` then the :class:`Future` was cancelled,
+       i.e. :meth:`Future.cancel` was called and returned `True`.  Any threads
+       waiting on the :class:`Future` completing (i.e. through
+       :func:`as_completed` or :func:`wait`) will be woken up.
 
        If the method returns `True` then the :class:`Future` was not cancelled
-       and has been put in the running state i.e. calls to
+       and has been put in the running state, i.e. calls to
        :meth:`Future.running` will return `True`.
 
        This method can only be called once and cannot be called after
@@ -314,7 +314,7 @@ The :class:`Future` class encapulates the asynchronous execution of a callable.
 
 
 Module Functions
-^^^^^^^^^^^^^^^^
+----------------
 
 .. function:: wait(fs, timeout=None, return_when=ALL_COMPLETED)
 
@@ -325,8 +325,8 @@ Module Functions
    set, named ``not_done``, contains uncompleted futures.
 
    *timeout* can be used to control the maximum number of seconds to wait before
-   returning. *timeout* can be an int or float. If *timeout* is not specified or
-   ``None``, there is no limit to the wait time.
+   returning.  *timeout* can be an int or float.  If *timeout* is not specified
+   or ``None``, there is no limit to the wait time.
 
    *return_when* indicates when this function should return.  It must be one of
    the following constants:
@@ -351,9 +351,16 @@ Module Functions
 
    Returns an iterator over the :class:`Future` instances (possibly created by
    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
+   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.
+
+
+.. seealso::
+
+   :pep:`3148` -- futures - execute computations asynchronously
+      The proposal which described this feature for inclusion in the Python
+      standard library.