blob: 1815e09d57f3f3c5e5eeaba57d45fdd786419a9d [file] [log] [blame]
Fred Drake4755e7d1999-06-21 18:25:49 +00001\section{\module{pipes} ---
2 Interface to shell pipelines}
3
4\declaremodule{standard}{pipes}
5 \platform{Unix}
Fred Drake57657bc2000-12-01 15:25:23 +00006\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
Fred Drakec116b822001-05-09 15:50:17 +00007\modulesynopsis{A Python interface to \UNIX\ shell pipelines.}
Fred Drake4755e7d1999-06-21 18:25:49 +00008
9
10The \module{pipes} module defines a class to abstract the concept of
Georg Brandlcaa94bd2006-01-23 22:00:17 +000011a \emph{pipeline} --- a sequence of converters from one file to
Fred Drake4755e7d1999-06-21 18:25:49 +000012another.
13
14Because the module uses \program{/bin/sh} command lines, a \POSIX{} or
15compatible shell for \function{os.system()} and \function{os.popen()}
16is required.
17
18The \module{pipes} module defines the following class:
19
20\begin{classdesc}{Template}{}
21An abstraction of a pipeline.
Fred Draked5d55ea1999-06-21 18:36:09 +000022\end{classdesc}
Fred Drake4755e7d1999-06-21 18:25:49 +000023
24Example:
25
26\begin{verbatim}
27>>> import pipes
28>>> t=pipes.Template()
29>>> t.append('tr a-z A-Z', '--')
30>>> f=t.open('/tmp/1', 'w')
31>>> f.write('hello world')
32>>> f.close()
33>>> open('/tmp/1').read()
34'HELLO WORLD'
35\end{verbatim}
36
37
38\subsection{Template Objects \label{template-objects}}
39
40Template objects following methods:
41
42\begin{methoddesc}{reset}{}
43Restore a pipeline template to its initial state.
44\end{methoddesc}
45
46\begin{methoddesc}{clone}{}
47Return a new, equivalent, pipeline template.
48\end{methoddesc}
49
50\begin{methoddesc}{debug}{flag}
51If \var{flag} is true, turn debugging on. Otherwise, turn debugging
52off. When debugging is on, commands to be executed are printed, and
53the shell is given \code{set -x} command to be more verbose.
54\end{methoddesc}
55
56\begin{methoddesc}{append}{cmd, kind}
57Append a new action at the end. The \var{cmd} variable must be a valid
58bourne shell command. The \var{kind} variable consists of two letters.
59
60The first letter can be either of \code{'-'} (which means the command
61reads its standard input), \code{'f'} (which means the commands reads
62a given file on the command line) or \code{'.'} (which means the commands
63reads no input, and hence must be first.)
64
Thomas Woutersf8316632000-07-16 19:01:10 +000065Similarly, the second letter can be either of \code{'-'} (which means
Fred Drake4755e7d1999-06-21 18:25:49 +000066the command writes to standard output), \code{'f'} (which means the
67command writes a file on the command line) or \code{'.'} (which means
68the command does not write anything, and hence must be last.)
69\end{methoddesc}
70
71\begin{methoddesc}{prepend}{cmd, kind}
72Add a new action at the beginning. See \method{append()} for explanations
73of the arguments.
74\end{methoddesc}
75
76\begin{methoddesc}{open}{file, mode}
77Return a file-like object, open to \var{file}, but read from or
78written to by the pipeline. Note that only one of \code{'r'},
79\code{'w'} may be given.
80\end{methoddesc}
81
82\begin{methoddesc}{copy}{infile, outfile}
83Copy \var{infile} to \var{outfile} through the pipe.
84\end{methoddesc}