I stand corrected, the patched docs do look good and are consistent with the warning in "Frequently Used Arguments" section in the subprocess module docs. Just a minor point about linking to subprocess.Popen rather than the subprocess module. http://bugs.python.org/review/21557/diff/13339/Doc/library/os.rst File Doc/library/os.rst (right): http://bugs.python.org/review/21557/diff/13339/Doc/library/os.rst#newcode290... Doc/library/os.rst:2905: .. warning:: Fair points. I also hadn't previously seen the warning in the frequently used arguments section (https://docs.python.org/2/library/subprocess.html#frequently-used-arguments) and do like that this is consistent with it. http://bugs.python.org/review/21557/diff/13339/Doc/library/os.rst#newcode291... Doc/library/os.rst:2913: For greater safety, consider using :mod:`subprocess` with This should point to subprocess.Popen (https://docs.python.org/2/library/subprocess.html#subprocess.Popen) rather than the module, no? http://bugs.python.org/review/21557/