mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-11-03 03:22:27 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 8

Remove obsolete \setindexsubitem macros.

Browse source 
Massive migration to methoddesc and memberdesc.

Logical markup as needed.

A sprinkling of index entries for flavor.
This commit is contained in:
Fred Drake 1998-04-04 07:15:02 +00:00
parent 71c1e502f0
commit fc57619811
36 changed files with 1528 additions and 1462 deletions
Download patch file Download diff file Expand all files Collapse all files

156
Doc/lib/libaifc.tex
View file

@ -1,4 +1,4 @@
\section{Standard Module \sectcode{aifc}}
\section{Standard Module \module{aifc}}
\label{module-aifc}
\stmodindex{aifc}
@ -6,6 +6,9 @@ This module provides support for reading and writing AIFF and AIFF-C
files. AIFF is Audio Interchange File Format, a format for storing
digital audio samples in a file. AIFF-C is a newer version of the
format that includes the ability to compress the audio data.
\index{Audio Interchange File Format}
\index{AIFF}
\index{AIFF-C}
Audio files have a number of parameters that describe the audio data.
The sampling rate or frame rate is the number of times per second the
@ -21,9 +24,8 @@ bits), uses two channels (stereo) and has a frame rate of 44,100
frames/second. This gives a frame size of 4 bytes (2*2), and a
second's worth occupies 2*2*44100 bytes, i.e.\ 176,400 bytes.
Module \code{aifc} defines the following function:
Module \module{aifc} defines the following function:
\setindexsubitem{(in module aifc)}
\begin{funcdesc}{open}{file, mode}
Open an AIFF or AIFF-C file and return an object instance with
methods that are described below. The argument file is either a
@ -32,159 +34,161 @@ string naming a file or a file object. The mode is either the string
when the file must be opened for writing. When used for writing, the
file object should be seekable, unless you know ahead of time how many
samples you are going to write in total and use
\code{writeframesraw()} and \code{setnframes()}.
\method{writeframesraw()} and \method{setnframes()}.
\end{funcdesc}
Objects returned by \code{aifc.open()} when a file is opened for
Objects returned by \function{open()} when a file is opened for
reading have the following methods:
\setindexsubitem{(aifc object method)}
\begin{funcdesc}{getnchannels}{}
\begin{methoddesc}[aifc]{getnchannels}{}
Return the number of audio channels (1 for mono, 2 for stereo).
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getsampwidth}{}
\begin{methoddesc}[aifc]{getsampwidth}{}
Return the size in bytes of individual samples.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getframerate}{}
\begin{methoddesc}[aifc]{getframerate}{}
Return the sampling rate (number of audio frames per second).
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getnframes}{}
\begin{methoddesc}[aifc]{getnframes}{}
Return the number of audio frames in the file.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getcomptype}{}
\begin{methoddesc}[aifc]{getcomptype}{}
Return a four-character string describing the type of compression used
in the audio file. For AIFF files, the returned value is
\code{'NONE'}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getcompname}{}
\begin{methoddesc}[aifc]{getcompname}{}
Return a human-readable description of the type of compression used in
the audio file. For AIFF files, the returned value is \code{'not
compressed'}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getparams}{}
\begin{methoddesc}[aifc]{getparams}{}
Return a tuple consisting of all of the above values in the above
order.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getmarkers}{}
\begin{methoddesc}[aifc]{getmarkers}{}
Return a list of markers in the audio file. A marker consists of a
tuple of three elements. The first is the mark ID (an integer), the
second is the mark position in frames from the beginning of the data
(an integer), the third is the name of the mark (a string).
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getmark}{id}
Return the tuple as described in \code{getmarkers} for the mark with
the given id.
\end{funcdesc}
\begin{methoddesc}[aifc]{getmark}{id}
Return the tuple as described in \method{getmarkers()} for the mark
with the given \var{id}.
\end{methoddesc}
\begin{funcdesc}{readframes}{nframes}
\begin{methoddesc}[aifc]{readframes}{nframes}
Read and return the next \var{nframes} frames from the audio file. The
returned data is a string containing for each frame the uncompressed
samples of all channels.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{rewind}{}
Rewind the read pointer. The next \code{readframes} will start from
\begin{methoddesc}[aifc]{rewind}{}
Rewind the read pointer. The next \method{readframes()} will start from
the beginning.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setpos}{pos}
\begin{methoddesc}[aifc]{setpos}{pos}
Seek to the specified frame number.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{tell}{}
\begin{methoddesc}[aifc]{tell}{}
Return the current frame number.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{close}{}
\begin{methoddesc}[aifc]{close}{}
Close the AIFF file. After calling this method, the object can no
longer be used.
\end{funcdesc}
\end{methoddesc}
Objects returned by \code{aifc.open()} when a file is opened for
writing have all the above methods, except for \code{readframes} and
\code{setpos}. In addition the following methods exist. The
\code{get} methods can only be called after the corresponding
\code{set} methods have been called. Before the first
\code{writeframes()} or \code{writeframesraw()}, all parameters except
for the number of frames must be filled in.
Objects returned by \function{open()} when a file is opened for
writing have all the above methods, except for \method{readframes()} and
\method{setpos()}. In addition the following methods exist. The
\method{get*()} methods can only be called after the corresponding
\method{set*()} methods have been called. Before the first
\method{writeframes()} or \method{writeframesraw()}, all parameters
except for the number of frames must be filled in.
\begin{funcdesc}{aiff}{}
\begin{methoddesc}[aifc]{aiff}{}
Create an AIFF file. The default is that an AIFF-C file is created,
unless the name of the file ends in \code{'.aiff'} in which case the
default is an AIFF file.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{aifc}{}
\begin{methoddesc}[aifc]{aifc}{}
Create an AIFF-C file. The default is that an AIFF-C file is created,
unless the name of the file ends in \code{'.aiff'} in which case the
default is an AIFF file.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setnchannels}{nchannels}
\begin{methoddesc}[aifc]{setnchannels}{nchannels}
Specify the number of channels in the audio file.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setsampwidth}{width}
\begin{methoddesc}[aifc]{setsampwidth}{width}
Specify the size in bytes of audio samples.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setframerate}{rate}
\begin{methoddesc}[aifc]{setframerate}{rate}
Specify the sampling frequency in frames per second.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setnframes}{nframes}
\begin{methoddesc}[aifc]{setnframes}{nframes}
Specify the number of frames that are to be written to the audio file.
If this parameter is not set, or not set correctly, the file needs to
support seeking.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setcomptype}{type, name}
\begin{methoddesc}[aifc]{setcomptype}{type, name}
Specify the compression type. If not specified, the audio data will
not be compressed. In AIFF files, compression is not possible. The
name parameter should be a human-readable description of the
compression type, the type parameter should be a four-character
string. Currently the following compression types are supported:
NONE, ULAW, ALAW, G722.
\end{funcdesc}
\index{u-LAW}
\index{A-LAW}
\index{G.722}
\end{methoddesc}
\begin{funcdesc}{setparams}{nchannels, sampwidth, framerate, comptype, compname}
\begin{methoddesc}[aifc]{setparams}{nchannels, sampwidth, framerate, comptype, compname}
Set all the above parameters at once. The argument is a tuple
consisting of the various parameters. This means that it is possible
to use the result of a \code{getparams()} call as argument to
\code{setparams()}.
\end{funcdesc}
to use the result of a \method{getparams()} call as argument to
\method{setparams()}.
\end{methoddesc}
\begin{funcdesc}{setmark}{id, pos, name}
\begin{methoddesc}[aifc]{setmark}{id, pos, name}
Add a mark with the given id (larger than 0), and the given name at
the given position. This method can be called at any time before
\code{close()}.
\end{funcdesc}
\method{close()}.
\end{methoddesc}
\begin{funcdesc}{tell}{}
\begin{methoddesc}[aifc]{tell}{}
Return the current write position in the output file. Useful in
combination with \code{setmark()}.
\end{funcdesc}
combination with \method{setmark()}.
\end{methoddesc}
\begin{funcdesc}{writeframes}{data}
\begin{methoddesc}[aifc]{writeframes}{data}
Write data to the output file. This method can only be called after
the audio file parameters have been set.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{writeframesraw}{data}
Like \code{writeframes()}, except that the header of the audio file is
not updated.
\end{funcdesc}
\begin{methoddesc}[aifc]{writeframesraw}{data}
Like \method{writeframes()}, except that the header of the audio file
is not updated.
\end{methoddesc}
\begin{funcdesc}{close}{}
\begin{methoddesc}[aifc]{close}{}
Close the AIFF file. The header of the file is updated to reflect the
actual size of the audio data. After calling this method, the object
can no longer be used.
\end{funcdesc}
\end{methoddesc}

138
Doc/lib/libal.tex
View file

@ -1,4 +1,4 @@
\section{Built-in Module \sectcode{al}}
\section{Built-in Module \module{al}}
\label{module-al}
\bimodindex{al}
@ -10,10 +10,11 @@ releases before 4.0.5. Again, see the manual to check whether a
specific function is available on your platform.
All functions and methods defined in this module are equivalent to
the C functions with \samp{AL} prefixed to their name.
the \C{} functions with \samp{AL} prefixed to their name.
Symbolic constants from the C header file \file{<audio.h>} are defined
in the standard module \code{AL}, see below.
Symbolic constants from the \C{} header file \code{<audio.h>} are
defined in the standard module \module{AL}\refstmodindex{AL}, see
below.
\strong{Warning:} the current version of the audio library may dump core
when bad argument values are passed rather than returning an error
@ -25,145 +26,146 @@ documented upper limit.)
The module defines the following functions:
\setindexsubitem{(in module al)}
\begin{funcdesc}{openport}{name, direction\optional{, config}}
The name and direction arguments are strings. The optional config
argument is a configuration object as returned by
\code{al.newconfig()}. The return value is an \dfn{port object};
methods of port objects are described below.
The name and direction arguments are strings. The optional
\var{config} argument is a configuration object as returned by
\function{newconfig()}. The return value is an \dfn{audio port
object}; methods of audio port objects are described below.
\end{funcdesc}
\begin{funcdesc}{newconfig}{}
The return value is a new \dfn{configuration object}; methods of
configuration objects are described below.
The return value is a new \dfn{audio configuration object}; methods of
audio configuration objects are described below.
\end{funcdesc}
\begin{funcdesc}{queryparams}{device}
The device argument is an integer. The return value is a list of
integers containing the data returned by ALqueryparams().
integers containing the data returned by \cfunction{ALqueryparams()}.
\end{funcdesc}
\begin{funcdesc}{getparams}{device, list}
The device argument is an integer. The list argument is a list such
as returned by \code{queryparams}; it is modified in place (!).
The \var{device} argument is an integer. The list argument is a list
such as returned by \function{queryparams()}; it is modified in place
(!).
\end{funcdesc}
\begin{funcdesc}{setparams}{device, list}
The device argument is an integer. The list argument is a list such
as returned by \code{al.queryparams}.
The \var{device} argument is an integer. The \var{list} argument is a
list such as returned by \function{queryparams()}.
\end{funcdesc}
\subsection{Configuration Objects}
\label{al-config-objects}
Configuration objects (returned by \code{al.newconfig()} have the
Configuration objects (returned by \function{newconfig()} have the
following methods:
\setindexsubitem{(audio configuration object method)}
\begin{funcdesc}{getqueuesize}{}
\begin{methoddesc}[audio configuration]{getqueuesize}{}
Return the queue size.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setqueuesize}{size}
\begin{methoddesc}[audio configuration]{setqueuesize}{size}
Set the queue size.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getwidth}{}
\begin{methoddesc}[audio configuration]{getwidth}{}
Get the sample width.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setwidth}{width}
\begin{methoddesc}[audio configuration]{setwidth}{width}
Set the sample width.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getchannels}{}
\begin{methoddesc}[audio configuration]{getchannels}{}
Get the channel count.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setchannels}{nchannels}
\begin{methoddesc}[audio configuration]{setchannels}{nchannels}
Set the channel count.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getsampfmt}{}
\begin{methoddesc}[audio configuration]{getsampfmt}{}
Get the sample format.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setsampfmt}{sampfmt}
\begin{methoddesc}[audio configuration]{setsampfmt}{sampfmt}
Set the sample format.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getfloatmax}{}
\begin{methoddesc}[audio configuration]{getfloatmax}{}
Get the maximum value for floating sample formats.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setfloatmax}{floatmax}
\begin{methoddesc}[audio configuration]{setfloatmax}{floatmax}
Set the maximum value for floating sample formats.
\end{funcdesc}
\end{methoddesc}
\subsection{Port Objects}
\label{al-port-objects}
Port objects (returned by \code{al.openport()} have the following
Port objects, as returned by \function{openport()}, have the following
methods:
\setindexsubitem{(audio port object method)}
\begin{funcdesc}{closeport}{}
\begin{methoddesc}[audio port]{closeport}{}
Close the port.
\end{funcdesc}
\end{methoddesc}[audio port]
\begin{funcdesc}{getfd}{}
\begin{methoddesc}[audio port]{getfd}{}
Return the file descriptor as an int.
\end{funcdesc}
\end{methoddesc}[audio port]
\begin{funcdesc}{getfilled}{}
\begin{methoddesc}[audio port]{getfilled}{}
Return the number of filled samples.
\end{funcdesc}
\end{methoddesc}[audio port]
\begin{funcdesc}{getfillable}{}
\begin{methoddesc}[audio port]{getfillable}{}
Return the number of fillable samples.
\end{funcdesc}
\end{methoddesc}[audio port]
\begin{funcdesc}{readsamps}{nsamples}
\begin{methoddesc}[audio port]{readsamps}{nsamples}
Read a number of samples from the queue, blocking if necessary.
Return the data as a string containing the raw data, (e.g., 2 bytes per
sample in big-endian byte order (high byte, low byte) if you have set
the sample width to 2 bytes).
\end{funcdesc}
\end{methoddesc}[audio port]
\begin{funcdesc}{writesamps}{samples}
\begin{methoddesc}[audio port]{writesamps}{samples}
Write samples into the queue, blocking if necessary. The samples are
encoded as described for the \code{readsamps} return value.
\end{funcdesc}
encoded as described for the \method{readsamps()} return value.
\end{methoddesc}[audio port]
\begin{funcdesc}{getfillpoint}{}
\begin{methoddesc}[audio port]{getfillpoint}{}
Return the `fill point'.
\end{funcdesc}
\end{methoddesc}[audio port]
\begin{funcdesc}{setfillpoint}{fillpoint}
\begin{methoddesc}[audio port]{setfillpoint}{fillpoint}
Set the `fill point'.
\end{funcdesc}
\end{methoddesc}[audio port]
\begin{funcdesc}{getconfig}{}
\begin{methoddesc}[audio port]{getconfig}{}
Return a configuration object containing the current configuration of
the port.
\end{funcdesc}
\end{methoddesc}[audio port]
\begin{funcdesc}{setconfig}{config}
\begin{methoddesc}[audio port]{setconfig}{config}
Set the configuration from the argument, a configuration object.
\end{funcdesc}
\end{methoddesc}[audio port]
\begin{funcdesc}{getstatus}{list}
\begin{methoddesc}[audio port]{getstatus}{list}
Get status information on last error.
\end{funcdesc}
\end{methoddesc}[audio port]
\section{Standard Module \sectcode{AL}}
\section{Standard Module \module{AL}}
\nodename{AL (uppercase)}
\stmodindex{AL}
This module defines symbolic constants needed to use the built-in
module \code{al} (see above); they are equivalent to those defined in
the C header file \file{<audio.h>} except that the name prefix
module \module{al} (see above); they are equivalent to those defined
in the \C{} header file \code{<audio.h>} except that the name prefix
\samp{AL_} is omitted. Read the module source for a complete list of
the defined names. Suggested use:

105
Doc/lib/libaudioop.tex
View file

@ -1,19 +1,25 @@
\section{Built-in Module \sectcode{audioop}}
\section{Built-in Module \module{audioop}}
\label{module-audioop}
\bimodindex{audioop}
The \code{audioop} module contains some useful operations on sound fragments.
It operates on sound fragments consisting of signed integer samples
8, 16 or 32 bits wide, stored in Python strings. This is the same
format as used by the \code{al} and \code{sunaudiodev} modules. All
scalar items are integers, unless specified otherwise.
The \module{audioop} module contains some useful operations on sound
fragments. It operates on sound fragments consisting of signed
integer samples 8, 16 or 32 bits wide, stored in Python strings. This
is the same format as used by the \module{al} and \module{sunaudiodev}
modules. All scalar items are integers, unless specified otherwise.
% This para is mostly here to provide an excuse for the index entries...
This module provides support for u-LAW and Intel/DVI ADPCM encodings.
\index{Intel/DVI ADPCM}
\index{ADPCM, Intel/DVI}
\index{u-LAW}
A few of the more complicated operations only take 16-bit samples,
otherwise the sample size (in bytes) is always a parameter of the operation.
otherwise the sample size (in bytes) is always a parameter of the
operation.
The module defines the following variables and functions:
\setindexsubitem{(in module audioop)}
\begin{excdesc}{error}
This exception is raised on all errors, such as unknown number of bytes
per sample, etc.
@ -28,14 +34,14 @@ length.
\begin{funcdesc}{adpcm2lin}{adpcmfragment, width, state}
Decode an Intel/DVI ADPCM coded fragment to a linear fragment. See
the description of \code{lin2adpcm} for details on ADPCM coding.
the description of \function{lin2adpcm()} for details on ADPCM coding.
Return a tuple \code{(\var{sample}, \var{newstate})} where the sample
has the width specified in \var{width}.
\end{funcdesc}
\begin{funcdesc}{adpcm32lin}{adpcmfragment, width, state}
Decode an alternative 3-bit ADPCM code. See \code{lin2adpcm3} for
details.
Decode an alternative 3-bit ADPCM code. See \function{lin2adpcm3()}
for details.
\end{funcdesc}
\begin{funcdesc}{avg}{fragment, width}
@ -60,26 +66,25 @@ argument.
\begin{funcdesc}{findfactor}{fragment, reference}
Return a factor \var{F} such that
\code{rms(add(fragment, mul(reference, -F)))} is minimal, i.e.,
return the factor with which you should multiply \var{reference} to
make it match as well as possible to \var{fragment}. The fragments
should both contain 2-byte samples.
\code{rms(add(\var{fragment}, mul(\var{reference}, -\var{F})))} is
minimal, i.e., return the factor with which you should multiply
\var{reference} to make it match as well as possible to
\var{fragment}. The fragments should both contain 2-byte samples.
The time taken by this routine is proportional to \code{len(fragment)}.
The time taken by this routine is proportional to
\code{len(\var{fragment})}.
\end{funcdesc}
\begin{funcdesc}{findfit}{fragment, reference}
This routine (which only accepts 2-byte sample fragments)
Try to match \var{reference} as well as possible to a portion of
\var{fragment} (which should be the longer fragment). This is
(conceptually) done by taking slices out of \var{fragment}, using
\code{findfactor} to compute the best match, and minimizing the
\function{findfactor()} to compute the best match, and minimizing the
result. The fragments should both contain 2-byte samples. Return a
tuple \code{(\var{offset}, \var{factor})} where \var{offset} is the
(integer) offset into \var{fragment} where the optimal match started
and \var{factor} is the (floating-point) factor as per
\code{findfactor}.
\function{findfactor()}.
\end{funcdesc}
\begin{funcdesc}{findmax}{fragment, length}
@ -88,7 +93,7 @@ bytes!)\ with maximum energy, i.e., return \var{i} for which
\code{rms(fragment[i*2:(i+length)*2])} is maximal. The fragments
should both contain 2-byte samples.
The routine takes time proportional to \code{len(fragment)}.
The routine takes time proportional to \code{len(\var{fragment})}.
\end{funcdesc}
\begin{funcdesc}{getsample}{fragment, width, index}
@ -106,11 +111,12 @@ between one sample and the next, divided by a (varying) step. The
Intel/DVI ADPCM algorithm has been selected for use by the IMA, so it
may well become a standard.
\code{State} is a tuple containing the state of the coder. The coder
\var{state} is a tuple containing the state of the coder. The coder
returns a tuple \code{(\var{adpcmfrag}, \var{newstate})}, and the
\var{newstate} should be passed to the next call of lin2adpcm. In the
initial call \code{None} can be passed as the state. \var{adpcmfrag}
is the ADPCM coded fragment packed 2 4-bit values per byte.
\var{newstate} should be passed to the next call of
\function{lin2adpcm()}. In the initial call, \code{None} can be
passed as the state. \var{adpcmfrag} is the ADPCM coded fragment
packed 2 4-bit values per byte.
\end{funcdesc}
\begin{funcdesc}{lin2adpcm3}{fragment, width, state}
@ -121,8 +127,8 @@ discouraged.
\end{funcdesc}
\begin{funcdesc}{lin2ulaw}{fragment, width}
Convert samples in the audio fragment to U-LAW encoding and return
this as a Python string. U-LAW is an audio encoding format whereby
Convert samples in the audio fragment to u-LAW encoding and return
this as a Python string. u-LAW is an audio encoding format whereby
you get a dynamic range of about 14 bits using only 8 bit samples. It
is used by the Sun audio hardware, among others.
\end{funcdesc}
@ -147,15 +153,18 @@ multiplied by the floating-point value \var{factor}. Overflow is
silently ignored.
\end{funcdesc}
\begin{funcdesc}{ratecv}{fragment, width, nchannels, inrate, outrate, state\optional{, weightA, weightB}}
\begin{funcdesc}{ratecv}{fragment, width, nchannels, inrate, outrate,
state\optional{, weightA\optional{, weightB}}}
Convert the frame rate of the input fragment.
\code{State} is a tuple containing the state of the converter. The
\var{state} is a tuple containing the state of the converter. The
converter returns a tupl \code{(\var{newfragment}, \var{newstate})},
and \var{newstate} should be passed to the next call of ratecv.
and \var{newstate} should be passed to the next call of
\function{ratecv()}.
The \code{weightA} and \code{weightB} arguments are parameters for a
simple digital filter and default to 1 and 0 respectively.
The \var{weightA} and \var{weightB} arguments are parameters for a
simple digital filter and default to \code{1} and \code{0}
respectively.
\end{funcdesc}
\begin{funcdesc}{reverse}{fragment, width}
@ -164,9 +173,12 @@ Reverse the samples in a fragment and returns the modified fragment.
\begin{funcdesc}{rms}{fragment, width}
Return the root-mean-square of the fragment, i.e.
%begin{latexonly}
\iftexi
%end{latexonly}
the square root of the quotient of the sum of all squared sample value,
divided by the sumber of samples.
%begin{latexonly}
\else
% in eqn: sqrt { sum S sub i sup 2 over n }
\begin{displaymath}
@ -174,6 +186,7 @@ divided by the sumber of samples.
\sqrt{\frac{\sum{{S_{i}}^{2}}}{n}}
\end{displaymath}
\fi
%end{latexonly}
This is a measure of the power in an audio signal.
\end{funcdesc}
@ -191,16 +204,17 @@ samples by \var{rfactor}.
\end{funcdesc}
\begin{funcdesc}{ulaw2lin}{fragment, width}
Convert sound fragments in ULAW encoding to linearly encoded sound
fragments. ULAW encoding always uses 8 bits samples, so \var{width}
Convert sound fragments in u-LAW encoding to linearly encoded sound
fragments. u-LAW encoding always uses 8 bits samples, so \var{width}
refers only to the sample width of the output fragment here.
\end{funcdesc}
Note that operations such as \code{mul} or \code{max} make no
distinction between mono and stereo fragments, i.e.\ all samples are
treated equal. If this is a problem the stereo fragment should be split
into two mono fragments first and recombined later. Here is an example
of how to do that:
Note that operations such as \function{mul()} or \function{max()} make
no distinction between mono and stereo fragments, i.e.\ all samples
are treated equal. If this is a problem the stereo fragment should be
split into two mono fragments first and recombined later. Here is an
example of how to do that:
\begin{verbatim}
def mul_stereo(sample, width, lfactor, rfactor):
lsample = audioop.tomono(sample, width, 1, 0)
@ -211,26 +225,27 @@ def mul_stereo(sample, width, lfactor, rfactor):
rsample = audioop.tostereo(rsample, width, 0, 1)
return audioop.add(lsample, rsample, width)
\end{verbatim}
%
If you use the ADPCM coder to build network packets and you want your
protocol to be stateless (i.e.\ to be able to tolerate packet loss)
you should not only transmit the data but also the state. Note that
you should send the \var{initial} state (the one you passed to
\code{lin2adpcm}) along to the decoder, not the final state (as returned by
the coder). If you want to use \code{struct} to store the state in
binary you can code the first element (the predicted value) in 16 bits
and the second (the delta index) in 8.
\function{lin2adpcm()}) along to the decoder, not the final state (as
returned by the coder). If you want to use \function{struct.struct()}
to store the state in binary you can code the first element (the
predicted value) in 16 bits and the second (the delta index) in 8.
The ADPCM coders have never been tried against other ADPCM coders,
only against themselves. It could well be that I misinterpreted the
standards in which case they will not be interoperable with the
respective standards.
The \code{find...} routines might look a bit funny at first sight.
The \function{find*()} routines might look a bit funny at first sight.
They are primarily meant to do echo cancellation. A reasonably
fast way to do this is to pick the most energetic piece of the output
sample, locate that in the input sample and subtract the whole output
sample from the input sample:
\begin{verbatim}
def echocancel(outputdata, inputdata):
pos = audioop.findmax(outputdata, 800) # one tenth second

130
Doc/lib/libbasehttp.tex
View file

