New module documentation sections from Moshe Zadka <moshez@math.huji.ac.il>!

6 files changed, 390 insertions, 0 deletions

diff --git a/Doc/lib/libcmp.tex b/Doc/lib/libcmp.tex
new file mode 100644
index 0000000..a30da72
--- /dev/null
+++ b/Doc/lib/libcmp.tex
@@ -0,0 +1,34 @@
+\section{\module{cmp} ---
+         File comparisons}
+
+\declaremodule{standard}{cmp}
+\sectionauthor{Moshe Zadka}{mzadka@geocities.com}
+\modulesynopsis{Compare files very efficiently.}
+
+The \module{cmp} module defines a function to compare files, taking all
+sort of short-cuts to make it a highly efficient operation.
+
+The \module{cmp} module defines the following function:
+
+\begin{funcdesc}{cmp}{f1, f2}
+Compare two files given as names. The following tricks are used to
+optimize the comparisons:
+
+\begin{itemize}
+        \item Files with identical type, size and mtime are assumed equal.
+        \item Files with different type or size are never equal.
+        \item The module only compares files it already compared if their
+        signature (type, size and mtime) changed.
+        \item No external programs are called.
+\end{itemize}
+\end{funcdesc}
+
+Example:
+
+\begin{verbatim}
+>>> import cmp
+>>> cmp.cmp('libundoc.tex', 'libundoc.tex')
+1
+>>> cmp.cmp('libundoc.tex', 'lib.tex')
+0
+\end{verbatim}
diff --git a/Doc/lib/libcmpcache.tex b/Doc/lib/libcmpcache.tex
new file mode 100644
index 0000000..cac08ed
--- /dev/null
+++ b/Doc/lib/libcmpcache.tex
@@ -0,0 +1,36 @@
+\section{\module{cmpcache} ---
+         Efficient file comparisons}
+
+\declaremodule{standard}{cmpcache}
+\sectionauthor{Moshe Zadka}{mzadka@geocities.com}
+\modulesynopsis{Compare files very efficiently.}
+
+The \module{cmpcache} module defines a function to compare files, taking all
+sort of short-cuts to make it a highly efficient operation.
+
+The \module{cmpcache} module defines the following function:
+
+\begin{funcdesc}{cmp}{f1, f2}
+Compare two files given as names. The following tricks are used to
+optimize the comparisons:
+
+\begin{itemize}
+        \item Signatures (type, size and mtime) are computed via
+              \refmodule{statcache}
+        \item Files with identical type, size and mtime are assumed equal.
+        \item Files with different type or size are never equal.
+        \item The module only compares files it already compared if their
+              signature changed.
+        \item No external programs are called.
+\end{itemize}
+\end{funcdesc}
+
+Example:
+
+\begin{verbatim}
+>>> import cmpcache
+>>> cmpcache.cmp('libundoc.tex', 'libundoc.tex')
+1
+>>> cmpcache.cmp('libundoc.tex', 'lib.tex')
+0
+\end{verbatim}
diff --git a/Doc/lib/libdircache.tex b/Doc/lib/libdircache.tex
new file mode 100644
index 0000000..cb26d51
--- /dev/null
+++ b/Doc/lib/libdircache.tex
@@ -0,0 +1,45 @@
+\section{\module{dircache} ---
+         Cached directory listings}
+
+\declaremodule{standard}{dircache}
+\sectionauthor{Moshe Zadka}{mzadka@geocities.com}
+\modulesynopsis{Return directory listing, with cache mechanism.}
+
+The \module{dircache} module defines a function for reading directory listing
+using a cache, and cache invalidation using the \var{mtime} of the directory.
+Additionally, it defines a function to annotate directories by appending
+a slash.
+
+The \module{dircache} module defines the following functions:
+
+\begin{funcdesc}{listdir}{path}
+Return a directory listing of \var{path}, as gotten from
+\function{os.listdir()}. Note that unless \var{path} changes, further call
+to \function{listdir()} will not re-read the directory structure.
+
+Note that the list returned should be regarded as read-only. (Perhaps
+a future version should change it to return a tuple?)
+\end{funcdesc}
+
+\begin{funcdesc}{opendir}{path}
+Same as \function{listdir()}. Defined for backwards compatability.
+\end{funcdesc}
+
+\begin{funcdesc}{annotate}{head, list}
+Assume \var{list} is a list of pathes relative to \var{head}, and append,
+in place, a \character{/} to each path which points to a directory.
+\end{funcdesc}
+
+\begin{verbatim}
+>>> import dircache
+>>> a=dircache.listdir('/')
+>>> a=a[:] # Copy the return value so we can change 'a'
+>>> a
+['bin', 'boot', 'cdrom', 'dev', 'etc', 'floppy', 'home', 'initrd', 'lib', 'lost+
+found', 'mnt', 'proc', 'root', 'sbin', 'tmp', 'usr', 'var', 'vmlinuz']
+>>> dircache.annotate('/', a)
+>>> a
+['bin/', 'boot/', 'cdrom/', 'dev/', 'etc/', 'floppy/', 'home/', 'initrd/', 'lib/
+', 'lost+found/', 'mnt/', 'proc/', 'root/', 'sbin/', 'tmp/', 'usr/', 'var/', 'vm
+linuz']
+\end{verbatim}
diff --git a/Doc/lib/libnew.tex b/Doc/lib/libnew.tex
new file mode 100644
index 0000000..ffd3568
--- /dev/null
+++ b/Doc/lib/libnew.tex
@@ -0,0 +1,57 @@
+\section{\module{new} ---
+         Runtime implementation object creation}
+
+\declaremodule{builtin}{new}
+\sectionauthor{Moshe Zadka}{mzadka@geocities.com}
+\modulesynopsis{Interface to the creation of runtime implementation objects.}
+
+
+The \module{new} module allows an interface to the interpreter object
+creation functions. This is for use primarily in marshal-type functions,
+when a new object needs to be created ``magically'' and not by using the
+regular creation functions. This module provides a low-level interface
+to the interpreter, so care must be exercised when using this module.
+
+The \module{new} module defines the following functions:
+
+\begin{funcdesc}{instance}{class, dict}
+This function creates an instance of \class{class} with dictionary
+\var{dict} without calling the \method{__init__()} constructor. Note that
+this means that there are no guarantees that the object will be in a
+consistent state.
+
+Arguments are \emph{not} type-checked, and an incorrectly typed argument
+will result in undefined behaviour.
+\end{funcdesc}
+
+\begin{funcdesc}{instancemethod}{function, instance, class}
+This function will return a method object, bound to \var{instance}, or
+unbound if \var{instance} is \code{None}. It is checked that
+\var{function} is callable, and that \var{instance} is an instance
+object or \code{None}.
+\end{funcdesc}
+
+\begin{funcdesc}{function}{code, globals\optional{, name\optional{argdefs}}}
+Returns a (Python) function with the given code and globals. If
+\var{name} is given, the function will have the given name. If
+\var{argdefs} is given, they will be the function defaults.
+\end{funcdesc}
+
+\begin{funcdesc}{code}{argcount, nlocals, stacksize, flags, codestring,
+                       constants, names, varnames, filename, name, firstlineno,
+                       lnotab}
+This function is an interface to the \cfunction{PyCode_New()} internal
+function.
+XXX This is still undocumented!!!!!!!!!!!
+\end{funcdesc}
+
+\begin{funcdesc}{module}{name}
+This function returns a new module object with name \var{name}.
+\var{name} should be a string.
+\end{funcdesc}
+
+\begin{funcdesc}{classobj}{name, baseclasses, dict}
+This function returns a new class object, with name \var{name}, derived
+from \var{baseclasses} (which should be a tuple of classes) and with
+namespace \var{dict}. All parameters are type checked.
+\end{funcdesc}
diff --git a/Doc/lib/libstatcache.tex b/Doc/lib/libstatcache.tex
new file mode 100644
index 0000000..46a697f
--- /dev/null
+++ b/Doc/lib/libstatcache.tex
@@ -0,0 +1,53 @@
+\section{\module{statcache} ---
+         An optimization of \function{os.stat()}}
+
+\declaremodule{standard}{statcache}
+\sectionauthor{Moshe Zadka}{mzadka@geocities.com}
+\modulesynopsis{Stat files, and remember results.}
+
+The \module{statcache} module provides a simple optimization to
+\function{os.stat()}: remembering the values of previous invocations.
+
+The \module{statcache} module defines the following functions:
+
+\begin{funcdesc}{stat}{path}
+This is the main module entry-point.
+Identical for \function{os.stat()}, except for remembering the result
+for future invocations of the function.
+\end{funcdesc}
+
+The rest of the functions are used to clear the cache, or parts of
+it.
+
+\begin{funcdesc}{reset}{}
+Clear the cache: forget all results of previous \code{stat}s.
+\end{funcdesc}
+
+\begin{funcdesc}{forget}{path}
+Forget the result of \code{stat(\var{path})}, if any.
+\end{funcdesc}
+
+\begin{funcdesc}{forget_prefix}{prefix}
+Forget all results of \code{stat(\var{path})} for \var{path} starting
+with \var{prefix}.
+\end{funcdesc}
+
+\begin{funcdesc}{forget_dir}{prefix}
+Forget all results of \code{stat(\var{path})} for \var{path} a file in
+the directory \var{prefix}, including \code{stat(\var{prefix})}.
+\end{funcdesc}
+
+\begin{funcdesc}{forget_except_prefix}{prefix}
+Similar to \function{forget_prefix()}, but for all \var{path}
+\emph{not} starting with \var{prefix}.
+\end{funcdesc}
+
+Example:
+
+\begin{verbatim}
+>>> import os, statcache
+>>> statcache.stat('.')
+(16893, 2049, 772, 18, 1000, 1000, 2048, 929609777, 929609777, 929609777)
+>>> os.stat('.')
+(16893, 2049, 772, 18, 1000, 1000, 2048, 929609777, 929609777, 929609777)
+\end{verbatim}
diff --git a/Doc/lib/libwave.tex b/Doc/lib/libwave.tex
new file mode 100644
index 0000000..8510f49
--- /dev/null
+++ b/Doc/lib/libwave.tex
@@ -0,0 +1,165 @@
+% Documentations stolen and LaTeX'ed from comments in file.
+\section{\module{wave} ---
+         Read and write .WAV files}
+
+\declaremodule{standard}{wave}
+\sectionauthor{Moshe Zadka}{mzadka@geocities.com}
+\modulesynopsis{Provide an interface to the WAV sound format.}
+
+The \module{wave} module provides a convenient interface to the WAV sound
+format. It does not support compression/decompression, but it does support
+mono/stereo.
+
+The \module{wave} module defines the following function:
+
+\begin{funcdesc}{open}{file, mode}
+If \var{file} is a string, open the file by that name, other treat it
+as a seekable file-like object. \var{mode} can be any of
+\begin{description}
+        \item[\code{'r'}, \code{'rb'}] Read only mode.
+        \item[\code{'w'}, \code{'wb'}] Write only mode.
+\end{description}
+Note that it does not allow read/write WAV files.
+
+A \var{mode} of \code{'r'} or \code{'rb'} returns a \class{Wave_read}
+object, while a \var{mode} of \code{'w'} or \code{'wb'} returns
+a \class{Wave_write} object.
+\end{funcdesc}
+
+\begin{funcdesc}{openfp}{file, mode}
+A synonym for \function{open()}, maintained for backwards compatibility.
+\end{funcdesc}
+
+\begin{excdesc}{Error}
+An error raised when something is impossible because it violates the
+WAV specification or hits an implementation deficiency.
+\end{excdesc}
+
+
+\subsection{Wave_read Objects \label{Wave-read-objects}}
+
+Wave_read objects, as returned by \function{open()} above, have the
+following methods:
+
+\begin{methoddesc}[Wave_read]{getnchannels}{}
+Returns number of audio channels (1 for mone, 2 for stereo).
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_read]{getsampwidth}{}
+Returns sample width in bytes.
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_read]{getframerate}{}
+Returns sampling frequency.
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_read]{getnframes}{}
+Returns number of audio frames.
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_read]{getcomptype}{}
+Returns compression type (\code{'NONE'} is the only supported type).
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_read]{getcompname}{}
+Human-readable version of \method{getcomptype()}.
+Usually \code{'not compressed'} parallels \code{'NONE'}.
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_read]{getparams}{}
+Returns a tuple
+\code{(nchannels, sampwidth, framerate, nframes, comptype, compname)},
+equivalent to output of the \code{get} methods.
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_read]{readframes}{n}
+Reads and returns at most \var{n} frames of audio, as a string of bytes.
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_read]{rewind}{}
+Rewind the file pointer to the beginning of the audio stream.
+\end{methoddesc}
+
+The following two functions are defined for compatibility with the
+\refmodule{aifc} module, and don't do anything interesting.
+
+\begin{methoddesc}[Wave_read]{getmarkers}{}
+Returns \code{None}.
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_read]{getmark}{id}
+Raise an error.
+\end{methoddesc}
+
+The following two methods define a term ``position'' which is compatible
+between them, and is otherwise implementation dependant.
+
+\begin{methoddesc}[Wave_read]{setpos}{pos}
+Set the file pointer to the specified position.
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_read]{tell}{}
+Return current file pointer position.
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_read]{close}{}
+Close the stream, and make the instance unusable. (This is
+called automatically on deletion.
+\end{methoddesc}
+
+
+\subsection{Wave_write Objects \label{Wave-write-objects}}
+
+Wave_write objects, as returned by \function{open()} above, have the
+following methods:
+
+\begin{methoddesc}[Wave_write]{setnchannels}{n}
+Set the number of channels.
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_write]{setsampwidth}{n}
+Set the sample width (in bytes.)
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_write]{setframerate}{n}
+Set the frame rate.
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_write]{setnframes}{n}
+Set the number of frames. This can be later changed, when and if more
+frames are written.
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_write]{setcomptype}{type, name}
+Set the compression type and description.
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_write]{setparams}{tuple}
+The \var{tuple} should be
+\code{(\var{nchannels}, \var{sampwidth}, \var{framerate},
+\var{nframes}, \var{comptype}, \var{compname})}, with values valid for
+the \code{set} methods.  Set all parameters.
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_write]{tell}{}
+Return current position in the file, with the same disclaimer for
+the \method{Wave_read.tell} and \method{Wave_read.setpos} methods.
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_write]{writeframesraw}{data}
+Write audio frames, without correcting \var{nframes}.
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_write]{writeframes}{data}
+Write audio frames and make sure \var{nframes} is correct.
+\end{methoddesc}
+
+\begin{methoddesc}[Wave_write]{close}{}
+Make sure \var{nframes} is correct, and close the file.
+
+This method is called upon deletion.
+\end{methoddesc}
+
+Note that it is invalid to set any parameters after calling
+\method{writeframes()} or \method{writeframesraw()}, and any attempt
+to do so will raise an error.