[issue27050] Demote run() below the high level APIs in subprocess docs

[Nick Coghlan]

Nick Coghlan added the comment:

For reference, http://bugs.python.org/issue13237 covers the original change to emphasise the convenience functions over the full flexibility of Popen. The intent behind that reorganisation was to make it straightforward to get started with the module without needing to first learn what a pipe is (or much of anything about command invocation other than the value of breaking things up into lists to ensure correct quoting). The direct link to the Popen docs in the introductory text was intended to make it easy for advanced users to skip directly to the full Popen docs.

In that context, the three convenience operations are "I don't really care if this works or not", "complain loudly if this doesn't work" and "capture the command output, while complaining loudly if it doesn't work". (Not coincidentally, these are roughly comparable to the operations supported by Perl's system() command and backtick expressions, only with exceptions taking the place of the "$?" magic variable)

Once a user understands what a pipe is well enough to have an opinion on the usefulness of operations other than the 3 basic ones, then I agree run() makes for a nice improvement over using Popen objects directly (thank you Thomas!), but it's still lower level than the convenience APIs (since you need more prior knowledge in order to use it effectively).

I do like David's suggestion of an introductory table providing quick links to the rest of the documentation. Something in the style of the itertools docs would likely be most suitable: https://docs.python.org/3/library/itertools.html

Also +1 on thrashing out the details at the PyCon US sprints, although I'll aim to put an initial draft together before then (so Thomas has a chance to comment on it)

----------

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue27050>
_______________________________________