@ -1,4 +1,4 @@
\section{Standard Module \sectcode{BaseHTTPServer}}
\section{Standard Module \module{BaseHTTPServer}}
\label{module-BaseHTTPServer}
\stmodindex{BaseHTTPServer}
@ -23,18 +23,21 @@ run the server looks like this:
\begin{verbatim}
def run(server_class=BaseHTTPServer.HTTPServer,
handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
server_address = ('', 8000)
httpd = server_class(server_address, handler_class)
httpd.serve_forever()
server_address = ('', 8000)
httpd = server_class(server_address, handler_class)
httpd.serve_forever()
\end{verbatim}
The \class{HTTPServer} class builds on the \class{TCPServer} class by
\begin{classdesc}{HTTPServer}{server_address, RequestHandlerClass}
This class builds on the \class{TCPServer} class by
storing the server address as instance
variables named \member{server_name} and \member{server_port}. The
server is accessible by the handler, typically through the handler's
\member{server} instance variable.
\end{classdesc}
The module's second class, \class{BaseHTTPRequestHandler}, is used
\begin{classdesc}{BaseHTTPRequestHandler}{request, client_address, server}
This class is used
to handle the HTTP requests that arrive at the server. By itself,
it cannot respond to any actual HTTP requests; it must be subclassed
to handle each request method (e.g. GET or POST).
@ -43,69 +46,69 @@ variables, and methods for use by subclasses.
The handler will parse the request and the headers, then call a
method specific to the request type. The method name is constructed
from the request. For example, for the request \samp{SPAM}, the
from the request. For example, for the request method \samp{SPAM}, the
\method{do_SPAM()} method will be called with no arguments. All of
the relevant information is stored into instance variables of the
handler.
the relevant information is stored in instance variables of the
handler. Subclasses should not need to override or extend the
\method{__init__()} method.
\end{classdesc}
\setindexsubitem{(BaseHTTPRequestHandler attribute)}
\class{BaseHTTPRequestHandler} has the following instance variables:
\begin{datadesc}{client_address}
\begin{memberdesc}{client_address}
Contains a tuple of the form \code{(\var{host}, \var{port})} referring
to the client's address.
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{command}
\begin{memberdesc}{command}
Contains the command (request type). For example, \code{'GET'}.
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{path}
\begin{memberdesc}{path}
Contains the request path.
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{request_version}
\begin{memberdesc}{request_version}
Contains the version string from the request. For example,
\code{'HTTP/1.0'}.
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{headers}
\begin{memberdesc}{headers}
Holds an instance of the class specified by the \member{MessageClass}
class variable. This instance parses and manages the headers in
the HTTP request.
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{rfile}
\begin{memberdesc}{rfile}
Contains an input stream, positioned at the start of the optional
input data.
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{wfile}
\begin{memberdesc}{wfile}
Contains the output stream for writing a response back to the client.
Proper adherance to the HTTP protocol must be used when writing
to this stream.
\end{datadesc}
\end{memberdesc}
\setindexsubitem{(BaseHTTPRequestHandler attribute)}
\code{BaseHTTPRequestHandler} has the following class variables:
\class{BaseHTTPRequestHandler} has the following class variables:
\begin{datadesc}{server_version}
\begin{memberdesc}{server_version}
Specifies the server software version. You may want to override
this.
The format is multiple whitespace-separated strings,
where each string is of the form name[/version].
For example, \code{'BaseHTTP/0.2'}.
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{sys_version}
\begin{memberdesc}{sys_version}
Contains the Python system version, in a form usable by the
\member{version_string} method and the \member{server_version} class
variable. For example, \code{'Python/1.4'}.
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{error_message_format}
\begin{memberdesc}{error_message_format}
Specifies a format string for building an error response to the
client. It uses parenthesized, keyed format specifiers, so the
format operand must be a dictionary. The \var{code} key should
@ -115,103 +118,102 @@ message of what occurred, and \var{explain} should be an
explanation of the error code number. Default \var{message}
and \var{explain} values can found in the \var{responses}
class variable.
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{protocol_version}
\begin{memberdesc}{protocol_version}
This specifies the HTTP protocol version used in responses.
Typically, this should not be overridden. Defaults to
\code{'HTTP/1.0'}.
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{MessageClass}
\begin{memberdesc}{MessageClass}
Specifies a \class{rfc822.Message}-like class to parse HTTP
headers. Typically, this is not overridden, and it defaults to
\class{mimetools.Message}.
\withsubitem{(in module mimetools)}{\ttindex{Message}}
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{responses}
\begin{memberdesc}{responses}
This variable contains a mapping of error code integers to two-element
tuples containing a short and long message. For example,
\code{\{\var{code}: (\var{shortmessage}, \var{longmessage})\}}. The
\var{shortmessage} is usually used as the \var{message} key in an
error response, and \var{longmessage} as the \var{explain} key
(see the \member{error_message_format} class variable).
\end{datadesc}
\end{memberdesc}
\setindexsubitem{(BaseHTTPRequestHandler method)}
A \class{BaseHTTPRequestHandler} instance has the following methods:
\begin{funcdesc}{handle}{}
\begin{methoddesc}{handle}{}
Overrides the superclass' \method{handle()} method to provide the
specific handler behavior. This method will parse and dispatch
the request to the appropriate \code{do_*()} method.
\end{funcdesc}
the request to the appropriate \method{do_*()} method.
\end{methoddesc}
\begin{funcdesc}{send_error}{code\optional{, message}}
\begin{methoddesc}{send_error}{code\optional{, message}}
Sends and logs a complete error reply to the client. The numeric
\var{code} specifies the HTTP error code, with \var{message} as
optional, more specific text. A complete set of headers is sent,
followed by text composed using the \member{error_message_format}
class variable.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{send_response}{code\optional{, message}}
\begin{methoddesc}{send_response}{code\optional{, message}}
Sends a response header and logs the accepted request. The HTTP
response line is sent, followed by \emph{Server} and \emph{Date}
headers. The values for these two headers are picked up from the
\method{version_string()} and \method{date_time_string()} methods,
respectively.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{send_header}{keyword, value}
\begin{methoddesc}{send_header}{keyword, value}
Writes a specific MIME header to the output stream. \var{keyword}
should specify the header keyword, with \var{value} specifying
its value.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{end_headers}{}
\begin{methoddesc}{end_headers}{}
Sends a blank line, indicating the end of the MIME headers in
the response.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{log_request}{\optional{code\optional{, size}}}
\begin{methoddesc}{log_request}{\optional{code\optional{, size}}}
Logs an accepted (successful) request. \var{code} should specify
the numeric HTTP code associated with the response. If a size of
the response is available, then it should be passed as the
\var{size} parameter.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{log_error}{...}
\begin{methoddesc}{log_error}{...}
Logs an error when a request cannot be fulfilled. By default,
it passes the message to \method{log_message()}, so it takes the
same arguments (\var{format} and additional values).
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{log_message}{format, ...}
\begin{methoddesc}{log_message}{format, ...}
Logs an arbitrary message to \code{sys.stderr}. This is typically
overridden to create custom error logging mechanisms. The
\var{format} argument is a standard printf-style format string,
where the additional arguments to \method{log_message()} are applied
as inputs to the formatting. The client address and current date
and time are prefixed to every message logged.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{version_string}{}
\begin{methoddesc}{version_string}{}
Returns the server software's version string. This is a combination
of the \member{server_version} and \member{sys_version} class variables.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{date_time_string}{}
\begin{methoddesc}{date_time_string}{}
Returns the current date and time, formatted for a message header.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{log_data_time_string}{}
\begin{methoddesc}{log_data_time_string}{}
Returns the current date and time, formatted for logging.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{address_string}{}
\begin{methoddesc}{address_string}{}
Returns the client address, formatted for logging. A name lookup
is performed on the client's IP address.
\end{funcdesc}
\end{methoddesc}

13
Doc/lib/libbinhex.tex
View file

@ -1,15 +1,13 @@
\section{Standard Module \sectcode{binhex}}
\section{Standard Module \module{binhex}}
\label{module-binhex}
\stmodindex{binhex}
This module encodes and decodes files in binhex4 format, a format
allowing representation of Macintosh files in ASCII. On the macintosh,
allowing representation of Macintosh files in \ASCII{}. On the Macintosh,
both forks of a file and the finder information are encoded (or
decoded), on other platforms only the data fork is handled.
The \code{binhex} module defines the following functions:
\setindexsubitem{(in module binhex)}
The \module{binhex} module defines the following functions:
\begin{funcdesc}{binhex}{input, output}
Convert a binary file with filename \var{input} to binhex file
@ -31,7 +29,8 @@ There is an alternative, more powerful interface to the coder and
decoder, see the source for details.
If you code or decode textfiles on non-Macintosh platforms they will
still use the macintosh newline convention (carriage-return as end of
still use the Macintosh newline convention (carriage-return as end of
line).
As of this writing, \var{hexbin} appears to not work in all cases.
As of this writing, \function{hexbin()} appears to not work in all
cases.

106
Doc/lib/libcd.tex
View file

@ -1,4 +1,4 @@
\section{Built-in Module \sectcode{cd}}
\section{Built-in Module \module{cd}}
\label{module-cd}
\bimodindex{cd}
@ -113,32 +113,34 @@ that can be set by the \method{addcallback()} method of CD parser
objects (see below).
\end{datadesc}
\subsection{Player Objects}
\label{player-objects}
Player objects (returned by \function{open()}) have the following
methods:
\setindexsubitem{(CD player method)}
\begin{funcdesc}{allowremoval}{}
\begin{methoddesc}[CD player]{allowremoval}{}
Unlocks the eject button on the CD-ROM drive permitting the user to
eject the caddy if desired.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{bestreadsize}{}
\begin{methoddesc}[CD player]{bestreadsize}{}
Returns the best value to use for the \var{num_frames} parameter of
the \method{readda()} method. Best is defined as the value that
permits a continuous flow of data from the CD-ROM drive.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{close}{}
\begin{methoddesc}[CD player]{close}{}
Frees the resources associated with the player object. After calling
\method{close()}, the methods of the object should no longer be used.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{eject}{}
\begin{methoddesc}[CD player]{eject}{}
Ejects the caddy from the CD-ROM drive.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getstatus}{}
\begin{methoddesc}[CD player]{getstatus}{}
Returns information pertaining to the current state of the CD-ROM
drive. The returned information is a tuple with the following values:
\var{state}, \var{track}, \var{rtime}, \var{atime}, \var{ttime},
@ -150,24 +152,24 @@ the meaning of the values, see the man page \manpage{CDgetstatus}{3dm}.
The value of \var{state} is one of the following: \constant{ERROR},
\constant{NODISC}, \constant{READY}, \constant{PLAYING},
\constant{PAUSED}, \constant{STILL}, or \constant{CDROM}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{gettrackinfo}{track}
\begin{methoddesc}[CD player]{gettrackinfo}{track}
Returns information about the specified track. The returned
information is a tuple consisting of two elements, the start time of
the track and the duration of the track.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{msftoblock}{min, sec, frame}
\begin{methoddesc}[CD player]{msftoblock}{min, sec, frame}
Converts a minutes, seconds, frames triple representing a time in
absolute time code into the corresponding logical block number for the
given CD-ROM drive. You should use \function{msftoframe()} rather than
\method{msftoblock()} for comparing times. The logical block number
differs from the frame number by an offset required by certain CD-ROM
drives.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{play}{start, play}
\begin{methoddesc}[CD player]{play}{start, play}
Starts playback of an audio CD in the CD-ROM drive at the specified
track. The audio output appears on the CD-ROM drive's headphone and
audio jacks (if fitted). Play stops at the end of the disc.
@ -175,71 +177,73 @@ audio jacks (if fitted). Play stops at the end of the disc.
CD; if \var{play} is 0, the CD will be set to an initial paused
state. The method \method{togglepause()} can then be used to commence
play.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{playabs}{minutes, seconds, frames, play}
\begin{methoddesc}[CD player]{playabs}{minutes, seconds, frames, play}
Like \method{play()}, except that the start is given in minutes,
seconds, and frames instead of a track number.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{playtrack}{start, play}
\begin{methoddesc}[CD player]{playtrack}{start, play}
Like \method{play()}, except that playing stops at the end of the
track.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{playtrackabs}{track, minutes, seconds, frames, play}
\begin{methoddesc}[CD player]{playtrackabs}{track, minutes, seconds, frames, play}
Like \method{play()}, except that playing begins at the spcified
absolute time and ends at the end of the specified track.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{preventremoval}{}
\begin{methoddesc}[CD player]{preventremoval}{}
Locks the eject button on the CD-ROM drive thus preventing the user
from arbitrarily ejecting the caddy.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{readda}{num_frames}
\begin{methoddesc}[CD player]{readda}{num_frames}
Reads the specified number of frames from an audio CD mounted in the
CD-ROM drive. The return value is a string representing the audio
frames. This string can be passed unaltered to the
\method{parseframe()} method of the parser object.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{seek}{minutes, seconds, frames}
\begin{methoddesc}[CD player]{seek}{minutes, seconds, frames}
Sets the pointer that indicates the starting point of the next read of
digital audio data from a CD-ROM. The pointer is set to an absolute
time code location specified in \var{minutes}, \var{seconds}, and
\var{frames}. The return value is the logical block number to which
the pointer has been set.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{seekblock}{block}
\begin{methoddesc}[CD player]{seekblock}{block}
Sets the pointer that indicates the starting point of the next read of
digital audio data from a CD-ROM. The pointer is set to the specified
logical block number. The return value is the logical block number to
which the pointer has been set.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{seektrack}{track}
\begin{methoddesc}[CD player]{seektrack}{track}
Sets the pointer that indicates the starting point of the next read of
digital audio data from a CD-ROM. The pointer is set to the specified
track. The return value is the logical block number to which the
pointer has been set.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{stop}{}
\begin{methoddesc}[CD player]{stop}{}
Stops the current playing operation.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{togglepause}{}
\begin{methoddesc}[CD player]{togglepause}{}
Pauses the CD if it is playing, and makes it play if it is paused.
\end{funcdesc}
\end{methoddesc}
\subsection{Parser Objects}
\label{cd-parser-objects}
Parser objects (returned by \function{createparser()}) have the
following methods:
\setindexsubitem{(CD parser method)}
\begin{funcdesc}{addcallback}{type, func, arg}
\begin{methoddesc}[CD parser]{addcallback}{type, func, arg}
Adds a callback for the parser. The parser has callbacks for eight
different types of data in the digital audio data stream. Constants
for these types are defined at the \module{cd} module level (see above).
@ -268,15 +272,15 @@ owner code, \\
\lineii{control}{Integer giving the control bits from the CD
subcode data}
\end{tableii}
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{deleteparser}{}
\begin{methoddesc}[CD parser]{deleteparser}{}
Deletes the parser and frees the memory it was using. The object
should not be used after this call. This call is done automatically
when the last reference to the object is removed.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{parseframe}{frame}
\begin{methoddesc}[CD parser]{parseframe}{frame}
Parses one or more frames of digital audio data from a CD such as
returned by \method{readda()}. It determines which subcodes are
present in the data. If these subcodes have changed since the last
@ -284,14 +288,14 @@ frame, then \method{parseframe()} executes a callback of the
appropriate type passing to it the subcode data found in the frame.
Unlike the \C{} function, more than one frame of digital audio data
can be passed to this method.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{removecallback}{type}
\begin{methoddesc}[CD parser]{removecallback}{type}
Removes the callback for the given \var{type}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{resetparser}{}
\begin{methoddesc}[CD parser]{resetparser}{}
Resets the fields of the parser used for tracking subcodes to an
initial state. \method{resetparser()} should be called after the disc
has been changed.
\end{funcdesc}
\end{methoddesc}

178
Doc/lib/libfl.tex
View file

@ -1,4 +1,4 @@
\section{Built-in Module \sectcode{fl}}
\section{Built-in Module \module{fl}}
\label{module-fl}
\bimodindex{fl}
@ -37,7 +37,7 @@ FORMS with pure GL windows.
function \cfunction{foreground()} and to the FORMS routine
\cfunction{fl_init()}.
\subsection{Functions Defined in Module \sectcode{fl}}
\subsection{Functions Defined in Module \module{fl}}
\nodename{FL Functions}
Module \module{fl} defines the following functions. For more
@ -83,7 +83,8 @@ Show a dialog box with a three-line message and YES and NO buttons.
It returns \code{1} if the user pressed YES, \code{0} if NO.
\end{funcdesc}
\begin{funcdesc}{show_choice}{str1, str2, str3, but1\optional{, but2, but3}}
\begin{funcdesc}{show_choice}{str1, str2, str3, but1\optional{,
but2\optional{, but3}}}
Show a dialog box with a three-line message and up to three buttons.
It returns the number of the button clicked by the user
(\code{1}, \code{2} or \code{3}).
@ -136,116 +137,117 @@ See the description in the FORMS documentation of
\end{funcdesc}
\subsection{Form Objects}
\label{form-objects}
Form objects (returned by \function{fl.make_form()} above) have the
Form objects (returned by \function{make_form()} above) have the
following methods. Each method corresponds to a \C{} function whose
name is prefixed with \samp{fl_}; and whose first argument is a form
pointer; please refer to the official FORMS documentation for
descriptions.
All the \code{add_*()} functions return a Python object
representing the FORMS object. Methods of FORMS objects are described
below. Most kinds of FORMS object also have some methods specific to
that kind; these methods are listed here.
All the \method{add_*()} methods return a Python object representing
the FORMS object. Methods of FORMS objects are described below. Most
kinds of FORMS object also have some methods specific to that kind;
these methods are listed here.
\begin{flushleft}
\setindexsubitem{(form method)}
\begin{funcdesc}{show_form}{placement, bordertype, name}
\begin{methoddesc}[form]{show_form}{placement, bordertype, name}
Show the form.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{hide_form}{}
\begin{methoddesc}[form]{hide_form}{}
Hide the form.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{redraw_form}{}
\begin{methoddesc}[form]{redraw_form}{}
Redraw the form.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{set_form_position}{x, y}
\begin{methoddesc}[form]{set_form_position}{x, y}
Set the form's position.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{freeze_form}{}
\begin{methoddesc}[form]{freeze_form}{}
Freeze the form.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{unfreeze_form}{}
\begin{methoddesc}[form]{unfreeze_form}{}
Unfreeze the form.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{activate_form}{}
\begin{methoddesc}[form]{activate_form}{}
Activate the form.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{deactivate_form}{}
\begin{methoddesc}[form]{deactivate_form}{}
Deactivate the form.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{bgn_group}{}
\begin{methoddesc}[form]{bgn_group}{}
Begin a new group of objects; return a group object.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{end_group}{}
\begin{methoddesc}[form]{end_group}{}
End the current group of objects.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{find_first}{}
\begin{methoddesc}[form]{find_first}{}
Find the first object in the form.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{find_last}{}
\begin{methoddesc}[form]{find_last}{}
Find the last object in the form.
\end{funcdesc}
\end{methoddesc}
%---
\begin{funcdesc}{add_box}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_box}{type, x, y, w, h, name}
Add a box object to the form.
No extra methods.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{add_text}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_text}{type, x, y, w, h, name}
Add a text object to the form.
No extra methods.
\end{funcdesc}
\end{methoddesc}
%\begin{funcdesc}{add_bitmap}{type, x, y, w, h, name}
%\begin{methoddesc}[form]{add_bitmap}{type, x, y, w, h, name}
%Add a bitmap object to the form.
%\end{funcdesc}
%\end{methoddesc}
\begin{funcdesc}{add_clock}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_clock}{type, x, y, w, h, name}
Add a clock object to the form. \\
Method:
\method{get_clock()}.
\end{funcdesc}
\end{methoddesc}
%---
\begin{funcdesc}{add_button}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_button}{type, x, y, w, h, name}
Add a button object to the form. \\
Methods:
\method{get_button()},
\method{set_button()}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{add_lightbutton}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_lightbutton}{type, x, y, w, h, name}
Add a lightbutton object to the form. \\
Methods:
\method{get_button()},
\method{set_button()}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{add_roundbutton}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_roundbutton}{type, x, y, w, h, name}
Add a roundbutton object to the form. \\
Methods:
\method{get_button()},
\method{set_button()}.
\end{funcdesc}
\end{methoddesc}
%---
\begin{funcdesc}{add_slider}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_slider}{type, x, y, w, h, name}
Add a slider object to the form. \\
Methods:
\method{set_slider_value()},
@ -256,9 +258,9 @@ Methods:
\method{set_slider_size()},
\method{set_slider_precision()},
\method{set_slider_step()}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{add_valslider}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_valslider}{type, x, y, w, h, name}
Add a valslider object to the form. \\
Methods:
\method{set_slider_value()},
@ -269,18 +271,18 @@ Methods:
\method{set_slider_size()},
\method{set_slider_precision()},
\method{set_slider_step()}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{add_dial}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_dial}{type, x, y, w, h, name}
Add a dial object to the form. \\
Methods:
\method{set_dial_value()},
\method{get_dial_value()},
\method{set_dial_bounds()},
\method{get_dial_bounds()}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{add_positioner}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_positioner}{type, x, y, w, h, name}
Add a positioner object to the form. \\
Methods:
\method{set_positioner_xvalue()},
@ -291,9 +293,9 @@ Methods:
\method{get_positioner_yvalue()},
\method{get_positioner_xbounds()},
\method{get_positioner_ybounds()}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{add_counter}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_counter}{type, x, y, w, h, name}
Add a counter object to the form. \\
Methods:
\method{set_counter_value()},
@ -302,30 +304,30 @@ Methods:
\method{set_counter_step()},
\method{set_counter_precision()},
\method{set_counter_return()}.
\end{funcdesc}
\end{methoddesc}
%---
\begin{funcdesc}{add_input}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_input}{type, x, y, w, h, name}
Add a input object to the form. \\
Methods:
\method{set_input()},
\method{get_input()},
\method{set_input_color()},
\method{set_input_return()}.
\end{funcdesc}
\end{methoddesc}
%---
\begin{funcdesc}{add_menu}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_menu}{type, x, y, w, h, name}
Add a menu object to the form. \\
Methods:
\method{set_menu()},
\method{get_menu()},
\method{addto_menu()}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{add_choice}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_choice}{type, x, y, w, h, name}
Add a choice object to the form. \\
Methods:
\method{set_choice()},
@ -337,9 +339,9 @@ Methods:
\method{get_choice_text()},
\method{set_choice_fontsize()},
\method{set_choice_fontstyle()}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{add_browser}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_browser}{type, x, y, w, h, name}
Add a browser object to the form. \\
Methods:
\method{set_browser_topline()},
@ -360,16 +362,16 @@ Methods:
\method{set_browser_fontsize()},
\method{set_browser_fontstyle()},
\method{set_browser_specialkey()}.
\end{funcdesc}
\end{methoddesc}
%---
\begin{funcdesc}{add_timer}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_timer}{type, x, y, w, h, name}
Add a timer object to the form. \\
Methods:
\method{set_timer()},
\method{get_timer()}.
\end{funcdesc}
\end{methoddesc}
\end{flushleft}
Form objects have the following data attributes; see the FORMS
@ -388,49 +390,49 @@ documentation:
\end{tableiii}
\subsection{FORMS Objects}
\label{forms-objects}
Besides methods specific to particular kinds of FORMS objects, all
FORMS objects also have the following methods:
\setindexsubitem{(FORMS method)}
\begin{funcdesc}{set_call_back}{function, argument}
\begin{methoddesc}[FORMS object]{set_call_back}{function, argument}
Set the object's callback function and argument. When the object
needs interaction, the callback function will be called with two
arguments: the object, and the callback argument. (FORMS objects
without a callback function are returned by \function{fl.do_forms()}
or \function{fl.check_forms()} when they need interaction.) Call this
method without arguments to remove the callback function.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{delete_object}{}
\begin{methoddesc}[FORMS object]{delete_object}{}
Delete the object.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{show_object}{}
\begin{methoddesc}[FORMS object]{show_object}{}
Show the object.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{hide_object}{}
\begin{methoddesc}[FORMS object]{hide_object}{}
Hide the object.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{redraw_object}{}
\begin{methoddesc}[FORMS object]{redraw_object}{}
Redraw the object.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{freeze_object}{}
\begin{methoddesc}[FORMS object]{freeze_object}{}
Freeze the object.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{unfreeze_object}{}
\begin{methoddesc}[FORMS object]{unfreeze_object}{}
Unfreeze the object.
\end{funcdesc}
\end{methoddesc}
%\begin{funcdesc}{handle_object}{} XXX
%\end{funcdesc}
%\begin{methoddesc}[FORMS object]{handle_object}{} XXX
%\end{methoddesc}
%\begin{funcdesc}{handle_object_direct}{} XXX
%\end{funcdesc}
%\begin{methoddesc}[FORMS object]{handle_object_direct}{} XXX
%\end{methoddesc}
FORMS objects have these data attributes; see the FORMS documentation:
@ -460,7 +462,7 @@ FORMS objects have these data attributes; see the FORMS documentation:
\lineiii{automatic}{int (read-only)}{(see FORMS docs)}
\end{tableiii}
\section{Standard Module \sectcode{FL}}
\section{Standard Module \module{FL}}
\label{module-FLuppercase}
\stmodindex{FL}
@ -475,7 +477,7 @@ import fl
from FL import *
\end{verbatim}
\section{Standard Module \sectcode{flp}}
\section{Standard Module \module{flp}}
\label{module-flp}
\stmodindex{flp}

85
Doc/lib/libftplib.tex
View file

