changeset: 80009:d9ca966cd116 branch: 2.7 parent: 80004:06b2a8c91ba5 user: Andrew Svetlov date: Sun Oct 28 11:48:02 2012 +0200 files: Doc/library/pipes.rst Doc/library/subprocess.rst description: Issue #14616: Document pipes.quote and mention this one in subprocess docs. Patch by Chris Rebert. diff -r 06b2a8c91ba5 -r d9ca966cd116 Doc/library/pipes.rst --- a/Doc/library/pipes.rst Sun Oct 28 10:12:47 2012 +0100 +++ b/Doc/library/pipes.rst Sun Oct 28 11:48:02 2012 +0200 @@ -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 ` 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 -r 06b2a8c91ba5 -r d9ca966cd116 Doc/library/subprocess.rst --- a/Doc/library/subprocess.rst Sun Oct 28 10:12:47 2012 +0100 +++ b/Doc/library/subprocess.rst Sun Oct 28 11:48:02 2012 +0200 @@ -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.