Issue #14616: Document pipes.quote and mention this one in subprocess docs.

Patch by Chris Rebert.

Doc/library/pipes.rst

@@ -16,8 +16,6 @@ The :mod:`pipes` module defines a class to abstract the concept of a *pipeline*
 Because the module uses :program:`/bin/sh` command lines, a POSIX or compatible
 shell for :func:`os.system` and :func:`os.popen` is required.
 
-The :mod:`pipes` module defines the following class:
-
 
 .. class:: Template()
 
@@ -35,6 +33,43 @@ Example::
    'HELLO WORLD'
 
 
+.. function:: quote(s)
+
+   .. deprecated:: 1.6
+      Prior to Python 2.7, this function was not publicly documented.  It is
+      finally exposed publicly in Python 3.3 as the
+      :func:`quote <shlex.quote>` function in the :mod:`shlex` module.
+
+   Return a shell-escaped version of the string *s*.  The returned value is a
+   string that can safely be used as one token in a shell command line, for
+   cases where you cannot use a list.
+
+   This idiom would be unsafe::
+
+      >>> filename = 'somefile; rm -rf ~'
+      >>> command = 'ls -l {}'.format(filename)
+      >>> print command  # executed by a shell: boom!
+      ls -l somefile; rm -rf ~
+
+   :func:`quote` lets you plug the security hole::
+
+      >>> command = 'ls -l {}'.format(quote(filename))
+      >>> print command
+      ls -l 'somefile; rm -rf ~'
+      >>> remote_command = 'ssh home {}'.format(quote(command))
+      >>> print remote_command
+      ssh home 'ls -l '"'"'somefile; rm -rf ~'"'"''
+
+   The quoting is compatible with UNIX shells and with :func:`shlex.split`:
+
+      >>> remote_command = shlex.split(remote_command)
+      >>> remote_command
+      ['ssh', 'home', "ls -l 'somefile; rm -rf ~'"]
+      >>> command = shlex.split(remote_command[-1])
+      >>> command
+      ['ls', '-l', 'somefile; rm -rf ~']
+
+
 .. _template-objects:
 
 Template Objects

Doc/library/subprocess.rst

@@ -256,6 +256,10 @@ default values. The arguments that are most commonly needed are:
       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:`pipes.quote` can be used to properly
+      escape whitespace and shell metacharacters in strings that are going to
+      be used to construct shell commands.
+
 These options, along with all of the other options, are described in more
 detail in the :class:`Popen` constructor documentation.