@ -1,4 +1,4 @@
\section{Standard Module \sectcode{ftplib}}
\section{Standard Module \module{ftplib}}
\label{module-ftplib}
\stmodindex{ftplib}
\indexii{FTP}{protocol}
@ -30,7 +30,8 @@ dr-xr-srwt 105 ftp-usr pdmaint 1536 Mar 21 14:32 ..
The module defines the following items:
\begin{classdesc}{FTP}{\optional{host\optional{, user\optional{, passwd\optional{, acct}}}}}
\begin{classdesc}{FTP}{\optional{host\optional{, user\optional{,
passwd\optional{, acct}}}}}
Return a new instance of the \code{FTP} class. When
\var{host} is given, the method call \code{connect(\var{host})} is
made. When \var{user} is given, additionally the method call
@ -63,37 +64,37 @@ Exception raised when a reply is received from the server that does
not begin with a digit in the range 1--5.
\end{excdesc}
\subsection{FTP Objects}
\label{ftp-objects}
\class{FTP} instances have the following methods:
\setindexsubitem{(FTP method)}
\begin{funcdesc}{set_debuglevel}{level}
\begin{methoddesc}{set_debuglevel}{level}
Set the instance's debugging level. This controls the amount of
debugging output printed. The default, \code{0}, produces no
debugging output. A value of \code{1} produces a moderate amount of
debugging output, generally a single line per request. A value of
\code{2} or higher produces the maximum amount of debugging output,
logging each line sent and received on the control connection.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{connect}{host\optional{, port}}
\begin{methoddesc}{connect}{host\optional{, port}}
Connect to the given host and port. The default port number is \code{21}, as
specified by the FTP protocol specification. It is rarely needed to
specify a different port number. This function should be called only
once for each instance; it should not be called at all if a host was
given when the instance was created. All other methods can only be
used after a connection has been made.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getwelcome}{}
\begin{methoddesc}{getwelcome}{}
Return the welcome message sent by the server in reply to the initial
connection. (This message sometimes contains disclaimers or help
information that may be relevant to the user.)
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{login}{\optional{user\optional{, passwd\optional{, acct}}}}
\begin{methoddesc}{login}{\optional{user\optional{, passwd\optional{, acct}}}}
Log in as the given \var{user}. The \var{passwd} and \var{acct}
parameters are optional and default to the empty string. If no
\var{user} is specified, it defaults to \code{'anonymous'}. If
@ -106,25 +107,25 @@ once for each instance, after a connection has been established; it
should not be called at all if a host and user were given when the
instance was created. Most FTP commands are only allowed after the
client has logged in.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{abort}{}
\begin{methoddesc}{abort}{}
Abort a file transfer that is in progress. Using this does not always
work, but it's worth a try.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{sendcmd}{command}
\begin{methoddesc}{sendcmd}{command}
Send a simple command string to the server and return the response
string.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{voidcmd}{command}
\begin{methoddesc}{voidcmd}{command}
Send a simple command string to the server and handle the response.
Return nothing if a response code in the range 200--299 is received.
Raise an exception otherwise.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{retrbinary}{command, callback\optional{, maxblocksize}}
\begin{methoddesc}{retrbinary}{command, callback\optional{, maxblocksize}}
Retrieve a file in binary transfer mode. \var{command} should be an
appropriate \samp{RETR} command, i.e.\ \code{'RETR \var{filename}'}.
The \var{callback} function is called for each block of data received,
@ -133,73 +134,73 @@ The optional \var{maxblocksize} argument specifies the maximum chunk size to
read on the low-level socket object created to do the actual transfer
(which will also be the largest size of the data blocks passed to
\var{callback}). A reasonable default is chosen.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{retrlines}{command\optional{, callback}}
\begin{methoddesc}{retrlines}{command\optional{, callback}}
Retrieve a file or directory listing in \ASCII{} transfer mode.
\var{command} should be an appropriate \samp{RETR} command (see
\method{retrbinary()} or a \samp{LIST} command (usually just the string
\code{'LIST'}). The \var{callback} function is called for each line,
with the trailing CRLF stripped. The default \var{callback} prints
the line to \code{sys.stdout}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{storbinary}{command, file, blocksize}
\begin{methoddesc}{storbinary}{command, file, blocksize}
Store a file in binary transfer mode. \var{command} should be an
appropriate \samp{STOR} command, i.e.\ \code{"STOR \var{filename}"}.
\var{file} is an open file object which is read until \EOF{} using its
\method{read()} method in blocks of size \var{blocksize} to provide the
data to be stored.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{storlines}{command, file}
\begin{methoddesc}{storlines}{command, file}
Store a file in \ASCII{} transfer mode. \var{command} should be an
appropriate \samp{STOR} command (see \method{storbinary()}). Lines are
read until \EOF{} from the open file object \var{file} using its
\method{readline()} method to privide the data to be stored.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{nlst}{argument\optional{, \ldots}}
\begin{methoddesc}{nlst}{argument\optional{, \ldots}}
Return a list of files as returned by the \samp{NLST} command. The
optional \var{argument} is a directory to list (default is the current
server directory). Multiple arguments can be used to pass
non-standard options to the \samp{NLST} command.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{dir}{argument\optional{, \ldots}}
\begin{methoddesc}{dir}{argument\optional{, \ldots}}
Return a directory listing as returned by the \samp{LIST} command, as
a list of lines. The optional \var{argument} is a directory to list
(default is the current server directory). Multiple arguments can be
used to pass non-standard options to the \samp{LIST} command. If the
last argument is a function, it is used as a \var{callback} function
as for \method{retrlines()}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{rename}{fromname, toname}
\begin{methoddesc}{rename}{fromname, toname}
Rename file \var{fromname} on the server to \var{toname}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{cwd}{pathname}
\begin{methoddesc}{cwd}{pathname}
Set the current directory on the server.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{mkd}{pathname}
\begin{methoddesc}{mkd}{pathname}
Create a new directory on the server.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{pwd}{}
\begin{methoddesc}{pwd}{}
Return the pathname of the current directory on the server.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{quit}{}
\begin{methoddesc}{quit}{}
Send a \samp{QUIT} command to the server and close the connection.
This is the ``polite'' way to close a connection, but it may raise an
exception of the server reponds with an error to the \samp{QUIT}
command.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{close}{}
\begin{methoddesc}{close}{}
Close the connection unilaterally. This should not be applied to an
already closed connection (e.g.\ after a successful call to
\method{quit()}.
\end{funcdesc}
\end{methoddesc}

42
Doc/lib/libhttplib.tex
View file

@ -1,4 +1,4 @@
\section{Standard Module \sectcode{httplib}}
\section{Standard Module \module{httplib}}
\label{module-httplib}
\stmodindex{httplib}
\indexii{HTTP}{protocol}
@ -9,7 +9,10 @@ HTTP protocol. It is normally not used directly --- the module
\module{urllib}\refstmodindex{urllib} uses it to handle URLs that use
HTTP.
The module defines one class, \class{HTTP}. An \class{HTTP} instance
The module defines one class, \class{HTTP}:
\begin{classdesc}{HTTP}{\optional{host\optional{, port}}}
An \class{HTTP} instance
represents one transaction with an HTTP server. It should be
instantiated passing it a host and optional port number. If no port
number is passed, the port is extracted from the host string if it has
@ -45,50 +48,50 @@ step 4 makes no calls).
file object that it returns.
\end{enumerate}
\end{classdesc}
\subsection{HTTP Objects}
\class{HTTP} instances have the following methods:
\setindexsubitem{(HTTP method)}
\begin{funcdesc}{set_debuglevel}{level}
\begin{methoddesc}{set_debuglevel}{level}
Set the debugging level (the amount of debugging output printed).
The default debug level is \code{0}, meaning no debugging output is
printed.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{connect}{host\optional{, port}}
\begin{methoddesc}{connect}{host\optional{, port}}
Connect to the server given by \var{host} and \var{port}. See the
intro for the default port. This should be called directly only if
the instance was instantiated without passing a host.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{send}{data}
\begin{methoddesc}{send}{data}
Send data to the server. This should be used directly only after the
\method{endheaders()} method has been called and before
\method{getreply()} has been called.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{putrequest}{request, selector}
\begin{methoddesc}{putrequest}{request, selector}
This should be the first call after the connection to the server has
been made. It sends a line to the server consisting of the
\var{request} string, the \var{selector} string, and the HTTP version
(\code{HTTP/1.0}).
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{putheader}{header, argument\optional{, ...}}
\begin{methoddesc}{putheader}{header, argument\optional{, ...}}
Send an \rfc{822} style header to the server. It sends a line to the
server consisting of the header, a colon and a space, and the first
argument. If more arguments are given, continuation lines are sent,
each consisting of a tab and an argument.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{endheaders}{}
\begin{methoddesc}{endheaders}{}
Send a blank line to the server, signalling the end of the headers.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getreply}{}
\begin{methoddesc}{getreply}{}
Complete the request by shutting down the sending end of the socket,
read the reply from the server, and return a triple
\code{(\var{replycode}, \var{message}, \var{headers})}. Here,
@ -98,13 +101,13 @@ message string corresponding to the reply code; and \var{headers} is
an instance of the class \class{mimetools.Message} containing the
headers received from the server. See the description of the
\module{mimetools}\refstmodindex{mimetools} module.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getfile}{}
\begin{methoddesc}{getfile}{}
Return a file object from which the data returned by the server can be
read, using the \method{read()}, \method{readline()} or
\method{readlines()} methods.
\end{funcdesc}
\end{methoddesc}
\subsection{Example}
\nodename{HTTP Example}
@ -123,5 +126,4 @@ Here is an example session:
>>> f = h.getfile()
>>> data = f.read() # Get the raw HTML
>>> f.close()
>>>
\end{verbatim}

28
Doc/lib/libimageop.tex
View file

@ -1,16 +1,14 @@
\section{Built-in Module \sectcode{imageop}}
\section{Built-in Module \module{imageop}}
\label{module-imageop}
\bimodindex{imageop}
The \code{imageop} module contains some useful operations on images.
It operates on images consisting of 8 or 32 bit pixels
stored in Python strings. This is the same format as used
by \code{gl.lrectwrite} and the \code{imgfile} module.
The \module{imageop} module contains some useful operations on images.
It operates on images consisting of 8 or 32 bit pixels stored in
Python strings. This is the same format as used by
\function{gl.lrectwrite()} and the \module{imgfile} module.
The module defines the following variables and functions:
\setindexsubitem{(in module imageop)}
\begin{excdesc}{error}
This exception is raised on all errors, such as unknown number of bits
per pixel, etc.
@ -21,11 +19,11 @@ per pixel, etc.
Return the selected part of \var{image}, which should by
\var{width} by \var{height} in size and consist of pixels of
\var{psize} bytes. \var{x0}, \var{y0}, \var{x1} and \var{y1} are like
the \code{lrectread} parameters, i.e.\ the boundary is included in the
new image. The new boundaries need not be inside the picture. Pixels
that fall outside the old image will have their value set to zero. If
\var{x0} is bigger than \var{x1} the new image is mirrored. The same
holds for the y coordinates.
the \function{gl.lrectread()} parameters, i.e.\ the boundary is
included in the new image. The new boundaries need not be inside the
picture. Pixels that fall outside the old image will have their value
set to zero. If \var{x0} is bigger than \var{x1} the new image is
mirrored. The same holds for the y coordinates.
\end{funcdesc}
\begin{funcdesc}{scale}{image, psize, width, height, newwidth, newheight}
@ -46,7 +44,7 @@ interlacing, hence the name.
\begin{funcdesc}{grey2mono}{image, width, height, threshold}
Convert a 8-bit deep greyscale image to a 1-bit deep image by
tresholding all the pixels. The resulting image is tightly packed and
is probably only useful as an argument to \code{mono2grey}.
is probably only useful as an argument to \function{mono2grey()}.
\end{funcdesc}
\begin{funcdesc}{dither2mono}{image, width, height}
@ -74,8 +72,8 @@ dithering.
\begin{funcdesc}{dither2grey2}{image, width, height}
Convert an 8-bit greyscale image to a 2-bit greyscale image with
dithering. As for \code{dither2mono}, the dithering algorithm is
currently very simple.
dithering. As for \function{dither2mono()}, the dithering algorithm
is currently very simple.
\end{funcdesc}
\begin{funcdesc}{grey42grey}{image, width, height}

18
Doc/lib/libjpeg.tex
View file

@ -1,10 +1,12 @@
\section{Built-in Module \sectcode{jpeg}}
\section{Built-in Module \module{jpeg}}
\label{module-jpeg}
\bimodindex{jpeg}
The module \module{jpeg} provides access to the jpeg compressor and
decompressor written by the Independent JPEG Group. JPEG is a (draft?)
standard for compressing pictures. For details on jpeg or the
decompressor written by the Independent JPEG Group%
\index{Independent JPEG Group}%
. JPEG is a (draft?)
standard for compressing pictures. For details on JPEG or the
Independent JPEG Group software refer to the JPEG standard or the
documentation provided with the software.
@ -18,19 +20,19 @@ in case of errors.
\begin{funcdesc}{compress}{data, w, h, b}
Treat data as a pixmap of width \var{w} and height \var{h}, with
\var{b} bytes per pixel. The data is in SGI GL order, so the first
pixel is in the lower-left corner. This means that \code{gl.lrectread}
pixel is in the lower-left corner. This means that \function{gl.lrectread()}
return data can immediately be passed to \function{compress()}.
Currently only 1 byte and 4 byte pixels are allowed, the former being
treated as greyscale and the latter as RGB color.
\function{compress()} returns a string that contains the compressed
picture, in JFIF format.
picture, in JFIF\index{JFIF} format.
\end{funcdesc}
\begin{funcdesc}{decompress}{data}
Data is a string containing a picture in JFIF format. It returns a
tuple \code{(\var{data}, \var{width}, \var{height},
Data is a string containing a picture in JFIF\index{JFIF} format. It
returns a tuple \code{(\var{data}, \var{width}, \var{height},
\var{bytesperpixel})}. Again, the data is suitable to pass to
\code{gl.lrectwrite}.
\function{gl.lrectwrite()}.
\end{funcdesc}
\begin{funcdesc}{setoption}{name, value}

29
Doc/lib/libmimetools.tex
View file

@ -1,8 +1,7 @@
\section{Standard Module \sectcode{mimetools}}
\section{Standard Module \module{mimetools}}
\label{module-mimetools}
\stmodindex{mimetools}
\setindexsubitem{(in module mimetools)}
This module defines a subclass of the \class{rfc822.Message} class and
a number of utility functions that are useful for the manipulation for
@ -53,9 +52,7 @@ open file \var{output}. The block size is currently fixed at 8192.
The \class{Message} class defines the following methods in
addition to the \class{rfc822.Message} methods:
\setindexsubitem{(mimetool.Message method)}
\begin{funcdesc}{getplist}{}
\begin{methoddesc}{getplist}{}
Return the parameter list of the \code{content-type} header. This is
a list if strings. For parameters of the form
\samp{\var{key}=\var{value}}, \var{key} is converted to lower case but
@ -63,36 +60,36 @@ a list if strings. For parameters of the form
\samp{Content-type: text/html; spam=1; Spam=2; Spam} then
\method{getplist()} will return the Python list \code{['spam=1',
'spam=2', 'Spam']}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getparam}{name}
\begin{methoddesc}{getparam}{name}
Return the \var{value} of the first parameter (as returned by
\method{getplist()} of the form \samp{\var{name}=\var{value}} for the
given \var{name}. If \var{value} is surrounded by quotes of the form
`\code{<}...\code{>}' or `\code{"}...\code{"}', these are removed.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getencoding}{}
\begin{methoddesc}{getencoding}{}
Return the encoding specified in the \code{content-transfer-encoding}
message header. If no such header exists, return \code{'7bit'}. The
encoding is converted to lower case.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{gettype}{}
\begin{methoddesc}{gettype}{}
Return the message type (of the form \samp{\var{type}/\var{subtype}})
as specified in the \code{content-type} header. If no such header
exists, return \code{'text/plain'}. The type is converted to lower
case.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getmaintype}{}
\begin{methoddesc}{getmaintype}{}
Return the main type as specified in the \code{content-type} header.
If no such header exists, return \code{'text'}. The main type is
converted to lower case.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getsubtype}{}
\begin{methoddesc}{getsubtype}{}
Return the subtype as specified in the \code{content-type} header. If
no such header exists, return \code{'plain'}. The subtype is
converted to lower case.
\end{funcdesc}
\end{methoddesc}

44
Doc/lib/libmpz.tex
View file

