/Doc/library/pipes.rst

 1
 2:mod:`pipes` --- Interface to shell pipelines
 3=============================================
 4
 5.. module:: pipes
 6   :platform: Unix
 7   :synopsis: A Python interface to Unix shell pipelines.
 8.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
 9
10
11The :mod:`pipes` module defines a class to abstract the concept of a *pipeline*
12--- a sequence of converters from one file to  another.
13
14Because the module uses :program:`/bin/sh` command lines, a POSIX or compatible
15shell for :func:`os.system` and :func:`os.popen` is required.
16
17The :mod:`pipes` module defines the following class:
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('/tmp/1', 'w')
30   >>> f.write('hello world')
31   >>> f.close()
32   >>> open('/tmp/1').read()
33   'HELLO WORLD'
34
35
36.. _template-objects:
37
38Template Objects
39----------------
40
41Template objects following methods:
42
43
44.. method:: Template.reset()
45
46   Restore a pipeline template to its initial state.
47
48
49.. method:: Template.clone()
50
51   Return a new, equivalent, pipeline template.
52
53
54.. method:: Template.debug(flag)
55
56   If *flag* is true, turn debugging on. Otherwise, turn debugging off. When
57   debugging is on, commands to be executed are printed, and the shell is given
58   ``set -x`` command to be more verbose.
59
60
61.. method:: Template.append(cmd, kind)
62
63   Append a new action at the end. The *cmd* variable must be a valid bourne shell
64   command. The *kind* variable consists of two letters.
65
66   The first letter can be either of ``'-'`` (which means the command reads its
67   standard input), ``'f'`` (which means the commands reads a given file on the
68   command line) or ``'.'`` (which means the commands reads no input, and hence
69   must be first.)
70
71   Similarly, the second letter can be either of ``'-'`` (which means  the command
72   writes to standard output), ``'f'`` (which means the  command writes a file on
73   the command line) or ``'.'`` (which means the command does not write anything,
74   and hence must be last.)
75
76
77.. method:: Template.prepend(cmd, kind)
78
79   Add a new action at the beginning. See :meth:`append` for explanations of the
80   arguments.
81
82
83.. method:: Template.open(file, mode)
84
85   Return a file-like object, open to *file*, but read from or written to by the
86   pipeline.  Note that only one of ``'r'``, ``'w'`` may be given.
87
88
89.. method:: Template.copy(infile, outfile)
90
91   Copy *infile* to *outfile* through the pipe.
92