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