@ -1,38 +1,48 @@
\section{Built-in Module \sectcode{mpz}}
\section{Built-in Module \module{mpz}}
\label{module-mpz}
\bimodindex{mpz}
This is an optional module. It is only available when Python is
configured to include it, which requires that the GNU MP software is
installed.
\index{MP, GNU library}
\index{arbitrary precision integers}
\index{integer!arbitrary precision}
This module implements the interface to part of the GNU MP library,
which defines arbitrary precision integer and rational number
arithmetic routines. Only the interfaces to the \emph{integer}
(\samp{mpz_{\rm \ldots}}) routines are provided. If not stated
(\function{mpz_*()}) routines are provided. If not stated
otherwise, the description in the GNU MP documentation can be applied.
In general, \dfn{mpz}-numbers can be used just like other standard
Python numbers, e.g.\ you can use the built-in operators like \code{+},
\code{*}, etc., as well as the standard built-in functions like
\code{abs}, \code{int}, \ldots, \code{divmod}, \code{pow}.
\strong{Please note:} the \emph{bitwise-xor} operation has been implemented as
a bunch of \emph{and}s, \emph{invert}s and \emph{or}s, because the library
lacks an \code{mpz_xor} function, and I didn't need one.
\function{abs()}, \function{int()}, \ldots, \function{divmod()},
\function{pow()}. \strong{Please note:} the \emph{bitwise-xor}
operation has been implemented as a bunch of \emph{and}s,
\emph{invert}s and \emph{or}s, because the library lacks an
\cfunction{mpz_xor()} function, and I didn't need one.
You create an mpz-number by calling the function called \code{mpz} (see
You create an mpz-number by calling the function \function{mpz()} (see
below for an exact description). An mpz-number is printed like this:
\code{mpz(\var{value})}.
\setindexsubitem{(in module mpz)}
\begin{funcdesc}{mpz}{value}
Create a new mpz-number. \var{value} can be an integer, a long,
another mpz-number, or even a string. If it is a string, it is
interpreted as an array of radix-256 digits, least significant digit
first, resulting in a positive number. See also the \code{binary}
first, resulting in a positive number. See also the \method{binary()}
method, described below.
\end{funcdesc}
\begin{datadesc}{MPZType}
The type of the objects returned by \function{mpz()} and most other
functions in this module.
\end{datadesc}
A number of \emph{extra} functions are defined in this module. Non
mpz-arguments are converted to mpz-values first, and the functions
return mpz-numbers.
@ -40,7 +50,7 @@ return mpz-numbers.
\begin{funcdesc}{powm}{base, exponent, modulus}
Return \code{pow(\var{base}, \var{exponent}) \%{} \var{modulus}}. If
\code{\var{exponent} == 0}, return \code{mpz(1)}. In contrast to the
\C-library function, this version can handle negative exponents.
\C{} library function, this version can handle negative exponents.
\end{funcdesc}
\begin{funcdesc}{gcd}{op1, op2}
@ -62,18 +72,18 @@ return mpz-numbers.
\end{funcdesc}
\begin{funcdesc}{divm}{numerator, denominator, modulus}
Returns a number \var{q}. such that
\code{\var{q} * \var{denominator} \%{} \var{modulus} == \var{numerator}}.
One could also implement this function in Python, using \code{gcdext}.
Returns a number \var{q} such that
\code{\var{q} * \var{denominator} \%{} \var{modulus} ==
\var{numerator}}. One could also implement this function in Python,
using \function{gcdext()}.
\end{funcdesc}
An mpz-number has one method:
\setindexsubitem{(mpz method)}
\begin{funcdesc}{binary}{}
\begin{methoddesc}[mpz]{binary}{}
Convert this mpz-number to a binary string, where the number has been
stored as an array of radix-256 digits, least significant digit first.
The mpz-number must have a value greater than or equal to zero,
otherwise a \code{ValueError}-exception will be raised.
\end{funcdesc}
otherwise \exception{ValueError} will be raised.
\end{methoddesc}

156
Doc/lib/libnntplib.tex
View file

@ -1,11 +1,10 @@
\section{Standard Module \sectcode{nntplib}}
\section{Standard Module \module{nntplib}}
\label{module-nntplib}
\stmodindex{nntplib}
\indexii{NNTP}{protocol}
\setindexsubitem{(in module nntplib)}
This module defines the class \code{NNTP} which implements the client
This module defines the class \class{NNTP} which implements the client
side of the NNTP protocol. It can be used to implement a news reader
or poster, or automated news processors. For more information on NNTP
(Network News Transfer Protocol), see Internet \rfc{977}.
@ -34,7 +33,6 @@ Group comp.lang.python has 59 articles, range 3742 to 3803
3803 Re: \POSIX{} wait and SIGCHLD
>>> s.quit()
'205 news.cwi.nl closing connection. Goodbye.'
>>>
\end{verbatim}
To post an article from a file (this assumes that the article has
@ -47,16 +45,15 @@ valid headers):
'240 Article posted successfully.'
>>> s.quit()
'205 news.cwi.nl closing connection. Goodbye.'
>>>
\end{verbatim}
%
The module itself defines the following items:
\begin{funcdesc}{NNTP}{host\optional{, port}}
Return a new instance of the \code{NNTP} class, representing a
\begin{classdesc}{NNTP}{host\optional{, port}}
Return a new instance of the \class{NNTP} class, representing a
connection to the NNTP server running on host \var{host}, listening at
port \var{port}. The default \var{port} is 119.
\end{funcdesc}
\end{classdesc}
\begin{excdesc}{error_reply}
Exception raised when an unexpected reply is received from the server.
@ -75,7 +72,9 @@ Exception raised when a reply is received from the server that does
not begin with a digit in the range 1--5.
\end{excdesc}
\subsection{NNTP Objects}
\label{nntp-objects}
NNTP instances have the following methods. The \var{response} that is
returned as the first item in the return tuple of almost all methods
@ -83,40 +82,40 @@ is the server's response: a string beginning with a three-digit code.
If the server's response indicates an error, the method raises one of
the above exceptions.
\setindexsubitem{(NNTP object method)}
\begin{funcdesc}{getwelcome}{}
\begin{methoddesc}{getwelcome}{}
Return the welcome message sent by the server in reply to the initial
connection. (This message sometimes contains disclaimers or help
information that may be relevant to the user.)
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{set_debuglevel}{level}
\begin{methoddesc}{set_debuglevel}{level}
Set the instance's debugging level. This controls the amount of
debugging output printed. The default, 0, produces no debugging
output. A value of 1 produces a moderate amount of debugging output,
generally a single line per request or response. A value of 2 or
higher produces the maximum amount of debugging output, logging each
line sent and received on the connection (including message text).
\end{funcdesc}
debugging output printed. The default, \code{0}, produces no debugging
output. A value of \code{1} produces a moderate amount of debugging
output, generally a single line per request or response. A value of
\code{2} or higher produces the maximum amount of debugging output,
logging each line sent and received on the connection (including
message text).
\end{methoddesc}
\begin{funcdesc}{newgroups}{date, time}
\begin{methoddesc}{newgroups}{date, time}
Send a \samp{NEWGROUPS} command. The \var{date} argument should be a
string of the form \code{"\var{yy}\var{mm}\var{dd}"} indicating the
date, and \var{time} should be a string of the form
\code{"\var{hh}\var{mm}\var{ss}"} indicating the time. Return a pair
\code{(\var{response}, \var{groups})} where \var{groups} is a list of
group names that are new since the given date and time.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{newnews}{group, date, time}
\begin{methoddesc}{newnews}{group, date, time}
Send a \samp{NEWNEWS} command. Here, \var{group} is a group name or
\code{"*"}, and \var{date} and \var{time} have the same meaning as for
\code{newgroups()}. Return a pair \code{(\var{response},
\code{'*'}, and \var{date} and \var{time} have the same meaning as for
\method{newgroups()}. Return a pair \code{(\var{response},
\var{articles})} where \var{articles} is a list of article ids.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{list}{}
\begin{methoddesc}{list}{}
Send a \samp{LIST} command. Return a pair \code{(\var{response},
\var{list})} where \var{list} is a list of tuples. Each tuple has the
form \code{(\var{group}, \var{last}, \var{first}, \var{flag})}, where
@ -124,106 +123,107 @@ form \code{(\var{group}, \var{last}, \var{first}, \var{flag})}, where
and first article numbers (as strings), and \var{flag} is \code{'y'}
if posting is allowed, \code{'n'} if not, and \code{'m'} if the
newsgroup is moderated. (Note the ordering: \var{last}, \var{first}.)
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{group}{name}
\begin{methoddesc}{group}{name}
Send a \samp{GROUP} command, where \var{name} is the group name.
Return a tuple \code{(\var{response}, \var{count}, \var{first},
\var{last}, \var{name})} where \var{count} is the (estimated) number
of articles in the group, \var{first} is the first article number in
the group, \var{last} is the last article number in the group, and
\var{name} is the group name. The numbers are returned as strings.
\end{funcdesc}
Return a tuple \code{(}\var{response}\code{,} \var{count}\code{,}
\var{first}\code{,} \var{last}\code{,} \var{name}\code{)} where
\var{count} is the (estimated) number of articles in the group,
\var{first} is the first article number in the group, \var{last} is
the last article number in the group, and \var{name} is the group
name. The numbers are returned as strings.
\end{methoddesc}
\begin{funcdesc}{help}{}
\begin{methoddesc}{help}{}
Send a \samp{HELP} command. Return a pair \code{(\var{response},
\var{list})} where \var{list} is a list of help strings.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{stat}{id}
\begin{methoddesc}{stat}{id}
Send a \samp{STAT} command, where \var{id} is the message id (enclosed
in \samp{<} and \samp{>}) or an article number (as a string).
in \character{<} and \character{>}) or an article number (as a string).
Return a triple \code{(\var{response}, \var{number}, \var{id})} where
\var{number} is the article number (as a string) and \var{id} is the
article id (enclosed in \samp{<} and \samp{>}).
\end{funcdesc}
article id (enclosed in \character{<} and \character{>}).
\end{methoddesc}
\begin{funcdesc}{next}{}
Send a \samp{NEXT} command. Return as for \code{stat()}.
\end{funcdesc}
\begin{methoddesc}{next}{}
Send a \samp{NEXT} command. Return as for \method{stat()}.
\end{methoddesc}
\begin{funcdesc}{last}{}
Send a \samp{LAST} command. Return as for \code{stat()}.
\end{funcdesc}
\begin{methoddesc}{last}{}
Send a \samp{LAST} command. Return as for \method{stat()}.
\end{methoddesc}
\begin{funcdesc}{head}{id}
\begin{methoddesc}{head}{id}
Send a \samp{HEAD} command, where \var{id} has the same meaning as for
\code{stat()}. Return a pair \code{(\var{response}, \var{list})}
\method{stat()}. Return a pair \code{(\var{response}, \var{list})}
where \var{list} is a list of the article's headers (an uninterpreted
list of lines, without trailing newlines).
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{body}{id}
\begin{methoddesc}{body}{id}
Send a \samp{BODY} command, where \var{id} has the same meaning as for
\code{stat()}. Return a pair \code{(\var{response}, \var{list})}
\method{stat()}. Return a pair \code{(\var{response}, \var{list})}
where \var{list} is a list of the article's body text (an
uninterpreted list of lines, without trailing newlines).
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{article}{id}
\begin{methoddesc}{article}{id}
Send a \samp{ARTICLE} command, where \var{id} has the same meaning as
for \code{stat()}. Return a pair \code{(\var{response}, \var{list})}
for \method{stat()}. Return a pair \code{(\var{response}, \var{list})}
where \var{list} is a list of the article's header and body text (an
uninterpreted list of lines, without trailing newlines).
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{slave}{}
\begin{methoddesc}{slave}{}
Send a \samp{SLAVE} command. Return the server's \var{response}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{xhdr}{header, string}
\begin{methoddesc}{xhdr}{header, string}
Send an \samp{XHDR} command. This command is not defined in the RFC
but is a common extension. The \var{header} argument is a header
keyword, e.g. \code{"subject"}. The \var{string} argument should have
keyword, e.g. \code{'subject'}. The \var{string} argument should have
the form \code{"\var{first}-\var{last}"} where \var{first} and
\var{last} are the first and last article numbers to search. Return a
pair \code{(\var{response}, \var{list})}, where \var{list} is a list of
pairs \code{(\var{id}, \var{text})}, where \var{id} is an article id
(as a string) and \var{text} is the text of the requested header for
that article.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{post}{file}
\begin{methoddesc}{post}{file}
Post an article using the \samp{POST} command. The \var{file}
argument is an open file object which is read until EOF using its
\code{readline()} method. It should be a well-formed news article,
including the required headers. The \code{post()} method
\method{readline()} method. It should be a well-formed news article,
including the required headers. The \method{post()} method
automatically escapes lines beginning with \samp{.}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{ihave}{id, file}
\begin{methoddesc}{ihave}{id, file}
Send an \samp{IHAVE} command. If the response is not an error, treat
\var{file} exactly as for the \code{post()} method.
\end{funcdesc}
\var{file} exactly as for the \method{post()} method.
\end{methoddesc}
\begin{funcdesc}{date}{}
\begin{methoddesc}{date}{}
Return a triple \code{(\var{response}, \var{date}, \var{time})},
containing the current date and time in a form suitable for the
\code{newnews} and \code{newgroups} methods.
\method{newnews()} and \method{newgroups()} methods.
This is an optional NNTP extension, and may not be supported by all
servers.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{xgtitle}{name}
Process an XGTITLE command, returning a pair \code{(\var{response},
\begin{methoddesc}{xgtitle}{name}
Process an \samp{XGTITLE} command, returning a pair \code{(\var{response},
\var{list})}, where \var{list} is a list of tuples containing
\code{(\var{name}, \var{title})}.
% XXX huh? Should that be name, description?
This is an optional NNTP extension, and may not be supported by all
servers.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{xover}{start, end}
\begin{methoddesc}{xover}{start, end}
Return a pair \code{(\var{resp}, \var{list})}. \var{list} is a list
of tuples, one for each article in the range delimited by the \var{start}
and \var{end} article numbers. Each tuple is of the form
@ -232,15 +232,15 @@ and \var{end} article numbers. Each tuple is of the form
\var{references}\code{,} \var{size}\code{,} \var{lines}\code{)}.
This is an optional NNTP extension, and may not be supported by all
servers.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{xpath}{id}
\begin{methoddesc}{xpath}{id}
Return a pair \code{(\var{resp}, \var{path})}, where \var{path} is the
directory path to the article with message ID \var{id}. This is an
optional NNTP extension, and may not be supported by all servers.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{quit}{}
\begin{methoddesc}{quit}{}
Send a \samp{QUIT} command and close the connection. Once this method
has been called, no other methods of the NNTP object should be called.
\end{funcdesc}
\end{methoddesc}

6
Doc/lib/librgbimg.tex
View file

@ -5,7 +5,7 @@
The \module{rgbimg} module allows Python programs to access SGI imglib image
files (also known as \file{.rgb} files). The module is far from
complete, but is provided anyway since the functionality that there is
is enough in some cases. Currently, colormap files are not supported.
enough in some cases. Currently, colormap files are not supported.
The module defines the following variables and functions:
@ -24,7 +24,7 @@ are currently supported.
This function reads and decodes the image on the specified file, and
returns it as a Python string. The string has 4 byte RGBA pixels.
The bottom left pixel is the first in
the string. This format is suitable to pass to \code{gl.lrectwrite},
the string. This format is suitable to pass to \function{gl.lrectwrite()},
for instance.
\end{funcdesc}
@ -34,7 +34,7 @@ file \var{file}. \var{x} and \var{y} give the size of the image.
\var{z} is 1 if the saved image should be 1 byte greyscale, 3 if the
saved image should be 3 byte RGB data, or 4 if the saved images should
be 4 byte RGBA data. The input data always contains 4 bytes per pixel.
These are the formats returned by \code{gl.lrectread}.
These are the formats returned by \function{gl.lrectread()}.
\end{funcdesc}
\begin{funcdesc}{ttob}{flag}

54
Doc/lib/librotor.tex
View file

@ -1,9 +1,10 @@
\section{Built-in Module \sectcode{rotor}}
\section{Built-in Module \module{rotor}}
\label{module-rotor}
\bimodindex{rotor}
This module implements a rotor-based encryption algorithm, contributed by
Lance Ellinghouse. The design is derived from the Enigma device, a machine
Lance Ellinghouse\index{Ellinghouse, Lance}. The design is derived
from the Enigma device\indexii{Enigma}{device}, a machine
used during World War II to encipher messages. A rotor is simply a
permutation. For example, if the character `A' is the origin of the rotor,
then a given rotor might map `A' to `L', `B' to `Z', `C' to `G', and so on.
@ -19,12 +20,10 @@ recursively. In other words, after enciphering one character, we advance
the rotors in the same fashion as a car's odometer. Decoding works in the
same way, except we reverse the permutations and apply them in the opposite
order.
\index{Ellinghouse, Lance}
\indexii{Enigma}{cipher}
The available functions in this module are:
\setindexsubitem{(in module rotor)}
\begin{funcdesc}{newrotor}{key\optional{, numrotors}}
Return a rotor object. \var{key} is a string containing the encryption key
for the object; it can contain arbitrary binary data. The key will be used
@ -35,32 +34,31 @@ if it is omitted, a default value of 6 will be used.
Rotor objects have the following methods:
\setindexsubitem{(rotor method)}
\begin{funcdesc}{setkey}{key}
\begin{methoddesc}[rotor]{setkey}{key}
Sets the rotor's key to \var{key}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{encrypt}{plaintext}
\begin{methoddesc}[rotor]{encrypt}{plaintext}
Reset the rotor object to its initial state and encrypt \var{plaintext},
returning a string containing the ciphertext. The ciphertext is always the
same length as the original plaintext.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{encryptmore}{plaintext}
\begin{methoddesc}[rotor]{encryptmore}{plaintext}
Encrypt \var{plaintext} without resetting the rotor object, and return a
string containing the ciphertext.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{decrypt}{ciphertext}
\begin{methoddesc}[rotor]{decrypt}{ciphertext}
Reset the rotor object to its initial state and decrypt \var{ciphertext},
returning a string containing the ciphertext. The plaintext string will
always be the same length as the ciphertext.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{decryptmore}{ciphertext}
\begin{methoddesc}[rotor]{decryptmore}{ciphertext}
Decrypt \var{ciphertext} without resetting the rotor object, and return a
string containing the ciphertext.
\end{funcdesc}
\end{methoddesc}
An example usage:
\begin{verbatim}
@ -80,17 +78,18 @@ An example usage:
'l(\315'
>>> del rt
\end{verbatim}
%
The module's code is not an exact simulation of the original Enigma device;
it implements the rotor encryption scheme differently from the original. The
most important difference is that in the original Enigma, there were only 5
or 6 different rotors in existence, and they were applied twice to each
character; the cipher key was the order in which they were placed in the
machine. The Python rotor module uses the supplied key to initialize a
random number generator; the rotor permutations and their initial positions
are then randomly generated. The original device only enciphered the
letters of the alphabet, while this module can handle any 8-bit binary data;
it also produces binary output. This module can also operate with an
The module's code is not an exact simulation of the original Enigma
device; it implements the rotor encryption scheme differently from the
original. The most important difference is that in the original
Enigma, there were only 5 or 6 different rotors in existence, and they
were applied twice to each character; the cipher key was the order in
which they were placed in the machine. The Python \module{rotor}
module uses the supplied key to initialize a random number generator;
the rotor permutations and their initial positions are then randomly
generated. The original device only enciphered the letters of the
alphabet, while this module can handle any 8-bit binary data; it also
produces binary output. This module can also operate with an
arbitrary number of rotors.
The original Enigma cipher was broken in 1944. % XXX: Is this right?
@ -102,5 +101,4 @@ for discouraging casual snooping through your files, it will probably be
just fine, and may be somewhat safer than using the \UNIX{} \program{crypt}
command.
\index{NSA}
\index{National Security Agency}\index{crypt(1)}
% XXX How were Unix commands represented in the docs?
\index{National Security Agency}

83
Doc/lib/libsunaudio.tex
View file

@ -1,15 +1,14 @@
\section{Built-in Module \sectcode{sunaudiodev}}
\section{Built-in Module \module{sunaudiodev}}
\label{module-sunaudiodev}
\bimodindex{sunaudiodev}
This module allows you to access the sun audio interface. The sun
audio hardware is capable of recording and playing back audio data
in U-LAW format with a sample rate of 8K per second. A full
description can be gotten with \samp{man audio}.
in u-LAW\index{u-LAW} format with a sample rate of 8K per second. A
full description can be found in the \manpage{audio}{7I} manual page.
The module defines the following variables and functions:
\setindexsubitem{(in module sunaudiodev)}
\begin{excdesc}{error}
This exception is raised on all errors. The argument is a string
describing what went wrong.
@ -22,87 +21,87 @@ is one of \code{'r'} for record-only access, \code{'w'} for play-only
access, \code{'rw'} for both and \code{'control'} for access to the
control device. Since only one process is allowed to have the recorder
or player open at the same time it is a good idea to open the device
only for the activity needed. See the audio manpage for details.
only for the activity needed. See \manpage{audio}{7I} for details.
\end{funcdesc}
\subsection{Audio Device Objects}
\label{audio-device-objects}
The audio device objects are returned by \code{open} define the
The audio device objects are returned by \function{open()} define the
following methods (except \code{control} objects which only provide
getinfo, setinfo and drain):
\method{getinfo()}, \method{setinfo()} and \method{drain()}):
\setindexsubitem{(audio device method)}
\begin{funcdesc}{close}{}
\begin{methoddesc}[audio device]{close}{}
This method explicitly closes the device. It is useful in situations
where deleting the object does not immediately close it since there
are other references to it. A closed device should not be used again.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{drain}{}
\begin{methoddesc}[audio device]{drain}{}
This method waits until all pending output is processed and then returns.
Calling this method is often not necessary: destroying the object will
automatically close the audio device and this will do an implicit drain.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{flush}{}
\begin{methoddesc}[audio device]{flush}{}
This method discards all pending output. It can be used avoid the
slow response to a user's stop request (due to buffering of up to one
second of sound).
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getinfo}{}
\begin{methoddesc}[audio device]{getinfo}{}
This method retrieves status information like input and output volume,
etc. and returns it in the form of
an audio status object. This object has no methods but it contains a
number of attributes describing the current device status. The names
and meanings of the attributes are described in
\file{/usr/include/sun/audioio.h} and in the audio man page. Member names
are slightly different from their C counterparts: a status object is
only a single structure. Members of the \code{play} substructure have
\samp{o_} prepended to their name and members of the \code{record}
structure have \samp{i_}. So, the C member \code{play.sample_rate} is
accessed as \code{o_sample_rate}, \code{record.gain} as \code{i_gain}
and \code{monitor_gain} plainly as \code{monitor_gain}.
\end{funcdesc}
\file{/usr/include/sun/audioio.h} and in the \manpage{audio}{7I}
manual page. Member names
are slightly different from their \C{} counterparts: a status object is
only a single structure. Members of the \cdata{play} substructure have
\samp{o_} prepended to their name and members of the \cdata{record}
structure have \samp{i_}. So, the \C{} member \cdata{play.sample_rate} is
accessed as \member{o_sample_rate}, \cdata{record.gain} as \member{i_gain}
and \cdata{monitor_gain} plainly as \member{monitor_gain}.
\end{methoddesc}
\begin{funcdesc}{ibufcount}{}
\begin{methoddesc}[audio device]{ibufcount}{}
This method returns the number of samples that are buffered on the
recording side, i.e.
the program will not block on a \function{read()} call of so many samples.
\end{funcdesc}
recording side, i.e.\ the program will not block on a
\function{read()} call of so many samples.
\end{methoddesc}
\begin{funcdesc}{obufcount}{}
\begin{methoddesc}[audio device]{obufcount}{}
This method returns the number of samples buffered on the playback
side. Unfortunately, this number cannot be used to determine a number
of samples that can be written without blocking since the kernel
output queue length seems to be variable.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{read}{size}
\begin{methoddesc}[audio device]{read}{size}
This method reads \var{size} samples from the audio input and returns
them as a Python string. The function blocks until enough data is available.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setinfo}{status}
\begin{methoddesc}[audio device]{setinfo}{status}
This method sets the audio device status parameters. The \var{status}
parameter is an device status object as returned by \function{getinfo()} and
possibly modified by the program.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{write}{samples}
\begin{methoddesc}[audio device]{write}{samples}
Write is passed a Python string containing audio samples to be played.
If there is enough buffer space free it will immediately return,
otherwise it will block.
\end{funcdesc}
\end{methoddesc}
There is a companion module, \module{SUNAUDIODEV}, which defines useful
There is a companion module,
\module{SUNAUDIODEV}\refstmodindex{SUNAUDIODEV}, which defines useful
symbolic constants like \constant{MIN_GAIN}, \constant{MAX_GAIN},
\constant{SPEAKER}, etc. The names of
the constants are the same names as used in the \C{} include file
\code{<sun/audioio.h>}, with the leading string \samp{AUDIO_}
stripped.
\refstmodindex{SUNAUDIODEV}
\constant{SPEAKER}, etc. The names of the constants are the same names
as used in the \C{} include file \code{<sun/audioio.h>}, with the
leading string \samp{AUDIO_} stripped.
Useability of the control device is limited at the moment, since there
is no way to use the ``wait for something to happen'' feature the

124
Doc/lib/libxmllib.tex
View file

@ -1,4 +1,4 @@
\section{Standard Module \sectcode{xmllib}}
\section{Standard Module \module{xmllib}}
% Author: Sjoerd Mullender
\label{module-xmllib}
\stmodindex{xmllib}
@ -13,59 +13,57 @@ The \class{XMLParser} class must be instantiated without arguments.
This class provides the following interface methods:
\setindexsubitem{(XMLParser method)}
\begin{funcdesc}{reset}{}
\begin{methoddesc}{reset}{}
Reset the instance. Loses all unprocessed data. This is called
implicitly at the instantiation time.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setnomoretags}{}
\begin{methoddesc}{setnomoretags}{}
Stop processing tags. Treat all following input as literal input
(CDATA).
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setliteral}{}
\begin{methoddesc}{setliteral}{}
Enter literal mode (CDATA mode).
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{feed}{data}
\begin{methoddesc}{feed}{data}
Feed some text to the parser. It is processed insofar as it consists
of complete elements; incomplete data is buffered until more data is
fed or \method{close()} is called.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{close}{}
\begin{methoddesc}{close}{}
Force processing of all buffered data as if it were followed by an
end-of-file mark. This method may be redefined by a derived class to
define additional processing at the end of the input, but the
redefined version should always call \method{close()}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{translate_references}{data}
\begin{methoddesc}{translate_references}{data}
Translate all entity and character references in \var{data} and
returns the translated string.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{handle_xml}{encoding, standalone}
This method is called when the \code{<?xml ...?>} tag is processed.
\begin{methoddesc}{handle_xml}{encoding, standalone}
This method is called when the \samp{<?xml ...?>} tag is processed.
The arguments are the values of the encoding and standalone attributes
in the tag. Both encoding and standalone are optional. The values
passed to \method{handle_xml()} default to \code{None} and the string
\code{'no'} respectively.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{handle_doctype}{tag, data}
This method is called when the \code{<!DOCTYPE...>} tag is processed.
\begin{methoddesc}{handle_doctype}{tag, data}
This method is called when the \samp{<!DOCTYPE...>} tag is processed.
The arguments are the name of the root element and the uninterpreted
contents of the tag, starting after the white space after the name of
the root element.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{handle_starttag}{tag, method, attributes}
\begin{methoddesc}{handle_starttag}{tag, method, attributes}
This method is called to handle start tags for which a
\code{start_\var{tag}()} method has been defined. The \var{tag}
argument is the name of the tag, and the \method{method} argument is the
\method{start_\var{tag}()} method has been defined. The \var{tag}
argument is the name of the tag, and the \var{method} argument is the
bound method which should be used to support semantic interpretation
of the start tag. The \var{attributes} argument is a dictionary of
attributes, the key being the \var{name} and the value being the
@ -76,29 +74,29 @@ been interpreted. For instance, for the tag
\code{handle_starttag('A', self.start_A, \{'HREF': 'http://www.cwi.nl/'\})}.
The base implementation simply calls \var{method} with \var{attributes}
as the only argument.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{handle_endtag}{tag, method}
\begin{methoddesc}{handle_endtag}{tag, method}
This method is called to handle endtags for which an
\code{end_\var{tag}()} method has been defined. The \var{tag}
\method{end_\var{tag}()} method has been defined. The \var{tag}
argument is the name of the tag, and the
\var{method} argument is the bound method which should be used to
support semantic interpretation of the end tag. If no
\code{end_\var{tag}()} method is defined for the closing element, this
\method{end_\var{tag}()} method is defined for the closing element, this
handler is not called. The base implementation simply calls
\var{method}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{handle_data}{data}
\begin{methoddesc}{handle_data}{data}
This method is called to process arbitrary data. It is intended to be
overridden by a derived class; the base class implementation does
nothing.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{handle_charref}{ref}
\begin{methoddesc}{handle_charref}{ref}
This method is called to process a character reference of the form
\samp{\&\#\var{ref};}. \var{ref} can either be a decimal number,
or a hexadecimal number when preceded by \code{x}.
or a hexadecimal number when preceded by an \character{x}.
In the base implementation, \var{ref} must be a number in the
range 0-255. It translates the character to \ASCII{} and calls the
method \method{handle_data()} with the character as argument. If
@ -106,9 +104,9 @@ method \method{handle_data()} with the character as argument. If
\code{unknown_charref(\var{ref})} is called to handle the error. A
subclass must override this method to provide support for character
references outside of the \ASCII{} range.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{handle_entityref}{ref}
\begin{methoddesc}{handle_entityref}{ref}
This method is called to process a general entity reference of the
form \samp{\&\var{ref};} where \var{ref} is an general entity
reference. It looks for \var{ref} in the instance (or class)
@ -119,48 +117,48 @@ with the translation; otherwise, it calls the method
\code{unknown_entityref(\var{ref})}. The default \member{entitydefs}
defines translations for \code{\&amp;}, \code{\&apos}, \code{\&gt;},
\code{\&lt;}, and \code{\&quot;}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{handle_comment}{comment}
\begin{methoddesc}{handle_comment}{comment}
This method is called when a comment is encountered. The
\var{comment} argument is a string containing the text between the
\samp{<!--} and \samp{-->} delimiters, but not the delimiters
themselves. For example, the comment \samp{<!--text-->} will
cause this method to be called with the argument \code{'text'}. The
default method does nothing.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{handle_cdata}{data}
\begin{methoddesc}{handle_cdata}{data}
This method is called when a CDATA element is encountered. The
\var{data} argument is a string containing the text between the
\samp{<![CDATA[} and \samp{]]>} delimiters, but not the delimiters
themselves. For example, the entity \samp{<![CDATA[text]]>} will
cause this method to be called with the argument \code{'text'}. The
default method does nothing, and is intended to be overridden.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{handle_proc}{name, data}
\begin{methoddesc}{handle_proc}{name, data}
This method is called when a processing instruction (PI) is
encountered. The \var{name} is the PI target, and the \var{data}
argument is a string containing the text between the PI target and the
closing delimiter, but not the delimiter itself. For example, the
instruction \samp{<?XML text?>} will cause this method to be called
with the arguments \code{'XML'} and \code{'text'}. The default method
does nothing. Note that if a document starts with \code{<?xml
does nothing. Note that if a document starts with \samp{<?xml
...?>}, \method{handle_xml()} is called to handle it.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{handle_special}{data}
\begin{methoddesc}{handle_special}{data}
This method is called when a declaration is encountered. The
\var{data} argument is a string containing the text between the
\samp{<!} and \samp{>} delimiters, but not the delimiters
themselves. For example, the entity \samp{<!ENTITY text>} will
cause this method to be called with the argument \code{'ENTITY text'}. The
default method does nothing. Note that \code{<!DOCTYPE ...>} is
default method does nothing. Note that \samp{<!DOCTYPE ...>} is
handled separately if it is located at the start of the document.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{syntax_error}{message}
\begin{methoddesc}{syntax_error}{message}
This method is called when a syntax error is encountered. The
\var{message} is a description of what was wrong. The default method
raises a \exception{RuntimeError} exception. If this method is
@ -168,31 +166,31 @@ overridden, it is permissable for it to return. This method is only
called when the error can be recovered from. Unrecoverable errors
raise a \exception{RuntimeError} without first calling
\method{syntax_error()}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{unknown_starttag}{tag, attributes}
\begin{methoddesc}{unknown_starttag}{tag, attributes}
This method is called to process an unknown start tag. It is intended
to be overridden by a derived class; the base class implementation
does nothing.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{unknown_endtag}{tag}
\begin{methoddesc}{unknown_endtag}{tag}
This method is called to process an unknown end tag. It is intended
to be overridden by a derived class; the base class implementation
does nothing.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{unknown_charref}{ref}
\begin{methoddesc}{unknown_charref}{ref}
This method is called to process unresolvable numeric character
references. It is intended to be overridden by a derived class; the
base class implementation does nothing.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{unknown_entityref}{ref}
\begin{methoddesc}{unknown_entityref}{ref}
This method is called to process an unknown entity reference. It is
intended to be overridden by a derived class; the base class
implementation does nothing.
\end{funcdesc}
\end{methoddesc}
Apart from overriding or extending the methods listed above, derived
classes may also define methods and variables of the following form to
@ -200,19 +198,19 @@ define processing of specific tags. Tag names in the input stream are
case dependent; the \var{tag} occurring in method names must be in the
correct case:
\begin{funcdescni}{start_\var{tag}}{attributes}
\begin{methoddescni}{start_\var{tag}}{attributes}
This method is called to process an opening tag \var{tag}. The
\var{attributes} argument has the same meaning as described for
\method{handle_starttag()} above. In fact, the base implementation of
\method{handle_starttag()} calls this method.
\end{funcdescni}
\end{methoddescni}
\begin{funcdescni}{end_\var{tag}}{}
\begin{methoddescni}{end_\var{tag}}{}
This method is called to process a closing tag \var{tag}.
\end{funcdescni}
\end{methoddescni}
\begin{datadescni}{\var{tag}_attributes}
If a class or instance variable \code{\var{tag}_attributes} exists, it
\begin{memberdescni}{\var{tag}_attributes}
If a class or instance variable \member{\var{tag}_attributes} exists, it
should be a list or a dictionary. If a list, the elements of the list
are the valid attributes for the element \var{tag}; if a dictionary,
the keys are the valid attributes for the element \var{tag}, and the
@ -222,4 +220,4 @@ In addition to the attributes that were present in the tag, the
attribute dictionary that is passed to \method{handle_starttag()} and
\method{unknown_starttag()} contains values for all attributes that
have a default value.
\end{datadescni}
\end{memberdescni}

156
Doc/libaifc.tex
View file

@ -1,4 +1,4 @@
\section{Standard Module \sectcode{aifc}}
\section{Standard Module \module{aifc}}
\label{module-aifc}
\stmodindex{aifc}
@ -6,6 +6,9 @@ This module provides support for reading and writing AIFF and AIFF-C
files. AIFF is Audio Interchange File Format, a format for storing
digital audio samples in a file. AIFF-C is a newer version of the
format that includes the ability to compress the audio data.
\index{Audio Interchange File Format}
\index{AIFF}
\index{AIFF-C}
Audio files have a number of parameters that describe the audio data.
The sampling rate or frame rate is the number of times per second the
@ -21,9 +24,8 @@ bits), uses two channels (stereo) and has a frame rate of 44,100
frames/second. This gives a frame size of 4 bytes (2*2), and a
second's worth occupies 2*2*44100 bytes, i.e.\ 176,400 bytes.
Module \code{aifc} defines the following function:
Module \module{aifc} defines the following function:
\setindexsubitem{(in module aifc)}
\begin{funcdesc}{open}{file, mode}
Open an AIFF or AIFF-C file and return an object instance with
methods that are described below. The argument file is either a
@ -32,159 +34,161 @@ string naming a file or a file object. The mode is either the string
when the file must be opened for writing. When used for writing, the
file object should be seekable, unless you know ahead of time how many
samples you are going to write in total and use
\code{writeframesraw()} and \code{setnframes()}.
\method{writeframesraw()} and \method{setnframes()}.
\end{funcdesc}
Objects returned by \code{aifc.open()} when a file is opened for
Objects returned by \function{open()} when a file is opened for
reading have the following methods:
\setindexsubitem{(aifc object method)}
\begin{funcdesc}{getnchannels}{}
\begin{methoddesc}[aifc]{getnchannels}{}
Return the number of audio channels (1 for mono, 2 for stereo).
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getsampwidth}{}
\begin{methoddesc}[aifc]{getsampwidth}{}
Return the size in bytes of individual samples.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getframerate}{}
\begin{methoddesc}[aifc]{getframerate}{}
Return the sampling rate (number of audio frames per second).
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getnframes}{}
\begin{methoddesc}[aifc]{getnframes}{}
Return the number of audio frames in the file.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getcomptype}{}
\begin{methoddesc}[aifc]{getcomptype}{}
Return a four-character string describing the type of compression used
in the audio file. For AIFF files, the returned value is
\code{'NONE'}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getcompname}{}
\begin{methoddesc}[aifc]{getcompname}{}
Return a human-readable description of the type of compression used in
the audio file. For AIFF files, the returned value is \code{'not
compressed'}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getparams}{}
\begin{methoddesc}[aifc]{getparams}{}
Return a tuple consisting of all of the above values in the above
order.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getmarkers}{}
\begin{methoddesc}[aifc]{getmarkers}{}
Return a list of markers in the audio file. A marker consists of a
tuple of three elements. The first is the mark ID (an integer), the
second is the mark position in frames from the beginning of the data
(an integer), the third is the name of the mark (a string).
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getmark}{id}
Return the tuple as described in \code{getmarkers} for the mark with
the given id.
\end{funcdesc}
\begin{methoddesc}[aifc]{getmark}{id}
Return the tuple as described in \method{getmarkers()} for the mark
with the given \var{id}.
\end{methoddesc}
\begin{funcdesc}{readframes}{nframes}
\begin{methoddesc}[aifc]{readframes}{nframes}
Read and return the next \var{nframes} frames from the audio file. The
returned data is a string containing for each frame the uncompressed
samples of all channels.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{rewind}{}
Rewind the read pointer. The next \code{readframes} will start from
\begin{methoddesc}[aifc]{rewind}{}
Rewind the read pointer. The next \method{readframes()} will start from
the beginning.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setpos}{pos}
\begin{methoddesc}[aifc]{setpos}{pos}
Seek to the specified frame number.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{tell}{}
\begin{methoddesc}[aifc]{tell}{}
Return the current frame number.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{close}{}
\begin{methoddesc}[aifc]{close}{}
Close the AIFF file. After calling this method, the object can no
longer be used.
\end{funcdesc}
\end{methoddesc}
Objects returned by \code{aifc.open()} when a file is opened for
writing have all the above methods, except for \code{readframes} and
\code{setpos}. In addition the following methods exist. The
\code{get} methods can only be called after the corresponding
\code{set} methods have been called. Before the first
\code{writeframes()} or \code{writeframesraw()}, all parameters except
for the number of frames must be filled in.
Objects returned by \function{open()} when a file is opened for
writing have all the above methods, except for \method{readframes()} and
\method{setpos()}. In addition the following methods exist. The
\method{get*()} methods can only be called after the corresponding
\method{set*()} methods have been called. Before the first
\method{writeframes()} or \method{writeframesraw()}, all parameters
except for the number of frames must be filled in.
\begin{funcdesc}{aiff}{}
\begin{methoddesc}[aifc]{aiff}{}
Create an AIFF file. The default is that an AIFF-C file is created,
unless the name of the file ends in \code{'.aiff'} in which case the
default is an AIFF file.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{aifc}{}
\begin{methoddesc}[aifc]{aifc}{}
Create an AIFF-C file. The default is that an AIFF-C file is created,
unless the name of the file ends in \code{'.aiff'} in which case the
default is an AIFF file.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setnchannels}{nchannels}
\begin{methoddesc}[aifc]{setnchannels}{nchannels}
Specify the number of channels in the audio file.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setsampwidth}{width}
\begin{methoddesc}[aifc]{setsampwidth}{width}
Specify the size in bytes of audio samples.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setframerate}{rate}
\begin{methoddesc}[aifc]{setframerate}{rate}
Specify the sampling frequency in frames per second.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setnframes}{nframes}
\begin{methoddesc}[aifc]{setnframes}{nframes}
Specify the number of frames that are to be written to the audio file.
If this parameter is not set, or not set correctly, the file needs to
support seeking.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setcomptype}{type, name}
\begin{methoddesc}[aifc]{setcomptype}{type, name}
Specify the compression type. If not specified, the audio data will
not be compressed. In AIFF files, compression is not possible. The
name parameter should be a human-readable description of the
compression type, the type parameter should be a four-character
string. Currently the following compression types are supported:
NONE, ULAW, ALAW, G722.
\end{funcdesc}
\index{u-LAW}
\index{A-LAW}
\index{G.722}
\end{methoddesc}
\begin{funcdesc}{setparams}{nchannels, sampwidth, framerate, comptype, compname}
\begin{methoddesc}[aifc]{setparams}{nchannels, sampwidth, framerate, comptype, compname}
Set all the above parameters at once. The argument is a tuple
consisting of the various parameters. This means that it is possible
to use the result of a \code{getparams()} call as argument to
\code{setparams()}.
\end{funcdesc}
to use the result of a \method{getparams()} call as argument to
\method{setparams()}.
\end{methoddesc}
\begin{funcdesc}{setmark}{id, pos, name}
\begin{methoddesc}[aifc]{setmark}{id, pos, name}
Add a mark with the given id (larger than 0), and the given name at
the given position. This method can be called at any time before
\code{close()}.
\end{funcdesc}
\method{close()}.
\end{methoddesc}
\begin{funcdesc}{tell}{}
\begin{methoddesc}[aifc]{tell}{}
Return the current write position in the output file. Useful in
combination with \code{setmark()}.
\end{funcdesc}
combination with \method{setmark()}.
\end{methoddesc}
\begin{funcdesc}{writeframes}{data}
\begin{methoddesc}[aifc]{writeframes}{data}
Write data to the output file. This method can only be called after
the audio file parameters have been set.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{writeframesraw}{data}
Like \code{writeframes()}, except that the header of the audio file is
not updated.
\end{funcdesc}
\begin{methoddesc}[aifc]{writeframesraw}{data}
Like \method{writeframes()}, except that the header of the audio file
is not updated.
\end{methoddesc}
\begin{funcdesc}{close}{}
\begin{methoddesc}[aifc]{close}{}
Close the AIFF file. The header of the file is updated to reflect the
actual size of the audio data. After calling this method, the object
can no longer be used.
\end{funcdesc}
\end{methoddesc}

138
Doc/libal.tex
View file

@ -1,4 +1,4 @@
\section{Built-in Module \sectcode{al}}
\section{Built-in Module \module{al}}
\label{module-al}
\bimodindex{al}
@ -10,10 +10,11 @@ releases before 4.0.5. Again, see the manual to check whether a
specific function is available on your platform.
All functions and methods defined in this module are equivalent to
the C functions with \samp{AL} prefixed to their name.
the \C{} functions with \samp{AL} prefixed to their name.
Symbolic constants from the C header file \file{<audio.h>} are defined
in the standard module \code{AL}, see below.
Symbolic constants from the \C{} header file \code{<audio.h>} are
defined in the standard module \module{AL}\refstmodindex{AL}, see
below.
\strong{Warning:} the current version of the audio library may dump core
when bad argument values are passed rather than returning an error
@ -25,145 +26,146 @@ documented upper limit.)
The module defines the following functions:
\setindexsubitem{(in module al)}
\begin{funcdesc}{openport}{name, direction\optional{, config}}
The name and direction arguments are strings. The optional config
argument is a configuration object as returned by
\code{al.newconfig()}. The return value is an \dfn{port object};
methods of port objects are described below.
The name and direction arguments are strings. The optional
\var{config} argument is a configuration object as returned by
\function{newconfig()}. The return value is an \dfn{audio port
object}; methods of audio port objects are described below.
\end{funcdesc}
\begin{funcdesc}{newconfig}{}
The return value is a new \dfn{configuration object}; methods of
configuration objects are described below.
The return value is a new \dfn{audio configuration object}; methods of
audio configuration objects are described below.
\end{funcdesc}
\begin{funcdesc}{queryparams}{device}
The device argument is an integer. The return value is a list of
integers containing the data returned by ALqueryparams().
integers containing the data returned by \cfunction{ALqueryparams()}.
\end{funcdesc}
\begin{funcdesc}{getparams}{device, list}
The device argument is an integer. The list argument is a list such
as returned by \code{queryparams}; it is modified in place (!).
The \var{device} argument is an integer. The list argument is a list
such as returned by \function{queryparams()}; it is modified in place
(!).
\end{funcdesc}
\begin{funcdesc}{setparams}{device, list}
The device argument is an integer. The list argument is a list such
as returned by \code{al.queryparams}.
The \var{device} argument is an integer. The \var{list} argument is a
list such as returned by \function{queryparams()}.
\end{funcdesc}
\subsection{Configuration Objects}
\label{al-config-objects}
Configuration objects (returned by \code{al.newconfig()} have the
Configuration objects (returned by \function{newconfig()} have the
following methods:
\setindexsubitem{(audio configuration object method)}
\begin{funcdesc}{getqueuesize}{}
\begin{methoddesc}[audio configuration]{getqueuesize}{}
Return the queue size.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setqueuesize}{size}
\begin{methoddesc}[audio configuration]{setqueuesize}{size}
Set the queue size.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getwidth}{}
\begin{methoddesc}[audio configuration]{getwidth}{}
Get the sample width.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setwidth}{width}
\begin{methoddesc}[audio configuration]{setwidth}{width}
Set the sample width.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getchannels}{}
\begin{methoddesc}[audio configuration]{getchannels}{}
Get the channel count.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setchannels}{nchannels}
\begin{methoddesc}[audio configuration]{setchannels}{nchannels}
Set the channel count.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getsampfmt}{}
\begin{methoddesc}[audio configuration]{getsampfmt}{}
Get the sample format.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setsampfmt}{sampfmt}
\begin{methoddesc}[audio configuration]{setsampfmt}{sampfmt}
Set the sample format.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getfloatmax}{}
\begin{methoddesc}[audio configuration]{getfloatmax}{}
Get the maximum value for floating sample formats.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setfloatmax}{floatmax}
\begin{methoddesc}[audio configuration]{setfloatmax}{floatmax}
Set the maximum value for floating sample formats.
\end{funcdesc}
\end{methoddesc}
\subsection{Port Objects}
\label{al-port-objects}
Port objects (returned by \code{al.openport()} have the following
Port objects, as returned by \function{openport()}, have the following
methods:
\setindexsubitem{(audio port object method)}
\begin{funcdesc}{closeport}{}
\begin{methoddesc}[audio port]{closeport}{}
Close the port.
\end{funcdesc}
\end{methoddesc}[audio port]
\begin{funcdesc}{getfd}{}
\begin{methoddesc}[audio port]{getfd}{}
Return the file descriptor as an int.
\end{funcdesc}
\end{methoddesc}[audio port]
\begin{funcdesc}{getfilled}{}
\begin{methoddesc}[audio port]{getfilled}{}
Return the number of filled samples.
\end{funcdesc}
\end{methoddesc}[audio port]
\begin{funcdesc}{getfillable}{}
\begin{methoddesc}[audio port]{getfillable}{}
Return the number of fillable samples.
\end{funcdesc}
\end{methoddesc}[audio port]
\begin{funcdesc}{readsamps}{nsamples}
\begin{methoddesc}[audio port]{readsamps}{nsamples}
Read a number of samples from the queue, blocking if necessary.
Return the data as a string containing the raw data, (e.g., 2 bytes per
sample in big-endian byte order (high byte, low byte) if you have set
the sample width to 2 bytes).
\end{funcdesc}
\end{methoddesc}[audio port]
\begin{funcdesc}{writesamps}{samples}
\begin{methoddesc}[audio port]{writesamps}{samples}
Write samples into the queue, blocking if necessary. The samples are
encoded as described for the \code{readsamps} return value.
\end{funcdesc}
encoded as described for the \method{readsamps()} return value.
\end{methoddesc}[audio port]
\begin{funcdesc}{getfillpoint}{}
\begin{methoddesc}[audio port]{getfillpoint}{}
Return the `fill point'.
\end{funcdesc}
\end{methoddesc}[audio port]
\begin{funcdesc}{setfillpoint}{fillpoint}
\begin{methoddesc}[audio port]{setfillpoint}{fillpoint}
Set the `fill point'.
\end{funcdesc}
\end{methoddesc}[audio port]
\begin{funcdesc}{getconfig}{}
\begin{methoddesc}[audio port]{getconfig}{}
Return a configuration object containing the current configuration of
the port.
\end{funcdesc}
\end{methoddesc}[audio port]
\begin{funcdesc}{setconfig}{config}
\begin{methoddesc}[audio port]{setconfig}{config}
Set the configuration from the argument, a configuration object.
\end{funcdesc}
\end{methoddesc}[audio port]
\begin{funcdesc}{getstatus}{list}
\begin{methoddesc}[audio port]{getstatus}{list}
Get status information on last error.
\end{funcdesc}
\end{methoddesc}[audio port]
\section{Standard Module \sectcode{AL}}
\section{Standard Module \module{AL}}
\nodename{AL (uppercase)}
\stmodindex{AL}
This module defines symbolic constants needed to use the built-in
module \code{al} (see above); they are equivalent to those defined in
the C header file \file{<audio.h>} except that the name prefix
module \module{al} (see above); they are equivalent to those defined
in the \C{} header file \code{<audio.h>} except that the name prefix
\samp{AL_} is omitted. Read the module source for a complete list of
the defined names. Suggested use:

105
Doc/libaudioop.tex
View file

@ -1,19 +1,25 @@
\section{Built-in Module \sectcode{audioop}}
\section{Built-in Module \module{audioop}}
\label{module-audioop}
\bimodindex{audioop}
The \code{audioop} module contains some useful operations on sound fragments.
It operates on sound fragments consisting of signed integer samples
8, 16 or 32 bits wide, stored in Python strings. This is the same
format as used by the \code{al} and \code{sunaudiodev} modules. All
scalar items are integers, unless specified otherwise.
The \module{audioop} module contains some useful operations on sound
fragments. It operates on sound fragments consisting of signed
integer samples 8, 16 or 32 bits wide, stored in Python strings. This
is the same format as used by the \module{al} and \module{sunaudiodev}
modules. All scalar items are integers, unless specified otherwise.
% This para is mostly here to provide an excuse for the index entries...
This module provides support for u-LAW and Intel/DVI ADPCM encodings.
\index{Intel/DVI ADPCM}
\index{ADPCM, Intel/DVI}
\index{u-LAW}
A few of the more complicated operations only take 16-bit samples,
otherwise the sample size (in bytes) is always a parameter of the operation.
otherwise the sample size (in bytes) is always a parameter of the
operation.
The module defines the following variables and functions:
\setindexsubitem{(in module audioop)}
\begin{excdesc}{error}
This exception is raised on all errors, such as unknown number of bytes
per sample, etc.
@ -28,14 +34,14 @@ length.
\begin{funcdesc}{adpcm2lin}{adpcmfragment, width, state}
Decode an Intel/DVI ADPCM coded fragment to a linear fragment. See
the description of \code{lin2adpcm} for details on ADPCM coding.
the description of \function{lin2adpcm()} for details on ADPCM coding.
Return a tuple \code{(\var{sample}, \var{newstate})} where the sample
has the width specified in \var{width}.
\end{funcdesc}
\begin{funcdesc}{adpcm32lin}{adpcmfragment, width, state}
Decode an alternative 3-bit ADPCM code. See \code{lin2adpcm3} for
details.
Decode an alternative 3-bit ADPCM code. See \function{lin2adpcm3()}
for details.
\end{funcdesc}
\begin{funcdesc}{avg}{fragment, width}
@ -60,26 +66,25 @@ argument.
\begin{funcdesc}{findfactor}{fragment, reference}
Return a factor \var{F} such that
\code{rms(add(fragment, mul(reference, -F)))} is minimal, i.e.,
return the factor with which you should multiply \var{reference} to
make it match as well as possible to \var{fragment}. The fragments
should both contain 2-byte samples.
\code{rms(add(\var{fragment}, mul(\var{reference}, -\var{F})))} is
minimal, i.e., return the factor with which you should multiply
\var{reference} to make it match as well as possible to
\var{fragment}. The fragments should both contain 2-byte samples.
The time taken by this routine is proportional to \code{len(fragment)}.
The time taken by this routine is proportional to
\code{len(\var{fragment})}.
\end{funcdesc}
\begin{funcdesc}{findfit}{fragment, reference}
This routine (which only accepts 2-byte sample fragments)
Try to match \var{reference} as well as possible to a portion of
\var{fragment} (which should be the longer fragment). This is
(conceptually) done by taking slices out of \var{fragment}, using
\code{findfactor} to compute the best match, and minimizing the
\function{findfactor()} to compute the best match, and minimizing the
result. The fragments should both contain 2-byte samples. Return a
tuple \code{(\var{offset}, \var{factor})} where \var{offset} is the
(integer) offset into \var{fragment} where the optimal match started
and \var{factor} is the (floating-point) factor as per
\code{findfactor}.
\function{findfactor()}.
\end{funcdesc}
\begin{funcdesc}{findmax}{fragment, length}
@ -88,7 +93,7 @@ bytes!)\ with maximum energy, i.e., return \var{i} for which
\code{rms(fragment[i*2:(i+length)*2])} is maximal. The fragments
should both contain 2-byte samples.
The routine takes time proportional to \code{len(fragment)}.
The routine takes time proportional to \code{len(\var{fragment})}.
\end{funcdesc}
\begin{funcdesc}{getsample}{fragment, width, index}
@ -106,11 +111,12 @@ between one sample and the next, divided by a (varying) step. The
Intel/DVI ADPCM algorithm has been selected for use by the IMA, so it
may well become a standard.
\code{State} is a tuple containing the state of the coder. The coder
\var{state} is a tuple containing the state of the coder. The coder
returns a tuple \code{(\var{adpcmfrag}, \var{newstate})}, and the
\var{newstate} should be passed to the next call of lin2adpcm. In the
initial call \code{None} can be passed as the state. \var{adpcmfrag}
is the ADPCM coded fragment packed 2 4-bit values per byte.
\var{newstate} should be passed to the next call of
\function{lin2adpcm()}. In the initial call, \code{None} can be
passed as the state. \var{adpcmfrag} is the ADPCM coded fragment
packed 2 4-bit values per byte.
\end{funcdesc}
\begin{funcdesc}{lin2adpcm3}{fragment, width, state}
@ -121,8 +127,8 @@ discouraged.
\end{funcdesc}
\begin{funcdesc}{lin2ulaw}{fragment, width}
Convert samples in the audio fragment to U-LAW encoding and return
this as a Python string. U-LAW is an audio encoding format whereby
Convert samples in the audio fragment to u-LAW encoding and return
this as a Python string. u-LAW is an audio encoding format whereby
you get a dynamic range of about 14 bits using only 8 bit samples. It
is used by the Sun audio hardware, among others.
\end{funcdesc}
@ -147,15 +153,18 @@ multiplied by the floating-point value \var{factor}. Overflow is
silently ignored.
\end{funcdesc}
\begin{funcdesc}{ratecv}{fragment, width, nchannels, inrate, outrate, state\optional{, weightA, weightB}}
\begin{funcdesc}{ratecv}{fragment, width, nchannels, inrate, outrate,
state\optional{, weightA\optional{, weightB}}}
Convert the frame rate of the input fragment.
\code{State} is a tuple containing the state of the converter. The
\var{state} is a tuple containing the state of the converter. The
converter returns a tupl \code{(\var{newfragment}, \var{newstate})},
and \var{newstate} should be passed to the next call of ratecv.
and \var{newstate} should be passed to the next call of
\function{ratecv()}.
The \code{weightA} and \code{weightB} arguments are parameters for a
simple digital filter and default to 1 and 0 respectively.
The \var{weightA} and \var{weightB} arguments are parameters for a
simple digital filter and default to \code{1} and \code{0}
respectively.
\end{funcdesc}
\begin{funcdesc}{reverse}{fragment, width}
@ -164,9 +173,12 @@ Reverse the samples in a fragment and returns the modified fragment.
\begin{funcdesc}{rms}{fragment, width}
Return the root-mean-square of the fragment, i.e.
%begin{latexonly}
\iftexi
%end{latexonly}
the square root of the quotient of the sum of all squared sample value,
divided by the sumber of samples.
%begin{latexonly}
\else
% in eqn: sqrt { sum S sub i sup 2 over n }
\begin{displaymath}
@ -174,6 +186,7 @@ divided by the sumber of samples.
\sqrt{\frac{\sum{{S_{i}}^{2}}}{n}}
\end{displaymath}
\fi
%end{latexonly}
This is a measure of the power in an audio signal.
\end{funcdesc}
@ -191,16 +204,17 @@ samples by \var{rfactor}.
\end{funcdesc}
\begin{funcdesc}{ulaw2lin}{fragment, width}
Convert sound fragments in ULAW encoding to linearly encoded sound
fragments. ULAW encoding always uses 8 bits samples, so \var{width}
Convert sound fragments in u-LAW encoding to linearly encoded sound
fragments. u-LAW encoding always uses 8 bits samples, so \var{width}
refers only to the sample width of the output fragment here.
\end{funcdesc}
Note that operations such as \code{mul} or \code{max} make no
distinction between mono and stereo fragments, i.e.\ all samples are
treated equal. If this is a problem the stereo fragment should be split
into two mono fragments first and recombined later. Here is an example
of how to do that:
Note that operations such as \function{mul()} or \function{max()} make
no distinction between mono and stereo fragments, i.e.\ all samples
are treated equal. If this is a problem the stereo fragment should be
split into two mono fragments first and recombined later. Here is an
example of how to do that:
\begin{verbatim}
def mul_stereo(sample, width, lfactor, rfactor):
lsample = audioop.tomono(sample, width, 1, 0)
@ -211,26 +225,27 @@ def mul_stereo(sample, width, lfactor, rfactor):
rsample = audioop.tostereo(rsample, width, 0, 1)
return audioop.add(lsample, rsample, width)
\end{verbatim}
%
If you use the ADPCM coder to build network packets and you want your
protocol to be stateless (i.e.\ to be able to tolerate packet loss)
you should not only transmit the data but also the state. Note that
you should send the \var{initial} state (the one you passed to
\code{lin2adpcm}) along to the decoder, not the final state (as returned by
the coder). If you want to use \code{struct} to store the state in
binary you can code the first element (the predicted value) in 16 bits
and the second (the delta index) in 8.
\function{lin2adpcm()}) along to the decoder, not the final state (as
returned by the coder). If you want to use \function{struct.struct()}
to store the state in binary you can code the first element (the
predicted value) in 16 bits and the second (the delta index) in 8.
The ADPCM coders have never been tried against other ADPCM coders,
only against themselves. It could well be that I misinterpreted the
standards in which case they will not be interoperable with the
respective standards.
The \code{find...} routines might look a bit funny at first sight.
The \function{find*()} routines might look a bit funny at first sight.
They are primarily meant to do echo cancellation. A reasonably
fast way to do this is to pick the most energetic piece of the output
sample, locate that in the input sample and subtract the whole output
sample from the input sample:
\begin{verbatim}
def echocancel(outputdata, inputdata):
pos = audioop.findmax(outputdata, 800) # one tenth second

130
Doc/libbasehttp.tex
View file

@ -1,4 +1,4 @@
\section{Standard Module \sectcode{BaseHTTPServer}}
\section{Standard Module \module{BaseHTTPServer}}
\label{module-BaseHTTPServer}
\stmodindex{BaseHTTPServer}
@ -23,18 +23,21 @@ run the server looks like this:
\begin{verbatim}
def run(server_class=BaseHTTPServer.HTTPServer,
handler_class=BaseHTTPServer.BaseHTTPRequestHandler):
server_address = ('', 8000)
httpd = server_class(server_address, handler_class)
httpd.serve_forever()
server_address = ('', 8000)
httpd = server_class(server_address, handler_class)
httpd.serve_forever()
\end{verbatim}
The \class{HTTPServer} class builds on the \class{TCPServer} class by
\begin{classdesc}{HTTPServer}{server_address, RequestHandlerClass}
This class builds on the \class{TCPServer} class by
storing the server address as instance
variables named \member{server_name} and \member{server_port}. The
server is accessible by the handler, typically through the handler's
\member{server} instance variable.
\end{classdesc}
The module's second class, \class{BaseHTTPRequestHandler}, is used
\begin{classdesc}{BaseHTTPRequestHandler}{request, client_address, server}
This class is used
to handle the HTTP requests that arrive at the server. By itself,
it cannot respond to any actual HTTP requests; it must be subclassed
to handle each request method (e.g. GET or POST).
@ -43,69 +46,69 @@ variables, and methods for use by subclasses.
The handler will parse the request and the headers, then call a
method specific to the request type. The method name is constructed
from the request. For example, for the request \samp{SPAM}, the
from the request. For example, for the request method \samp{SPAM}, the
\method{do_SPAM()} method will be called with no arguments. All of
the relevant information is stored into instance variables of the
handler.
the relevant information is stored in instance variables of the
handler. Subclasses should not need to override or extend the
\method{__init__()} method.
\end{classdesc}
\setindexsubitem{(BaseHTTPRequestHandler attribute)}
\class{BaseHTTPRequestHandler} has the following instance variables:
\begin{datadesc}{client_address}
\begin{memberdesc}{client_address}
Contains a tuple of the form \code{(\var{host}, \var{port})} referring
to the client's address.
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{command}
\begin{memberdesc}{command}
Contains the command (request type). For example, \code{'GET'}.
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{path}
\begin{memberdesc}{path}
Contains the request path.
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{request_version}
\begin{memberdesc}{request_version}
Contains the version string from the request. For example,
\code{'HTTP/1.0'}.
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{headers}
\begin{memberdesc}{headers}
Holds an instance of the class specified by the \member{MessageClass}
class variable. This instance parses and manages the headers in
the HTTP request.
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{rfile}
\begin{memberdesc}{rfile}
Contains an input stream, positioned at the start of the optional
input data.
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{wfile}
\begin{memberdesc}{wfile}
Contains the output stream for writing a response back to the client.
Proper adherance to the HTTP protocol must be used when writing
to this stream.
\end{datadesc}
\end{memberdesc}
\setindexsubitem{(BaseHTTPRequestHandler attribute)}
\code{BaseHTTPRequestHandler} has the following class variables:
\class{BaseHTTPRequestHandler} has the following class variables:
\begin{datadesc}{server_version}
\begin{memberdesc}{server_version}
Specifies the server software version. You may want to override
this.
The format is multiple whitespace-separated strings,
where each string is of the form name[/version].
For example, \code{'BaseHTTP/0.2'}.
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{sys_version}
\begin{memberdesc}{sys_version}
Contains the Python system version, in a form usable by the
\member{version_string} method and the \member{server_version} class
variable. For example, \code{'Python/1.4'}.
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{error_message_format}
\begin{memberdesc}{error_message_format}
Specifies a format string for building an error response to the
client. It uses parenthesized, keyed format specifiers, so the
format operand must be a dictionary. The \var{code} key should
@ -115,103 +118,102 @@ message of what occurred, and \var{explain} should be an
explanation of the error code number. Default \var{message}
and \var{explain} values can found in the \var{responses}
class variable.
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{protocol_version}
\begin{memberdesc}{protocol_version}
This specifies the HTTP protocol version used in responses.
Typically, this should not be overridden. Defaults to
\code{'HTTP/1.0'}.
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{MessageClass}
\begin{memberdesc}{MessageClass}
Specifies a \class{rfc822.Message}-like class to parse HTTP
headers. Typically, this is not overridden, and it defaults to
\class{mimetools.Message}.
\withsubitem{(in module mimetools)}{\ttindex{Message}}
\end{datadesc}
\end{memberdesc}
\begin{datadesc}{responses}
\begin{memberdesc}{responses}
This variable contains a mapping of error code integers to two-element
tuples containing a short and long message. For example,
\code{\{\var{code}: (\var{shortmessage}, \var{longmessage})\}}. The
\var{shortmessage} is usually used as the \var{message} key in an
error response, and \var{longmessage} as the \var{explain} key
(see the \member{error_message_format} class variable).
\end{datadesc}
\end{memberdesc}
\setindexsubitem{(BaseHTTPRequestHandler method)}
A \class{BaseHTTPRequestHandler} instance has the following methods:
\begin{funcdesc}{handle}{}
\begin{methoddesc}{handle}{}
Overrides the superclass' \method{handle()} method to provide the
specific handler behavior. This method will parse and dispatch
the request to the appropriate \code{do_*()} method.
\end{funcdesc}
the request to the appropriate \method{do_*()} method.
\end{methoddesc}
\begin{funcdesc}{send_error}{code\optional{, message}}
\begin{methoddesc}{send_error}{code\optional{, message}}
Sends and logs a complete error reply to the client. The numeric
\var{code} specifies the HTTP error code, with \var{message} as
optional, more specific text. A complete set of headers is sent,
followed by text composed using the \member{error_message_format}
class variable.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{send_response}{code\optional{, message}}
\begin{methoddesc}{send_response}{code\optional{, message}}
Sends a response header and logs the accepted request. The HTTP
response line is sent, followed by \emph{Server} and \emph{Date}
headers. The values for these two headers are picked up from the
\method{version_string()} and \method{date_time_string()} methods,
respectively.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{send_header}{keyword, value}
\begin{methoddesc}{send_header}{keyword, value}
Writes a specific MIME header to the output stream. \var{keyword}
should specify the header keyword, with \var{value} specifying
its value.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{end_headers}{}
\begin{methoddesc}{end_headers}{}
Sends a blank line, indicating the end of the MIME headers in
the response.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{log_request}{\optional{code\optional{, size}}}
\begin{methoddesc}{log_request}{\optional{code\optional{, size}}}
Logs an accepted (successful) request. \var{code} should specify
the numeric HTTP code associated with the response. If a size of
the response is available, then it should be passed as the
\var{size} parameter.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{log_error}{...}
\begin{methoddesc}{log_error}{...}
Logs an error when a request cannot be fulfilled. By default,
it passes the message to \method{log_message()}, so it takes the
same arguments (\var{format} and additional values).
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{log_message}{format, ...}
\begin{methoddesc}{log_message}{format, ...}
Logs an arbitrary message to \code{sys.stderr}. This is typically
overridden to create custom error logging mechanisms. The
\var{format} argument is a standard printf-style format string,
where the additional arguments to \method{log_message()} are applied
as inputs to the formatting. The client address and current date
and time are prefixed to every message logged.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{version_string}{}
\begin{methoddesc}{version_string}{}
Returns the server software's version string. This is a combination
of the \member{server_version} and \member{sys_version} class variables.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{date_time_string}{}
\begin{methoddesc}{date_time_string}{}
Returns the current date and time, formatted for a message header.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{log_data_time_string}{}
\begin{methoddesc}{log_data_time_string}{}
Returns the current date and time, formatted for logging.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{address_string}{}
\begin{methoddesc}{address_string}{}
Returns the client address, formatted for logging. A name lookup
is performed on the client's IP address.
\end{funcdesc}
\end{methoddesc}

13
Doc/libbinhex.tex
View file

@ -1,15 +1,13 @@
\section{Standard Module \sectcode{binhex}}
\section{Standard Module \module{binhex}}
\label{module-binhex}
\stmodindex{binhex}
This module encodes and decodes files in binhex4 format, a format
allowing representation of Macintosh files in ASCII. On the macintosh,
allowing representation of Macintosh files in \ASCII{}. On the Macintosh,
both forks of a file and the finder information are encoded (or
decoded), on other platforms only the data fork is handled.
The \code{binhex} module defines the following functions:
\setindexsubitem{(in module binhex)}
The \module{binhex} module defines the following functions:
\begin{funcdesc}{binhex}{input, output}
Convert a binary file with filename \var{input} to binhex file
@ -31,7 +29,8 @@ There is an alternative, more powerful interface to the coder and
decoder, see the source for details.
If you code or decode textfiles on non-Macintosh platforms they will
still use the macintosh newline convention (carriage-return as end of
still use the Macintosh newline convention (carriage-return as end of
line).
As of this writing, \var{hexbin} appears to not work in all cases.
As of this writing, \function{hexbin()} appears to not work in all
cases.

106
Doc/libcd.tex
View file

@ -1,4 +1,4 @@
\section{Built-in Module \sectcode{cd}}
\section{Built-in Module \module{cd}}
\label{module-cd}
\bimodindex{cd}
@ -113,32 +113,34 @@ that can be set by the \method{addcallback()} method of CD parser
objects (see below).
\end{datadesc}
\subsection{Player Objects}
\label{player-objects}
Player objects (returned by \function{open()}) have the following
methods:
\setindexsubitem{(CD player method)}
\begin{funcdesc}{allowremoval}{}
\begin{methoddesc}[CD player]{allowremoval}{}
Unlocks the eject button on the CD-ROM drive permitting the user to
eject the caddy if desired.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{bestreadsize}{}
\begin{methoddesc}[CD player]{bestreadsize}{}
Returns the best value to use for the \var{num_frames} parameter of
the \method{readda()} method. Best is defined as the value that
permits a continuous flow of data from the CD-ROM drive.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{close}{}
\begin{methoddesc}[CD player]{close}{}
Frees the resources associated with the player object. After calling
\method{close()}, the methods of the object should no longer be used.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{eject}{}
\begin{methoddesc}[CD player]{eject}{}
Ejects the caddy from the CD-ROM drive.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getstatus}{}
\begin{methoddesc}[CD player]{getstatus}{}
Returns information pertaining to the current state of the CD-ROM
drive. The returned information is a tuple with the following values:
\var{state}, \var{track}, \var{rtime}, \var{atime}, \var{ttime},
@ -150,24 +152,24 @@ the meaning of the values, see the man page \manpage{CDgetstatus}{3dm}.
The value of \var{state} is one of the following: \constant{ERROR},
\constant{NODISC}, \constant{READY}, \constant{PLAYING},
\constant{PAUSED}, \constant{STILL}, or \constant{CDROM}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{gettrackinfo}{track}
\begin{methoddesc}[CD player]{gettrackinfo}{track}
Returns information about the specified track. The returned
information is a tuple consisting of two elements, the start time of
the track and the duration of the track.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{msftoblock}{min, sec, frame}
\begin{methoddesc}[CD player]{msftoblock}{min, sec, frame}
Converts a minutes, seconds, frames triple representing a time in
absolute time code into the corresponding logical block number for the
given CD-ROM drive. You should use \function{msftoframe()} rather than
\method{msftoblock()} for comparing times. The logical block number
differs from the frame number by an offset required by certain CD-ROM
drives.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{play}{start, play}
\begin{methoddesc}[CD player]{play}{start, play}
Starts playback of an audio CD in the CD-ROM drive at the specified
track. The audio output appears on the CD-ROM drive's headphone and
audio jacks (if fitted). Play stops at the end of the disc.
@ -175,71 +177,73 @@ audio jacks (if fitted). Play stops at the end of the disc.
CD; if \var{play} is 0, the CD will be set to an initial paused
state. The method \method{togglepause()} can then be used to commence
play.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{playabs}{minutes, seconds, frames, play}
\begin{methoddesc}[CD player]{playabs}{minutes, seconds, frames, play}
Like \method{play()}, except that the start is given in minutes,
seconds, and frames instead of a track number.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{playtrack}{start, play}
\begin{methoddesc}[CD player]{playtrack}{start, play}
Like \method{play()}, except that playing stops at the end of the
track.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{playtrackabs}{track, minutes, seconds, frames, play}
\begin{methoddesc}[CD player]{playtrackabs}{track, minutes, seconds, frames, play}
Like \method{play()}, except that playing begins at the spcified
absolute time and ends at the end of the specified track.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{preventremoval}{}
\begin{methoddesc}[CD player]{preventremoval}{}
Locks the eject button on the CD-ROM drive thus preventing the user
from arbitrarily ejecting the caddy.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{readda}{num_frames}
\begin{methoddesc}[CD player]{readda}{num_frames}
Reads the specified number of frames from an audio CD mounted in the
CD-ROM drive. The return value is a string representing the audio
frames. This string can be passed unaltered to the
\method{parseframe()} method of the parser object.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{seek}{minutes, seconds, frames}
\begin{methoddesc}[CD player]{seek}{minutes, seconds, frames}
Sets the pointer that indicates the starting point of the next read of
digital audio data from a CD-ROM. The pointer is set to an absolute
time code location specified in \var{minutes}, \var{seconds}, and
\var{frames}. The return value is the logical block number to which
the pointer has been set.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{seekblock}{block}
\begin{methoddesc}[CD player]{seekblock}{block}
Sets the pointer that indicates the starting point of the next read of
digital audio data from a CD-ROM. The pointer is set to the specified
logical block number. The return value is the logical block number to
which the pointer has been set.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{seektrack}{track}
\begin{methoddesc}[CD player]{seektrack}{track}
Sets the pointer that indicates the starting point of the next read of
digital audio data from a CD-ROM. The pointer is set to the specified
track. The return value is the logical block number to which the
pointer has been set.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{stop}{}
\begin{methoddesc}[CD player]{stop}{}
Stops the current playing operation.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{togglepause}{}
\begin{methoddesc}[CD player]{togglepause}{}
Pauses the CD if it is playing, and makes it play if it is paused.
\end{funcdesc}
\end{methoddesc}
\subsection{Parser Objects}
\label{cd-parser-objects}
Parser objects (returned by \function{createparser()}) have the
following methods:
\setindexsubitem{(CD parser method)}
\begin{funcdesc}{addcallback}{type, func, arg}
\begin{methoddesc}[CD parser]{addcallback}{type, func, arg}
Adds a callback for the parser. The parser has callbacks for eight
different types of data in the digital audio data stream. Constants
for these types are defined at the \module{cd} module level (see above).
@ -268,15 +272,15 @@ owner code, \\
\lineii{control}{Integer giving the control bits from the CD
subcode data}
\end{tableii}
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{deleteparser}{}
\begin{methoddesc}[CD parser]{deleteparser}{}
Deletes the parser and frees the memory it was using. The object
should not be used after this call. This call is done automatically
when the last reference to the object is removed.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{parseframe}{frame}
\begin{methoddesc}[CD parser]{parseframe}{frame}
Parses one or more frames of digital audio data from a CD such as
returned by \method{readda()}. It determines which subcodes are
present in the data. If these subcodes have changed since the last
@ -284,14 +288,14 @@ frame, then \method{parseframe()} executes a callback of the
appropriate type passing to it the subcode data found in the frame.
Unlike the \C{} function, more than one frame of digital audio data
can be passed to this method.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{removecallback}{type}
\begin{methoddesc}[CD parser]{removecallback}{type}
Removes the callback for the given \var{type}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{resetparser}{}
\begin{methoddesc}[CD parser]{resetparser}{}
Resets the fields of the parser used for tracking subcodes to an
initial state. \method{resetparser()} should be called after the disc
has been changed.
\end{funcdesc}
\end{methoddesc}

178
Doc/libfl.tex
View file

@ -1,4 +1,4 @@
\section{Built-in Module \sectcode{fl}}
\section{Built-in Module \module{fl}}
\label{module-fl}
\bimodindex{fl}
@ -37,7 +37,7 @@ FORMS with pure GL windows.
function \cfunction{foreground()} and to the FORMS routine
\cfunction{fl_init()}.
\subsection{Functions Defined in Module \sectcode{fl}}
\subsection{Functions Defined in Module \module{fl}}
\nodename{FL Functions}
Module \module{fl} defines the following functions. For more
@ -83,7 +83,8 @@ Show a dialog box with a three-line message and YES and NO buttons.
It returns \code{1} if the user pressed YES, \code{0} if NO.
\end{funcdesc}
\begin{funcdesc}{show_choice}{str1, str2, str3, but1\optional{, but2, but3}}
\begin{funcdesc}{show_choice}{str1, str2, str3, but1\optional{,
but2\optional{, but3}}}
Show a dialog box with a three-line message and up to three buttons.
It returns the number of the button clicked by the user
(\code{1}, \code{2} or \code{3}).
@ -136,116 +137,117 @@ See the description in the FORMS documentation of
\end{funcdesc}
\subsection{Form Objects}
\label{form-objects}
Form objects (returned by \function{fl.make_form()} above) have the
Form objects (returned by \function{make_form()} above) have the
following methods. Each method corresponds to a \C{} function whose
name is prefixed with \samp{fl_}; and whose first argument is a form
pointer; please refer to the official FORMS documentation for
descriptions.
All the \code{add_*()} functions return a Python object
representing the FORMS object. Methods of FORMS objects are described
below. Most kinds of FORMS object also have some methods specific to
that kind; these methods are listed here.
All the \method{add_*()} methods return a Python object representing
the FORMS object. Methods of FORMS objects are described below. Most
kinds of FORMS object also have some methods specific to that kind;
these methods are listed here.
\begin{flushleft}
\setindexsubitem{(form method)}
\begin{funcdesc}{show_form}{placement, bordertype, name}
\begin{methoddesc}[form]{show_form}{placement, bordertype, name}
Show the form.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{hide_form}{}
\begin{methoddesc}[form]{hide_form}{}
Hide the form.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{redraw_form}{}
\begin{methoddesc}[form]{redraw_form}{}
Redraw the form.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{set_form_position}{x, y}
\begin{methoddesc}[form]{set_form_position}{x, y}
Set the form's position.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{freeze_form}{}
\begin{methoddesc}[form]{freeze_form}{}
Freeze the form.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{unfreeze_form}{}
\begin{methoddesc}[form]{unfreeze_form}{}
Unfreeze the form.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{activate_form}{}
\begin{methoddesc}[form]{activate_form}{}
Activate the form.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{deactivate_form}{}
\begin{methoddesc}[form]{deactivate_form}{}
Deactivate the form.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{bgn_group}{}
\begin{methoddesc}[form]{bgn_group}{}
Begin a new group of objects; return a group object.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{end_group}{}
\begin{methoddesc}[form]{end_group}{}
End the current group of objects.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{find_first}{}
\begin{methoddesc}[form]{find_first}{}
Find the first object in the form.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{find_last}{}
\begin{methoddesc}[form]{find_last}{}
Find the last object in the form.
\end{funcdesc}
\end{methoddesc}
%---
\begin{funcdesc}{add_box}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_box}{type, x, y, w, h, name}
Add a box object to the form.
No extra methods.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{add_text}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_text}{type, x, y, w, h, name}
Add a text object to the form.
No extra methods.
\end{funcdesc}
\end{methoddesc}
%\begin{funcdesc}{add_bitmap}{type, x, y, w, h, name}
%\begin{methoddesc}[form]{add_bitmap}{type, x, y, w, h, name}
%Add a bitmap object to the form.
%\end{funcdesc}
%\end{methoddesc}
\begin{funcdesc}{add_clock}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_clock}{type, x, y, w, h, name}
Add a clock object to the form. \\
Method:
\method{get_clock()}.
\end{funcdesc}
\end{methoddesc}
%---
\begin{funcdesc}{add_button}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_button}{type, x, y, w, h, name}
Add a button object to the form. \\
Methods:
\method{get_button()},
\method{set_button()}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{add_lightbutton}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_lightbutton}{type, x, y, w, h, name}
Add a lightbutton object to the form. \\
Methods:
\method{get_button()},
\method{set_button()}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{add_roundbutton}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_roundbutton}{type, x, y, w, h, name}
Add a roundbutton object to the form. \\
Methods:
\method{get_button()},
\method{set_button()}.
\end{funcdesc}
\end{methoddesc}
%---
\begin{funcdesc}{add_slider}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_slider}{type, x, y, w, h, name}
Add a slider object to the form. \\
Methods:
\method{set_slider_value()},
@ -256,9 +258,9 @@ Methods:
\method{set_slider_size()},
\method{set_slider_precision()},
\method{set_slider_step()}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{add_valslider}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_valslider}{type, x, y, w, h, name}
Add a valslider object to the form. \\
Methods:
\method{set_slider_value()},
@ -269,18 +271,18 @@ Methods:
\method{set_slider_size()},
\method{set_slider_precision()},
\method{set_slider_step()}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{add_dial}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_dial}{type, x, y, w, h, name}
Add a dial object to the form. \\
Methods:
\method{set_dial_value()},
\method{get_dial_value()},
\method{set_dial_bounds()},
\method{get_dial_bounds()}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{add_positioner}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_positioner}{type, x, y, w, h, name}
Add a positioner object to the form. \\
Methods:
\method{set_positioner_xvalue()},
@ -291,9 +293,9 @@ Methods:
\method{get_positioner_yvalue()},
\method{get_positioner_xbounds()},
\method{get_positioner_ybounds()}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{add_counter}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_counter}{type, x, y, w, h, name}
Add a counter object to the form. \\
Methods:
\method{set_counter_value()},
@ -302,30 +304,30 @@ Methods:
\method{set_counter_step()},
\method{set_counter_precision()},
\method{set_counter_return()}.
\end{funcdesc}
\end{methoddesc}
%---
\begin{funcdesc}{add_input}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_input}{type, x, y, w, h, name}
Add a input object to the form. \\
Methods:
\method{set_input()},
\method{get_input()},
\method{set_input_color()},
\method{set_input_return()}.
\end{funcdesc}
\end{methoddesc}
%---
\begin{funcdesc}{add_menu}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_menu}{type, x, y, w, h, name}
Add a menu object to the form. \\
Methods:
\method{set_menu()},
\method{get_menu()},
\method{addto_menu()}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{add_choice}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_choice}{type, x, y, w, h, name}
Add a choice object to the form. \\
Methods:
\method{set_choice()},
@ -337,9 +339,9 @@ Methods:
\method{get_choice_text()},
\method{set_choice_fontsize()},
\method{set_choice_fontstyle()}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{add_browser}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_browser}{type, x, y, w, h, name}
Add a browser object to the form. \\
Methods:
\method{set_browser_topline()},
@ -360,16 +362,16 @@ Methods:
\method{set_browser_fontsize()},
\method{set_browser_fontstyle()},
\method{set_browser_specialkey()}.
\end{funcdesc}
\end{methoddesc}
%---
\begin{funcdesc}{add_timer}{type, x, y, w, h, name}
\begin{methoddesc}[form]{add_timer}{type, x, y, w, h, name}
Add a timer object to the form. \\
Methods:
\method{set_timer()},
\method{get_timer()}.
\end{funcdesc}
\end{methoddesc}
\end{flushleft}
Form objects have the following data attributes; see the FORMS
@ -388,49 +390,49 @@ documentation:
\end{tableiii}
\subsection{FORMS Objects}
\label{forms-objects}
Besides methods specific to particular kinds of FORMS objects, all
FORMS objects also have the following methods:
\setindexsubitem{(FORMS method)}
\begin{funcdesc}{set_call_back}{function, argument}
\begin{methoddesc}[FORMS object]{set_call_back}{function, argument}
Set the object's callback function and argument. When the object
needs interaction, the callback function will be called with two
arguments: the object, and the callback argument. (FORMS objects
without a callback function are returned by \function{fl.do_forms()}
or \function{fl.check_forms()} when they need interaction.) Call this
method without arguments to remove the callback function.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{delete_object}{}
\begin{methoddesc}[FORMS object]{delete_object}{}
Delete the object.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{show_object}{}
\begin{methoddesc}[FORMS object]{show_object}{}
Show the object.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{hide_object}{}
\begin{methoddesc}[FORMS object]{hide_object}{}
Hide the object.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{redraw_object}{}
\begin{methoddesc}[FORMS object]{redraw_object}{}
Redraw the object.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{freeze_object}{}
\begin{methoddesc}[FORMS object]{freeze_object}{}
Freeze the object.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{unfreeze_object}{}
\begin{methoddesc}[FORMS object]{unfreeze_object}{}
Unfreeze the object.
\end{funcdesc}
\end{methoddesc}
%\begin{funcdesc}{handle_object}{} XXX
%\end{funcdesc}
%\begin{methoddesc}[FORMS object]{handle_object}{} XXX
%\end{methoddesc}
%\begin{funcdesc}{handle_object_direct}{} XXX
%\end{funcdesc}
%\begin{methoddesc}[FORMS object]{handle_object_direct}{} XXX
%\end{methoddesc}
FORMS objects have these data attributes; see the FORMS documentation:
@ -460,7 +462,7 @@ FORMS objects have these data attributes; see the FORMS documentation:
\lineiii{automatic}{int (read-only)}{(see FORMS docs)}
\end{tableiii}
\section{Standard Module \sectcode{FL}}
\section{Standard Module \module{FL}}
\label{module-FLuppercase}
\stmodindex{FL}
@ -475,7 +477,7 @@ import fl
from FL import *
\end{verbatim}
\section{Standard Module \sectcode{flp}}
\section{Standard Module \module{flp}}
\label{module-flp}
\stmodindex{flp}

85
Doc/libftplib.tex
View file

@ -1,4 +1,4 @@
\section{Standard Module \sectcode{ftplib}}
\section{Standard Module \module{ftplib}}
\label{module-ftplib}
\stmodindex{ftplib}
\indexii{FTP}{protocol}
@ -30,7 +30,8 @@ dr-xr-srwt 105 ftp-usr pdmaint 1536 Mar 21 14:32 ..
The module defines the following items:
\begin{classdesc}{FTP}{\optional{host\optional{, user\optional{, passwd\optional{, acct}}}}}
\begin{classdesc}{FTP}{\optional{host\optional{, user\optional{,
passwd\optional{, acct}}}}}
Return a new instance of the \code{FTP} class. When
\var{host} is given, the method call \code{connect(\var{host})} is
made. When \var{user} is given, additionally the method call
@ -63,37 +64,37 @@ Exception raised when a reply is received from the server that does
not begin with a digit in the range 1--5.
\end{excdesc}
\subsection{FTP Objects}
\label{ftp-objects}
\class{FTP} instances have the following methods:
\setindexsubitem{(FTP method)}
\begin{funcdesc}{set_debuglevel}{level}
\begin{methoddesc}{set_debuglevel}{level}
Set the instance's debugging level. This controls the amount of
debugging output printed. The default, \code{0}, produces no
debugging output. A value of \code{1} produces a moderate amount of
debugging output, generally a single line per request. A value of
\code{2} or higher produces the maximum amount of debugging output,
logging each line sent and received on the control connection.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{connect}{host\optional{, port}}
\begin{methoddesc}{connect}{host\optional{, port}}
Connect to the given host and port. The default port number is \code{21}, as
specified by the FTP protocol specification. It is rarely needed to
specify a different port number. This function should be called only
once for each instance; it should not be called at all if a host was
given when the instance was created. All other methods can only be
used after a connection has been made.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getwelcome}{}
\begin{methoddesc}{getwelcome}{}
Return the welcome message sent by the server in reply to the initial
connection. (This message sometimes contains disclaimers or help
information that may be relevant to the user.)
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{login}{\optional{user\optional{, passwd\optional{, acct}}}}
\begin{methoddesc}{login}{\optional{user\optional{, passwd\optional{, acct}}}}
Log in as the given \var{user}. The \var{passwd} and \var{acct}
parameters are optional and default to the empty string. If no
\var{user} is specified, it defaults to \code{'anonymous'}. If
@ -106,25 +107,25 @@ once for each instance, after a connection has been established; it
should not be called at all if a host and user were given when the
instance was created. Most FTP commands are only allowed after the
client has logged in.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{abort}{}
\begin{methoddesc}{abort}{}
Abort a file transfer that is in progress. Using this does not always
work, but it's worth a try.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{sendcmd}{command}
\begin{methoddesc}{sendcmd}{command}
Send a simple command string to the server and return the response
string.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{voidcmd}{command}
\begin{methoddesc}{voidcmd}{command}
Send a simple command string to the server and handle the response.
Return nothing if a response code in the range 200--299 is received.
Raise an exception otherwise.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{retrbinary}{command, callback\optional{, maxblocksize}}
\begin{methoddesc}{retrbinary}{command, callback\optional{, maxblocksize}}
Retrieve a file in binary transfer mode. \var{command} should be an
appropriate \samp{RETR} command, i.e.\ \code{'RETR \var{filename}'}.
The \var{callback} function is called for each block of data received,
@ -133,73 +134,73 @@ The optional \var{maxblocksize} argument specifies the maximum chunk size to
read on the low-level socket object created to do the actual transfer
(which will also be the largest size of the data blocks passed to
\var{callback}). A reasonable default is chosen.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{retrlines}{command\optional{, callback}}
\begin{methoddesc}{retrlines}{command\optional{, callback}}
Retrieve a file or directory listing in \ASCII{} transfer mode.
\var{command} should be an appropriate \samp{RETR} command (see
\method{retrbinary()} or a \samp{LIST} command (usually just the string
\code{'LIST'}). The \var{callback} function is called for each line,
with the trailing CRLF stripped. The default \var{callback} prints
the line to \code{sys.stdout}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{storbinary}{command, file, blocksize}
\begin{methoddesc}{storbinary}{command, file, blocksize}
Store a file in binary transfer mode. \var{command} should be an
appropriate \samp{STOR} command, i.e.\ \code{"STOR \var{filename}"}.
\var{file} is an open file object which is read until \EOF{} using its
\method{read()} method in blocks of size \var{blocksize} to provide the
data to be stored.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{storlines}{command, file}
\begin{methoddesc}{storlines}{command, file}
Store a file in \ASCII{} transfer mode. \var{command} should be an
appropriate \samp{STOR} command (see \method{storbinary()}). Lines are
read until \EOF{} from the open file object \var{file} using its
\method{readline()} method to privide the data to be stored.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{nlst}{argument\optional{, \ldots}}
\begin{methoddesc}{nlst}{argument\optional{, \ldots}}
Return a list of files as returned by the \samp{NLST} command. The
optional \var{argument} is a directory to list (default is the current
server directory). Multiple arguments can be used to pass
non-standard options to the \samp{NLST} command.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{dir}{argument\optional{, \ldots}}
\begin{methoddesc}{dir}{argument\optional{, \ldots}}
Return a directory listing as returned by the \samp{LIST} command, as
a list of lines. The optional \var{argument} is a directory to list
(default is the current server directory). Multiple arguments can be
used to pass non-standard options to the \samp{LIST} command. If the
last argument is a function, it is used as a \var{callback} function
as for \method{retrlines()}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{rename}{fromname, toname}
\begin{methoddesc}{rename}{fromname, toname}
Rename file \var{fromname} on the server to \var{toname}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{cwd}{pathname}
\begin{methoddesc}{cwd}{pathname}
Set the current directory on the server.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{mkd}{pathname}
\begin{methoddesc}{mkd}{pathname}
Create a new directory on the server.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{pwd}{}
\begin{methoddesc}{pwd}{}
Return the pathname of the current directory on the server.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{quit}{}
\begin{methoddesc}{quit}{}
Send a \samp{QUIT} command to the server and close the connection.
This is the ``polite'' way to close a connection, but it may raise an
exception of the server reponds with an error to the \samp{QUIT}
command.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{close}{}
\begin{methoddesc}{close}{}
Close the connection unilaterally. This should not be applied to an
already closed connection (e.g.\ after a successful call to
\method{quit()}.
\end{funcdesc}
\end{methoddesc}

42
Doc/libhttplib.tex
View file

@ -1,4 +1,4 @@
\section{Standard Module \sectcode{httplib}}
\section{Standard Module \module{httplib}}
\label{module-httplib}
\stmodindex{httplib}
\indexii{HTTP}{protocol}
@ -9,7 +9,10 @@ HTTP protocol. It is normally not used directly --- the module
\module{urllib}\refstmodindex{urllib} uses it to handle URLs that use
HTTP.
The module defines one class, \class{HTTP}. An \class{HTTP} instance
The module defines one class, \class{HTTP}:
\begin{classdesc}{HTTP}{\optional{host\optional{, port}}}
An \class{HTTP} instance
represents one transaction with an HTTP server. It should be
instantiated passing it a host and optional port number. If no port
number is passed, the port is extracted from the host string if it has
@ -45,50 +48,50 @@ step 4 makes no calls).
file object that it returns.
\end{enumerate}
\end{classdesc}
\subsection{HTTP Objects}
\class{HTTP} instances have the following methods:
\setindexsubitem{(HTTP method)}
\begin{funcdesc}{set_debuglevel}{level}
\begin{methoddesc}{set_debuglevel}{level}
Set the debugging level (the amount of debugging output printed).
The default debug level is \code{0}, meaning no debugging output is
printed.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{connect}{host\optional{, port}}
\begin{methoddesc}{connect}{host\optional{, port}}
Connect to the server given by \var{host} and \var{port}. See the
intro for the default port. This should be called directly only if
the instance was instantiated without passing a host.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{send}{data}
\begin{methoddesc}{send}{data}
Send data to the server. This should be used directly only after the
\method{endheaders()} method has been called and before
\method{getreply()} has been called.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{putrequest}{request, selector}
\begin{methoddesc}{putrequest}{request, selector}
This should be the first call after the connection to the server has
been made. It sends a line to the server consisting of the
\var{request} string, the \var{selector} string, and the HTTP version
(\code{HTTP/1.0}).
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{putheader}{header, argument\optional{, ...}}
\begin{methoddesc}{putheader}{header, argument\optional{, ...}}
Send an \rfc{822} style header to the server. It sends a line to the
server consisting of the header, a colon and a space, and the first
argument. If more arguments are given, continuation lines are sent,
each consisting of a tab and an argument.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{endheaders}{}
\begin{methoddesc}{endheaders}{}
Send a blank line to the server, signalling the end of the headers.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getreply}{}
\begin{methoddesc}{getreply}{}
Complete the request by shutting down the sending end of the socket,
read the reply from the server, and return a triple
\code{(\var{replycode}, \var{message}, \var{headers})}. Here,
@ -98,13 +101,13 @@ message string corresponding to the reply code; and \var{headers} is
an instance of the class \class{mimetools.Message} containing the
headers received from the server. See the description of the
\module{mimetools}\refstmodindex{mimetools} module.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getfile}{}
\begin{methoddesc}{getfile}{}
Return a file object from which the data returned by the server can be
read, using the \method{read()}, \method{readline()} or
\method{readlines()} methods.
\end{funcdesc}
\end{methoddesc}
\subsection{Example}
\nodename{HTTP Example}
@ -123,5 +126,4 @@ Here is an example session:
>>> f = h.getfile()
>>> data = f.read() # Get the raw HTML
>>> f.close()
>>>
\end{verbatim}

28
Doc/libimageop.tex
View file

@ -1,16 +1,14 @@
\section{Built-in Module \sectcode{imageop}}
\section{Built-in Module \module{imageop}}
\label{module-imageop}
\bimodindex{imageop}
The \code{imageop} module contains some useful operations on images.
It operates on images consisting of 8 or 32 bit pixels
stored in Python strings. This is the same format as used
by \code{gl.lrectwrite} and the \code{imgfile} module.
The \module{imageop} module contains some useful operations on images.
It operates on images consisting of 8 or 32 bit pixels stored in
Python strings. This is the same format as used by
\function{gl.lrectwrite()} and the \module{imgfile} module.
The module defines the following variables and functions:
\setindexsubitem{(in module imageop)}
\begin{excdesc}{error}
This exception is raised on all errors, such as unknown number of bits
per pixel, etc.
@ -21,11 +19,11 @@ per pixel, etc.
Return the selected part of \var{image}, which should by
\var{width} by \var{height} in size and consist of pixels of
\var{psize} bytes. \var{x0}, \var{y0}, \var{x1} and \var{y1} are like
the \code{lrectread} parameters, i.e.\ the boundary is included in the
new image. The new boundaries need not be inside the picture. Pixels
that fall outside the old image will have their value set to zero. If
\var{x0} is bigger than \var{x1} the new image is mirrored. The same
holds for the y coordinates.
the \function{gl.lrectread()} parameters, i.e.\ the boundary is
included in the new image. The new boundaries need not be inside the
picture. Pixels that fall outside the old image will have their value
set to zero. If \var{x0} is bigger than \var{x1} the new image is
mirrored. The same holds for the y coordinates.
\end{funcdesc}
\begin{funcdesc}{scale}{image, psize, width, height, newwidth, newheight}
@ -46,7 +44,7 @@ interlacing, hence the name.
\begin{funcdesc}{grey2mono}{image, width, height, threshold}
Convert a 8-bit deep greyscale image to a 1-bit deep image by
tresholding all the pixels. The resulting image is tightly packed and
is probably only useful as an argument to \code{mono2grey}.
is probably only useful as an argument to \function{mono2grey()}.
\end{funcdesc}
\begin{funcdesc}{dither2mono}{image, width, height}
@ -74,8 +72,8 @@ dithering.
\begin{funcdesc}{dither2grey2}{image, width, height}
Convert an 8-bit greyscale image to a 2-bit greyscale image with
dithering. As for \code{dither2mono}, the dithering algorithm is
currently very simple.
dithering. As for \function{dither2mono()}, the dithering algorithm
is currently very simple.
\end{funcdesc}
\begin{funcdesc}{grey42grey}{image, width, height}

18
Doc/libjpeg.tex
View file

@ -1,10 +1,12 @@
\section{Built-in Module \sectcode{jpeg}}
\section{Built-in Module \module{jpeg}}
\label{module-jpeg}
\bimodindex{jpeg}
The module \module{jpeg} provides access to the jpeg compressor and
decompressor written by the Independent JPEG Group. JPEG is a (draft?)
standard for compressing pictures. For details on jpeg or the
decompressor written by the Independent JPEG Group%
\index{Independent JPEG Group}%
. JPEG is a (draft?)
standard for compressing pictures. For details on JPEG or the
Independent JPEG Group software refer to the JPEG standard or the
documentation provided with the software.
@ -18,19 +20,19 @@ in case of errors.
\begin{funcdesc}{compress}{data, w, h, b}
Treat data as a pixmap of width \var{w} and height \var{h}, with
\var{b} bytes per pixel. The data is in SGI GL order, so the first
pixel is in the lower-left corner. This means that \code{gl.lrectread}
pixel is in the lower-left corner. This means that \function{gl.lrectread()}
return data can immediately be passed to \function{compress()}.
Currently only 1 byte and 4 byte pixels are allowed, the former being
treated as greyscale and the latter as RGB color.
\function{compress()} returns a string that contains the compressed
picture, in JFIF format.
picture, in JFIF\index{JFIF} format.
\end{funcdesc}
\begin{funcdesc}{decompress}{data}
Data is a string containing a picture in JFIF format. It returns a
tuple \code{(\var{data}, \var{width}, \var{height},
Data is a string containing a picture in JFIF\index{JFIF} format. It
returns a tuple \code{(\var{data}, \var{width}, \var{height},
\var{bytesperpixel})}. Again, the data is suitable to pass to
\code{gl.lrectwrite}.
\function{gl.lrectwrite()}.
\end{funcdesc}
\begin{funcdesc}{setoption}{name, value}

29
Doc/libmimetools.tex
View file

@ -1,8 +1,7 @@
\section{Standard Module \sectcode{mimetools}}
\section{Standard Module \module{mimetools}}
\label{module-mimetools}
\stmodindex{mimetools}
\setindexsubitem{(in module mimetools)}
This module defines a subclass of the \class{rfc822.Message} class and
a number of utility functions that are useful for the manipulation for
@ -53,9 +52,7 @@ open file \var{output}. The block size is currently fixed at 8192.
The \class{Message} class defines the following methods in
addition to the \class{rfc822.Message} methods:
\setindexsubitem{(mimetool.Message method)}
\begin{funcdesc}{getplist}{}
\begin{methoddesc}{getplist}{}
Return the parameter list of the \code{content-type} header. This is
a list if strings. For parameters of the form
\samp{\var{key}=\var{value}}, \var{key} is converted to lower case but
@ -63,36 +60,36 @@ a list if strings. For parameters of the form
\samp{Content-type: text/html; spam=1; Spam=2; Spam} then
\method{getplist()} will return the Python list \code{['spam=1',
'spam=2', 'Spam']}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getparam}{name}
\begin{methoddesc}{getparam}{name}
Return the \var{value} of the first parameter (as returned by
\method{getplist()} of the form \samp{\var{name}=\var{value}} for the
given \var{name}. If \var{value} is surrounded by quotes of the form
`\code{<}...\code{>}' or `\code{"}...\code{"}', these are removed.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getencoding}{}
\begin{methoddesc}{getencoding}{}
Return the encoding specified in the \code{content-transfer-encoding}
message header. If no such header exists, return \code{'7bit'}. The
encoding is converted to lower case.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{gettype}{}
\begin{methoddesc}{gettype}{}
Return the message type (of the form \samp{\var{type}/\var{subtype}})
as specified in the \code{content-type} header. If no such header
exists, return \code{'text/plain'}. The type is converted to lower
case.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getmaintype}{}
\begin{methoddesc}{getmaintype}{}
Return the main type as specified in the \code{content-type} header.
If no such header exists, return \code{'text'}. The main type is
converted to lower case.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getsubtype}{}
\begin{methoddesc}{getsubtype}{}
Return the subtype as specified in the \code{content-type} header. If
no such header exists, return \code{'plain'}. The subtype is
converted to lower case.
\end{funcdesc}
\end{methoddesc}

