[docs] [issue13237] subprocess docs should emphasise convenience functions

Nick Coghlan report at bugs.python.org
Thu Oct 27 10:06:27 CEST 2011


Nick Coghlan <ncoghlan at gmail.com> added the comment:

As the last checkin message says, I've made the documentation for the helper functions more self-contained. Each now has its own short "shell=True" warning with a pointer to the full explanation in the shared parameter description. There was also a copy-and-paste error in the Popen docs where the cross-reference for "shell=True" was a note rather than a warning, so I fixed that.

For the helper functions, people are unlikely to pass in "stdout=PIPE" or "stderr=PIPE" in the first place, since there's no point (you can't get at the Popen object, so you can't at the streams in order to read from them). Accordingly, I downgraded the relevant boxes to be notes rather than warnings (the boxes down near Popen.wait() and the data attribute descriptions remain warnings).

The latest version also uses the "keyword only" syntax for all three helper functions, but describes them with the following text in each case:

=========
The arguments shown above are merely the most common ones, described below in :ref:`frequently-used-arguments` (hence the slightly odd notation in the abbreviated signature).
=========

For 3.x, I'll reword that to:

=========
The arguments shown above are merely the most common ones, described below in :ref:`frequently-used-arguments` (hence the use of keyword only argument notation in the abbreviated signature).
=========

----------

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


More information about the docs mailing list