traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Some cleanup of the subprocess docs in 2.7. Adds a reference to the 

subprocess32 project in PyPI for posix users.
This commit is contained in:
Gregory P. Smith 2014-04-15 07:59:44 -07:00
parent 7fc8a10577
commit 8f813fe2f2
1 changed files with 30 additions and 29 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

59
Doc/library/subprocess.rst
View File

@ -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: