source: trunk/essentials/dev-lang/python/Doc/lib/libpipes.tex@ 3368

\section{\module{pipes} ---
         Interface to shell pipelines}

\declaremodule{standard}{pipes}
  \platform{Unix}
\sectionauthor{Moshe Zadka}{[email protected]}
\modulesynopsis{A Python interface to \UNIX\ shell pipelines.}


The \module{pipes} module defines a class to abstract the concept of
a \emph{pipeline} --- a sequence of converters from one file to 
another.

Because the module uses \program{/bin/sh} command lines, a \POSIX{} or
compatible shell for \function{os.system()} and \function{os.popen()}
is required.

The \module{pipes} module defines the following class:

\begin{classdesc}{Template}{}
An abstraction of a pipeline.
\end{classdesc}

Example:

\begin{verbatim}
>>> import pipes
>>> t=pipes.Template()
>>> t.append('tr a-z A-Z', '--')
>>> f=t.open('/tmp/1', 'w')
>>> f.write('hello world')
>>> f.close()
>>> open('/tmp/1').read()
'HELLO WORLD'
\end{verbatim}


\subsection{Template Objects \label{template-objects}}

Template objects following methods:

\begin{methoddesc}{reset}{}
Restore a pipeline template to its initial state.
\end{methoddesc}

\begin{methoddesc}{clone}{}
Return a new, equivalent, pipeline template.
\end{methoddesc}

\begin{methoddesc}{debug}{flag}
If \var{flag} is true, turn debugging on. Otherwise, turn debugging
off. When debugging is on, commands to be executed are printed, and
the shell is given \code{set -x} command to be more verbose.
\end{methoddesc}

\begin{methoddesc}{append}{cmd, kind}
Append a new action at the end. The \var{cmd} variable must be a valid
bourne shell command. The \var{kind} variable consists of two letters.

The first letter can be either of \code{'-'} (which means the command
reads its standard input), \code{'f'} (which means the commands reads
a given file on the command line) or \code{'.'} (which means the commands
reads no input, and hence must be first.)

Similarly, the second letter can be either of \code{'-'} (which means 
the command writes to standard output), \code{'f'} (which means the 
command writes a file on the command line) or \code{'.'} (which means
the command does not write anything, and hence must be last.)
\end{methoddesc}

\begin{methoddesc}{prepend}{cmd, kind}
Add a new action at the beginning. See \method{append()} for explanations
of the arguments.
\end{methoddesc}

\begin{methoddesc}{open}{file, mode}
Return a file-like object, open to \var{file}, but read from or
written to by the pipeline.  Note that only one of \code{'r'},
\code{'w'} may be given.
\end{methoddesc}

\begin{methoddesc}{copy}{infile, outfile}
Copy \var{infile} to \var{outfile} through the pipe.
\end{methoddesc}