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

Issue #13237: Make the subprocess convenience helper documentation self-contained aside from the shared parameter description. Downgrade the pipe warnings at that level to notes (since those pipes are hidden, people are unlikely to even try it)

This commit is contained in:
Nick Coghlan 2011-10-27 17:55:13 +10:00
parent 6d089df1b8
commit 87ba642ce6
1 changed files with 42 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

52
Doc/library/subprocess.rst
View File

@ -42,9 +42,10 @@ use cases, the underlying :class:`Popen` interface can be used directly.
return the :attr:`returncode` attribute. return the :attr:`returncode` attribute.
The arguments shown above are merely the most common ones, described below The arguments shown above are merely the most common ones, described below
in :ref:`frequently-used-arguments`. The full function signature is the in :ref:`frequently-used-arguments` (hence the slightly odd notation in
same as that of the :class:`Popen` constructor - the convenience functions the abbreviated signature). The full function signature is the same as
pass all supplied arguments directly through to that interface. that of the :class:`Popen` constructor - this functions passes all
supplied arguments directly through to that interface.
Examples:: Examples::
@ -56,20 +57,32 @@ use cases, the underlying :class:`Popen` interface can be used directly.
.. warning:: .. 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.
.. note::
Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this function. As Do not use ``stdout=PIPE`` or ``stderr=PIPE`` with this function. As
the pipes are not being read in the current process, the child 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 process may block if it generates enough output to a pipe to fill up
the OS pipe buffer. the OS pipe buffer.
.. function:: check_call(*callargs, **kwargs) .. function:: check_call(args, *, stdin=None, stdout=None, stderr=None, shell=False)
Run command with arguments. Wait for command to complete. If the return Run command with arguments. Wait for command to complete. If the return
code was zero then return, otherwise raise :exc:`CalledProcessError`. The code was zero then return, otherwise raise :exc:`CalledProcessError`. The
:exc:`CalledProcessError` object will have the return code in the :exc:`CalledProcessError` object will have the return code in the
:attr:`returncode` attribute. :attr:`returncode` attribute.
The arguments are the same as for :func:`call`. Examples:: 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). The full function signature is the same as
that of the :class:`Popen` constructor - this functions passes all
supplied arguments directly through to that interface.
Examples::
>>> subprocess.check_call(["ls", "-l"]) >>> subprocess.check_call(["ls", "-l"])
0 0
@ -83,10 +96,19 @@ use cases, the underlying :class:`Popen` interface can be used directly.
.. warning:: .. warning::
See the warning for :func:`call`. 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.
.. 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.
.. function:: check_output(*callargs, **kwargs) .. function:: check_output(args, *, stdin=None, stderr=None, shell=False, universal_newlines=False)
Run command with arguments and return its output as a byte string. Run command with arguments and return its output as a byte string.
@ -95,8 +117,12 @@ use cases, the underlying :class:`Popen` interface can be used directly.
:attr:`returncode` attribute and any output in the :attr:`output` :attr:`returncode` attribute and any output in the :attr:`output`
attribute. attribute.
The arguments are the same as for :func:`call`, except that *stdout* is The arguments shown above are merely the most common ones, described below
not permitted as it is used internally. in :ref:`frequently-used-arguments` (hence the slightly odd notation in
the abbreviated signature). The full function signature is largely the
same as that of the :class:`Popen` constructor, except that *stdout* is
not permitted as it is used internally. All other supplied arguments are
passed directly through to the :class:`Popen` constructor.
Examples:: Examples::
@ -121,6 +147,12 @@ use cases, the underlying :class:`Popen` interface can be used directly.
.. warning:: .. 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.
.. note::
Do not use ``stderr=PIPE`` with this function. As the pipe is not being 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 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. generates enough output to the pipe to fill up the OS pipe buffer.
@ -306,7 +338,7 @@ functions.
If *shell* is :const:`True`, the specified command will be executed through the If *shell* is :const:`True`, the specified command will be executed through the
shell. shell.
.. note:: .. warning::
Enabling this option can be a security hazard if combined with untrusted Enabling this option can be a security hazard if combined with untrusted
input. See the warning under :ref:`frequently-used-arguments` input. See the warning under :ref:`frequently-used-arguments`