44
Doc/libmpz.tex
View file

@ -1,38 +1,48 @@
\section{Built-in Module \sectcode{mpz}}
\section{Built-in Module \module{mpz}}
\label{module-mpz}
\bimodindex{mpz}
This is an optional module. It is only available when Python is
configured to include it, which requires that the GNU MP software is
installed.
\index{MP, GNU library}
\index{arbitrary precision integers}
\index{integer!arbitrary precision}
This module implements the interface to part of the GNU MP library,
which defines arbitrary precision integer and rational number
arithmetic routines. Only the interfaces to the \emph{integer}
(\samp{mpz_{\rm \ldots}}) routines are provided. If not stated
(\function{mpz_*()}) routines are provided. If not stated
otherwise, the description in the GNU MP documentation can be applied.
In general, \dfn{mpz}-numbers can be used just like other standard
Python numbers, e.g.\ you can use the built-in operators like \code{+},
\code{*}, etc., as well as the standard built-in functions like
\code{abs}, \code{int}, \ldots, \code{divmod}, \code{pow}.
\strong{Please note:} the \emph{bitwise-xor} operation has been implemented as
a bunch of \emph{and}s, \emph{invert}s and \emph{or}s, because the library
lacks an \code{mpz_xor} function, and I didn't need one.
\function{abs()}, \function{int()}, \ldots, \function{divmod()},
\function{pow()}. \strong{Please note:} the \emph{bitwise-xor}
operation has been implemented as a bunch of \emph{and}s,
\emph{invert}s and \emph{or}s, because the library lacks an
\cfunction{mpz_xor()} function, and I didn't need one.
You create an mpz-number by calling the function called \code{mpz} (see
You create an mpz-number by calling the function \function{mpz()} (see
below for an exact description). An mpz-number is printed like this:
\code{mpz(\var{value})}.
\setindexsubitem{(in module mpz)}
\begin{funcdesc}{mpz}{value}
Create a new mpz-number. \var{value} can be an integer, a long,
another mpz-number, or even a string. If it is a string, it is
interpreted as an array of radix-256 digits, least significant digit
first, resulting in a positive number. See also the \code{binary}
first, resulting in a positive number. See also the \method{binary()}
method, described below.
\end{funcdesc}
\begin{datadesc}{MPZType}
The type of the objects returned by \function{mpz()} and most other
functions in this module.
\end{datadesc}
A number of \emph{extra} functions are defined in this module. Non
mpz-arguments are converted to mpz-values first, and the functions
return mpz-numbers.
@ -40,7 +50,7 @@ return mpz-numbers.
\begin{funcdesc}{powm}{base, exponent, modulus}
Return \code{pow(\var{base}, \var{exponent}) \%{} \var{modulus}}. If
\code{\var{exponent} == 0}, return \code{mpz(1)}. In contrast to the
\C-library function, this version can handle negative exponents.
\C{} library function, this version can handle negative exponents.
\end{funcdesc}
\begin{funcdesc}{gcd}{op1, op2}
@ -62,18 +72,18 @@ return mpz-numbers.
\end{funcdesc}
\begin{funcdesc}{divm}{numerator, denominator, modulus}
Returns a number \var{q}. such that
\code{\var{q} * \var{denominator} \%{} \var{modulus} == \var{numerator}}.
One could also implement this function in Python, using \code{gcdext}.
Returns a number \var{q} such that
\code{\var{q} * \var{denominator} \%{} \var{modulus} ==
\var{numerator}}. One could also implement this function in Python,
using \function{gcdext()}.
\end{funcdesc}
An mpz-number has one method:
\setindexsubitem{(mpz method)}
\begin{funcdesc}{binary}{}
\begin{methoddesc}[mpz]{binary}{}
Convert this mpz-number to a binary string, where the number has been
stored as an array of radix-256 digits, least significant digit first.
The mpz-number must have a value greater than or equal to zero,
otherwise a \code{ValueError}-exception will be raised.
\end{funcdesc}
otherwise \exception{ValueError} will be raised.
\end{methoddesc}

156
Doc/libnntplib.tex
View file

@ -1,11 +1,10 @@
\section{Standard Module \sectcode{nntplib}}
\section{Standard Module \module{nntplib}}
\label{module-nntplib}
\stmodindex{nntplib}
\indexii{NNTP}{protocol}
\setindexsubitem{(in module nntplib)}
This module defines the class \code{NNTP} which implements the client
This module defines the class \class{NNTP} which implements the client
side of the NNTP protocol. It can be used to implement a news reader
or poster, or automated news processors. For more information on NNTP
(Network News Transfer Protocol), see Internet \rfc{977}.
@ -34,7 +33,6 @@ Group comp.lang.python has 59 articles, range 3742 to 3803
3803 Re: \POSIX{} wait and SIGCHLD
>>> s.quit()
'205 news.cwi.nl closing connection. Goodbye.'
>>>
\end{verbatim}
To post an article from a file (this assumes that the article has
@ -47,16 +45,15 @@ valid headers):
'240 Article posted successfully.'
>>> s.quit()
'205 news.cwi.nl closing connection. Goodbye.'
>>>
\end{verbatim}
%
The module itself defines the following items:
\begin{funcdesc}{NNTP}{host\optional{, port}}
Return a new instance of the \code{NNTP} class, representing a
\begin{classdesc}{NNTP}{host\optional{, port}}
Return a new instance of the \class{NNTP} class, representing a
connection to the NNTP server running on host \var{host}, listening at
port \var{port}. The default \var{port} is 119.
\end{funcdesc}
\end{classdesc}
\begin{excdesc}{error_reply}
Exception raised when an unexpected reply is received from the server.
@ -75,7 +72,9 @@ Exception raised when a reply is received from the server that does
not begin with a digit in the range 1--5.
\end{excdesc}
\subsection{NNTP Objects}
\label{nntp-objects}
NNTP instances have the following methods. The \var{response} that is
returned as the first item in the return tuple of almost all methods
@ -83,40 +82,40 @@ is the server's response: a string beginning with a three-digit code.
If the server's response indicates an error, the method raises one of
the above exceptions.
\setindexsubitem{(NNTP object method)}
\begin{funcdesc}{getwelcome}{}
\begin{methoddesc}{getwelcome}{}
Return the welcome message sent by the server in reply to the initial
connection. (This message sometimes contains disclaimers or help
information that may be relevant to the user.)
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{set_debuglevel}{level}
\begin{methoddesc}{set_debuglevel}{level}
Set the instance's debugging level. This controls the amount of
debugging output printed. The default, 0, produces no debugging
output. A value of 1 produces a moderate amount of debugging output,
generally a single line per request or response. A value of 2 or
higher produces the maximum amount of debugging output, logging each
line sent and received on the connection (including message text).
\end{funcdesc}
debugging output printed. The default, \code{0}, produces no debugging
output. A value of \code{1} produces a moderate amount of debugging
output, generally a single line per request or response. A value of
\code{2} or higher produces the maximum amount of debugging output,
logging each line sent and received on the connection (including
message text).
\end{methoddesc}
\begin{funcdesc}{newgroups}{date, time}
\begin{methoddesc}{newgroups}{date, time}
Send a \samp{NEWGROUPS} command. The \var{date} argument should be a
string of the form \code{"\var{yy}\var{mm}\var{dd}"} indicating the
date, and \var{time} should be a string of the form
\code{"\var{hh}\var{mm}\var{ss}"} indicating the time. Return a pair
\code{(\var{response}, \var{groups})} where \var{groups} is a list of
group names that are new since the given date and time.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{newnews}{group, date, time}
\begin{methoddesc}{newnews}{group, date, time}
Send a \samp{NEWNEWS} command. Here, \var{group} is a group name or
\code{"*"}, and \var{date} and \var{time} have the same meaning as for
\code{newgroups()}. Return a pair \code{(\var{response},
\code{'*'}, and \var{date} and \var{time} have the same meaning as for
\method{newgroups()}. Return a pair \code{(\var{response},
\var{articles})} where \var{articles} is a list of article ids.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{list}{}
\begin{methoddesc}{list}{}
Send a \samp{LIST} command. Return a pair \code{(\var{response},
\var{list})} where \var{list} is a list of tuples. Each tuple has the
form \code{(\var{group}, \var{last}, \var{first}, \var{flag})}, where
@ -124,106 +123,107 @@ form \code{(\var{group}, \var{last}, \var{first}, \var{flag})}, where
and first article numbers (as strings), and \var{flag} is \code{'y'}
if posting is allowed, \code{'n'} if not, and \code{'m'} if the
newsgroup is moderated. (Note the ordering: \var{last}, \var{first}.)
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{group}{name}
\begin{methoddesc}{group}{name}
Send a \samp{GROUP} command, where \var{name} is the group name.
Return a tuple \code{(\var{response}, \var{count}, \var{first},
\var{last}, \var{name})} where \var{count} is the (estimated) number
of articles in the group, \var{first} is the first article number in
the group, \var{last} is the last article number in the group, and
\var{name} is the group name. The numbers are returned as strings.
\end{funcdesc}
Return a tuple \code{(}\var{response}\code{,} \var{count}\code{,}
\var{first}\code{,} \var{last}\code{,} \var{name}\code{)} where
\var{count} is the (estimated) number of articles in the group,
\var{first} is the first article number in the group, \var{last} is
the last article number in the group, and \var{name} is the group
name. The numbers are returned as strings.
\end{methoddesc}
\begin{funcdesc}{help}{}
\begin{methoddesc}{help}{}
Send a \samp{HELP} command. Return a pair \code{(\var{response},
\var{list})} where \var{list} is a list of help strings.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{stat}{id}
\begin{methoddesc}{stat}{id}
Send a \samp{STAT} command, where \var{id} is the message id (enclosed
in \samp{<} and \samp{>}) or an article number (as a string).
in \character{<} and \character{>}) or an article number (as a string).
Return a triple \code{(\var{response}, \var{number}, \var{id})} where
\var{number} is the article number (as a string) and \var{id} is the
article id (enclosed in \samp{<} and \samp{>}).
\end{funcdesc}
article id (enclosed in \character{<} and \character{>}).
\end{methoddesc}
\begin{funcdesc}{next}{}
Send a \samp{NEXT} command. Return as for \code{stat()}.
\end{funcdesc}
\begin{methoddesc}{next}{}
Send a \samp{NEXT} command. Return as for \method{stat()}.
\end{methoddesc}
\begin{funcdesc}{last}{}
Send a \samp{LAST} command. Return as for \code{stat()}.
\end{funcdesc}
\begin{methoddesc}{last}{}
Send a \samp{LAST} command. Return as for \method{stat()}.
\end{methoddesc}
\begin{funcdesc}{head}{id}
\begin{methoddesc}{head}{id}
Send a \samp{HEAD} command, where \var{id} has the same meaning as for
\code{stat()}. Return a pair \code{(\var{response}, \var{list})}
\method{stat()}. Return a pair \code{(\var{response}, \var{list})}
where \var{list} is a list of the article's headers (an uninterpreted
list of lines, without trailing newlines).
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{body}{id}
\begin{methoddesc}{body}{id}
Send a \samp{BODY} command, where \var{id} has the same meaning as for
\code{stat()}. Return a pair \code{(\var{response}, \var{list})}
\method{stat()}. Return a pair \code{(\var{response}, \var{list})}
where \var{list} is a list of the article's body text (an
uninterpreted list of lines, without trailing newlines).
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{article}{id}
\begin{methoddesc}{article}{id}
Send a \samp{ARTICLE} command, where \var{id} has the same meaning as
for \code{stat()}. Return a pair \code{(\var{response}, \var{list})}
for \method{stat()}. Return a pair \code{(\var{response}, \var{list})}
where \var{list} is a list of the article's header and body text (an
uninterpreted list of lines, without trailing newlines).
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{slave}{}
\begin{methoddesc}{slave}{}
Send a \samp{SLAVE} command. Return the server's \var{response}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{xhdr}{header, string}
\begin{methoddesc}{xhdr}{header, string}
Send an \samp{XHDR} command. This command is not defined in the RFC
but is a common extension. The \var{header} argument is a header
keyword, e.g. \code{"subject"}. The \var{string} argument should have
keyword, e.g. \code{'subject'}. The \var{string} argument should have
the form \code{"\var{first}-\var{last}"} where \var{first} and
\var{last} are the first and last article numbers to search. Return a
pair \code{(\var{response}, \var{list})}, where \var{list} is a list of
pairs \code{(\var{id}, \var{text})}, where \var{id} is an article id
(as a string) and \var{text} is the text of the requested header for
that article.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{post}{file}
\begin{methoddesc}{post}{file}
Post an article using the \samp{POST} command. The \var{file}
argument is an open file object which is read until EOF using its
\code{readline()} method. It should be a well-formed news article,
including the required headers. The \code{post()} method
\method{readline()} method. It should be a well-formed news article,
including the required headers. The \method{post()} method
automatically escapes lines beginning with \samp{.}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{ihave}{id, file}
\begin{methoddesc}{ihave}{id, file}
Send an \samp{IHAVE} command. If the response is not an error, treat
\var{file} exactly as for the \code{post()} method.
\end{funcdesc}
\var{file} exactly as for the \method{post()} method.
\end{methoddesc}
\begin{funcdesc}{date}{}
\begin{methoddesc}{date}{}
Return a triple \code{(\var{response}, \var{date}, \var{time})},
containing the current date and time in a form suitable for the
\code{newnews} and \code{newgroups} methods.
\method{newnews()} and \method{newgroups()} methods.
This is an optional NNTP extension, and may not be supported by all
servers.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{xgtitle}{name}
Process an XGTITLE command, returning a pair \code{(\var{response},
\begin{methoddesc}{xgtitle}{name}
Process an \samp{XGTITLE} command, returning a pair \code{(\var{response},
\var{list})}, where \var{list} is a list of tuples containing
\code{(\var{name}, \var{title})}.
% XXX huh? Should that be name, description?
This is an optional NNTP extension, and may not be supported by all
servers.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{xover}{start, end}
\begin{methoddesc}{xover}{start, end}
Return a pair \code{(\var{resp}, \var{list})}. \var{list} is a list
of tuples, one for each article in the range delimited by the \var{start}
and \var{end} article numbers. Each tuple is of the form
@ -232,15 +232,15 @@ and \var{end} article numbers. Each tuple is of the form
\var{references}\code{,} \var{size}\code{,} \var{lines}\code{)}.
This is an optional NNTP extension, and may not be supported by all
servers.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{xpath}{id}
\begin{methoddesc}{xpath}{id}
Return a pair \code{(\var{resp}, \var{path})}, where \var{path} is the
directory path to the article with message ID \var{id}. This is an
optional NNTP extension, and may not be supported by all servers.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{quit}{}
\begin{methoddesc}{quit}{}
Send a \samp{QUIT} command and close the connection. Once this method
has been called, no other methods of the NNTP object should be called.
\end{funcdesc}
\end{methoddesc}

6
Doc/librgbimg.tex
View file

@ -5,7 +5,7 @@
The \module{rgbimg} module allows Python programs to access SGI imglib image
files (also known as \file{.rgb} files). The module is far from
complete, but is provided anyway since the functionality that there is
is enough in some cases. Currently, colormap files are not supported.
enough in some cases. Currently, colormap files are not supported.
The module defines the following variables and functions:
@ -24,7 +24,7 @@ are currently supported.
This function reads and decodes the image on the specified file, and
returns it as a Python string. The string has 4 byte RGBA pixels.
The bottom left pixel is the first in
the string. This format is suitable to pass to \code{gl.lrectwrite},
the string. This format is suitable to pass to \function{gl.lrectwrite()},
for instance.
\end{funcdesc}
@ -34,7 +34,7 @@ file \var{file}. \var{x} and \var{y} give the size of the image.
\var{z} is 1 if the saved image should be 1 byte greyscale, 3 if the
saved image should be 3 byte RGB data, or 4 if the saved images should
be 4 byte RGBA data. The input data always contains 4 bytes per pixel.
These are the formats returned by \code{gl.lrectread}.
These are the formats returned by \function{gl.lrectread()}.
\end{funcdesc}
\begin{funcdesc}{ttob}{flag}

54
Doc/librotor.tex
View file

@ -1,9 +1,10 @@
\section{Built-in Module \sectcode{rotor}}
\section{Built-in Module \module{rotor}}
\label{module-rotor}
\bimodindex{rotor}
This module implements a rotor-based encryption algorithm, contributed by
Lance Ellinghouse. The design is derived from the Enigma device, a machine
Lance Ellinghouse\index{Ellinghouse, Lance}. The design is derived
from the Enigma device\indexii{Enigma}{device}, a machine
used during World War II to encipher messages. A rotor is simply a
permutation. For example, if the character `A' is the origin of the rotor,
then a given rotor might map `A' to `L', `B' to `Z', `C' to `G', and so on.
@ -19,12 +20,10 @@ recursively. In other words, after enciphering one character, we advance
the rotors in the same fashion as a car's odometer. Decoding works in the
same way, except we reverse the permutations and apply them in the opposite
order.
\index{Ellinghouse, Lance}
\indexii{Enigma}{cipher}
The available functions in this module are:
\setindexsubitem{(in module rotor)}
\begin{funcdesc}{newrotor}{key\optional{, numrotors}}
Return a rotor object. \var{key} is a string containing the encryption key
for the object; it can contain arbitrary binary data. The key will be used
@ -35,32 +34,31 @@ if it is omitted, a default value of 6 will be used.
Rotor objects have the following methods:
\setindexsubitem{(rotor method)}
\begin{funcdesc}{setkey}{key}
\begin{methoddesc}[rotor]{setkey}{key}
Sets the rotor's key to \var{key}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{encrypt}{plaintext}
\begin{methoddesc}[rotor]{encrypt}{plaintext}
Reset the rotor object to its initial state and encrypt \var{plaintext},
returning a string containing the ciphertext. The ciphertext is always the
same length as the original plaintext.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{encryptmore}{plaintext}
\begin{methoddesc}[rotor]{encryptmore}{plaintext}
Encrypt \var{plaintext} without resetting the rotor object, and return a
string containing the ciphertext.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{decrypt}{ciphertext}
\begin{methoddesc}[rotor]{decrypt}{ciphertext}
Reset the rotor object to its initial state and decrypt \var{ciphertext},
returning a string containing the ciphertext. The plaintext string will
always be the same length as the ciphertext.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{decryptmore}{ciphertext}
\begin{methoddesc}[rotor]{decryptmore}{ciphertext}
Decrypt \var{ciphertext} without resetting the rotor object, and return a
string containing the ciphertext.
\end{funcdesc}
\end{methoddesc}
An example usage:
\begin{verbatim}
@ -80,17 +78,18 @@ An example usage:
'l(\315'
>>> del rt
\end{verbatim}
%
The module's code is not an exact simulation of the original Enigma device;
it implements the rotor encryption scheme differently from the original. The
most important difference is that in the original Enigma, there were only 5
or 6 different rotors in existence, and they were applied twice to each
character; the cipher key was the order in which they were placed in the
machine. The Python rotor module uses the supplied key to initialize a
random number generator; the rotor permutations and their initial positions
are then randomly generated. The original device only enciphered the
letters of the alphabet, while this module can handle any 8-bit binary data;
it also produces binary output. This module can also operate with an
The module's code is not an exact simulation of the original Enigma
device; it implements the rotor encryption scheme differently from the
original. The most important difference is that in the original
Enigma, there were only 5 or 6 different rotors in existence, and they
were applied twice to each character; the cipher key was the order in
which they were placed in the machine. The Python \module{rotor}
module uses the supplied key to initialize a random number generator;
the rotor permutations and their initial positions are then randomly
generated. The original device only enciphered the letters of the
alphabet, while this module can handle any 8-bit binary data; it also
produces binary output. This module can also operate with an
arbitrary number of rotors.
The original Enigma cipher was broken in 1944. % XXX: Is this right?
@ -102,5 +101,4 @@ for discouraging casual snooping through your files, it will probably be
just fine, and may be somewhat safer than using the \UNIX{} \program{crypt}
command.
\index{NSA}
\index{National Security Agency}\index{crypt(1)}
% XXX How were Unix commands represented in the docs?
\index{National Security Agency}

83
Doc/libsunaudio.tex
View file

@ -1,15 +1,14 @@
\section{Built-in Module \sectcode{sunaudiodev}}
\section{Built-in Module \module{sunaudiodev}}
\label{module-sunaudiodev}
\bimodindex{sunaudiodev}
This module allows you to access the sun audio interface. The sun
audio hardware is capable of recording and playing back audio data
in U-LAW format with a sample rate of 8K per second. A full
description can be gotten with \samp{man audio}.
in u-LAW\index{u-LAW} format with a sample rate of 8K per second. A
full description can be found in the \manpage{audio}{7I} manual page.
The module defines the following variables and functions:
\setindexsubitem{(in module sunaudiodev)}
\begin{excdesc}{error}
This exception is raised on all errors. The argument is a string
describing what went wrong.
@ -22,87 +21,87 @@ is one of \code{'r'} for record-only access, \code{'w'} for play-only
access, \code{'rw'} for both and \code{'control'} for access to the
control device. Since only one process is allowed to have the recorder
or player open at the same time it is a good idea to open the device
only for the activity needed. See the audio manpage for details.
only for the activity needed. See \manpage{audio}{7I} for details.
\end{funcdesc}
\subsection{Audio Device Objects}
\label{audio-device-objects}
The audio device objects are returned by \code{open} define the
The audio device objects are returned by \function{open()} define the
following methods (except \code{control} objects which only provide
getinfo, setinfo and drain):
\method{getinfo()}, \method{setinfo()} and \method{drain()}):
\setindexsubitem{(audio device method)}
\begin{funcdesc}{close}{}
\begin{methoddesc}[audio device]{close}{}
This method explicitly closes the device. It is useful in situations
where deleting the object does not immediately close it since there
are other references to it. A closed device should not be used again.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{drain}{}
\begin{methoddesc}[audio device]{drain}{}
This method waits until all pending output is processed and then returns.
Calling this method is often not necessary: destroying the object will
automatically close the audio device and this will do an implicit drain.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{flush}{}
\begin{methoddesc}[audio device]{flush}{}
This method discards all pending output. It can be used avoid the
slow response to a user's stop request (due to buffering of up to one
second of sound).
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{getinfo}{}
\begin{methoddesc}[audio device]{getinfo}{}
This method retrieves status information like input and output volume,
etc. and returns it in the form of
an audio status object. This object has no methods but it contains a
number of attributes describing the current device status. The names
and meanings of the attributes are described in
\file{/usr/include/sun/audioio.h} and in the audio man page. Member names
are slightly different from their C counterparts: a status object is
only a single structure. Members of the \code{play} substructure have
\samp{o_} prepended to their name and members of the \code{record}
structure have \samp{i_}. So, the C member \code{play.sample_rate} is
accessed as \code{o_sample_rate}, \code{record.gain} as \code{i_gain}
and \code{monitor_gain} plainly as \code{monitor_gain}.
\end{funcdesc}
\file{/usr/include/sun/audioio.h} and in the \manpage{audio}{7I}
manual page. Member names
are slightly different from their \C{} counterparts: a status object is
only a single structure. Members of the \cdata{play} substructure have
\samp{o_} prepended to their name and members of the \cdata{record}
structure have \samp{i_}. So, the \C{} member \cdata{play.sample_rate} is
accessed as \member{o_sample_rate}, \cdata{record.gain} as \member{i_gain}
and \cdata{monitor_gain} plainly as \member{monitor_gain}.
\end{methoddesc}
\begin{funcdesc}{ibufcount}{}
\begin{methoddesc}[audio device]{ibufcount}{}
This method returns the number of samples that are buffered on the
recording side, i.e.
the program will not block on a \function{read()} call of so many samples.
\end{funcdesc}
recording side, i.e.\ the program will not block on a
\function{read()} call of so many samples.
\end{methoddesc}
\begin{funcdesc}{obufcount}{}
\begin{methoddesc}[audio device]{obufcount}{}
This method returns the number of samples buffered on the playback
side. Unfortunately, this number cannot be used to determine a number
of samples that can be written without blocking since the kernel
output queue length seems to be variable.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{read}{size}
\begin{methoddesc}[audio device]{read}{size}
This method reads \var{size} samples from the audio input and returns
them as a Python string. The function blocks until enough data is available.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setinfo}{status}
\begin{methoddesc}[audio device]{setinfo}{status}
This method sets the audio device status parameters. The \var{status}
parameter is an device status object as returned by \function{getinfo()} and
possibly modified by the program.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{write}{samples}
\begin{methoddesc}[audio device]{write}{samples}
Write is passed a Python string containing audio samples to be played.
If there is enough buffer space free it will immediately return,
otherwise it will block.
\end{funcdesc}
\end{methoddesc}
There is a companion module, \module{SUNAUDIODEV}, which defines useful
There is a companion module,
\module{SUNAUDIODEV}\refstmodindex{SUNAUDIODEV}, which defines useful
symbolic constants like \constant{MIN_GAIN}, \constant{MAX_GAIN},
\constant{SPEAKER}, etc. The names of
the constants are the same names as used in the \C{} include file
\code{<sun/audioio.h>}, with the leading string \samp{AUDIO_}
stripped.
\refstmodindex{SUNAUDIODEV}
\constant{SPEAKER}, etc. The names of the constants are the same names
as used in the \C{} include file \code{<sun/audioio.h>}, with the
leading string \samp{AUDIO_} stripped.
Useability of the control device is limited at the moment, since there
is no way to use the ``wait for something to happen'' feature the

124
Doc/libxmllib.tex
View file

@ -1,4 +1,4 @@
\section{Standard Module \sectcode{xmllib}}
\section{Standard Module \module{xmllib}}
% Author: Sjoerd Mullender
\label{module-xmllib}
\stmodindex{xmllib}
@ -13,59 +13,57 @@ The \class{XMLParser} class must be instantiated without arguments.
This class provides the following interface methods:
\setindexsubitem{(XMLParser method)}
\begin{funcdesc}{reset}{}
\begin{methoddesc}{reset}{}
Reset the instance. Loses all unprocessed data. This is called
implicitly at the instantiation time.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setnomoretags}{}
\begin{methoddesc}{setnomoretags}{}
Stop processing tags. Treat all following input as literal input
(CDATA).
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{setliteral}{}
\begin{methoddesc}{setliteral}{}
Enter literal mode (CDATA mode).
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{feed}{data}
\begin{methoddesc}{feed}{data}
Feed some text to the parser. It is processed insofar as it consists
of complete elements; incomplete data is buffered until more data is
fed or \method{close()} is called.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{close}{}
\begin{methoddesc}{close}{}
Force processing of all buffered data as if it were followed by an
end-of-file mark. This method may be redefined by a derived class to
define additional processing at the end of the input, but the
redefined version should always call \method{close()}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{translate_references}{data}
\begin{methoddesc}{translate_references}{data}
Translate all entity and character references in \var{data} and
returns the translated string.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{handle_xml}{encoding, standalone}
This method is called when the \code{<?xml ...?>} tag is processed.
\begin{methoddesc}{handle_xml}{encoding, standalone}
This method is called when the \samp{<?xml ...?>} tag is processed.
The arguments are the values of the encoding and standalone attributes
in the tag. Both encoding and standalone are optional. The values
passed to \method{handle_xml()} default to \code{None} and the string
\code{'no'} respectively.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{handle_doctype}{tag, data}
This method is called when the \code{<!DOCTYPE...>} tag is processed.
\begin{methoddesc}{handle_doctype}{tag, data}
This method is called when the \samp{<!DOCTYPE...>} tag is processed.
The arguments are the name of the root element and the uninterpreted
contents of the tag, starting after the white space after the name of
the root element.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{handle_starttag}{tag, method, attributes}
\begin{methoddesc}{handle_starttag}{tag, method, attributes}
This method is called to handle start tags for which a
\code{start_\var{tag}()} method has been defined. The \var{tag}
argument is the name of the tag, and the \method{method} argument is the
\method{start_\var{tag}()} method has been defined. The \var{tag}
argument is the name of the tag, and the \var{method} argument is the
bound method which should be used to support semantic interpretation
of the start tag. The \var{attributes} argument is a dictionary of
attributes, the key being the \var{name} and the value being the
@ -76,29 +74,29 @@ been interpreted. For instance, for the tag
\code{handle_starttag('A', self.start_A, \{'HREF': 'http://www.cwi.nl/'\})}.
The base implementation simply calls \var{method} with \var{attributes}
as the only argument.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{handle_endtag}{tag, method}
\begin{methoddesc}{handle_endtag}{tag, method}
This method is called to handle endtags for which an
\code{end_\var{tag}()} method has been defined. The \var{tag}
\method{end_\var{tag}()} method has been defined. The \var{tag}
argument is the name of the tag, and the
\var{method} argument is the bound method which should be used to
support semantic interpretation of the end tag. If no
\code{end_\var{tag}()} method is defined for the closing element, this
\method{end_\var{tag}()} method is defined for the closing element, this
handler is not called. The base implementation simply calls
\var{method}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{handle_data}{data}
\begin{methoddesc}{handle_data}{data}
This method is called to process arbitrary data. It is intended to be
overridden by a derived class; the base class implementation does
nothing.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{handle_charref}{ref}
\begin{methoddesc}{handle_charref}{ref}
This method is called to process a character reference of the form
\samp{\&\#\var{ref};}. \var{ref} can either be a decimal number,
or a hexadecimal number when preceded by \code{x}.
or a hexadecimal number when preceded by an \character{x}.
In the base implementation, \var{ref} must be a number in the
range 0-255. It translates the character to \ASCII{} and calls the
method \method{handle_data()} with the character as argument. If
@ -106,9 +104,9 @@ method \method{handle_data()} with the character as argument. If
\code{unknown_charref(\var{ref})} is called to handle the error. A
subclass must override this method to provide support for character
references outside of the \ASCII{} range.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{handle_entityref}{ref}
\begin{methoddesc}{handle_entityref}{ref}
This method is called to process a general entity reference of the
form \samp{\&\var{ref};} where \var{ref} is an general entity
reference. It looks for \var{ref} in the instance (or class)
@ -119,48 +117,48 @@ with the translation; otherwise, it calls the method
\code{unknown_entityref(\var{ref})}. The default \member{entitydefs}
defines translations for \code{\&amp;}, \code{\&apos}, \code{\&gt;},
\code{\&lt;}, and \code{\&quot;}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{handle_comment}{comment}
\begin{methoddesc}{handle_comment}{comment}
This method is called when a comment is encountered. The
\var{comment} argument is a string containing the text between the
\samp{<!--} and \samp{-->} delimiters, but not the delimiters
themselves. For example, the comment \samp{<!--text-->} will
cause this method to be called with the argument \code{'text'}. The
default method does nothing.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{handle_cdata}{data}
\begin{methoddesc}{handle_cdata}{data}
This method is called when a CDATA element is encountered. The
\var{data} argument is a string containing the text between the
\samp{<![CDATA[} and \samp{]]>} delimiters, but not the delimiters
themselves. For example, the entity \samp{<![CDATA[text]]>} will
cause this method to be called with the argument \code{'text'}. The
default method does nothing, and is intended to be overridden.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{handle_proc}{name, data}
\begin{methoddesc}{handle_proc}{name, data}
This method is called when a processing instruction (PI) is
encountered. The \var{name} is the PI target, and the \var{data}
argument is a string containing the text between the PI target and the
closing delimiter, but not the delimiter itself. For example, the
instruction \samp{<?XML text?>} will cause this method to be called
with the arguments \code{'XML'} and \code{'text'}. The default method
does nothing. Note that if a document starts with \code{<?xml
does nothing. Note that if a document starts with \samp{<?xml
...?>}, \method{handle_xml()} is called to handle it.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{handle_special}{data}
\begin{methoddesc}{handle_special}{data}
This method is called when a declaration is encountered. The
\var{data} argument is a string containing the text between the
\samp{<!} and \samp{>} delimiters, but not the delimiters
themselves. For example, the entity \samp{<!ENTITY text>} will
cause this method to be called with the argument \code{'ENTITY text'}. The
default method does nothing. Note that \code{<!DOCTYPE ...>} is
default method does nothing. Note that \samp{<!DOCTYPE ...>} is
handled separately if it is located at the start of the document.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{syntax_error}{message}
\begin{methoddesc}{syntax_error}{message}
This method is called when a syntax error is encountered. The
\var{message} is a description of what was wrong. The default method
raises a \exception{RuntimeError} exception. If this method is
@ -168,31 +166,31 @@ overridden, it is permissable for it to return. This method is only
called when the error can be recovered from. Unrecoverable errors
raise a \exception{RuntimeError} without first calling
\method{syntax_error()}.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{unknown_starttag}{tag, attributes}
\begin{methoddesc}{unknown_starttag}{tag, attributes}
This method is called to process an unknown start tag. It is intended
to be overridden by a derived class; the base class implementation
does nothing.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{unknown_endtag}{tag}
\begin{methoddesc}{unknown_endtag}{tag}
This method is called to process an unknown end tag. It is intended
to be overridden by a derived class; the base class implementation
does nothing.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{unknown_charref}{ref}
\begin{methoddesc}{unknown_charref}{ref}
This method is called to process unresolvable numeric character
references. It is intended to be overridden by a derived class; the
base class implementation does nothing.
\end{funcdesc}
\end{methoddesc}
\begin{funcdesc}{unknown_entityref}{ref}
\begin{methoddesc}{unknown_entityref}{ref}
This method is called to process an unknown entity reference. It is
intended to be overridden by a derived class; the base class
implementation does nothing.
\end{funcdesc}
\end{methoddesc}
Apart from overriding or extending the methods listed above, derived
classes may also define methods and variables of the following form to
@ -200,19 +198,19 @@ define processing of specific tags. Tag names in the input stream are
case dependent; the \var{tag} occurring in method names must be in the
correct case:
\begin{funcdescni}{start_\var{tag}}{attributes}
\begin{methoddescni}{start_\var{tag}}{attributes}
This method is called to process an opening tag \var{tag}. The
\var{attributes} argument has the same meaning as described for
\method{handle_starttag()} above. In fact, the base implementation of
\method{handle_starttag()} calls this method.
\end{funcdescni}
\end{methoddescni}
\begin{funcdescni}{end_\var{tag}}{}
\begin{methoddescni}{end_\var{tag}}{}
This method is called to process a closing tag \var{tag}.
\end{funcdescni}
\end{methoddescni}
\begin{datadescni}{\var{tag}_attributes}
If a class or instance variable \code{\var{tag}_attributes} exists, it
\begin{memberdescni}{\var{tag}_attributes}
If a class or instance variable \member{\var{tag}_attributes} exists, it
should be a list or a dictionary. If a list, the elements of the list
are the valid attributes for the element \var{tag}; if a dictionary,
the keys are the valid attributes for the element \var{tag}, and the
@ -222,4 +220,4 @@ In addition to the attributes that were present in the tag, the
attribute dictionary that is passed to \method{handle_starttag()} and
\method{unknown_starttag()} contains values for all attributes that
have a default value.
\end{datadescni}
\end{memberdescni}