[Python-checkins] cpython (3.4): Remove the warning-soup from the subprocess documentation by adding

Sun May 11 22:29:44 CEST 2014

http://hg.python.org/cpython/rev/ccdc70b66bd5
changeset: 90641:ccdc70b66bd5
branch: 3.4
parent: 90639:2e26703d7d2a
user: Gregory P. Smith <greg at krypto.org>
date: Sun May 11 13:26:21 2014 -0700
summary:
 Remove the warning-soup from the subprocess documentation by adding
a Security Considerations section as preferred by both the devguide
and documentation users who do not wish to go insane.
files:
 Doc/library/subprocess.rst | 127 +++++++++---------------
 1 files changed, 48 insertions(+), 79 deletions(-)

diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -54,18 +54,12 @@
 >>> subprocess.call("exit 1", shell=True)
 1
 
- .. 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
- 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. The child process will block if it generates enough
+ output to a pipe to fill up the OS pipe buffer as the pipes are
+ not being read from.
 
 .. versionchanged:: 3.3
 *timeout* was added.
@@ -99,18 +93,12 @@
 ...
 subprocess.CalledProcessError: Command 'exit 1' returned non-zero exit status 1
 
- .. 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
- 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. The child process will block if it generates enough
+ output to a pipe to fill up the OS pipe buffer as the pipes are
+ not being read from.
 
 .. versionchanged:: 3.3
 *timeout* was added.
@@ -177,17 +165,12 @@
 ... shell=True)
 'ls: non_existent_file: No such file or directory\n'
 
- .. 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
- 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 ``stdout=PIPE`` or ``stderr=PIPE`` with this
+ function. The child process will block if it generates enough
+ output to a pipe to fill up the OS pipe buffer as the pipes are
+ not being read from.
 
 .. versionadded:: 3.1
 
@@ -210,7 +193,7 @@
 
 Special value that can be used as the *stdin*, *stdout* or *stderr* argument
 to :class:`Popen` and indicates that a pipe to the standard stream should be
- opened.
+ opened. Most useful with :meth:`Popen.communicate`.
 
 
 .. data:: STDOUT
@@ -336,28 +319,9 @@
 instead of ``locale.getpreferredencoding()``. See the
 :class:`io.TextIOWrapper` class for more information on this change.
 
- .. warning::
+ .. note::
 
- Executing shell commands that incorporate unsanitized input from an
- untrusted source makes a program vulnerable to `shell injection
- <http://en.wikipedia.org/wiki/Shell_injection#Shell_injection>`_,
- a serious security flaw which can result in arbitrary command execution.
- For this reason, the use of ``shell=True`` is **strongly discouraged**
- in cases where the command string is constructed from external input::
-
- >>> from subprocess import call
- >>> filename = input("What file would you like to display?\n")
- What file would you like to display?
- non_existent; rm -rf / #
- >>> call("cat " + filename, shell=True) # Uh-oh. This will end badly...
-
- ``shell=False`` disables all shell based features, but does not suffer
- from this vulnerability; see the Note in the :class:`Popen` constructor
- documentation for helpful hints in getting ``shell=False`` to work.
-
- When using ``shell=True``, :func:`shlex.quote` can be used to properly
- escape whitespace and shell metacharacters in strings that are going to
- be used to construct shell commands.
+ Read the `Security Considerations`_ section before using ``shell=True``.
 
 These options, along with all of the other options, are described in more
 detail in the :class:`Popen` constructor documentation.
@@ -438,11 +402,9 @@
 into the shell (e.g. :command:`dir` or :command:`copy`). You do not need
 ``shell=True`` to run a batch file or console-based executable.
 
- .. warning::
+ .. note::
 
- Passing ``shell=True`` can be a security hazard if combined with
- untrusted input. See the warning under :ref:`frequently-used-arguments`
- for details.
+ Read the `Security Considerations`_ section before using ``shell=True``.
 
 *bufsize* will be supplied as the corresponding argument to the :func:`open`
 function when creating the stdin/stdout/stderr pipe file objects: :const:`0`
@@ -598,14 +560,21 @@
 The :exc:`SubprocessError` base class was added.
 
 
-Security
-^^^^^^^^
+Security Considerations
+-----------------------
 
-Unlike some other popen functions, this implementation will never call a
-system shell implicitly. This means that all characters, including shell
-metacharacters, can safely be passed to child processes. Obviously, if the
-shell is invoked explicitly, then it is the application's responsibility to
-ensure that all whitespace and metacharacters are quoted appropriately.
+Unlike some other popen functions, this implementation will never
+implicitly call a system shell. This means that all characters,
+including shell metacharacters, can safely be passed to child processes.
+If the shell is invoked explicitly, via ``shell=True``, it is the application's
+responsibility to ensure that all whitespace and metacharacters are
+quoted appropriately to avoid
+`shell injection <http://en.wikipedia.org/wiki/Shell_injection#Shell_injection>`_
+vulnerabilities.
+
+When using ``shell=True``, the :func:`shlex.quote` function can be
+used to properly escape whitespace and shell metacharacters in strings
+that are going to be used to construct shell commands.
 
 
 Popen Objects
@@ -631,25 +600,25 @@
 
 .. note::
 
+ This will deadlock when using ``stdout=PIPE`` or ``stderr=PIPE``
+ and the child process generates enough output to a pipe such that
+ it blocks waiting for the OS pipe buffer to accept more data.
+ Use :meth:`Popen.communicate` when using pipes to avoid that.
+
+ .. note::
+
 The function is implemented using a busy loop (non-blocking call and
 short sleeps). Use the :mod:`asyncio` module for an asynchronous wait:
 see :class:`asyncio.create_subprocess_exec`.
 
- .. warning::
-
- This will deadlock when using ``stdout=PIPE`` and/or
- ``stderr=PIPE`` and the child process generates enough output to
- a pipe such that it blocks waiting for the OS pipe buffer to
- accept more data. Use :meth:`communicate` to avoid that.
-
 .. versionchanged:: 3.3
 *timeout* was added.
 
 .. deprecated:: 3.4
 
- Do not use the undocumented *endtime* parameter. It is was
- unintentionally exposed in 3.3 but was intended to be private
- for internal use. Use *timeout* instead.
+ Do not use the *endtime* parameter. It is was unintentionally
+ exposed in 3.3 but was left undocumented as it was intended to be
+ private for internal use. Use *timeout* instead.
 
 .. method:: Popen.communicate(input=None, timeout=None)
 
@@ -716,13 +685,6 @@
 
 The following attributes are also available:
 
-.. warning::
-
- Use :meth:`~Popen.communicate` rather than :attr:`.stdin.write <Popen.stdin>`,
- :attr:`.stdout.read <Popen.stdout>` or :attr:`.stderr.read <Popen.stderr>` to avoid
- deadlocks due to any of the other OS pipe buffers filling up and blocking the
- child process.
-
 .. attribute:: Popen.args
 
 The *args* argument as it was passed to :class:`Popen` -- a
@@ -756,6 +718,13 @@
 ``True``, the stream is a text stream, otherwise it is a byte stream. If the
 *stderr* argument was not :data:`PIPE`, this attribute is ``None``.
 
+.. warning::
+
+ Use :meth:`~Popen.communicate` rather than :attr:`.stdin.write <Popen.stdin>`,
+ :attr:`.stdout.read <Popen.stdout>` or :attr:`.stderr.read <Popen.stderr>` to avoid
+ deadlocks due to any of the other OS pipe buffers filling up and blocking the
+ child process.
+
 
 .. attribute:: Popen.pid
 
-- 
Repository URL: http://hg.python.org/cpython
