From 4755e7d5c1eea7e4751997afaa341a4d6ac64f5e Mon Sep 17 00:00:00 2001 From: Fred Drake Date: Mon, 21 Jun 1999 18:25:49 +0000 Subject: [PATCH] Three more modules documented by Moshe! --- Doc/lib/lib.tex | 3 ++ Doc/lib/libpipes.tex | 84 ++++++++++++++++++++++++++++++++++++++ Doc/lib/librlcompleter.tex | 59 ++++++++++++++++++++++++++ Doc/lib/libstatvfs.tex | 51 +++++++++++++++++++++++ 4 files changed, 197 insertions(+) create mode 100644 Doc/lib/libpipes.tex create mode 100644 Doc/lib/librlcompleter.tex create mode 100644 Doc/lib/libstatvfs.tex diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 6502bff7e35..e9f184acd58 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -131,6 +131,7 @@ add new extensions to Python and how to embed it in other applications. \input{libdircache} \input{libstat} \input{libstatcache} +\input{libstatvfs} \input{libcmp} \input{libcmpcache} \input{libtime} @@ -156,6 +157,7 @@ add new extensions to Python and how to embed it in other applications. \input{libbsddb} \input{libzlib} \input{libgzip} +\input{librlcompleter} \input{libunix} % UNIX Specific Services \input{libposix} @@ -166,6 +168,7 @@ add new extensions to Python and how to embed it in other applications. \input{libgdbm} \input{libtermios} \input{libfcntl} +\input{libpipes} \input{libposixfile} \input{libresource} \input{libsyslog} diff --git a/Doc/lib/libpipes.tex b/Doc/lib/libpipes.tex new file mode 100644 index 00000000000..389448bbcf3 --- /dev/null +++ b/Doc/lib/libpipes.tex @@ -0,0 +1,84 @@ +\section{\module{pipes} --- + Interface to shell pipelines} + +\declaremodule{standard}{pipes} + \platform{Unix} +\sectionauthor{Moshe Zadka}{mzadka@geocities.com} +\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 convertors 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{funcdesc} + +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.) + +Similarily, 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} diff --git a/Doc/lib/librlcompleter.tex b/Doc/lib/librlcompleter.tex new file mode 100644 index 00000000000..dd666761137 --- /dev/null +++ b/Doc/lib/librlcompleter.tex @@ -0,0 +1,59 @@ +\section{\module{rlcompleter} --- + Completion function for readline} + +\declaremodule{standard}{rlcompleter} +\sectionauthor{Moshe Zadka}{mzadka@geocities.com} +\modulesynopsis{Python identifier completion in the readline library.} + +The \module{rlcompleter} module defines a completion function for +the \module{readline} module by completing valid Python identifiers and +keyword. + +The \module{rlcompleter} module defines the \class{Completer} class. + +Example: + +\begin{verbatim} +>>> import rlcompleter +>>> import readline +>>> readline.parse_and_bind("tab: complete") +>>> readline. +readline.__doc__ readline.get_line_buffer readline.read_init_file +readline.__file__ readline.insert_text readline.set_completer +readline.__name__ readline.parse_and_bind +>>> readline. +\end{verbatim} + +The \module{rlcompleter} module is designed for use with Python's +interactive mode. A user can add the following lines to his or her +initialization file (identified by the \envvar{PYTHONSTARTUP} +environment variable) to get automatic \kbd{Tab} completion: + +\begin{verbatim} +try: + import readline +except ImportError: + print "Module readline not available." +else: + import rlcompleter + readline.parse_and_bind("tab: complete") +\end{verbatim} + + +\subsection{Completer Objects \label{completer-objects}} + +Completer objects have the following method: + +\begin{methoddesc}[Completer]{complete}{text, state} +Return the \var{state}th completion for \var{text}. + +If called for \var{text} that doesn't includea period character +(\character{.}), it will complete from names currently defined in +\refmodule{__main__}, \refmodule{__builtin__} and keywords (as defined +by the \refmodule{keyword} module). + +If called for a dotted name, it will try to evaluate anything without +obvious side-effects (i.e., functions will not be evaluated, but it +can generate calls to \method{__getattr__()}) upto the last part, and +find matches for the rest via the \function{dir()} function. +\end{methoddesc} diff --git a/Doc/lib/libstatvfs.tex b/Doc/lib/libstatvfs.tex new file mode 100644 index 00000000000..e71ad72b7fd --- /dev/null +++ b/Doc/lib/libstatvfs.tex @@ -0,0 +1,51 @@ +\section{\module{statvfs} --- + Constants used with \function{os.statvfs()}} + +\declaremodule{standard}{statvfs} +% LaTeX'ed from comments in module +\sectionauthor{Moshe Zadka}{mzadka@geocities.com} +\modulesynopsis{Constants for interpreting the result of + \function{os.statvfs()}.} + +The \module{statvfs} module defines constants so interpreting the result +if \function{os.statvfs()}, which returns a tuple, can be made without +remembering ``magic numbers.'' Each of the constants defined in this +module is the \emph{index} of the entry in the tuple returned by +\function{os.statvfs()} that contains the specified information. + + +\begin{datadesc}{F_BSIZE} +Preferred file system block size. +\end{datadesc} + +\begin{datadesc}{F_FRSIZE} +Fundamental file system block size. +\end{datadesc} + +\begin{datadesc}{F_BFREE} +Total number of free blocks. +\end{datadesc} + +\begin{datadesc}{F_BAVAIL} +Free blocks available to non-super user. +\end{datadesc} + +\begin{datadesc}{F_FILES} +Total number of file nodes. +\end{datadesc} + +\begin{datadesc}{F_FFREE} +Total number of free file nodes. +\end{datadesc} + +\begin{datadesc}{F_FAVAIL} +Free nodes available to non-superuser. +\end{datadesc} + +\begin{datadesc}{F_FLAG} +Flags. System dependant: see \cfunction{statvfs()} man page. +\end{datadesc} + +\begin{datadesc}{F_NAMEMAX} +Maximum file name length. +\end{datadesc}