ada/cpython
0
0
Fork 0
mirror of https://github.com/AdaCore/cpython.git synced 2026-02-12 12:57:15 -08:00
Code Issues Packages Projects Releases Wiki Activity

Restructured library documentation

Browse Source
This commit is contained in:
Guido van Rossum
1994-01-02 01:22:07 +00:00
parent 0b0719866e
commit 5fdeeeae2a
101 changed files with 12244 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

177
Doc/lib/libal.tex Normal file
View File

@@ -0,0 +1,177 @@
\section{Built-in Module \sectcode{al}}
\bimodindex{al}
This module provides access to the audio facilities of the Indigo and
4D/35 workstations, described in section 3A of the IRIX 4.0 man pages
(and also available as an option in IRIX 3.3). You'll need to read
those man pages to understand what these functions do!
Some of the functions are not available in releases below 4.0.5.
Again, see the manual to check whether a specific function is
available on your platform.
Symbolic constants from the C header file \file{<audio.h>} are defined
in the standard module \code{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
status. Unfortunately, since the precise circumstances under which
this may happen are undocumented and hard to check, the Python
interface can provide no protection against this kind of problems.
(One example is specifying an excessive queue size --- there is no
documented upper limit.)
Module \code{al} defines the following functions:
\renewcommand{\indexsubitem}{(in module al)}
\begin{funcdesc}{openport}{name\, direction\, config}
Equivalent to the C function ALopenport(). The name and direction
arguments are strings. The optional config argument is an opaque
configuration object as returned by \code{al.newconfig()}. The return
value is an opaque port object; methods of port objects are described
below.
\end{funcdesc}
\begin{funcdesc}{newconfig}{}
Equivalent to the C function ALnewconfig(). The return value is a new
opaque configuration object; methods of configuration objects are
described below.
\end{funcdesc}
\begin{funcdesc}{queryparams}{device}
Equivalent to the C function ALqueryparams(). The device argument is
an integer. The return value is a list of integers containing the
data returned by ALqueryparams().
\end{funcdesc}
\begin{funcdesc}{getparams}{device\, list}
Equivalent to the C function ALgetparams(). The device argument is an
integer. The list argument is a list such as returned by
\code{queryparams}; it is modified in place (!).
\end{funcdesc}
\begin{funcdesc}{setparams}{device\, list}
Equivalent to the C function ALsetparams(). The device argument is an
integer.The list argument is a list such as returned by
\code{al.queryparams}.
\end{funcdesc}
Configuration objects (returned by \code{al.newconfig()} have the
following methods:
\renewcommand{\indexsubitem}{(audio configuration object method)}
\begin{funcdesc}{getqueuesize}{}
Return the queue size; equivalent to the C function ALgetqueuesize().
\end{funcdesc}
\begin{funcdesc}{setqueuesize}{size}
Set the queue size; equivalent to the C function ALsetqueuesize().
\end{funcdesc}
\begin{funcdesc}{getwidth}{}
Get the sample width; equivalent to the C function ALgetwidth().
\end{funcdesc}
\begin{funcdesc}{getwidth}{width}
Set the sample width; equivalent to the C function ALsetwidth().
\end{funcdesc}
\begin{funcdesc}{getchannels}{}
Get the channel count; equivalent to the C function ALgetchannels().
\end{funcdesc}
\begin{funcdesc}{setchannels}{nchannels}
Set the channel count; equivalent to the C function ALsetchannels().
\end{funcdesc}
\begin{funcdesc}{getsampfmt}{}
Get the sample format; equivalent to the C function ALgetsampfmt().
\end{funcdesc}
\begin{funcdesc}{setsampfmt}{sampfmt}
Set the sample format; equivalent to the C function ALsetsampfmt().
\end{funcdesc}
\begin{funcdesc}{getfloatmax}{}
Get the maximum value for floating sample formats;
equivalent to the C function ALgetfloatmax().
\end{funcdesc}
\begin{funcdesc}{setfloatmax}{floatmax}
Set the maximum value for floating sample formats;
equivalent to the C function ALsetfloatmax().
\end{funcdesc}
Port objects (returned by \code{al.openport()} have the following
methods:
\renewcommand{\indexsubitem}{(audio port object method)}
\begin{funcdesc}{closeport}{}
Close the port; equivalent to the C function ALcloseport().
\end{funcdesc}
\begin{funcdesc}{getfd}{}
Return the file descriptor as an int; equivalent to the C function
ALgetfd().
\end{funcdesc}
\begin{funcdesc}{getfilled}{}
Return the number of filled samples; equivalent to the C function
ALgetfilled().
\end{funcdesc}
\begin{funcdesc}{getfillable}{}
Return the number of fillable samples; equivalent to the C function
ALgetfillable().
\end{funcdesc}
\begin{funcdesc}{readsamps}{nsamples}
Read a number of samples from the queue, blocking if necessary;
equivalent to the C function ALreadsamples. The data is returned 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}
\begin{funcdesc}{writesamps}{samples}
Write samples into the queue, blocking if necessary; equivalent to the
C function ALwritesamples. The samples are encoded as described for
the \code{readsamps} return value.
\end{funcdesc}
\begin{funcdesc}{getfillpoint}{}
Return the `fill point'; equivalent to the C function ALgetfillpoint().
\end{funcdesc}
\begin{funcdesc}{setfillpoint}{fillpoint}
Set the `fill point'; equivalent to the C function ALsetfillpoint().
\end{funcdesc}
\begin{funcdesc}{getconfig}{}
Return a configuration object containing the current configuration of
the port; equivalent to the C function ALgetconfig().
\end{funcdesc}
\begin{funcdesc}{setconfig}{config}
Set the configuration from the argument, a configuration object;
equivalent to the C function ALsetconfig().
\end{funcdesc}
\begin{funcdesc}{getstatus}{list}
Get status information on last error
equivalent to C function ALgetstatus().
\end{funcdesc}
\section{Standard Module \sectcode{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
\samp{AL_} is omitted. Read the module source for a complete list of
the defined names. Suggested use:
\bcode\begin{verbatim}
import al
from AL import *
\end{verbatim}\ecode

128
Doc/lib/libamoeba.tex Normal file
View File

@@ -0,0 +1,128 @@
\chapter{AMOEBA ONLY}
\section{Built-in Module \sectcode{amoeba}}
\bimodindex{amoeba}
This module provides some object types and operations useful for
Amoeba applications. It is only available on systems that support
Amoeba operations. RPC errors and other Amoeba errors are reported as
the exception \code{amoeba.error = 'amoeba.error'}.
The module \code{amoeba} defines the following items:
\renewcommand{\indexsubitem}{(in module amoeba)}
\begin{funcdesc}{name_append}{path\, cap}
Stores a capability in the Amoeba directory tree.
Arguments are the pathname (a string) and the capability (a capability
object as returned by
\code{name_lookup()}).
\end{funcdesc}
\begin{funcdesc}{name_delete}{path}
Deletes a capability from the Amoeba directory tree.
Argument is the pathname.
\end{funcdesc}
\begin{funcdesc}{name_lookup}{path}
Looks up a capability.
Argument is the pathname.
Returns a
\dfn{capability}
object, to which various interesting operations apply, described below.
\end{funcdesc}
\begin{funcdesc}{name_replace}{path\, cap}
Replaces a capability in the Amoeba directory tree.
Arguments are the pathname and the new capability.
(This differs from
\code{name_append()}
in the behavior when the pathname already exists:
\code{name_append()}
finds this an error while
\code{name_replace()}
allows it, as its name suggests.)
\end{funcdesc}
\begin{datadesc}{capv}
A table representing the capability environment at the time the
interpreter was started.
(Alas, modifying this table does not affect the capability environment
of the interpreter.)
For example,
\code{amoeba.capv['ROOT']}
is the capability of your root directory, similar to
\code{getcap("ROOT")}
in C.
\end{datadesc}
\begin{excdesc}{error}
The exception raised when an Amoeba function returns an error.
The value accompanying this exception is a pair containing the numeric
error code and the corresponding string, as returned by the C function
\code{err_why()}.
\end{excdesc}
\begin{funcdesc}{timeout}{msecs}
Sets the transaction timeout, in milliseconds.
Returns the previous timeout.
Initially, the timeout is set to 2 seconds by the Python interpreter.
\end{funcdesc}
\subsection{Capability Operations}
Capabilities are written in a convenient ASCII format, also used by the
Amoeba utilities
{\it c2a}(U)
and
{\it a2c}(U).
For example:
\bcode\begin{verbatim}
>>> amoeba.name_lookup('/profile/cap')
aa:1c:95:52:6a:fa/14(ff)/8e:ba:5b:8:11:1a
>>>
\end{verbatim}\ecode
The following methods are defined for capability objects.
\renewcommand{\indexsubitem}{(capability method)}
\begin{funcdesc}{dir_list}{}
Returns a list of the names of the entries in an Amoeba directory.
\end{funcdesc}
\begin{funcdesc}{b_read}{offset\, maxsize}
Reads (at most)
\var{maxsize}
bytes from a bullet file at offset
\var{offset.}
The data is returned as a string.
EOF is reported as an empty string.
\end{funcdesc}
\begin{funcdesc}{b_size}{}
Returns the size of a bullet file.
\end{funcdesc}
\begin{funcdesc}{dir_append}{}
\funcline{dir_delete}{}\
\funcline{dir_lookup}{}\
\funcline{dir_replace}{}
Like the corresponding
\samp{name_}*
functions, but with a path relative to the capability.
(For paths beginning with a slash the capability is ignored, since this
is the defined semantics for Amoeba.)
\end{funcdesc}
\begin{funcdesc}{std_info}{}
Returns the standard info string of the object.
\end{funcdesc}
\begin{funcdesc}{tod_gettime}{}
Returns the time (in seconds since the Epoch, in UCT, as for POSIX) from
a time server.
\end{funcdesc}
\begin{funcdesc}{tod_settime}{t}
Sets the time kept by a time server.
\end{funcdesc}

109
Doc/lib/libarray.tex Normal file
View File

@@ -0,0 +1,109 @@
\section{Built-in module \sectcode{array}}
\bimodindex{array}
\index{arrays}
This module defines a new object type which can efficiently represent
an array of basic values: characters, integers, floating point
numbers. Arrays are sequence types and behave very much like lists,
except that the type of objects stored in them is constrained. The
type is specified at object creation time by using a \dfn{type code},
which is a single character. The following type codes are defined:
\begin{tableiii}{|c|c|c|}{code}{Typecode}{Type}{Minimal size in bytes}
\lineiii{'c'}{character}{1}
\lineiii{'b'}{signed integer}{1}
\lineiii{'h'}{signed integer}{2}
\lineiii{'i'}{signed integer}{2}
\lineiii{'l'}{signed integer}{4}
\lineiii{'f'}{floating point}{4}
\lineiii{'d'}{floating point}{8}
\end{tableiii}
The actual representation of values is determined by the machine
architecture (strictly spoken, by the C implementation). The actual
size can be accessed through the \var{typecode} attribute.
The module defines the following function:
\renewcommand{\indexsubitem}{(in module array)}
\begin{funcdesc}{array}{typecode\, initializer}
Return a new array whose items are restricted by \var{typecode}, and
initialized from the optional \var{initializer} value, which must be a
list or a string. The list or string is passed to the new array's
\code{fromlist()} or \code{fromstring()} method (see below) to add
initial items to the array.
\end{funcdesc}
Array objects support the following data items and methods:
\begin{datadesc}{typecode}
The typecode character used to create the array.
\end{datadesc}
\begin{datadesc}{itemsize}
The length in bytes of one array item in the internal representation.
\end{datadesc}
\begin{funcdesc}{append}{x}
Append a new item with value \var{x} to the end of the array.
\end{funcdesc}
\begin{funcdesc}{byteswap}{x}
``Byteswap'' all items of the array. This is only supported for
integer values. It is useful when reading data ffrom a file written
on a machine with a different byte order.
\end{funcdesc}
\begin{funcdesc}{fromfile}{f\, n}
Read \var{n} items (as machine values) from the file object \var{f}
and append them to the end of the array. If less than \var{n} items
are available, \code{EOFError} is raised, but the items that were
available are still inserted into the array.
\end{funcdesc}
\begin{funcdesc}{fromlist}{list}
Appends items from the list. This is equivalent to
\code{for x in \var{list}: a.append(x)}
except that if there is a type error, the array is unchanged.
\end{funcdesc}
\begin{funcdesc}{fromstring}{s}
Appends items from the string, interpreting the string as an
array of machine values (i.e. as if it had been read from a
file using the \code{fromfile()} method).
\end{funcdesc}
\begin{funcdesc}{insert}{i\, x}
Insert a new item with value \var{x} in the array before position
\var{i}.
\end{funcdesc}
\begin{funcdesc}{tofile}{f}
Write all items (as machine values) to the file object \var{f}.
\end{funcdesc}
\begin{funcdesc}{tolist}{}
Convert the array to an ordinary list with the same items.
\end{funcdesc}
\begin{funcdesc}{tostring}{}
Convert the array to an array of machine values and return the
string representation (the same sequence of bytes that would
be written to a file by the \code{tofile()} method.)
\end{funcdesc}
When an array object is printed or converted to a string, it is
represented as \code{array(\var{typecode}, \var{initializer})}. The
\var{initializer} is omitted if the array is empty, otherwise it is a
string if the \var{typecode} is \code{'c'}, otherwise it is a list of
numbers. The string is guaranteed to be able to be converted back to
an array with the same type and value using reverse quotes
(\code{``}). Examples:
\bcode\begin{verbatim}
array('l')
array('c', 'hello world')
array('l', [1, 2, 3, 4, 5])
array('d', [1.0, 2.0, 3.14])
\end{verbatim}\ecode

241
Doc/lib/libaudioop.tex Normal file
View File

@@ -0,0 +1,241 @@
\section{Built-in module \sectcode{audioop}}
\bimodindex{audioop}
The audioop module contains some useful operations on sound fragments.
It operates on sound fragments consisting of signed integer samples of
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.
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.
The module defines the following variables and functions:
\renewcommand{\indexsubitem}{(in module audioop)}
\begin{excdesc}{error}
This exception is raised on all errors, such as unknown number of bytes
per sample, etc.
\end{excdesc}
\begin{funcdesc}{add}{fragment1\, fragment2\, width}
This function returns a fragment that is the addition of the two samples
passed as parameters. \var{width} is the sample width in bytes, either
\code{1}, \code{2} or \code{4}. Both fragments should have the same length.
\end{funcdesc}
\begin{funcdesc}{adpcm2lin}{adpcmfragment\, width\, state}
This routine decodes an Intel/DVI ADPCM coded fragment to a linear
fragment. See the description of \code{lin2adpcm} for details on ADPCM
coding. The routine returns 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}
This routine decodes an alternative 3-bit ADPCM code. See
\code{lin2adpcm3} for details.
\end{funcdesc}
\begin{funcdesc}{avg}{fragment\, width}
This function returns the average over all samples in the fragment.
\end{funcdesc}
\begin{funcdesc}{avgpp}{fragment\, width}
This function returns the average peak-peak value over all samples in
the fragment. No filtering is done, so the useability of this routine
is questionable.
\end{funcdesc}
\begin{funcdesc}{bias}{fragment\, width\, bias}
This function returns a fragment that is the original fragment with a
bias added to each sample.
\end{funcdesc}
\begin{funcdesc}{cross}{fragment\, width}
This function returns the number of zero crossings in the fragment
passed as an argument.
\end{funcdesc}
\begin{funcdesc}{findfactor}{fragment\, reference}
This routine (which only accepts 2-byte sample fragments) calculates a
factor \var{F} such that \code{rms(add(fragment, mul(reference, -F)))}
is minimal, i.e. it calculates the factor with which you should
multiply \var{reference} to make it match as good as possible to
\var{fragment}. The fragments should be the same size.
The time taken by this routine is proportional to \code{len(fragment)}.
\end{funcdesc}
\begin{funcdesc}{findfit}{fragment\, reference}
This routine (which only accepts 2-byte sample fragments) tries to
match \var{reference} as good as possible to a portion of
\var{fragment} (which should be the longer fragment). It
(conceptually) does this by taking slices out of \var{fragment}, using
\code{findfactor} to compute the best match, and minimizing the
result.
It returns a tuple \code{(\var{offset}, \var{factor})} with offset the
(integer) offset into \var{fragment} where the optimal match started
and \var{factor} the floating-point factor as per findfactor.
\end{funcdesc}
\begin{funcdesc}{findmax}{fragment\, length}
This routine (which only accepts 2-byte sample fragments) searches
\var{fragment} for a slice of length \var{length} samples (not bytes!)
with maximum energy, i.e. it returns \var{i} for which
\code{rms(fragment[i*2:(i+length)*2])} is maximal.
The routine takes time proportional to \code{len(fragment)}.
\end{funcdesc}
\begin{funcdesc}{getsample}{fragment\, width\, index}
This function returns the value of sample \var{index} from the
fragment.
\end{funcdesc}
\begin{funcdesc}{lin2lin}{fragment\, width\, newwidth}
This function converts samples between 1-, 2- and 4-byte formats.
\end{funcdesc}
\begin{funcdesc}{lin2adpcm}{fragment\, width\, state}
This function converts samples to 4 bit Intel/DVI ADPCM encoding.
ADPCM coding is an adaptive coding scheme, whereby each 4 bit number
is the difference between one sample and the next, divided by a
(varying) step. The Intel/DVI ADPCM algorythm has been selected for
use by the IMA, so may well become a standard.
\code{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.
\end{funcdesc}
\begin{funcdesc}{lin2adpcm3}{fragment\, width\, state}
This is an alternative ADPCM coder that uses only 3 bits per sample.
It is not compatible with the Intel/DVI ADPCM coder and its output is
not packed (due to laziness on the side of the author). Its use is
discouraged.
\end{funcdesc}
\begin{funcdesc}{lin2ulaw}{fragment\, width}
This function converts samples in the audio fragment to U-LAW encoding
and returns 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}
\begin{funcdesc}{minmax}{fragment\, width}
This function returns a tuple consisting of the minimum and maximum
values of all samples in the sound fragment.
\end{funcdesc}
\begin{funcdesc}{max}{fragment\, width}
This function returns the maximum of the {\em absolute value} of all
samples in a fragment.
\end{funcdesc}
\begin{funcdesc}{maxpp}{fragment\, width}
This function returns the maximum peak-peak value in the sound fragment.
\end{funcdesc}
\begin{funcdesc}{mul}{fragment\, width\, factor}
Mul returns a fragment that has all samples in the original framgent
multiplied by the floating-point value \var{factor}. Overflow is
silently ignored.
\end{funcdesc}
\begin{funcdesc}{reverse}{fragment\, width}
This function reverses the samples in a fragment and returns the
modified fragment.
\end{funcdesc}
\begin{funcdesc}{tomono}{fragment\, width\, lfactor\, rfactor}
This function converts a stereo fragment to a mono fragment. The left
channel is multiplied by \var{lfactor} and the right channel by
\var{rfactor} before adding the two channels to give a mono signal.
\end{funcdesc}
\begin{funcdesc}{tostereo}{fragment\, width\, lfactor\, rfactor}
This function generates a stereo fragment from a mono fragment. Each
pair of samples in the stereo fragment are computed from the mono
sample, whereby left channel samples are multiplied by \var{lfactor}
and right channel samples by \var{rfactor}.
\end{funcdesc}
\begin{funcdesc}{mul}{fragment\, width\, factor}
Mul returns a fragment that has all samples in the original framgent
multiplied by the floating-point value \var{factor}. Overflow is
silently ignored.
\end{funcdesc}
\begin{funcdesc}{rms}{fragment\, width\, factor}
Returns the root-mean-square of the fragment, i.e.
\iftexi
the square root of the quotient of the sum of all squared sample value,
divided by the sumber of samples.
\else
% in eqn: sqrt { sum S sub i sup 2 over n }
\begin{displaymath}
\catcode`_=8
\sqrt{\frac{\sum{{S_{i}}^{2}}}{n}}
\end{displaymath}
\fi
This is a measure of the power in an audio signal.
\end{funcdesc}
\begin{funcdesc}{ulaw2lin}{fragment\, width}
This function converts sound fragments in ULAW encoding to linearly
encoded sound fragments. ULAW 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:
\bcode\begin{verbatim}
def mul_stereo(sample, width, lfactor, rfactor):
lsample = audioop.tomono(sample, width, 1, 0)
rsample = audioop.tomono(sample, width, 0, 1)
lsample = audioop.mul(sample, width, lfactor)
rsample = audioop.mul(sample, width, rfactor)
lsample = audioop.tostereo(lsample, width, 1, 0)
rsample = audioop.tostereo(rsample, width, 0, 1)
return audioop.add(lsample, rsample, width)
\end{verbatim}\ecode
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
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.
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.
They are primarily meant for doing 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:
\bcode\begin{verbatim}
def echocancel(outputdata, inputdata):
pos = audioop.findmax(outputdata, 800) # one tenth second
out_test = outputdata[pos*2:]
in_test = inputdata[pos*2:]
ipos, factor = audioop.findfit(in_test, out_test)
# Optional (for better cancellation):
# factor = audioop.findfactor(in_test[ipos*2:ipos*2+len(out_test)],
# out_test)
prefill = '\0'*(pos+ipos)*2
postfill = '\0'*(len(inputdata)-len(prefill)-len(outputdata))
outputdata = prefill + audioop.mul(outputdata,2,-factor) + postfill
return audioop.add(inputdata, outputdata, 2)
\end{verbatim}\ecode

6
Doc/lib/libbltin.tex Normal file
View File

@@ -0,0 +1,6 @@
\section{Built-in Module \sectcode{__builtin__}}
\bimodindex{__builtin__}
This module provides direct access to all `built-in' identifier of
Python; e.g. \code{__builtin__.open} is the full name for the built-in
function \code{open}.

5
Doc/lib/libcrypto.tex Normal file
View File

@@ -0,0 +1,5 @@
\chapter{CRYPTOGRAPHIC EXTENSIONS}
The modules described in this chapter implement various algorithms of
a cryptographic nature. They are available at the discretion of the
installation.

24
Doc/lib/libdbm.tex Normal file
View File

@@ -0,0 +1,24 @@
\section{Built-in Module \sectcode{dbm}}
\bimodindex{dbm}
Dbm provides python programs with an interface to the unix \code{ndbm}
database library. Dbm objects are of the mapping type, so they can be
handled just like objects of the built-in \dfn{dictionary} type,
except that keys and values are always strings, and printing a dbm
object doesn't print the keys and values.
The module defines the following constant and functions:
\renewcommand{\indexsubitem}{(in module dbm)}
\begin{excdesc}{error}
Raised on dbm-specific errors, such as I/O errors. \code{KeyError} is
raised for general mapping errors like specifying an incorrect key.
\end{excdesc}
\begin{funcdesc}{open}{filename\, rwmode\, filemode}
Open a dbm database and return a mapping object. \var{filename} is
the name of the database file (without the \file{.dir} or \file{.pag}
extensions), \var{rwmode} is \code{'r'}, \code{'w'} or \code{'rw'} as for
\code{open}, and \var{filemode} is the unix mode of the file, used only
when the database has to be created.
\end{funcdesc}

172
Doc/lib/libexcs.tex Normal file
View File

@@ -0,0 +1,172 @@
\section{Built-in Exceptions}
Exceptions are string objects. Two distinct string objects with the
same value are different exceptions. This is done to force programmers
to use exception names rather than their string value when specifying
exception handlers. The string value of all built-in exceptions is
their name, but this is not a requirement for user-defined exceptions
or exceptions defined by library modules.
The following exceptions can be generated by the interpreter or
built-in functions. Except where mentioned, they have an `associated
value' indicating the detailed cause of the error. This may be a
string or a tuple containing several items of information (e.g., an
error code and a string explaining the code).
User code can raise built-in exceptions. This can be used to test an
exception handler or to report an error condition `just like' the
situation in which the interpreter raises the same exception; but
beware that there is nothing to prevent user code from raising an
inappropriate error.
\renewcommand{\indexsubitem}{(built-in exception)}
\begin{excdesc}{AttributeError}
% xref to attribute reference?
Raised when an attribute reference or assignment fails. (When an
object does not support attributes references or attribute assignments
at all, \code{TypeError} is raised.)
\end{excdesc}
\begin{excdesc}{EOFError}
% XXXJH xrefs here
Raised when one of the built-in functions (\code{input()} or
\code{raw_input()}) hits an end-of-file condition (\EOF{}) without
reading any data.
% XXXJH xrefs here
(N.B.: the \code{read()} and \code{readline()} methods of file
objects return an empty string when they hit \EOF{}.) No associated value.
\end{excdesc}
\begin{excdesc}{IOError}
% XXXJH xrefs here
Raised when an I/O operation (such as a \code{print} statement, the
built-in \code{open()} function or a method of a file object) fails
for an I/O-related reason, e.g., `file not found', `disk full'.
\end{excdesc}
\begin{excdesc}{ImportError}
% XXXJH xref to import statement?
Raised when an \code{import} statement fails to find the module
definition or when a \code{from {\rm \ldots} import} fails to find a
name that is to be imported.
\end{excdesc}
\begin{excdesc}{IndexError}
% XXXJH xref to sequences
Raised when a sequence subscript is out of range. (Slice indices are
silently truncated to fall in the allowed range; if an index is not a
plain integer, \code{TypeError} is raised.)
\end{excdesc}
\begin{excdesc}{KeyError}
% XXXJH xref to mapping objects?
Raised when a mapping (dictionary) key is not found in the set of
existing keys.
\end{excdesc}
\begin{excdesc}{KeyboardInterrupt}
Raised when the user hits the interrupt key (normally
\kbd{Control-C} or
\key{DEL}). During execution, a check for interrupts is made regularly.
% XXXJH xrefs here
Interrupts typed when a built-in function \code{input()} or
\code{raw_input()}) is waiting for input also raise this exception. No
associated value.
\end{excdesc}
\begin{excdesc}{MemoryError}
Raised when an operation runs out of memory but the situation may
still be rescued (by deleting some objects). The associated value is
a string indicating what kind of (internal) operation ran out of memory.
Note that because of the underlying memory management architecture
(\C{}'s \code{malloc()} function), the interpreter may not always be able
to completely recover from this situation; it nevertheless raises an
exception so that a stack traceback can be printed, in case a run-away
program was the cause.
\end{excdesc}
\begin{excdesc}{NameError}
Raised when a local or global name is not found. This applies only
to unqualified names. The associated value is the name that could
not be found.
\end{excdesc}
\begin{excdesc}{OverflowError}
% XXXJH reference to long's and/or int's?
Raised when the result of an arithmetic operation is too large to be
represented. This cannot occur for long integers (which would rather
raise \code{MemoryError} than give up). Because of the lack of
standardization of floating point exception handling in \C{}, most
floating point operations also aren't checked. For plain integers,
all operations that can overflow are checked except left shift, where
typical applications prefer to drop bits than raise an exception.
\end{excdesc}
\begin{excdesc}{RuntimeError}
Raised when an error is detected that doesn't fall in any of the
other categories. The associated value is a string indicating what
precisely went wrong. (This exception is a relic from a previous
version of the interpreter; it is not used any more except by some
extension modules that haven't been converted to define their own
exceptions yet.)
\end{excdesc}
\begin{excdesc}{SyntaxError}
% XXXJH xref to these functions?
Raised when the parser encounters a syntax error. This may occur in
an \code{import} statement, in an \code{exec} statement, in a call
to the built-in function \code{eval()} or \code{input()}, or
when reading the initial script or standard input (also
interactively).
\end{excdesc}
\begin{excdesc}{SystemError}
Raised when the interpreter finds an internal error, but the
situation does not look so serious to cause it to abandon all hope.
The associated value is a string indicating what went wrong (in
low-level terms).
You should report this to the author or maintainer of your Python
interpreter. Be sure to report the version string of the Python
interpreter (\code{sys.version}; it is also printed at the start of an
interactive Python session), the exact error message (the exception's
associated value) and if possible the source of the program that
triggered the error.
\end{excdesc}
\begin{excdesc}{SystemExit}
% XXXJH xref to module sys?
This exception is raised by the \code{sys.exit()} function. When it
is not handled, the Python interpreter exits; no stack traceback is
printed. If the associated value is a plain integer, it specifies the
system exit status (passed to \C{}'s \code{exit()} function); if it is
\code{None}, the exit status is zero; if it has another type (such as
a string), the object's value is printed and the exit status is one.
A call to \code{sys.exit} is translated into an exception so that
clean-up handlers (\code{finally} clauses of \code{try} statements)
can be executed, and so that a debugger can execute a script without
running the risk of losing control. The \code{posix._exit()} function
can be used if it is absolutely positively necessary to exit
immediately (e.g., after a \code{fork()} in the child process).
\end{excdesc}
\begin{excdesc}{TypeError}
Raised when a built-in operation or function is applied to an object
of inappropriate type. The associated value is a string giving
details about the type mismatch.
\end{excdesc}
\begin{excdesc}{ValueError}
Raised when a built-in operation or function receives an argument
that has the right type but an inappropriate value, and the
situation is not described by a more precise exception such as
\code{IndexError}.
\end{excdesc}
\begin{excdesc}{ZeroDivisionError}
Raised when the second argument of a division or modulo operation is
zero. The associated value is a string indicating the type of the
operands and the operation.
\end{excdesc}

483
Doc/lib/libfl.tex Normal file
View File

@@ -0,0 +1,483 @@
\section{Built-in Module \sectcode{fl}}
\bimodindex{fl}
This module provides an interface to the FORMS Library by Mark
Overmars, version 2.0b. For more info about FORMS, write to
{\tt markov@cs.ruu.nl}.
Most functions are literal translations of their C equivalents,
dropping the initial \samp{fl_} from their name. Constants used by the
library are defined in module \code{FL} described below.
The creation of objects is a little different in Python than in C:
instead of the `current form' maintained by the library to which new
FORMS objects are added, all functions that add a FORMS object to a
button are methods of the Python object representing the form.
Consequently, there are no Python equivalents for the C functions
\code{fl_addto_form} and \code{fl_end_form}, and the equivalent of
\code{fl_bgn_form} is called \code{fl.make_form}.
Watch out for the somewhat confusing terminology: FORMS uses the word
\dfn{object} for the buttons, sliders etc. that you can place in a form.
In Python, `object' means any value. The Python interface to FORMS
introduces two new Python object types: form objects (representing an
entire form) and FORMS objects (representing one button, slider etc.).
Hopefully this isn't too confusing...
There are no `free objects' in the Python interface to FORMS, nor is
there an easy way to add object classes written in Python. The FORMS
interface to GL event handling is avaiable, though, so you can mix
FORMS with pure GL windows.
\strong{Please note:} importing \code{fl} implies a call to the GL function
\code{foreground()} and to the FORMS routine \code{fl_init()}.
\subsection{Functions defined in module \sectcode{fl}}
Module \code{fl} defines the following functions. For more information
about what they do, see the description of the equivalent C function
in the FORMS documentation:
\renewcommand{\indexsubitem}{(in module fl)}
\begin{funcdesc}{make_form}{type\, width\, height}
Create a form with given type, width and height. This returns a
\dfn{form} object, whose methods are described below.
\end{funcdesc}
\begin{funcdesc}{do_forms}{}
The standard FORMS main loop. Returns a Python object representing
the FORMS object needing interaction, or the special value
\code{FL.EVENT}.
\end{funcdesc}
\begin{funcdesc}{check_forms}{}
Check for FORMS events. Returns what \code{do_forms} above returns,
or \code{None} if there is no event that immediately needs
interaction.
\end{funcdesc}
\begin{funcdesc}{set_event_call_back}{function}
Set the event callback function.
\end{funcdesc}
\begin{funcdesc}{set_graphics_mode}{rgbmode\, doublebuffering}
Set the graphics modes.
\end{funcdesc}
\begin{funcdesc}{get_rgbmode}{}
Return the current rgb mode. This is the value of the C global
variable \code{fl_rgbmode}.
\end{funcdesc}
\begin{funcdesc}{show_message}{str1\, str2\, str3}
Show a dialog box with a three-line message and an OK button.
\end{funcdesc}
\begin{funcdesc}{show_question}{str1\, str2\, str3}
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\, but2\, 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}).
The \var{but2} and \var{but3} arguments are optional.
\end{funcdesc}
\begin{funcdesc}{show_input}{prompt\, default}
Show a dialog box with a one-line prompt message and text field in
which the user can enter a string. The second argument is the default
input string. It returns the string value as edited by the user.
\end{funcdesc}
\begin{funcdesc}{show_file_selector}{message\, directory\, pattern\, default}
Show a dialog box inm which the user can select a file. It returns
the absolute filename selected by the user, or \code{None} if the user
presses Cancel.
\end{funcdesc}
\begin{funcdesc}{get_directory}{}
\funcline{get_pattern}{}
\funcline{get_filename}{}
These functions return the directory, pattern and filename (the tail
part only) selected by the user in the last \code{show_file_selector}
call.
\end{funcdesc}
\begin{funcdesc}{qdevice}{dev}
\funcline{unqdevice}{dev}
\funcline{isqueued}{dev}
\funcline{qtest}{}
\funcline{qread}{}
%\funcline{blkqread}{?}
\funcline{qreset}{}
\funcline{qenter}{dev\, val}
\funcline{get_mouse}{}
\funcline{tie}{button\, valuator1\, valuator2}
These functions are the FORMS interfaces to the corresponding GL
functions. Use these if you want to handle some GL events yourself
when using \code{fl.do_events}. When a GL event is detected that
FORMS cannot handle, \code{fl.do_forms()} returns the special value
\code{FL.EVENT} and you should call \code{fl.qread()} to read the
event from the queue. Don't use the equivalent GL functions!
\end{funcdesc}
\begin{funcdesc}{color}{}
\funcline{mapcolor}{}
\funcline{getmcolor}{}
See the description in the FORMS documentation of \code{fl_color},
\code{fl_mapcolor} and \code{fl_getmcolor}.
\end{funcdesc}
\subsection{Form object methods and data attributes}
Form objects (returned by \code{fl.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 \samp{add_{\rm \ldots}} 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.
\begin{flushleft}
\renewcommand{\indexsubitem}{(form object method)}
\begin{funcdesc}{show_form}{placement\, bordertype\, name}
Show the form.
\end{funcdesc}
\begin{funcdesc}{hide_form}{}
Hide the form.
\end{funcdesc}
\begin{funcdesc}{redraw_form}{}
Redraw the form.
\end{funcdesc}
\begin{funcdesc}{set_form_position}{x\, y}
Set the form's position.
\end{funcdesc}
\begin{funcdesc}{freeze_form}{}
Freeze the form.
\end{funcdesc}
\begin{funcdesc}{unfreeze_form}{}
Unfreeze the form.
\end{funcdesc}
\begin{funcdesc}{activate_form}{}
Activate the form.
\end{funcdesc}
\begin{funcdesc}{deactivate_form}{}
Deactivate the form.
\end{funcdesc}
\begin{funcdesc}{bgn_group}{}
Begin a new group of objects; return a group object.
\end{funcdesc}
\begin{funcdesc}{end_group}{}
End the current group of objects.
\end{funcdesc}
\begin{funcdesc}{find_first}{}
Find the first object in the form.
\end{funcdesc}
\begin{funcdesc}{find_last}{}
Find the last object in the form.
\end{funcdesc}
%---
\begin{funcdesc}{add_box}{type\, x\, y\, w\, h\, name}
Add a box object to the form.
No extra methods.
\end{funcdesc}
\begin{funcdesc}{add_text}{type\, x\, y\, w\, h\, name}
Add a text object to the form.
No extra methods.
\end{funcdesc}
%\begin{funcdesc}{add_bitmap}{type\, x\, y\, w\, h\, name}
%Add a bitmap object to the form.
%\end{funcdesc}
\begin{funcdesc}{add_clock}{type\, x\, y\, w\, h\, name}
Add a clock object to the form. \\
Method:
\code{get_clock}.
\end{funcdesc}
%---
\begin{funcdesc}{add_button}{type\, x\, y\, w\, h\, name}
Add a button object to the form. \\
Methods:
\code{get_button},
\code{set_button}.
\end{funcdesc}
\begin{funcdesc}{add_lightbutton}{type\, x\, y\, w\, h\, name}
Add a lightbutton object to the form. \\
Methods:
\code{get_button},
\code{set_button}.
\end{funcdesc}
\begin{funcdesc}{add_roundbutton}{type\, x\, y\, w\, h\, name}
Add a roundbutton object to the form. \\
Methods:
\code{get_button},
\code{set_button}.
\end{funcdesc}
%---
\begin{funcdesc}{add_slider}{type\, x\, y\, w\, h\, name}
Add a slider object to the form. \\
Methods:
\code{set_slider_value},
\code{get_slider_value},
\code{set_slider_bounds},
\code{get_slider_bounds},
\code{set_slider_return},
\code{set_slider_size},
\code{set_slider_precision},
\code{set_slider_step}.
\end{funcdesc}
\begin{funcdesc}{add_valslider}{type\, x\, y\, w\, h\, name}
Add a valslider object to the form. \\
Methods:
\code{set_slider_value},
\code{get_slider_value},
\code{set_slider_bounds},
\code{get_slider_bounds},
\code{set_slider_return},
\code{set_slider_size},
\code{set_slider_precision},
\code{set_slider_step}.
\end{funcdesc}
\begin{funcdesc}{add_dial}{type\, x\, y\, w\, h\, name}
Add a dial object to the form. \\
Methods:
\code{set_dial_value},
\code{get_dial_value},
\code{set_dial_bounds},
\code{get_dial_bounds}.
\end{funcdesc}
\begin{funcdesc}{add_positioner}{type\, x\, y\, w\, h\, name}
Add a positioner object to the form. \\
Methods:
\code{set_positioner_xvalue},
\code{set_positioner_yvalue},
\code{set_positioner_xbounds},
\code{set_positioner_ybounds},
\code{get_positioner_xvalue},
\code{get_positioner_yvalue},
\code{get_positioner_xbounds},
\code{get_positioner_ybounds}.
\end{funcdesc}
\begin{funcdesc}{add_counter}{type\, x\, y\, w\, h\, name}
Add a counter object to the form. \\
Methods:
\code{set_counter_value},
\code{get_counter_value},
\code{set_counter_bounds},
\code{set_counter_step},
\code{set_counter_precision},
\code{set_counter_return}.
\end{funcdesc}
%---
\begin{funcdesc}{add_input}{type\, x\, y\, w\, h\, name}
Add a input object to the form. \\
Methods:
\code{set_input},
\code{get_input},
\code{set_input_color},
\code{set_input_return}.
\end{funcdesc}
%---
\begin{funcdesc}{add_menu}{type\, x\, y\, w\, h\, name}
Add a menu object to the form. \\
Methods:
\code{set_menu},
\code{get_menu},
\code{addto_menu}.
\end{funcdesc}
\begin{funcdesc}{add_choice}{type\, x\, y\, w\, h\, name}
Add a choice object to the form. \\
Methods:
\code{set_choice},
\code{get_choice},
\code{clear_choice},
\code{addto_choice},
\code{replace_choice},
\code{delete_choice},
\code{get_choice_text},
\code{set_choice_fontsize},
\code{set_choice_fontstyle}.
\end{funcdesc}
\begin{funcdesc}{add_browser}{type\, x\, y\, w\, h\, name}
Add a browser object to the form. \\
Methods:
\code{set_browser_topline},
\code{clear_browser},
\code{add_browser_line},
\code{addto_browser},
\code{insert_browser_line},
\code{delete_browser_line},
\code{replace_browser_line},
\code{get_browser_line},
\code{load_browser},
\code{get_browser_maxline},
\code{select_browser_line},
\code{deselect_browser_line},
\code{deselect_browser},
\code{isselected_browser_line},
\code{get_browser},
\code{set_browser_fontsize},
\code{set_browser_fontstyle},
\code{set_browser_specialkey}.
\end{funcdesc}
%---
\begin{funcdesc}{add_timer}{type\, x\, y\, w\, h\, name}
Add a timer object to the form. \\
Methods:
\code{set_timer},
\code{get_timer}.
\end{funcdesc}
\end{flushleft}
Form objects have the following data attributes; see the FORMS
documentation:
\begin{tableiii}{|l|c|l|}{code}{Name}{Type}{Meaning}
\lineiii{window}{int (read-only)}{GL window id}
\lineiii{w}{float}{form width}
\lineiii{h}{float}{form height}
\lineiii{x}{float}{form x origin}
\lineiii{y}{float}{form y origin}
\lineiii{deactivated}{int}{nonzero if form is deactivated}
\lineiii{visible}{int}{nonzero if form is visible}
\lineiii{frozen}{int}{nonzero if form is frozen}
\lineiii{doublebuf}{int}{nonzero if double buffering on}
\end{tableiii}
\subsection{FORMS object methods and data attributes}
Besides methods specific to particular kinds of FORMS objects, all
FORMS objects also have the following methods:
\renewcommand{\indexsubitem}{(FORMS object method)}
\begin{funcdesc}{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 \code{fl.do_forms()} or
\code{fl.check_forms()} when they need interaction.) Call this method
without arguments to remove the callback function.
\end{funcdesc}
\begin{funcdesc}{delete_object}{}
Delete the object.
\end{funcdesc}
\begin{funcdesc}{show_object}{}
Show the object.
\end{funcdesc}
\begin{funcdesc}{hide_object}{}
Hide the object.
\end{funcdesc}
\begin{funcdesc}{redraw_object}{}
Redraw the object.
\end{funcdesc}
\begin{funcdesc}{freeze_object}{}
Freeze the object.
\end{funcdesc}
\begin{funcdesc}{unfreeze_object}{}
Unfreeze the object.
\end{funcdesc}
%\begin{funcdesc}{handle_object}{} XXX
%\end{funcdesc}
%\begin{funcdesc}{handle_object_direct}{} XXX
%\end{funcdesc}
FORMS objects have these data attributes; see the FORMS documentation:
\begin{tableiii}{|l|c|l|}{code}{Name}{Type}{Meaning}
\lineiii{objclass}{int (read-only)}{object class}
\lineiii{type}{int (read-only)}{object type}
\lineiii{boxtype}{int}{box type}
\lineiii{x}{float}{x origin}
\lineiii{y}{float}{y origin}
\lineiii{w}{float}{width}
\lineiii{h}{float}{height}
\lineiii{col1}{int}{primary color}
\lineiii{col2}{int}{secondary color}
\lineiii{align}{int}{alignment}
\lineiii{lcol}{int}{label color}
\lineiii{lsize}{float}{label font size}
\lineiii{label}{string}{label string}
\lineiii{lstyle}{int}{label style}
\lineiii{pushed}{int (read-only)}{(see FORMS docs)}
\lineiii{focus}{int (read-only)}{(see FORMS docs)}
\lineiii{belowmouse}{int (read-only)}{(see FORMS docs)}
\lineiii{frozen}{int (read-only)}{(see FORMS docs)}
\lineiii{active}{int (read-only)}{(see FORMS docs)}
\lineiii{input}{int (read-only)}{(see FORMS docs)}
\lineiii{visible}{int (read-only)}{(see FORMS docs)}
\lineiii{radio}{int (read-only)}{(see FORMS docs)}
\lineiii{automatic}{int (read-only)}{(see FORMS docs)}
\end{tableiii}
\section{Standard Module \sectcode{FL}}
\nodename{FL (uppercase)}
\stmodindex{FL}
This module defines symbolic constants needed to use the built-in
module \code{fl} (see above); they are equivalent to those defined in
the C header file \file{<forms.h>} except that the name prefix
\samp{FL_} is omitted. Read the module source for a complete list of
the defined names. Suggested use:
\bcode\begin{verbatim}
import fl
from FL import *
\end{verbatim}\ecode
\section{Standard Module \sectcode{flp}}
\stmodindex{flp}
This module defines functions that can read form definitions created
by the `form designer' (\code{fdesign}) program that comes with the
FORMS library (see module \code{fl} above).
For now, see the file \file{flp.doc} in the Python library source
directory for a description.
XXX A complete description should be inserted here!

86
Doc/lib/libfm.tex Normal file
View File

@@ -0,0 +1,86 @@
\section{Built-in Module \sectcode{fm}}
\bimodindex{fm}
This module provides access to the IRIS {\em Font Manager} library.
It is available only on Silicon Graphics machines.
See also: 4Sight User's Guide, Section 1, Chapter 5: Using the IRIS
Font Manager.
This is not yet a full interface to the IRIS Font Manager.
Among the unsupported features are: matrix operations; cache
operations; character operations (use string operations instead); some
details of font info; individual glyph metrics; and printer matching.
It supports the following operations:
\renewcommand{\indexsubitem}{(in module fm)}
\begin{funcdesc}{init}{}
Initialization function.
Calls \code{fminit()}.
It is normally not necessary to call this function, since it is called
automatically the first time the \code{fm} module is imported.
\end{funcdesc}
\begin{funcdesc}{findfont}{fontname}
Return a font handle object.
Calls \code{fmfindfont(\var{fontname})}.
\end{funcdesc}
\begin{funcdesc}{enumerate}{}
Returns a list of available font names.
This is an interface to \code{fmenumerate()}.
\end{funcdesc}
\begin{funcdesc}{prstr}{string}
Render a string using the current font (see the \code{setfont()} font
handle method below).
Calls \code{fmprstr(\var{string})}.
\end{funcdesc}
\begin{funcdesc}{setpath}{string}
Sets the font search path.
Calls \code{fmsetpath(string)}.
(XXX Does not work!?!)
\end{funcdesc}
\begin{funcdesc}{fontpath}{}
Returns the current font search path.
\end{funcdesc}
Font handle objects support the following operations:
\renewcommand{\indexsubitem}{(font handle method)}
\begin{funcdesc}{scalefont}{factor}
Returns a handle for a scaled version of this font.
Calls \code{fmscalefont(\var{fh}, \var{factor})}.
\end{funcdesc}
\begin{funcdesc}{setfont}{}
Makes this font the current font.
Note: the effect is undone silently when the font handle object is
deleted.
Calls \code{fmsetfont(\var{fh})}.
\end{funcdesc}
\begin{funcdesc}{getfontname}{}
Returns this font's name.
Calls \code{fmgetfontname(\var{fh})}.
\end{funcdesc}
\begin{funcdesc}{getcomment}{}
Returns the comment string associated with this font.
Raises an exception if there is none.
Calls \code{fmgetcomment(\var{fh})}.
\end{funcdesc}
\begin{funcdesc}{getfontinfo}{}
Returns a tuple giving some pertinent data about this font.
This is an interface to \code{fmgetfontinfo()}.
The returned tuple contains the following numbers:
\code{(\var{printermatched}, \var{fixed_width}, \var{xorig}, \var{yorig}, \var{xsize}, \var{ysize}, \var{height}, \var{nglyphs})}.
\end{funcdesc}
\begin{funcdesc}{getstrwidth}{string}
Returns the width, in pixels, of the string when drawn in this font.
Calls \code{fmgetstrwidth(\var{fh}, \var{string})}.
\end{funcdesc}

356
Doc/lib/libfuncs.tex Normal file
View File

@@ -0,0 +1,356 @@
\section{Built-in Functions}
The Python interpreter has a number of functions built into it that
are always available. They are listed here in alphabetical order.
\renewcommand{\indexsubitem}{(built-in function)}
\begin{funcdesc}{abs}{x}
Return the absolute value of a number. The argument may be a plain
or long integer or a floating point number.
\end{funcdesc}
\begin{funcdesc}{apply}{function\, args}
The \var{function} argument must be a callable object (a user-defined or
built-in function or method, or a class object) and the \var{args}
argument must be a tuple. The \var{function} is called with
\var{args} as argument list; the number of arguments is the the length
of the tuple. (This is different from just calling
\code{\var{func}(\var{args})}, since in that case there is always
exactly one argument.)
\end{funcdesc}
\begin{funcdesc}{chr}{i}
Return a string of one character whose \ASCII{} code is the integer
\var{i}, e.g., \code{chr(97)} returns the string \code{'a'}. This is the
inverse of \code{ord()}. The argument must be in the range [0..255],
inclusive.
\end{funcdesc}
\begin{funcdesc}{cmp}{x\, y}
Compare the two objects \var{x} and \var{y} and return an integer
according to the outcome. The return value is negative if \code{\var{x}
< \var{y}}, zero if \code{\var{x} == \var{y}} and strictly positive if
\code{\var{x} > \var{y}}.
\end{funcdesc}
\begin{funcdesc}{coerce}{x\, y}
Return a tuple consisting of the two numeric arguments converted to
a common type, using the same rules as used by arithmetic
operations.
\end{funcdesc}
\begin{funcdesc}{compile}{string\, filename\, kind}
Compile the \var{string} into a code object. Code objects can be
executed by a \code{exec()} statement or evaluated by a call to
\code{eval()}. The \var{filename} argument should
give the file from which the code was read; pass e.g. \code{'<string>'}
if it wasn't read from a file. The \var{kind} argument specifies
what kind of code must be compiled; it can be \code{'exec'} if
\var{string} consists of a sequence of statements, or \code{'eval'}
if it consists of a single expression.
\end{funcdesc}
\begin{funcdesc}{dir}{}
Without arguments, return the list of names in the current local
symbol table. With a module, class or class instance object as
argument (or anything else that has a \code{__dict__} attribute),
returns the list of names in that object's attribute dictionary.
The resulting list is sorted. For example:
\bcode\begin{verbatim}
>>> import sys
>>> dir()
['sys']
>>> dir(sys)
['argv', 'exit', 'modules', 'path', 'stderr', 'stdin', 'stdout']
>>>
\end{verbatim}\ecode
\end{funcdesc}
\begin{funcdesc}{divmod}{a\, b}
Take two numbers as arguments and return a pair of integers
consisting of their integer quotient and remainder. With mixed
operand types, the rules for binary arithmetic operators apply. For
plain and long integers, the result is the same as
\code{(\var{a} / \var{b}, \var{a} \%{} \var{b})}.
For floating point numbers the result is the same as
\code{(math.floor(\var{a} / \var{b}), \var{a} \%{} \var{b})}.
\end{funcdesc}
\begin{funcdesc}{eval}{s\, globals\, locals}
The arguments are a string and two optional dictionaries. The
string argument is parsed and evaluated as a Python expression
(technically speaking, a condition list) using the dictionaries as
global and local name space. The string must not contain null bytes
or newline characters. The return value is the
result of the expression. If the third argument is omitted it
defaults to the second. If both dictionaries are omitted, the
expression is executed in the environment where \code{eval} is
called. Syntax errors are reported as exceptions. Example:
\bcode\begin{verbatim}
>>> x = 1
>>> print eval('x+1')
2
>>>
\end{verbatim}\ecode
This function can also be used to execute arbitrary code objects
(e.g. created by \code{compile()}). In this case pass a code
object instead of a string. The code object must have been compiled
passing \code{'eval'} to the \var{kind} argument.
Note: dynamic execution of statements is supported by the
\code{exec} statement.
\end{funcdesc}
\begin{funcdesc}{filter}{function\, list}
Construct a list from those elements of \var{list} for which
\var{function} returns true. If \var{list} is a string or a tuple,
the result also has that type; otherwise it is always a list. If
\var{function} is \code{None}, the identity function is assumed,
i.e. all elements of \var{list} that are false (zero or empty) are
removed.
\end{funcdesc}
\begin{funcdesc}{float}{x}
Convert a number to floating point. The argument may be a plain or
long integer or a floating point number.
\end{funcdesc}
\begin{funcdesc}{getattr}{object\, name}
The arguments are an object and a string. The string must be the
name
of one of the object's attributes. The result is the value of that
attribute. For example, \code{getattr(\var{x}, '\var{foobar}')} is equivalent to
\code{\var{x}.\var{foobar}}.
\end{funcdesc}
\begin{funcdesc}{hasattr}{object\, name}
The arguments are an object and a string. The result is 1 if the
string is the name of one of the object's attributes, 0 if not.
(This is implemented by calling \code{getattr(object, name)} and
seeing whether it raises an exception or not.)
\end{funcdesc}
\begin{funcdesc}{hash}{object}
Return the hash value of the object (if it has one). Hash values
are 32-bit integers. They are used to quickly compare dictionary
keys during a dictionary lookup. Numeric values that compare equal
have the same hash value (even if they are of different types, e.g.
1 and 1.0).
\end{funcdesc}
\begin{funcdesc}{hex}{x}
Convert a number to a hexadecimal string. The result is a valid
Python expression.
\end{funcdesc}
\begin{funcdesc}{id}{object}
Return the `identity' of an object. This is an integer which is
guaranteed to be unique and constant for this object during its
lifetime. (Two objects whose lifetimes are disjunct may have the
same id() value.) (Implementation note: this is the address of the
object.)
\end{funcdesc}
\begin{funcdesc}{input}{prompt}
Almost equivalent to \code{eval(raw_input(\var{prompt}))}. As for
\code{raw_input()}, the prompt argument is optional. The difference is
that a long input expression may be broken over multiple lines using the
backslash convention.
\end{funcdesc}
\begin{funcdesc}{int}{x}
Convert a number to a plain integer. The argument may be a plain or
long integer or a floating point number.
\end{funcdesc}
\begin{funcdesc}{len}{s}
Return the length (the number of items) of an object. The argument
may be a sequence (string, tuple or list) or a mapping (dictionary).
\end{funcdesc}
\begin{funcdesc}{long}{x}
Convert a number to a long integer. The argument may be a plain or
long integer or a floating point number.
\end{funcdesc}
\begin{funcdesc}{map}{function\, list\, ...}
Apply \var{function} to every item of \var{list} and return a list
of the results. If additional \var{list} arguments are passed,
\var{function} must take that many arguments and is applied to
the items of all lists in parallel; if a list is shorter than another
it is assumed to be extended with \code{None} items. If
\var{function} is \code{None}, the identity function is assumed; if
there are multiple list arguments, \code{map} returns a list
consisting of tuples containing the corresponding items from all lists
(i.e. a kind of transpose operation). The \var{list} arguments may be
any kind of sequence; the result is always a list.
\end{funcdesc}
\begin{funcdesc}{max}{s}
Return the largest item of a non-empty sequence (string, tuple or
list).
\end{funcdesc}
\begin{funcdesc}{min}{s}
Return the smallest item of a non-empty sequence (string, tuple or
list).
\end{funcdesc}
\begin{funcdesc}{oct}{x}
Convert a number to an octal string. The result is a valid Python
expression.
\end{funcdesc}
\begin{funcdesc}{open}{filename\, mode}
% XXXJH xrefs here to Built-in types?
Return a new file object (described earlier under Built-in Types).
The string arguments are the same as for \code{stdio}'s
\code{fopen()}: \var{filename} is the file name to be opened,
\var{mode} indicates how the file is to be opened: \code{'r'} for
reading, \code{'w'} for writing (truncating an existing file), and
\code{'a'} opens it for appending. Modes \code{'r+'}, \code{'w+'} and
\code{'a+'} open the file for updating, provided the underlying
\code{stdio} library understands this. On systems that differentiate
between binary and text files, \code{'b'} appended to the mode opens
the file in binary mode. If the file cannot be opened, \code{IOError}
is raised.
\end{funcdesc}
\begin{funcdesc}{ord}{c}
Return the \ASCII{} value of a string of one character. E.g.,
\code{ord('a')} returns the integer \code{97}. This is the inverse of
\code{chr()}.
\end{funcdesc}
\begin{funcdesc}{pow}{x\, y}
Return \var{x} to the power \var{y}. The arguments must have
numeric types. With mixed operand types, the rules for binary
arithmetic operators apply. The effective operand type is also the
type of the result; if the result is not expressible in this type, the
function raises an exception; e.g., \code{pow(2, -1)} is not allowed.
\end{funcdesc}
\begin{funcdesc}{range}{start\, end\, step}
This is a versatile function to create lists containing arithmetic
progressions. It is most often used in \code{for} loops. The
arguments must be plain integers. If the \var{step} argument is
omitted, it defaults to \code{1}. If the \var{start} argument is
omitted, it defaults to \code{0}. The full form returns a list of
plain integers \code{[\var{start}, \var{start} + \var{step},
\var{start} + 2 * \var{step}, \ldots]}. If \var{step} is positive,
the last element is the largest \code{\var{start} + \var{i} *
\var{step}} less than \var{end}; if \var{step} is negative, the last
element is the largest \code{\var{start} + \var{i} * \var{step}}
greater than \var{end}. \var{step} must not be zero. Example:
\bcode\begin{verbatim}
>>> range(10)
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
>>> range(1, 11)
[1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
>>> range(0, 30, 5)
[0, 5, 10, 15, 20, 25]
>>> range(0, 10, 3)
[0, 3, 6, 9]
>>> range(0, -10, -1)
[0, -1, -2, -3, -4, -5, -6, -7, -8, -9]
>>> range(0)
[]
>>> range(1, 0)
[]
>>>
\end{verbatim}\ecode
\end{funcdesc}
\begin{funcdesc}{raw_input}{prompt}
The string argument is optional; if present, it is written to
standard
output without a trailing newline. The function then reads a line
from input, converts it to a string (stripping a trailing newline),
and returns that. When \EOF{} is read, \code{EOFError} is raised.
Example:
\bcode\begin{verbatim}
>>> s = raw_input('--> ')
--> Monty Python's Flying Circus
>>> s
'Monty Python\'s Flying Circus'
>>>
\end{verbatim}\ecode
\end{funcdesc}
\begin{funcdesc}{reduce}{function\, list\, initializer}
Apply the binary \var{function} to the items of \var{list} so as to
reduce the list to a single value. E.g.,
\code{reduce(lambda x, y: x*y, \var{list}, 1)} returns the product of
the elements of \var{list}. The optional \var{initializer} can be
thought of as being prepended to \var{list} so as to allow reduction
of an empty \var{list}. The \var{list} arguments may be any kind of
sequence.
\end{funcdesc}
\begin{funcdesc}{reload}{module}
Re-parse and re-initialize an already imported \var{module}. The
argument must be a module object, so it must have been successfully
imported before. This is useful if you have edited the module source
file using an external editor and want to try out the new version
without leaving the Python interpreter. Note that if a module is
syntactically correct but its initialization fails, the first
\code{import} statement for it does not import the name, but does
create a (partially initialized) module object; to reload the module
you must first \code{import} it again (this will just make the
partially initialized module object available) before you can
\code{reload()} it.
\end{funcdesc}
\begin{funcdesc}{repr}{object}
Return a string containing a printable representation of an object.
This is the same value yielded by conversions (reverse quotes).
It is sometimes useful to be able to access this operation as an
ordinary function. For many types, this function makes an attempt
to return a string that would yield an object with the same value
when passed to \code{eval()}.
\end{funcdesc}
\begin{funcdesc}{round}{x\, n}
Return the floating point value \var{x} rounded to \var{n} digits
after the decimal point. If \var{n} is omitted, it defaults to zero.
The result is a floating point number. Values are rounded to the
closest multiple of 10 to the power minus \var{n}; if two multiples
are equally close, rounding is done away from 0 (so e.g.
\code{round(0.5)} is \code{1.0} and \code{round(-0.5)} is \code{-1.0}).
\end{funcdesc}
\begin{funcdesc}{setattr}{object\, name\, value}
This is the counterpart of \code{getattr}. The arguments are an
object, a string and an arbitrary value. The string must be the name
of one of the object's attributes. The function assigns the value to
the attribute, provided the object allows it. For example,
\code{setattr(\var{x}, '\var{foobar}', 123)} is equivalent to
\code{\var{x}.\var{foobar} = 123}.
\end{funcdesc}
\begin{funcdesc}{str}{object}
Return a string containing a nicely printable representation of an
object. For strings, this returns the string itself. The difference
with \code{repr(\var{object}} is that \code{str(\var{object}} does not
always attempt to return a string that is acceptable to \code{eval()};
its goal is to return a printable string.
\end{funcdesc}
\begin{funcdesc}{type}{object}
% XXXJH xref to buil-in objects here?
Return the type of an \var{object}. The return value is a type
object. There is not much you can do with type objects except compare
them to other type objects; e.g., the following checks if a variable
is a string:
\bcode\begin{verbatim}
>>> if type(x) == type(''): print 'It is a string'
\end{verbatim}\ecode
\end{funcdesc}

55
Doc/lib/libgetopt.tex Normal file
View File

@@ -0,0 +1,55 @@
\section{Standard Module \sectcode{getopt}}
\stmodindex{getopt}
This module helps scripts to parse the command line arguments in
\code{sys.argv}.
It uses the same conventions as the \UNIX{}
\code{getopt()}
function.
It defines the function
\code{getopt.getopt(args, options)}
and the exception
\code{getopt.error}.
The first argument to
\code{getopt()}
is the argument list passed to the script with its first element
chopped off (i.e.,
\code{sys.argv[1:]}).
The second argument is the string of option letters that the
script wants to recognize, with options that require an argument
followed by a colon (i.e., the same format that \UNIX{}
\code{getopt()}
uses).
The return value consists of two elements: the first is a list of
option-and-value pairs; the second is the list of program arguments
left after the option list was stripped (this is a trailing slice of the
first argument).
Each option-and-value pair returned has the option as its first element,
prefixed with a hyphen (e.g.,
\code{'-x'}),
and the option argument as its second element, or an empty string if the
option has no argument.
The options occur in the list in the same order in which they were
found, thus allowing multiple occurrences.
Example:
\bcode\begin{verbatim}
>>> import getopt, string
>>> args = string.split('-a -b -cfoo -d bar a1 a2')
>>> args
['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2']
>>> optlist, args = getopt.getopt(args, 'abc:d:')
>>> optlist
[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')]
>>> args
['a1', 'a2']
>>>
\end{verbatim}\ecode
The exception
\code{getopt.error = 'getopt error'}
is raised when an unrecognized option is found in the argument list or
when an option requiring an argument is given none.
The argument to the exception is a string indicating the cause of the
error.

197
Doc/lib/libgl.tex Normal file
View File

@@ -0,0 +1,197 @@
\section{Built-in Module \sectcode{gl}}
\bimodindex{gl}
This module provides access to the Silicon Graphics
{\em Graphics Library}.
It is available only on Silicon Graphics machines.
\strong{Warning:}
Some illegal calls to the GL library cause the Python interpreter to dump
core.
In particular, the use of most GL calls is unsafe before the first
window is opened.
The module is too large to document here in its entirety, but the
following should help you to get started.
The parameter conventions for the C functions are translated to Python as
follows:
\begin{itemize}
\item
All (short, long, unsigned) int values are represented by Python
integers.
\item
All float and double values are represented by Python floating point
numbers.
In most cases, Python integers are also allowed.
\item
All arrays are represented by one-dimensional Python lists.
In most cases, tuples are also allowed.
\item
\begin{sloppypar}
All string and character arguments are represented by Python strings,
for instance,
\code{winopen('Hi There!')}
and
\code{rotate(900, 'z')}.
\end{sloppypar}
\item
All (short, long, unsigned) integer arguments or return values that are
only used to specify the length of an array argument are omitted.
For example, the C call
\bcode\begin{verbatim}
lmdef(deftype, index, np, props)
\end{verbatim}\ecode
is translated to Python as
\bcode\begin{verbatim}
lmdef(deftype, index, props)
\end{verbatim}\ecode
\item
Output arguments are omitted from the argument list; they are
transmitted as function return values instead.
If more than one value must be returned, the return value is a tuple.
If the C function has both a regular return value (that is not omitted
because of the previous rule) and an output argument, the return value
comes first in the tuple.
Examples: the C call
\bcode\begin{verbatim}
getmcolor(i, &red, &green, &blue)
\end{verbatim}\ecode
is translated to Python as
\bcode\begin{verbatim}
red, green, blue = getmcolor(i)
\end{verbatim}\ecode
\end{itemize}
The following functions are non-standard or have special argument
conventions:
\renewcommand{\indexsubitem}{(in module gl)}
\begin{funcdesc}{varray}{argument}
%JHXXX the argument-argument added
Equivalent to but faster than a number of
\code{v3d()}
calls.
The \var{argument} is a list (or tuple) of points.
Each point must be a tuple of coordinates
\code{(\var{x}, \var{y}, \var{z})} or \code{(\var{x}, \var{y})}.
The points may be 2- or 3-dimensional but must all have the
same dimension.
Float and int values may be mixed however.
The points are always converted to 3D double precision points
by assuming \code{\var{z} = 0.0} if necessary (as indicated in the man page),
and for each point
\code{v3d()}
is called.
\end{funcdesc}
\begin{funcdesc}{nvarray}{}
Equivalent to but faster than a number of
\code{n3f}
and
\code{v3f}
calls.
The argument is an array (list or tuple) of pairs of normals and points.
Each pair is a tuple of a point and a normal for that point.
Each point or normal must be a tuple of coordinates
\code{(\var{x}, \var{y}, \var{z})}.
Three coordinates must be given.
Float and int values may be mixed.
For each pair,
\code{n3f()}
is called for the normal, and then
\code{v3f()}
is called for the point.
\end{funcdesc}
\begin{funcdesc}{vnarray}{}
Similar to
\code{nvarray()}
but the pairs have the point first and the normal second.
\end{funcdesc}
\begin{funcdesc}{nurbssurface}{s_k\, t_k\, ctl\, s_ord\, t_ord\, type}
% XXX s_k[], t_k[], ctl[][]
%\itembreak
Defines a nurbs surface.
The dimensions of
\code{\var{ctl}[][]}
are computed as follows:
\code{[len(\var{s_k}) - \var{s_ord}]},
\code{[len(\var{t_k}) - \var{t_ord}]}.
\end{funcdesc}
\begin{funcdesc}{nurbscurve}{knots\, ctlpoints\, order\, type}
Defines a nurbs curve.
The length of ctlpoints is
\code{len(\var{knots}) - \var{order}}.
\end{funcdesc}
\begin{funcdesc}{pwlcurve}{points\, type}
Defines a piecewise-linear curve.
\var{points}
is a list of points.
\var{type}
must be
\code{N_ST}.
\end{funcdesc}
\begin{funcdesc}{pick}{n}
\funcline{select}{n}
The only argument to these functions specifies the desired size of the
pick or select buffer.
\end{funcdesc}
\begin{funcdesc}{endpick}{}
\funcline{endselect}{}
These functions have no arguments.
They return a list of integers representing the used part of the
pick/select buffer.
No method is provided to detect buffer overrun.
\end{funcdesc}
Here is a tiny but complete example GL program in Python:
\bcode\begin{verbatim}
import gl, GL, time
def main():
gl.foreground()
gl.prefposition(500, 900, 500, 900)
w = gl.winopen('CrissCross')
gl.ortho2(0.0, 400.0, 0.0, 400.0)
gl.color(GL.WHITE)
gl.clear()
gl.color(GL.RED)
gl.bgnline()
gl.v2f(0.0, 0.0)
gl.v2f(400.0, 400.0)
gl.endline()
gl.bgnline()
gl.v2f(400.0, 0.0)
gl.v2f(0.0, 400.0)
gl.endline()
time.sleep(5)
main()
\end{verbatim}\ecode
\section{Standard Modules \sectcode{GL} and \sectcode{DEVICE}}
\stmodindex{GL}
\stmodindex{DEVICE}
These modules define the constants used by the Silicon Graphics
{\em Graphics Library}
that C programmers find in the header files
\file{<gl/gl.h>}
and
\file{<gl/device.h>}.
Read the module source files for details.

32
Doc/lib/libgrp.tex Normal file
View File

@@ -0,0 +1,32 @@
\section{Built-in Module \sectcode{grp}}
\bimodindex{grp}
This module provides access to the \UNIX{} group database.
It is available on all \UNIX{} versions.
Group database entries are reported as 4-tuples containing the
following items from the group database (see \file{<grp.h>}), in order:
\code{gr_name},
\code{gr_passwd},
\code{gr_gid},
\code{gr_mem}.
The gid is an integer, name and password are strings, and the member
list is a list of strings.
(Note that most users are not explicitly listed as members of the
group(s) they are in.)
An exception is raised if the entry asked for cannot be found.
It defines the following items:
\renewcommand{\indexsubitem}{(in module grp)}
\begin{funcdesc}{getgrgid}{gid}
Return the group database entry for the given numeric group ID.
\end{funcdesc}
\begin{funcdesc}{getgrnam}{name}
Return the group database entry for the given group name.
\end{funcdesc}
\begin{funcdesc}{getgrall}{}
Return a list of all available group entries entries, in arbitrary order.
\end{funcdesc}

87
Doc/lib/libimageop.tex Normal file
View File

@@ -0,0 +1,87 @@
\section{Built-in module \sectcode{imageop}}
\bimodindex{imageop}
The 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 defines the following variables and functions:
\renewcommand{\indexsubitem}{(in module imageop)}
\begin{excdesc}{error}
This exception is raised on all errors, such as unknown number of bits
per pixel, etc.
\end{excdesc}
\begin{funcdesc}{crop}{image\, psize\, width\, height\, x0\, y0\, x1\, y1}
This function takes the image in \code{image}, which should by
\code{width} by \code{height} in size and consist of pixels of
\code{psize} bytes, and returns the selected part of that image. \code{X0},
\code{y0}, \code{x1} and \code{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 \code{x0} is bigger than \code{x1} the new image is mirrored. The
same holds for the y coordinates.
\end{funcdesc}
\begin{funcdesc}{scale}{image\, psize\, width\, height\, newwidth\, newheight}
This function returns a \code{image} scaled to size \code{newwidth} by
\code{newheight}. No interpolation is done, scaling is done by
simple-minded pixel duplication or removal. Therefore, computer-generated
images or dithered images will not look nice after scaling.
\end{funcdesc}
\begin{funcdesc}{tovideo}{image\, psize\, width\, height}
This function runs a vertical low-pass filter over an image. It does
so by computing each destination pixel as the average of two
vertically-aligned source pixels. The main use of this routine is to
forestall excessive flicker if the image is displayed on a video
device that uses interlacing, hence the name.
\end{funcdesc}
\begin{funcdesc}{grey2mono}{image\, width\, height\, threshold}
This function converts 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}.
\end{funcdesc}
\begin{funcdesc}{dither2mono}{image\, width\, height}
This function also converts an 8-bit greyscale image to a 1-bit
monochrome image but it uses a (simple-minded) dithering algorithm.
\end{funcdesc}
\begin{funcdesc}{mono2grey}{image\, width\, height\, p0\, p1}
This function converts a 1-bit monochrome image to an 8 bit greyscale
or color image. All pixels that are zero-valued on input get value
\code{p0} on output and all one-value input pixels get value \code{p1}
on output. To convert a monochrome black-and-white image to greyscale
pass the values \code{0} and \code{255} respectively.
\end{funcdesc}
\begin{funcdesc}{grey2grey4}{image\, width\, height}
Convert an 8-bit greyscale image to a 4-bit greyscale image without
dithering.
\end{funcdesc}
\begin{funcdesc}{grey2grey2}{image\, width\, height}
Convert an 8-bit greyscale image to a 2-bit greyscale image without
dithering.
\end{funcdesc}
\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.
\end{funcdesc}
\begin{funcdesc}{grey42grey}{image\, width\, height}
Convert a 4-bit greyscale image to an 8-bit greyscale image.
\end{funcdesc}
\begin{funcdesc}{grey22grey}{image\, width\, height}
Convert a 2-bit greyscale image to an 8-bit greyscale image.
\end{funcdesc}

63
Doc/lib/libimgfile.tex Normal file
View File

@@ -0,0 +1,63 @@
\section{Built-in module \sectcode{imgfile}}
\bimodindex{imgfile}
The imgfile 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.
The module defines the following variables and functions:
\renewcommand{\indexsubitem}{(in module imgfile)}
\begin{excdesc}{error}
This exception is raised on all errors, such as unsupported file type, etc.
\end{excdesc}
\begin{funcdesc}{getsizes}{file}
This function returns a tuple \code{(\var{x}, \var{y}, \var{z})} where
\var{x} and \var{y} are the size of the image in pixels and
\var{z} is the number of
bytes per pixel. Only 3 byte RGB pixels and 1 byte greyscale pixels
are currently supported.
\end{funcdesc}
\begin{funcdesc}{read}{file}
This function reads and decodes the image on the specified file, and
returns it as a python string. The string has either 1 byte greyscale
pixels or 4 byte RGBA pixels. The bottom left pixel is the first in
the string. This format is suitable to pass to \code{gl.lrectwrite},
for instance.
\end{funcdesc}
\begin{funcdesc}{readscaled}{file\, x\, y\, filter\, blur}
This function is identical to read but it returns an image that is
scaled to the given \var{x} and \var{y} sizes. If the \var{filter} and
\var{blur} parameters are omitted scaling is done by
simply dropping or duplicating pixels, so the result will be less than
perfect, especially for computer-generated images.
Alternatively, you can specify a filter to use to smoothen the image
after scaling. The filter forms supported are \code{'impulse'},
\code{'box'}, \code{'triangle'}, \code{'quadratic'} and
\code{'gaussian'}. If a filter is specified \var{blur} is an optional
parameter specifying the blurriness of the filter. It defaults to \code{1.0}.
Readscaled makes no
attempt to keep the aspect ratio correct, so that is the users'
responsibility.
\end{funcdesc}
\begin{funcdesc}{ttob}{flag}
This function sets a global flag which defines whether the scan lines
of the image are read or written from bottom to top (flag is zero,
compatible with SGI GL) or from top to bottom(flag is one,
compatible with X). The default is zero.
\end{funcdesc}
\begin{funcdesc}{write}{file\, data\, x\, y\, z}
This function writes the RGB or greyscale data in \var{data} to image
file \var{file}. \var{x} and \var{y} give the size of the image,
\var{z} is 1 for 1 byte greyscale images or 3 for RGB images (which are
stored as 4 byte values of which only the lower three bytes are used).
These are the formats returned by \code{gl.lrectread}.
\end{funcdesc}

17
Doc/lib/libintro.tex Normal file
View File

@@ -0,0 +1,17 @@
\chapter{Introduction}
The Python library consists of three parts, with different levels of
integration with the interpreter.
Closest to the interpreter are built-in types, exceptions and functions.
Next are built-in modules, which are written in \C{} and linked statically
with the interpreter.
Finally there are standard modules that are implemented entirely in
Python, but are always available.
For efficiency, some standard modules may become built-in modules in
future versions of the interpreter.
\indexii{built-in}{types}
\indexii{built-in}{exceptions}
\indexii{built-in}{functions}
\indexii{built-in}{modules}
\indexii{standard}{modules}
\indexii{\C{}}{language}

51
Doc/lib/libjpeg.tex Normal file
View File

@@ -0,0 +1,51 @@
\section{Built-in Module \sectcode{jpeg}}
\bimodindex{jpeg}
The 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
Indepent JPEG Group software refer to the JPEG standard or the
documentation provided with the software.
The jpeg module defines these functions:
\renewcommand{\indexsubitem}{(in module jpeg)}
\begin{funcdesc}{compress}{data\, w\, h\, b}
Treat data as a pixmap of width w and height h, with b bytes per
pixel. The data is in sgi gl order, so the first pixel is in the
lower-left corner. This means that lrectread return data can
immedeately be passed to compress. Currently only 1 byte and 4 byte
pixels are allowed, the former being treaded as greyscale and the
latter as RGB color. Compress returns a string that contains the
compressed picture, in 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}, \var{bytesperpixel})}.
Again, the data is suitable to pass to lrectwrite.
\end{funcdesc}
\begin{funcdesc}{setoption}{name\, value}
Set various options. Subsequent compress and decompress calls
will use these options. The following options are available:
\begin{description}
\item[\code{'forcegray'}]
Force output to be grayscale, even if input is RGB.
\item[\code{'quality'}]
Set the quality of the compressed image to a
value between \code{0} and \code{100} (default is \code{75}). Compress only.
\item[\code{'optimize'}]
Perform huffman table optimization. Takes longer, but results in
smaller compressed image. Compress only.
\item[\code{'smooth'}]
Perform inter-block smoothing on uncompressed image. Only useful for
low-quality images. Decompress only.
\end{description}
\end{funcdesc}
Compress and uncompress raise the error jpeg.error in case of errors.

6
Doc/lib/libmain.tex Normal file
View File

@@ -0,0 +1,6 @@
\section{Built-in Module \sectcode{__main__}}
\bimodindex{__main__}
This module represents the (otherwise anonymous) scope in which the
interpreter's main program executes --- commands read either from
standard input or from a script file.

59
Doc/lib/libmarshal.tex Normal file
View File

@@ -0,0 +1,59 @@
\section{Built-in Module \sectcode{marshal}}
\bimodindex{marshal}
This module contains functions that can read and write Python
values in a binary format. The format is specific to Python, but
independent of machine architecture issues (e.g., you can write a
Python value to a file on a VAX, transport the file to a Mac, and read
it back there). Details of the format not explained here; read the
source if you're interested.%
\footnote{The name of this module stems from a bit of terminology used
by the designers of Modula-3 (amongst others), who use the term
``marshalling'' for shipping of data around in a self-contained form.
Strictly speaking, ``to marshal'' means to convert some data from
internal to external form (in an RPC buffer for instance) and
``unmarshalling'' for the reverse process.}
Not all Python object types are supported; in general, only objects
whose value is independent from a particular invocation of Python can
be written and read by this module. The following types are supported:
\code{None}, integers, long integers, floating point numbers,
strings, tuples, lists, dictionaries, and code objects, where it
should be understood that tuples, lists and dictionaries are only
supported as long as the values contained therein are themselves
supported; and recursive lists and dictionaries should not be written
(they will cause an infinite loop).
There are functions that read/write files as well as functions
operating on strings.
The module defines these functions:
\renewcommand{\indexsubitem}{(in module marshal)}
\begin{funcdesc}{dump}{value\, file}
Write the value on the open file. The value must be a supported
type. The file must be an open file object such as
\code{sys.stdout} or returned by \code{open()} or
\code{posix.popen()}.
If the value has an unsupported type, garbage is written which cannot
be read back by \code{load()}.
\end{funcdesc}
\begin{funcdesc}{load}{file}
Read one value from the open file and return it. If no valid value
is read, raise \code{EOFError}, \code{ValueError} or
\code{TypeError}. The file must be an open file object.
\end{funcdesc}
\begin{funcdesc}{dumps}{value}
Return the string that would be written to a file by
\code{dump(value, file)}. The value must be a supported type.
\end{funcdesc}
\begin{funcdesc}{loads}{string}
Convert the string to a value. If no valid value is found, raise
\code{EOFError}, \code{ValueError} or \code{TypeError}. Extra
characters in the string are ignored.
\end{funcdesc}

Some files were not shown because too many files have changed in this diff Show More