From 64bc94e3ec72780c27b39f8298b0e1b6af1d5e4e Mon Sep 17 00:00:00 2001 From: Fred Drake Date: Thu, 17 Jun 1999 15:11:35 +0000 Subject: New module documentation sections from Moshe Zadka ! --- Doc/lib/libcmp.tex | 34 ++++++++++ Doc/lib/libcmpcache.tex | 36 +++++++++++ Doc/lib/libdircache.tex | 45 +++++++++++++ Doc/lib/libnew.tex | 57 ++++++++++++++++ Doc/lib/libstatcache.tex | 53 +++++++++++++++ Doc/lib/libwave.tex | 165 +++++++++++++++++++++++++++++++++++++++++++++++ 6 files changed, 390 insertions(+) create mode 100644 Doc/lib/libcmp.tex create mode 100644 Doc/lib/libcmpcache.tex create mode 100644 Doc/lib/libdircache.tex create mode 100644 Doc/lib/libnew.tex create mode 100644 Doc/lib/libstatcache.tex create mode 100644 Doc/lib/libwave.tex 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. -- cgit v0.12