[Python-checkins] cpython (2.7): Issue #14616: Document pipes.quote and mention this one in subprocess docs.

[andrew.svetlov]

http://hg.python.org/cpython/rev/d9ca966cd116
changeset:   80009:d9ca966cd116
branch:      2.7
parent:      80004:06b2a8c91ba5
user:        Andrew Svetlov <andrew.svetlov at gmail.com>
date:        Sun Oct 28 11:48:02 2012 +0200
summary:
  Issue #14616: Document pipes.quote and mention this one in subprocess docs.

Patch by Chris Rebert.

files:
  Doc/library/pipes.rst      |  39 ++++++++++++++++++++++++-
  Doc/library/subprocess.rst |   4 ++
  2 files changed, 41 insertions(+), 2 deletions(-)


diff --git a/Doc/library/pipes.rst b/Doc/library/pipes.rst
--- a/Doc/library/pipes.rst
+++ b/Doc/library/pipes.rst
@@ -16,8 +16,6 @@
 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 @@
    '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
diff --git a/Doc/library/subprocess.rst b/Doc/library/subprocess.rst
--- a/Doc/library/subprocess.rst
+++ b/Doc/library/subprocess.rst
@@ -256,6 +256,10 @@
       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.
 

-- 
Repository URL: http://hg.python.org/cpython