[Python-ideas] Executor Docs [was: Re: Add an introspection API to Executor]

[Ethan Furman]

On 08/25/2014 09:37 PM, Antoine Pitrou wrote:
> Le 26/08/2014 00:22, Ethan Furman a écrit :
>>
>> I went in search of docs to see what the API actually was, and while I
>> know the source code is a great place to go look for education and finer
>> points, should we have to go looking there just to see what the __init__
>> parameters are?
>
> So, you didn't find the docs?
>
> https://docs.python.org/3/library/concurrent.futures.html#threadpoolexecutor
>
> """
> class concurrent.futures.ThreadPoolExecutor(max_workers)
>
>      An Executor subclass that uses a pool of at most max_workers threads to execute calls asynchronously.
> """
>
> https://docs.python.org/3/library/concurrent.futures.html#processpoolexecutor
>
> """
> class concurrent.futures.ProcessPoolExecutor(max_workers=None)
>
>      An Executor subclass that executes calls asynchronously using a pool 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.
> """

I did find the docs, and even with your plain text guide I almost didn't see them when I looked just now.  Too much 
fancy going on there, and all the green examples -- yeah, it's hard to read.

For comparison, here's what help(ThreadPoolExecutor) shows:

class ThreadPoolExecutor(concurrent.futures._base.Executor)
  |  Method resolution order:
  |      ThreadPoolExecutor
  |      concurrent.futures._base.Executor
  |      builtins.object
  |
  |  Methods defined here:
  |
  |  __init__(self, max_workers)
  |      Initializes a new ThreadPoolExecutor instance.
  |
  |      Args:
  |          max_workers: The maximum number of threads that can be used to
  |              execute the given calls.
  |
  |  shutdown(self, wait=True)
  |      Clean-up the resources associated with the Executor.
  |
  |      It is safe to call this method several times. Otherwise, no other
  |      methods can be called after this one.
  |
  |      Args:
  |          wait: If True then shutdown will not return until all running
  |              futures have finished executing and the resources used by the
  |              executor have been reclaimed.
  |
  |  submit(self, fn, *args, **kwargs)
  |      Submits a callable to be executed with the given arguments.
  |
  |      Schedules the callable to be executed as fn(*args, **kwargs) and returns
  |      a Future instance representing the execution of the callable.
  |
  |      Returns:
  |          A Future representing the given call.


Much easier to understand.

Looking at the docs again, I think the biggest hurdle to finding that line and recognizing it for what it is is the fact 
that it comes /after/ all the examples.  That's backwards.  Why would you need examples for something you haven't read yet?

--
~Ethan~