From 8f813fe2f2932fb03ce8b1b5eb96168f1f3a5bc4 Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Tue, 15 Apr 2014 07:59:44 -0700 Subject: [PATCH] Some cleanup of the subprocess docs in 2.7. Adds a reference to the subprocess32 project in PyPI for posix users. --- Doc/library/subprocess.rst | 59 +++++++++++++++++++------------------- 1 file changed, 30 insertions(+), 29 deletions(-) diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst index 9eba597341..54149ebf54 100644 --- a/Doc/library/subprocess.rst +++ b/Doc/library/subprocess.rst @@ -20,20 +20,26 @@ replace several older modules and functions:: popen2.* commands.* -Information about how the :mod:`subprocess` module can be used to replace these -modules and functions can be found in the following sections. +Information about how this module can be used to replace the older +functions can be found in the subprocess-replacements_ section. .. seealso:: + POSIX users (Linux, BSD, etc.) are strongly encouraged to install + and use the much more recent subprocess32_ module instead of the + version included with python 2.7. It is a drop in replacement with + better behavior in many situations. + :pep:`324` -- PEP proposing the subprocess module +.. _subprocess32: https://pypi.python.org/pypi/subprocess32/ Using the :mod:`subprocess` Module ---------------------------------- -The recommended approach to invoking subprocesses is to use the following -convenience functions for all use cases they can handle. For more advanced -use cases, the underlying :class:`Popen` interface can be used directly. +The recommended way to launch subprocesses is to use the following +convenience functions. For more advanced use cases when these do not +meet your needs, use the underlying :class:`Popen` interface. .. function:: call(args, *, stdin=None, stdout=None, stderr=None, shell=False) @@ -57,16 +63,15 @@ use cases, the underlying :class:`Popen` interface can be used directly. .. warning:: - Invoking the system shell with ``shell=True`` can be a security hazard - if combined with untrusted input. See the warning under - :ref:`frequently-used-arguments` for details. + Using ``shell=True`` can be a security hazard. See the warning + under :ref:`frequently-used-arguments` for details. .. note:: - Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this function. As - the pipes are not being read in the current process, the child - process may block if it generates enough output to a pipe to fill up - the OS pipe buffer. + Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this function + as that can deadlock based on the child process output volume. + Use :class:`Popen` with the :meth:`communicate` method when you + need pipes. .. function:: check_call(args, *, stdin=None, stdout=None, stderr=None, shell=False) @@ -96,16 +101,15 @@ use cases, the underlying :class:`Popen` interface can be used directly. .. warning:: - Invoking the system shell with ``shell=True`` can be a security hazard - if combined with untrusted input. See the warning under - :ref:`frequently-used-arguments` for details. + Using ``shell=True`` can be a security hazard. See the warning + under :ref:`frequently-used-arguments` for details. .. note:: - Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this function. As - the pipes are not being read in the current process, the child - process may block if it generates enough output to a pipe to fill up - the OS pipe buffer. + Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this function + as that can deadlock based on the child process output volume. + Use :class:`Popen` with the :meth:`communicate` method when you + need pipes. .. function:: check_output(args, *, stdin=None, stderr=None, shell=False, universal_newlines=False) @@ -145,19 +149,16 @@ use cases, the underlying :class:`Popen` interface can be used directly. .. versionadded:: 2.7 - .. - .. warning:: - Invoking the system shell with ``shell=True`` can be a security hazard - if combined with untrusted input. See the warning under - :ref:`frequently-used-arguments` for details. + Using ``shell=True`` can be a security hazard. See the warning + under :ref:`frequently-used-arguments` for details. .. note:: - Do not use ``stderr=PIPE`` with this function. As the pipe is not being - read in the current process, the child process may block if it - generates enough output to the pipe to fill up the OS pipe buffer. + Do not use ``stderr=PIPE`` with this function as that can deadlock + based on the child process error volume. Use :class:`Popen` with + the :meth:`communicate` method when you need a stderr pipe. .. data:: PIPE @@ -740,9 +741,9 @@ Replacing :func:`os.system` :: - sts = os.system("mycmd" + " myarg") + status = os.system("mycmd" + " myarg") # becomes - sts = call("mycmd" + " myarg", shell=True) + status = subprocess.call("mycmd" + " myarg", shell=True) Notes: -- 2.50.1