edit concurrent.future docs

Doc/library/concurrent.futures.rst

@@ -7,28 +7,24 @@
 The :mod:`concurrent.futures` module provides a high-level interface for
 asynchronously executing callables.
 
-The asynchronous execution can be be performed by threads using
+The asynchronous execution can be be performed with threads, using
-:class:`ThreadPoolExecutor` or seperate processes using
+:class:`ThreadPoolExecutor`, or seperate processes, using
 :class:`ProcessPoolExecutor`. Both implement the same interface, which is
 defined by the abstract :class:`Executor` class.
 
 Executor Objects
 ^^^^^^^^^^^^^^^^
 
-:class:`Executor` is an abstract class that provides methods to execute calls
+.. class:: Executor
-asynchronously. It should not be used directly, but through its two
-subclasses: :class:`ThreadPoolExecutor` and :class:`ProcessPoolExecutor`.
-
-.. class:: Executor()
 
    An abstract class that provides methods to execute calls asynchronously. It
-   should not be used directly, but through its two subclasses:
+   should not be used directly, but through its concrete subclasses.
-   :class:`ThreadPoolExecutor` and :class:`ProcessPoolExecutor`.
 
     .. method:: submit(fn, *args, **kwargs)
 
-       Schedules the callable to be executed as *fn*(*\*args*, *\*\*kwargs*) and
+       Schedules the callable, *fn*, to be executed as ``fn(*args **kwargs)``
-       returns a :class:`Future` representing the execution of the callable.
+       and returns a :class:`Future` object representing the execution of the
+       callable.
 
        ::
 
@@ -38,14 +34,14 @@ subclasses: :class:`ThreadPoolExecutor` and :class:`ProcessPoolExecutor`.
 
     .. method:: map(func, *iterables, timeout=None)
 
-       Equivalent to `map(*func*, *\*iterables*)` but func is executed
+       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
+       original call to :meth:`Executor.map`. *timeout* can be an int or a
-       float. If *timeout* is not specified or ``None`` then there is no limit
+       float. If *timeout* is not specified or ``None``, there is no limit to
-       to the wait time. If a call raises an exception then that exception will
+       the wait time. If a call raises an exception, then that exception will be
-       be raised when its value is retrieved from the iterator.
+       raised when its value is retrieved from the iterator.
 
     .. method:: shutdown(wait=True)
 
@@ -54,11 +50,11 @@ subclasses: :class:`ThreadPoolExecutor` and :class:`ProcessPoolExecutor`.
        :meth:`Executor.submit` and :meth:`Executor.map` made after shutdown will
        raise :exc:`RuntimeError`.
 
-       If *wait* is `True` then this method will not return until all the
+       If *wait* is ``True`` then this method will not return until all the
        pending futures are done executing and the resources associated with the
-       executor have been freed. If *wait* is `False` then this method will
+       executor have been freed. If *wait* is ``False`` then this method will
-       return immediately and the resources associated with the executor will
+       return immediately and the resources associated with the executor will be
-       be freed when all pending futures are done executing. Regardless of the
+       freed when all pending futures are done executing. Regardless of the
        value of *wait*, the entire Python program will not exit until all
        pending futures are done executing.
 
@@ -78,10 +74,10 @@ subclasses: :class:`ThreadPoolExecutor` and :class:`ProcessPoolExecutor`.
 ThreadPoolExecutor
 ^^^^^^^^^^^^^^^^^^
 
-The :class:`ThreadPoolExecutor` class is an :class:`Executor` subclass that uses
+:class:`ThreadPoolExecutor` is a :class:`Executor` subclass that uses a pool of
-a pool of threads to execute calls asynchronously.
+threads to execute calls asynchronously.
 
-Deadlock can occur when the callable associated with a :class:`Future` waits on
+Deadlocks can occur when the callable associated with a :class:`Future` waits on
 the results of another :class:`Future`. For example:
 
 ::
@@ -121,9 +117,6 @@ And:
    An :class:`Executor` subclass that uses a pool of at most *max_workers*
    threads to execute calls asynchronously.
 
-   Deadlock can occur when the callable associated with a :class:`Future` waits
-   on the results of another :class:`Future`.
-
 .. _threadpoolexecutor-example:
 
 ThreadPoolExecutor Example
@@ -169,10 +162,9 @@ to a :class:`ProcessPoolExecutor` will result in deadlock.
 
 .. class:: ProcessPoolExecutor(max_workers=None)
 
-   An :class:`Executor` subclass that executes calls asynchronously using a
+   An :class:`Executor` subclass that executes calls asynchronously using a pool
-   pool of at most *max_workers* processes. If *max_workers* is ``None`` or
+   of at most *max_workers* processes. If *max_workers* is ``None`` or not
-   not given then as many worker processes will be created as the machine has
+   given, it will default to the number of processors on the machine.
-   processors.
 
 .. _processpoolexecutor-example:
 
@@ -215,7 +207,7 @@ Future Objects
 The :class:`Future` class encapulates the asynchronous execution of a callable.
 :class:`Future` instances are created by :meth:`Executor.submit`.
 
-.. class:: Future()
+.. class:: Future
 
    Encapulates the asynchronous execution of a callable. :class:`Future`
    instances are created by :meth:`Executor.submit` and should not be created
