diff --git a/Doc/lib/libcodeop.tex b/Doc/lib/libcodeop.tex new file mode 100644 index 00000000000..a0b58a5d353 --- /dev/null +++ b/Doc/lib/libcodeop.tex @@ -0,0 +1,45 @@ +% LaTeXed from excellent doc-string. +\section{\module{codeop} --- + Compile Python code} + +\declaremodule{standard}{codeop} +\sectionauthor{Moshe Zadka}{mzadka@geocities.com} +\modulesynopsis{Compile (possibly incomplete) Python code.} + +The \module{codeop} module provides a function to compile Python code +with hints on whether it certainly complete, possible complete or +definitely incomplete. This is used by the \refmodule{code} module +and should not normally be used directly. + +The \module{codeop} module defines the following function: + +\begin{funcdesc}{compile_command} + {source\optional{, filename\optional{, symbol}}} + +Try to compile \var{source}, which should be a string of Python +code. Return a code object if \var{source} is valid +Python code. In that case, the filename attribute of the code object +will be \var{filename}, which defaults to \code{''}. + +Return \code{None} if \var{source} is \emph{not} valid Python +code, but is a prefix of valid Python code. + +Raise an exception if there is a problem with \var{source}: +\begin{itemize} + \item \exception{SyntaxError} + if there is invalid Python syntax. + \item \exception{OverflowError} + if there is an invalid numeric constant. +\end{itemize} + +The \var{symbol} argument means whether to compile it as a statement +(\code{'single'}, the default) or as an expression (\code{'eval'}). + +\strong{Caveat:} +It is possible (but not likely) that the parser stops parsing +with a successful outcome before reaching the end of the source; +in this case, trailing symbols may be ignored instead of causing an +error. For example, a backslash followed by two newlines may be +followed by arbitrary garbage. This will be fixed once the API +for the parser is better. +\end{funcdesc} diff --git a/Doc/lib/libsunau.tex b/Doc/lib/libsunau.tex new file mode 100644 index 00000000000..3850ce9cb1c --- /dev/null +++ b/Doc/lib/libsunau.tex @@ -0,0 +1,174 @@ +\section{\module{sunau} --- + Read and write Sun AU files} + +\declaremodule{standard}{sunau} +\sectionauthor{Moshe Zadka}{mzadka@geocities.com} +\modulesynopsis{Provide an interface to the Sun AU sound format.} + +The \module{sunau} module provides a convenient interface to the Sun AU sound +format. Note that this module is interface-compatible with the modules +\refmodule{aifc} and \refmodule{wave}. + +The \module{sunau} module defines the following functions: + +\begin{funcdesc}{open}{file, mode} +If \var{file} is a string, open the file by that name, otherwise treat it +as a seekable file-like object. \var{mode} can be any of +\begin{description} + \item[\code{'r'}] Read only mode. + \item[\code{'w'}] Write only mode. +\end{description} +Note that it does not allow read/write files. + +A \var{mode} of \code{'r'} returns a \class{AU_read} +object, while a \var{mode} of \code{'w'} or \code{'wb'} returns +a \class{AU_write} object. +\end{funcdesc} + +\begin{funcdesc}{openfp}{file, mode} +A synonym for \function{open}, maintained for backwards compatibility. +\end{funcdesc} + +The \module{sunau} module defines the following exception: + +\begin{excdesc}{Error} +An error raised when something is impossible because of Sun AU specs or +implementation deficiency. +\end{excdesc} + +The \module{sunau} module defines the following data item: + +\begin{datadesc}{AUDIO_FILE_MAGIC} +An integer every valid Sun AU file begins with a big-endian encoding of. +\end{datadesc} + + +\subsection{AU_read Objects \label{au-read-objects}} + +AU_read objects, as returned by \function{open()} above, have the +following methods: + +\begin{methoddesc}[AU_read]{close}{} +Close the stream, and make the instance unusable. (This is +called automatically on deletion.) +\end{methoddesc} + +\begin{methoddesc}[AU_read]{getnchannels}{} +Returns number of audio channels (1 for mone, 2 for stereo). +\end{methoddesc} + +\begin{methoddesc}[AU_read]{getsampwidth}{} +Returns sample width in bytes. +\end{methoddesc} + +\begin{methoddesc}[AU_read]{getframerate}{} +Returns sampling frequency. +\end{methoddesc} + +\begin{methoddesc}[AU_read]{getnframes}{} +Returns number of audio frames. +\end{methoddesc} + +\begin{methoddesc}[AU_read]{getcomptype}{} +Returns compression type. +Supported compression types are \code{'ULAW'}, \code{'ALAW'} and \code{'NONE'}. +\end{methoddesc} + +\begin{methoddesc}[AU_read]{getcompname}{} +Human-readable version of \method{getcomptype()}. +The supported types have the respective names \code{'CCITT G.711 +u-law'}, \code{'CCITT G.711 A-law'} and \code{'not compressed'}. +\end{methoddesc} + +\begin{methoddesc}[AU_read]{getparams}{} +Returns a tuple \code{(\var{nchannels}, \var{sampwidth}, +\var{framerate}, \var{nframes}, \var{comptype}, \var{compname})}, +equivalent to output of the \method{get*()} methods. +\end{methoddesc} + +\begin{methoddesc}[AU_read]{readframes}{n} +Reads and returns at most \var{n} frames of audio, as a string of bytes. +\end{methoddesc} + +\begin{methoddesc}[AU_read]{rewind}{} +Rewind the file pointer to the beginning of the audio stream. +\end{methoddesc} + +The following two methods define a term ``position'' which is compatible +between them, and is otherwise implementation dependant. + +\begin{methoddesc}[AU_read]{setpos}{pos} +Set the file pointer to the specified position. +\end{methoddesc} + +\begin{methoddesc}[AU_read]{tell}{} +Return current file pointer position. +\end{methoddesc} + +The following two functions are defined for compatibility with the +\refmodule{aifc}, and don't do anything interesting. + +\begin{methoddesc}[AU_read]{getmarkers}{} +Returns \code{None}. +\end{methoddesc} + +\begin{methoddesc}[AU_read]{getmark}{id} +Raise an error. +\end{methoddesc} + + +\subsection{AU_write Objects \label{au-write-objects}} + +AU_write objects, as returned by \function{open()} above, have the +following methods: + +\begin{methoddesc}[AU_write]{setnchannels}{n} +Set the number of channels. +\end{methoddesc} + +\begin{methoddesc}[AU_write]{setsampwidth}{n} +Set the sample width (in bytes.) +\end{methoddesc} + +\begin{methoddesc}[AU_write]{setframerate}{n} +Set the frame rate. +\end{methoddesc} + +\begin{methoddesc}[AU_write]{setnframes}{n} +Set the number of frames. This can be later changed, when and if more +frames are written. +\end{methoddesc} + + +\begin{methoddesc}[AU_write]{setcomptype}{type, name} +Set the compression type and description. +Only \code{'NONE'} and \code{'ULAW'} are supported on output. +\end{methoddesc} + +\begin{methoddesc}[AU_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 \method{set*()} methods. Set all parameters. +\end{methoddesc} + +\begin{methoddesc}[AU_write]{tell}{} +Return current position in the file, with the same disclaimer for +the \method{AU_read.tell()} and \method{AU_read.setpos()} methods. +\end{methoddesc} + +\begin{methoddesc}[AU_write]{writeframesraw}{data} +Write audio frames, without correcting \var{nframes}. +\end{methoddesc} + +\begin{methoddesc}[AU_write]{writeframes}{data} +Write audio frames and make sure \var{nframes} is correct. +\end{methoddesc} + +\begin{methoddesc}[AU_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()}.