bpo-17140: Document multiprocessing's ThreadPool

[godlygeek]

Up until now the multiprocessing.pool.ThreadPool class has gone
undocumented, despite being a public class in multiprocessing that is
included in multiprocessing.pool.__all__.

https://bugs.python.org/issue17140

[Fidget-Spinner]

This LGTM. The only comment I have is that it seems strange to place ThreadPool under the Process Pools section, though I understand that it makes sense since it's a subclass of Pool. Maybe we can create a Thread Pools subsection for it. What do you think?

[godlygeek]

I almost did that, and don't mind changing it to be that way if you prefer. Would you like the new section directly below the "Process Pools" section?

I also considered putting it in the "The :mod:multiprocessing.dummy module" section, which is slightly weird since it's in multiprocessing.pool, but also is arguably the place where it best belongs since it is related to the "multiprocessing but with threads instead of processes" thing that multiprocessing.dummy does, and because multiprocessing.dummy.Pool does return ThreadPool instances (though it is a wrapper function around multiprocessing.Pool.ThreadPool for some reason, not an alias for it).

[Fidget-Spinner]

I almost did that, and don't mind changing it to be that way if you prefer. Would you like the new section directly below the "Process Pools" section?

Hmm I think, I'll wait and see what the core dev who reviews this prefers. Thanks for working on this :).

[godlygeek]

@pablogsal OK, I've force-pushed a new commit that yanks it down into the multiprocessing.dummy section, and explains that ThreadPoolExecutor is generally preferable. Take a look and let me know if you think there's anything else it needs, please.

[pablogsal]

LGTM

I will leave some days in case Antoine has time to review this before landing in case he has some new insights or he wants some changes.

[godlygeek]

I just made one final change - I had the note about preferring ThreadPoolExecutor above the class definition, and I've moved it down into the documentation for the class instead.

[godlygeek]

One more force push - I noticed a missing word after re-reading this.

[pablogsal]

One more force push - I noticed a missing word after re-reading this.

Note the there is no need for force pushes: the commits will be squashed and the core Dev merging will write the final commit anyway.

[pitrou]

This is fine with me. Thanks for reviewing @pablogsal !

[miss-islington]

Thanks @godlygeek for the PR, and @pablogsal for merging it 🌮🎉.. I'm working now to backport this PR to: 3.7, 3.8, 3.9.
🐍🍒⛏🤖

[bedevere-bot]

GH-23834 is a backport of this pull request to the 3.9 branch.

[bedevere-bot]

GH-23835 is a backport of this pull request to the 3.8 branch.

[bedevere-bot]

GH-23836 is a backport of this pull request to the 3.7 branch.