1:mod:`pipes` --- Interface to shell pipelines 2============================================= 3 4.. module:: pipes 5 :platform: Unix 6 :synopsis: A Python interface to Unix shell pipelines. 7.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il> 8 9**Source code:** :source:`Lib/pipes.py` 10 11-------------- 12 13The :mod:`pipes` module defines a class to abstract the concept of a *pipeline* 14--- a sequence of converters from one file to another. 15 16Because the module uses :program:`/bin/sh` command lines, a POSIX or compatible 17shell for :func:`os.system` and :func:`os.popen` is required. 18 19 20.. class:: Template() 21 22 An abstraction of a pipeline. 23 24Example:: 25 26 >>> import pipes 27 >>> t = pipes.Template() 28 >>> t.append('tr a-z A-Z', '--') 29 >>> f = t.open('pipefile', 'w') 30 >>> f.write('hello world') 31 >>> f.close() 32 >>> open('pipefile').read() 33 'HELLO WORLD' 34 35 36.. function:: quote(s) 37 38 .. deprecated:: 2.7 39 Prior to Python 2.7, this function was not publicly documented. It is 40 finally exposed publicly in Python 3.3 as the 41 :func:`quote <shlex.quote>` function in the :mod:`shlex` module. 42 43 Return a shell-escaped version of the string *s*. The returned value is a 44 string that can safely be used as one token in a shell command line, for 45 cases where you cannot use a list. 46 47 This idiom would be unsafe:: 48 49 >>> filename = 'somefile; rm -rf ~' 50 >>> command = 'ls -l {}'.format(filename) 51 >>> print command # executed by a shell: boom! 52 ls -l somefile; rm -rf ~ 53 54 :func:`quote` lets you plug the security hole:: 55 56 >>> command = 'ls -l {}'.format(quote(filename)) 57 >>> print command 58 ls -l 'somefile; rm -rf ~' 59 >>> remote_command = 'ssh home {}'.format(quote(command)) 60 >>> print remote_command 61 ssh home 'ls -l '"'"'somefile; rm -rf ~'"'"'' 62 63 The quoting is compatible with UNIX shells and with :func:`shlex.split`: 64 65 >>> remote_command = shlex.split(remote_command) 66 >>> remote_command 67 ['ssh', 'home', "ls -l 'somefile; rm -rf ~'"] 68 >>> command = shlex.split(remote_command[-1]) 69 >>> command 70 ['ls', '-l', 'somefile; rm -rf ~'] 71 72 73.. _template-objects: 74 75Template Objects 76---------------- 77 78Template objects following methods: 79 80 81.. method:: Template.reset() 82 83 Restore a pipeline template to its initial state. 84 85 86.. method:: Template.clone() 87 88 Return a new, equivalent, pipeline template. 89 90 91.. method:: Template.debug(flag) 92 93 If *flag* is true, turn debugging on. Otherwise, turn debugging off. When 94 debugging is on, commands to be executed are printed, and the shell is given 95 ``set -x`` command to be more verbose. 96 97 98.. method:: Template.append(cmd, kind) 99 100 Append a new action at the end. The *cmd* variable must be a valid bourne shell 101 command. The *kind* variable consists of two letters. 102 103 The first letter can be either of ``'-'`` (which means the command reads its 104 standard input), ``'f'`` (which means the commands reads a given file on the 105 command line) or ``'.'`` (which means the commands reads no input, and hence 106 must be first.) 107 108 Similarly, the second letter can be either of ``'-'`` (which means the command 109 writes to standard output), ``'f'`` (which means the command writes a file on 110 the command line) or ``'.'`` (which means the command does not write anything, 111 and hence must be last.) 112 113 114.. method:: Template.prepend(cmd, kind) 115 116 Add a new action at the beginning. See :meth:`append` for explanations of the 117 arguments. 118 119 120.. method:: Template.open(file, mode) 121 122 Return a file-like object, open to *file*, but read from or written to by the 123 pipeline. Note that only one of ``'r'``, ``'w'`` may be given. 124 125 126.. method:: Template.copy(infile, outfile) 127 128 Copy *infile* to *outfile* through the pipe. 129 130