@@ -223,48 +215,49 @@ The :class:`Future` class encapulates the asynchronous execution of a callable.
 
     .. method:: cancel()
 
-       Attempt to cancel the call. If the call is currently being executed then
+       Attempt to cancel the call. If the call is currently being executed and
-       it cannot be cancelled and the method will return `False`, otherwise the
+       cannot be cancelled and the method will return ``False``, otherwise the
-       call will be cancelled and the method will return `True`.
+       call will be cancelled and the method will return ``True``.
 
     .. method:: cancelled()
 
-       Return `True` if the call was successfully cancelled.
+       Return ``True`` if the call was successfully cancelled.
 
     .. method:: running()
 
-       Return `True` if the call is currently being executed and cannot be
+       Return ``True`` if the call is currently being executed and cannot be
        cancelled.
 
     .. method:: done()
 
-       Return `True` if the call was successfully cancelled or finished running.
+       Return ``True`` if the call was successfully cancelled or finished
+       running.
 
     .. method:: result(timeout=None)
 
        Return the value returned 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
+       completed in *timeout* seconds, then a :exc:`TimeoutError` will be
-       raised. *timeout* can be an int or float.If *timeout* is not specified
+       raised. *timeout* can be an int or float. If *timeout* is not specified
-       or ``None`` then there is no limit to the wait time.
+       or ``None``, there is no limit to the wait time.
 
        If the future is cancelled before completing then :exc:`CancelledError`
        will be raised.
 
-       If the call raised then this method will raise the same exception.
+       If the call raised, this method will raise the same exception.
 
     .. 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.
+       completed in *timeout* seconds, then a :exc:`TimeoutError` will be
-       *timeout* can be an int or float. If *timeout* is not specified or
+       raised.  *timeout* can be an int or float. If *timeout* is not specified
-       ``None`` then there is no limit to the wait time.
+       or ``None``, there is no limit to the wait time.
 
        If the future is cancelled before completing then :exc:`CancelledError`
        will be raised.
 
-       If the call completed without raising then ``None`` is returned.
+       If the call completed without raising, ``None`` is returned.
 
     .. method:: add_done_callback(fn)
 
@@ -274,11 +267,11 @@ The :class:`Future` class encapulates the asynchronous execution of a callable.
 
        Added callables are called in the order that they were added and are
        always called in a thread belonging to the process that added them. If
-       the callable raises an :exc:`Exception` then it will be logged and
+       the callable raises a :exc:`Exception` subclass, it will be logged and
-       ignored. If the callable raises another :exc:`BaseException` then the
+       ignored. If the callable raises a :exc:`BaseException` subclass, the
-       behavior is not defined.
+       behavior is undefined.
 
-       If the future has already completed or been cancelled then *fn* will be
+       If the future has already completed or been cancelled, *fn* will be
        called immediately.
 
    The following :class:`Future` methods are meant for use in unit tests and
@@ -326,14 +319,14 @@ Module Functions
 .. function:: wait(fs, timeout=None, return_when=ALL_COMPLETED)
 
    Wait for the :class:`Future` instances (possibly created by different
-   :class:`Executor` instances) given by *fs*  to complete. Returns a named
+   :class:`Executor` instances) given by *fs* to complete. Returns a named
-   2-tuple of sets. The first set, named "done", contains the futures that
+   2-tuple of sets. The first set, named ``done``, contains the futures that
    completed (finished or were cancelled) before the wait completed. The second
-   set, named "not_done", contains uncompleted futures.
+   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`` then there is no limit to the wait time.
+   ``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:
@@ -348,7 +341,7 @@ Module Functions
       |                             | future finishes by raising an          |
       |                             | exception. If no future raises an      |
       |                             | exception then it is equivalent to     |
-      |                             | `ALL_COMPLETED`.                       |
+      |                             | :const:`ALL_COMPLETED`.                |
       +-----------------------------+----------------------------------------+
       | :const:`ALL_COMPLETED`      | The function will return when all      |
       |                             | futures finish or are cancelled.       |
@@ -356,11 +349,11 @@ Module Functions
 
 .. function:: as_completed(fs, timeout=None)
 
-   Returns an iterator over the :class:`Future` instances  (possibly created
+   Returns an iterator over the :class:`Future` instances (possibly created by
-   by different :class:`Executor` instances) given by *fs* that yields futures
+   different :class:`Executor` instances) given by *fs* that yields futures as
-   as they complete (finished or were cancelled). Any futures that completed
+   they complete (finished or were cancelled). Any futures that completed before
-   before :func:`as_completed()` was called will be yielded first. The returned
+   :func:`as_completed` is called will be yielded first. The returned iterator
-   iterator raises a :exc:`TimeoutError` if :meth:`__next__()` is called and
+   raises a :exc:`TimeoutError` if :meth:`__next__` is called and the result
-   the result isn't available after *timeout* seconds from the original call
+   isn't available after *timeout* seconds from the original call to
-   to :func:`as_completed()`. *timeout* can be an int or float. If *timeout*
+   :func:`as_completed`. *timeout* can be an int or float. If *timeout* is not
-   is not specified or ``None`` then there is no limit to the wait time.
+   specified or ``None``, there is no limit to the wait time.