Changeset 391 for python/trunk/Doc/library/pipes.rst

Timestamp:

Mar 19, 2014, 11:31:01 PM (11 years ago)

Author:

dmik

Message:

python: Merge vendor 2.7.6 to trunk.

Location:

python/trunk

Files:

• . (modified) (1 prop)
• Doc/library/pipes.rst (modified) (4 diffs)

python/trunk/Doc/library/pipes.rst

@@ -1 @@
-
 :mod:`pipes` --- Interface to shell pipelines
 =============================================
@@ -8 +7 @@
 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
 
+**Source code:** :source:`Lib/pipes.py`
+
+--------------
 
 The :mod:`pipes` module defines a class to abstract the concept of a *pipeline*
@@ -14 +16 @@
 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:
 
 
@@ -25 +25 @@
 
    >>> import pipes
-   >>> t=pipes.Template()
+   >>> t = pipes.Template()
    >>> t.append('tr a-z A-Z', '--')
-   >>> f=t.open('/tmp/1', 'w')
+   >>> f = t.open('pipefile', 'w')
    >>> f.write('hello world')
    >>> f.close()
-   >>> open('/tmp/1').read()
+   >>> open('pipefile').read()
    'HELLO WORLD'
+
+
+.. function:: quote(s)
+
+   .. deprecated:: 2.7
+      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 ~']