cpython/Doc/lib.tex

% Format this file with latex.

%\documentstyle[palatino,11pt,myformat]{article}
\documentstyle[11pt,myformat]{article}

\sloppy

\title{\bf
	Python Library Reference \\
	(DRAFT)
}

\author{
	Guido van Rossum \\
	Dept. CST, CWI, Kruislaan 413 \\
	1098 SJ Amsterdam, The Netherlands \\
	E-mail: {\tt guido@cwi.nl}
}

\begin{document}

\pagenumbering{roman}

\maketitle

\begin{abstract}

\noindent
This document describes the built-in types, exceptions and functions and
the standard modules that come with the {\Python} system.
It assumes basic knowledge about the {\Python} language.
For an informal introduction to the language, see the Tutorial document.
The Language Reference document (XXX not yet existing)
gives a more formal reference to the language.

\end{abstract}

\pagebreak

\tableofcontents

\pagebreak

\pagenumbering{arabic}

\section{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.

\section{Built-in Types, Exceptions and Functions}

Names for built-in exceptions and functions are found in a separate
read-only symbol table which cannot be modified.
This table is searched last, so local and global user-defined names can
override built-in names.
Built-in types have no names but are created by syntactic constructs
(such as constants) or built-in functions.
They are described together here for easy reference.%
\footnote{
The descriptions sorely lack explanations of the exceptions that
may be raised---this will be fixed in a future version of this
document.
}

\subsection{Built-in Types}

The following sections describe the standard types that are built into the
interpreter.
\subsubsection{Numeric Types}

There are two numeric types: integers and floating point numbers.
Integers are implemented using {\tt long} in C, so they have at least 32
bits of precision.
Floating point numbers are implemented using {\tt double} in C.
All bets on precision are off.
Numbers are created by numeric constants or as the result of built-in
functions and operators.

Numeric types support the following operations:

\begin{center}
\begin{tabular}{|c|l|c|}
\hline
Operation & Result & Notes \\
\hline
{\tt abs}({\em x}) & absolute value of {\em x} & \\
{\tt int}({\em x}) & {\em x} converted to integer & (1) \\
{\tt float}({\em x}) & {\em x} converted to floating point & \\
{\tt -}{\em x} & {\em x} negated & \\
{\tt +}{\em x} & {\em x} unchanged & \\
{\em x}{\tt +}{\em y} & sum of {\em x} and {\em y} & \\
{\em x}{\tt -}{\em y} & difference of {\em x} and {\em y} & \\
{\em x}{\tt *}{\em y} & product of {\em x} and {\em y} & \\
{\em x}{\tt /}{\em y} & quotient of {\em x} and {\em y} & (2) \\
{\em x}{\tt \%}{\em y} & remainder of {\em x}{\tt /}{\em y} & (3) \\
\hline
\end{tabular}
\end{center}

\noindent
Notes:
\begin{description}
\item[(1)]
This may round or truncate as in C; see functions {\tt floor} and
{\tt ceil} in module {\tt math}.
\item[(2)]
Integer division is defined as in C: the result is an integer; with
positive operands, it truncates towards zero; with a negative operand,
the result is unspecified.
\item[(3)]
Only defined for integers.
\end{description}

Mixed arithmetic is not supported; both operands must have the same type.
Mixed comparisons return the wrong result (floats always compare smaller
than integers).%
\footnote{
These restrictions are bugs in the language definitions and will be
fixed in the future.
}
\subsubsection{Sequence Types}

There are three sequence types: strings, lists and tuples.
Strings constants are written in single quotes: {\tt 'xyzzy'}.
Lists are constructed with square brackets: {\tt [a,~b,~c]}.
Tuples are constructed by the comma operator or with an empty set of
parentheses: {\tt a,~b,~c} or {\tt ()}.

Sequence types support the following operations ({\em s} and {\em t} are
sequences of the same type; {\em n}, {\em i} and {\em j} are integers):

\begin{center}
\begin{tabular}{|c|l|c|}
\hline
Operation & Result & Notes \\
\hline
{\tt len}({\em s}) & length of {\em s} & \\
{\tt min}({\em s}) & smallest item of {\em s} & \\
{\tt max}({\em s}) & largest item of {\em s} & \\
{\em x} {\tt in} {\em s} &
	true if an item of {\em s} is equal to {\em x} & \\
{\em x} {\tt not} {\tt in} {\em s} &
	false if an item of {\em s} is equal to {\em x} & \\
{\em s}{\tt +}{\em t} & the concatenation of {\em s} and {\em t} & \\
{\em s}{\tt *}{\em n}, {\em n}*{\em s} &
	{\em n} copies of {\em s} concatenated & (1) \\
{\em s}[{\em i}] & {\em i}'th item of {\em s} & \\
{\em s}[{\em i}:{\em j}] &
	slice of {\em s} from {\em i} to {\em j} & (2) \\
\hline
\end{tabular}
\end{center}

\noindent
Notes:
\begin{description}
\item[(1)]
Sequence repetition is only supported for strings.
\item[(2)]
The slice of $s$ from $i$ to $j$ is defined as the sequence
of items with index $k$ such that $i \leq k < j$.
Special rules apply for negative and omitted indices; see the Tutorial
or the Reference Manual.
\end{description}

\paragraph{Mutable Sequence Types.}

List objects support additional operations that allow in-place
modification of the object.
These operations would be supported by other mutable sequence types
(when added to the language) as well.
Strings and tuples are immutable sequence types and such objects cannot
be modified once created.
The following operations are defined on mutable sequence types (where
{\em x} is an arbitrary object):

\begin{center}
\begin{tabular}{|c|l|}
\hline
Operation & Result \\
\hline
{\em s}[{\em i}] = {\em x} &
	item {\em i} of {\em s} is replaced by {\em x} \\
{\em s}[{\em i}:{\em j}] = {\em t} &
	slice of {\em s} from {\em i} to {\em j} is replaced by {\em t} \\
{\tt del} {\em s}[{\em i}:{\em j}] &
	same as {\em s}[{\em i}:{\em j}] = [] \\
{\em s}.{\tt append}({\em x}) &
	same as {\em s}[{\tt len}({\em x}):{\tt len}({\em x})] = [{\em x}] \\
{\em s}.{\tt insert}({\em i}, {\em x}) &
	same as {\em s}[{\em i}:{\em i}] = [{\em x}] \\
{\em s}.{\tt sort}() &
	the items of {\em s} are permuted to satisfy \\
	&
	$s[i] \leq s[j]$ for $i < j$\\
\hline
\end{tabular}
\end{center}

\subsubsection{Mapping Types}

A
{\em mapping}
object maps values of one type (the key type) to arbitrary objects.
Mappings are mutable objects.
There is currently only one mapping type, the
{\em dictionary}.
A dictionary's keys are strings.
An empty dictionary is created by the expression \verb"{}".
An extension of this notation is used to display dictionaries when
written (see the example below).

The following operations are defined on mappings (where {\em a} is a
mapping, {\em k} is a key and {\em x} is an arbitrary object):

\begin{center}
\begin{tabular}{|c|l|c|}
\hline
Operation & Result & Notes\\
\hline
{\tt len}({\em a}) & the number of elements in {\em a} & \\
{\em a}[{\em k}] & the item of {\em a} with key {\em k} & \\
{\em a}[{\em k}] = {\em x} & set {\em a}[{\em k}] to {\em x} & \\
{\tt del} {\em a}[{\em k}] & remove {\em a}[{\em k}] from {\em a} & \\
{\em a}.{\tt keys}() & a copy of {\em a}'s list of keys & (1) \\
{\em a}.{\tt has\_key}({\em k}) & true if {\em a} has a key {\em k} & \\
\hline
\end{tabular}
\end{center}

\noindent
Notes:
\begin{description}
\item[(1)]
Keys are listed in random order.
\end{description}

A small example using a dictionary:
\begin{code}\begin{verbatim}
>>> tel = {}
>>> tel['jack'] = 4098
>>> tel['sape'] = 4139
>>> tel['guido'] = 4127
>>> tel['jack']
4098
>>> tel
{'sape': 4139; 'guido': 4127; 'jack': 4098}
>>> del tel['sape']
>>> tel['irv'] = 4127
>>> tel
{'guido': 4127; 'irv': 4127; 'jack': 4098}
>>> tel.keys()
['guido', 'irv', 'jack']
>>> tel.has_key('guido')
1
>>> 
\end{verbatim}\end{code}
\subsubsection{Other Built-in Types}

The interpreter supports several other kinds of objects.
Most of these support only one or two operations.

\paragraph{Modules.}

The only operation on a module is member acces: {\em m}{\tt .}{\em name},
where {\em m} is a module and {\em name} accesses a name defined in
{\em m}'s symbol table.
Module members can be assigned to.

\paragraph{Classes and Class Objects.}

XXX Classes will be explained at length in a later version of this
document.

\paragraph{Functions.}

Function objects are created by function definitions.
The only operation on a function object is to call it:
{\em func}({\em optional-arguments}).

Built-in functions have a different type than user-defined functions,
but they support the same operation.

\paragraph{Methods.}

Methods are functions that are called using the member acces notation.
There are two flavors: built-in methods (such as {\tt append()} on
lists) and class member methods.
Built-in methods are described with the types that support them.
XXX Class member methods will be described in a later version of this
document.

\paragraph{Type Objects.}

Type objects represent the various object types.
An object's type is accessed by the built-in function
{\tt type()}.
There are no operations on type objects.

\paragraph{The Null Object.}

This object is returned by functions that don't explicitly return a
value.
It supports no operations.
There is exactly one null object.

\paragraph{File Objects.}

File objects are implemented using C's
{\em stdio}
package and can be created with the built-in function
{\tt open()}.
They have the following methods:
\begin{description}
\item[{\tt close()}]
Closes the file.
A closed file cannot be read or written anymore.
\item[{\tt read(size)}]
Reads at most
{\tt size}
bytes from the file (less if the read hits EOF).
The bytes are returned as a string object.
An empty string is returned when EOF is hit immediately.
(For certain files, like ttys, it makes sense to continue reading after
an EOF is hit.)
\item[{\tt readline(size)}]
Reads a line of at most
{\tt size}
bytes from the file.
A trailing newline character, if present, is kept in the string.
The size is optional and defaults to a large number (but not infinity).
EOF is reported as by
{\tt read().}
\item[{\tt write(str)}]
Writes a string to the file.
Returns no value.
\end{description}

\subsection{Built-in Exceptions}

The following exceptions can be generated by the interpreter or
built-in functions.
Except where mentioned, they have a string argument (also known as the
`associated value' of an exception) indicating the detailed cause of the
error.
The strings listed with the exception names are their values when used
in an expression or printed.
\begin{description}
\item[{\tt EOFError = 'end-of-file read'} (no argument)]
%.br
Raised when a built-in function ({\tt input()} or {\tt raw\_input()})
hits an end-of-file condition (EOF) without reading any data.
(N.B.: the {\tt read()} and {\tt readline()} methods of file objects
return an empty string when they hit EOF.)
\item[{\tt KeyboardInterrupt = 'end-of-file read'} (no argument)]
%.br
Raised when the user hits the interrupt key (normally Control-C or DEL).
During execution, a check for interrupts is made regularly.
Interrupts typed when a built-in function ({\tt input()} or
{\tt raw\_input()}) is waiting for input also raise this exception.
\item[{\tt MemoryError = 'out of memory'}]
%.br
Raised when an operation runs out of memory but the situation
may still be rescued (by deleting some objects).
\item[{\tt NameError = 'undefined name'}]
%.br
Raised when a name is not found.
This applies to unqualified names, module names (on {\tt import}),
module members and object methods.
The string argument is the name that could not be found.
\item[{\tt RuntimeError = 'run-time error'}]
%.br
Raised for a variety of reasons, e.g., division by zero or index out of
range.
\item[{\tt SystemError = 'system error'}]
%.br
Raised when the interpreter finds an internal error, but the situation
does not look so serious to cause it to abandon all hope.
\item[{\tt TypeError = 'type error'}]
%.br
Raised when an operation or built-in function is applied to an object of
inappropriate type.
\end{description}

\subsection{Built-in Functions}

The {\Python} interpreter has a small number of functions built into it that
are always available.
They are listed here in alphabetical order.
\begin{description}
\item[{\tt abs(x)}]
Returns the absolute value of a number.
The argument may be an integer or floating point number.
\item[{\tt dir()}]
Without arguments, this function returns the list of names in the
current local symbol table, sorted alphabetically.
With a module object as argument, it returns the sorted list of names in
that module's global symbol table.
For example:
\begin{code}\begin{verbatim}
>>> import sys
>>> dir()
['sys']
>>> dir(sys)
['argv', 'exit', 'modules', 'path', 'stderr', 'stdin', 'stdout']
>>> 
\end{verbatim}\end{code}
\item[{\tt divmod(a, b)}]
%.br
Takes two integers as arguments and returns a pair of integers
consisting of their quotient and remainder.
For
\begin{code}\begin{verbatim}
q, r = divmod(a, b)
\end{verbatim}\end{code}
the invariants are:
\begin{code}\begin{verbatim}
a = q*b + r
abs(r) < abs(b)
r has the same sign as b
\end{verbatim}\end{code}
For example:
\begin{code}\begin{verbatim}
>>> divmod(100, 7)
(14, 2)
>>> divmod(-100, 7)
(-15, 5)
>>> divmod(100, -7)
(-15, -5)
>>> divmod(-100, -7)
(14, -2)
>>> 
\end{verbatim}\end{code}
\item[{\tt eval(s)}]
Takes a string as argument and parses and evaluates it as a {\Python}
expression.
The expression is executed using the current local and global symbol
tables.
Syntax errors are reported as exceptions.
For example:
\begin{code}\begin{verbatim}
>>> x = 1
>>> eval('x+1')
2
>>> 
\end{verbatim}\end{code}
\item[{\tt exec(s)}]
Takes a string as argument and parses and evaluates it as a sequence of
{\Python} statements.
The string should end with a newline (\verb"'\n'").
The statement is executed using the current local and global symbol
tables.
Syntax errors are reported as exceptions.
For example:
\begin{code}\begin{verbatim}
>>> x = 1
>>> exec('x = x+1\n')
>>> x
2
>>> 
\end{verbatim}\end{code}
\item[{\tt float(x)}]
Converts a number to floating point.
The argument may be an integer or floating point number.
\item[{\tt input(s)}]
Equivalent to
{\tt eval(raw\_input(s))}.
As for
{\tt raw\_input()},
the argument is optional.
\item[{\tt len(s)}]
Returns the length (the number of items) of an object.
The argument may be a sequence (string, tuple or list) or a mapping
(dictionary).
\item[{\tt max(s)}]
Returns the largest item of a non-empty sequence (string, tuple or list).
\item[{\tt min(s)}]
Returns the smallest item of a non-empty sequence (string, tuple or list).
\item[{\tt open(name, mode)}]
%.br
Returns a file object (described earlier under Built-in Types).
The string arguments are the same as for stdio's
{\tt fopen()}:
{\tt 'r'}
opens the file for reading,
{\tt 'w'}
opens it for writing (truncating an existing file),
{\tt 'a'}
opens it for appending.%
\footnote{
This function should go into a built-in module
{\tt io}.
}
\item[{\tt range()}]
This is a versatile function to create lists containing arithmetic
progressions of integers.
With two integer arguments, it returns the ascending sequence of
integers starting at the first and ending one before the second
argument.
A single argument is used as the end point of the sequence, with 0 used
as the starting point.
A third argument specifies the step size; negative steps are allowed and
work as expected, but don't specify a zero step.
The resulting list may be empty.
For example:
\begin{code}\begin{verbatim}
>>> range(10)
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
>>> range(1, 1+10)
[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}\end{code}
\item[{\tt raw\_input(s)}]
%.br
The 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.
EOF is reported as an exception.
For example:
\begin{code}\begin{verbatim}
>>> raw_input('Type anything: ')
Type anything: Teenage Mutant Ninja Turtles
'Teenage Mutant Ninja Turtles'
>>> 
\end{verbatim}\end{code}
\item[{\tt type(x)}]
Returns the type of an object.
Types are objects themselves:
the type of a type object is its own type.
\end{description}

\section{Built-in Modules}

The modules described in this section are built into the interpreter.
They must be imported using
{\tt import}.
Some modules are not always available; it is a configuration option to
provide them.
Details are listed with the descriptions, but the best way to see if
a module exists in a particular implementation is to attempt to import
it.

\subsection{Built-in Module {\tt sys}}

This module provides access to some variables used or maintained by the
interpreter and to functions that interact strongly with the interpreter.
It is always available.
\begin{description}
\item[{\tt argv}]
The list of command line arguments passed to a {\Python} script.
{\tt sys.argv[0]}
is the script name.
If no script name was passed to the {\Python} interpreter,
{\tt sys.argv}
is empty.
\item[{\tt exit(n)}]
Exits from {\Python} with numeric exit status
{\tt n}.
This closes all open files and performs other cleanup-actions required by
the interpreter (but
{\em finally clauses}
of
{\tt try}
statements are not executed!).
\item[{\tt modules}]
Gives the list of modules that have already been loaded.
This can be manipulated to force reloading of modules and other tricks.
\item[{\tt path}]
A list of strings that specifies the search path for modules.
Initialized from the environment variable {\tt PYTHONPATH}, or an
installation-dependent default.
\item[{\tt ps1,~ps2}]
Strings specifying the primary and secondary prompt of the interpreter.
These are only defined if the interpreter is in interactive mode.
Their initial values in this case are
{\tt '>>> '}
and
{\tt '... '}.
\item[{\tt stdin, stdout, stderr}]
%.br
File objects corresponding to the interpreter's standard input, output
and error streams.
{\tt sys.stdin}
is used for all interpreter input except for scripts but including calls
to
{\tt input()}
and
{\tt raw\_input()}.
{\tt sys.stdout}
is used for the output of
{\tt print} and expression statements
and for the prompts of
{\tt input()}
and
{\tt raw\_input()}.
The interpreter's own prompts and its error messages are written to
stderr.
Assigning to
{\tt sys.stderr}
has no effect on the interpreter; it can be used to write error messages
to stderr using
{\tt print}.
\end{description}

\subsection{Built-in Module {\tt math}}

This module is always available.
It provides access to the mathematical functions defined by the C
standard.
They are:
{\tt acos(x)},
{\tt asin(x)},
{\tt atan(x)},
{\tt atan2(x,y)},
{\tt ceil(x)},
{\tt cos(x)},
{\tt cosh(x)},
{\tt exp(x)},
{\tt fabs(x)},
{\tt floor(x)},
%{\tt fmod(...)}  XXX not yet
%{\tt frexp(...)} XXX not yet
%{\tt ldexp(...)} XXX not yet
{\tt log(x)},
{\tt log10(x)},
%{\tt modf(...)}  XXX not yet
{\tt pow(x,y)},
{\tt sin(x)},
{\tt sinh(x)},
{\tt sqrt(x)},
{\tt tan(x)},
{\tt tanh(x)}.

It also defines two mathematical constants:
{\tt pi}
and
{\tt e}.

\subsection{Built-in Module {\tt time}}

This module provides various time-related functions.
It is always available.
Functions are:
\begin{description}
\item[{\tt sleep(secs)}]
Suspends execution for the given number of seconds.
\item[{\tt time()}]
Returns the time in seconds since the Epoch (Thursday January 1,
00:00:00, 1970 UCT on \UNIX\ machines).
\end{description}

\noindent
In some versions (Amoeba, Mac) the following functions also exist:
\begin{description}
\item[{\tt millisleep(msecs)}]
Suspends execution for the given number of milliseconds.
\item[{\tt millitimer()}]
Returns the number of milliseconds of real time elapsed since some point
in the past that is fixed per execution of the python interpreter (but
may change in each following run).
\end{description}

\noindent
The granularity of the milliseconds functions may be more than a
millisecond (100 msecs on Amoeba, 1/60 sec on the Mac).

\subsection{Built-in Module {\tt posix}}

This module provides access to operating system functionality that is
standardized by the C Standard and the POSIX standard (a thinly diguised
{\UNIX} interface).
It is available in all {\Python} versions except on the Macintosh.
Errors are reported exceptions.
It defines the following items:
\begin{description}
\item[{\tt chdir(path)}]
Changes the current directory to
{\tt path}.
\item[{\tt chmod(path, mode)}]
Change the mode of
{\tt path}
to the numeric
{\tt mode}.
\item[{\tt environ}]
A dictionary representing the string environment at the time
the interpreter was started.
(Modifying this dictionary does not affect the string environment of the
interpreter.)
For example,
{\tt posix.environ['HOME']}
is the pathname of your home directory, equivalent to
{\tt getenv("HOME")}
in C.
\item[{\tt error = 'posix.error'}]
%.br
The exception raised when an POSIX function returns an error.
The value accompanying this exception is a pair containing the numeric
error code from
{\tt errno}
and the corresponding string, as would be printed by the C function
{\tt perror()}.
\item[{\tt getcwd()}]
Returns a string representing the current working directory.
\item[{\tt link(src, dst)}]
Creates a hard link pointing to
{\tt src}
named
{\tt dst}.
\item[{\tt listdir(path)}]
Returns a list containing the names of the entries in the
directory.
The list is in arbitrary order.
It includes the special entries
{\tt '.'}
and
{\tt '..'}
if they are present in the directory.
\item[{\tt mkdir(path, mode)}]
Creates a directory named
{\tt path}
with numeric mode
{\tt mode}.
\item[{\tt rename(src, dst)}]
Renames the file or directory
{\tt src}
to
{\tt dst}.
\item[{\tt rmdir(path)}]
Removes the directory
{\tt path}.
\item[{\tt stat(path)}]
Performs a
{\em stat}
system call on the given path.
The return value is a tuple of at least 10 integers giving the most
important (and portable) members of the
{\em stat}
structure, in the order
{\tt st\_mode},
{\tt st\_ino},
{\tt st\_dev},
{\tt st\_nlink},
{\tt st\_uid},
{\tt st\_gid},
{\tt st\_size},
{\tt st\_atime},
{\tt st\_mtime},
{\tt st\_ctime}.
More items may be added at the end by some implementations.
\item[{\tt system(command)}]
Executes the command (a string) in a subshell.
This is implemented by calling the Standard C function
{\tt system()},
and has the same limitations.
Changes to
{\tt posix.environ},
{\tt sys.stdin}
etc. are not reflected in the environment of the executed command.
The return value is the exit status of the process as returned by
Standard C
{\tt system()}.
\item[{\tt umask(mask)}]
Sets the current numeric umask and returns the previous umask.
\item[{\tt unlink(path)}]
Unlinks the file
{\tt path}.
\item[{\tt utimes(path, (atime, mtime))}]
%.br
Sets the access and modified time of the file to the given values.
(The second argument is a tuple of two items.)
\end{description}

The following functions are only available on systems that support
symbolic links:
\begin{description}
\item[{\tt lstat(path)}]
Like
{\tt stat()},
but does not follow symbolic links.
\item[{\tt readlink(path)}]
Returns a string representing the path to which the symbolic link
points.
\item[{\tt symlink(src, dst)}]
Creates a symbolic link pointing to
{\tt src}
named
{\tt dst}.
\end{description}

\subsection{Built-in Module {\tt stdwin}}

This module defines several new object types and functions that
provide access to the functionality of the Standard Window System
Interface, STDWIN [CWI report CR-R8817].
It is available on systems to which STDWIN has been ported (which is
most systems).
It is only available if the {\tt DISPLAY} environment variable is set
or an explicit `{\tt -display \it displayname}' argument is passed to
the interpreter.

Functions have names that usually resemble their C STDWIN counterparts
with the initial `w' dropped.
Points are represented by pairs of integers; rectangles
by pairs of points.
For a complete description of STDWIN please refer to the documentation
of STDWIN for C programmers (aforementioned CWI report).
\subsubsection{Functions Defined in Module {\tt stdwin}}

The following functions are defined in the {\tt stdwin} module:
\begin{description}
\item[{\tt open(title)}]
%.br
Opens a new window whose initial title is given by the string argument.
Returns a window object; window object methods are described below.%
\footnote{
The {\Python} version of STDWIN does not support draw procedures; all
drawing requests are reported as draw events.
}
\item[{\tt getevent()}]
%.br
Waits for and returns the next event.
An event is returned as a triple: the first element is the event
type, a small integer; the second element is the window object to which
the event applies, or
{\tt None}
if it applies to no window in particular;
the third element is type-dependent.
Names for event types and command codes are defined in the standard
module
{\tt stdwinevent}.
\item[{\tt setdefwinpos(h, v)}]
%.br
Sets the default window position.
\item[{\tt setdefwinsize(width, height)}]
%.br
Sets the default window size.
\item[{\tt menucreate(title)}]
%.br
Creates a menu object referring to a global menu (a menu that appears in
all windows).
Methods of menu objects are described below.
\item[{\tt fleep()}]
%.br
Causes a beep or bell (or perhaps a `visual bell' or flash, hence the
name).
\item[{\tt message(string)}]
%.br
Displays a dialog box containing the string.
The user must click OK before the function returns.
\item[{\tt askync(prompt, default)}]
%.br
Displays a dialog that prompts the user to answer a question with yes or
no.
The function returns 0 for no, 1 for yes.
If the user hits the Return key, the default (which must be 0 or 1) is
returned.
If the user cancels the dialog, the
{\tt KeyboardInterrupt}
exception is raised.
\item[{\tt askstr(prompt, default)}]
%.br
Displays a dialog that prompts the user for a string.
If the user hits the Return key, the default string is returned.
If the user cancels the dialog, the
{\tt KeyboardInterrupt}
exception is raised.
\item[{\tt askfile(prompt, default, new)}]
%.br
Asks the user to specify a filename.
If
{\tt new}
is zero it must be an existing file; otherwise, it must be a new file.
If the user cancels the dialog, the
{\tt KeyboardInterrupt}
exception is raised.
\item[{\tt setcutbuffer(i, string)}]
%.br
Stores the string in the system's cut buffer number
{\tt i},
where it can be found (for pasting) by other applications.
On X11, there are 8 cut buffers (numbered 0..7).
Cut buffer number 0 is the `clipboard' on the Macintosh.
\item[{\tt getcutbuffer(i)}]
%.br
Returns the contents of the system's cut buffer number
{\tt i}.
\item[{\tt rotatebutbuffers(n)}]
%.br
On X11, this rotates the 8 cut buffers by
{\tt n}.
Ignored on the Macintosh.
\item[{\tt getselection(i)}]
%.br
Returns X11 selection number
{\tt i.}
Selections are not cut buffers.
Selection numbers are defined in module
{\tt stdwinevents}.
Selection {\tt WS\_PRIMARY} is the
{\em primary}
selection (used by
xterm,
for instance);
selection {\tt WS\_SECONDARY} is the
{\em secondary}
selection; selection {\tt WS\_CLIPBOARD} is the
{\em clipboard}
selection (used by
xclipboard).
On the Macintosh, this always returns an empty string.
\item[{\tt resetselection(i)}]
%.br
Resets selection number
{\tt i},
if this process owns it.
(See window method
{\tt setselection()}).
\item[{\tt baseline()}]
%.br
Return the baseline of the current font (defined by STDWIN as the
vertical distance between the baseline and the top of the
characters).%
\footnote{
There is no way yet to set the current font.
This will change in a future version.
}
\item[{\tt lineheight()}]
%.br
Return the total line height of the current font.
\item[{\tt textbreak(str, width)}]
%.br
Return the number of characters of the string that fit into a space of
{\tt width}
bits wide when drawn in the curent font.
\item[{\tt textwidth(str)}]
%.br
Return the width in bits of the string when drawn in the current font.
\subsubsection{Window Object Methods}
\end{description}

Window objects are created by
{\tt stdwin.open()}.
There is no explicit function to close a window; windows are closed when
they are garbage-collected.
Window objects have the following methods:
\begin{description}
\item[{\tt begindrawing()}]
Returns a drawing object, whose methods (described below) allow drawing
in the window.
\item[{\tt change(rect)}]
Invalidates the given rectangle; this may cause a draw event.
\item[{\tt gettitle()}]
Returns the window's title string.
\item[{\tt getdocsize()}]
Returns a pair of integers giving the size of the document as set by
{\tt setdocsize()}.
\item[{\tt getorigin()}]
Returns a pair of integers giving the origin of the window with respect
to the document.
\item[{\tt getwinsize()}]
Returns a pair of integers giving the size of the window.
\item[{\tt menucreate(title)}]
Creates a menu object referring to a local menu (a menu that appears
only in this window).
Methods menu objects are described below.
\item[{\tt scroll(rect,~point)}]
Scrolls the given rectangle by the vector given by the point.
\item[{\tt setwincursor(name)}]
Sets the window cursor to a cursor of the given name.
It raises the
{\tt Runtime\-Error}
exception if no cursor of the given name exists.
Suitable names are
{\tt 'ibeam'},
{\tt 'arrow'},
{\tt 'cross'},
{\tt 'watch'}
and
{\tt 'plus'}.
On X11, there are many more (see
{\tt <X11/cursorfont.h>}).
\item[{\tt setdocsize(point)}]
Sets the size of the drawing document.
\item[{\tt setorigin(point)}]
Moves the origin of the window to the given point in the document.
\item[{\tt setselection(i, str)}]
Attempts to set X11 selection number
{\tt i}
to the string
{\tt str}.
(See stdwin method
{\tt getselection()}
for the meaning of
{\tt i}.)
Returns true if it succeeds.
If it succeeds, the window ``owns'' the selection until
(a) another applications takes ownership of the selection; or
(b) the window is deleted; or
(c) the application clears ownership by calling
{\tt stdwin.resetselection(i)}.
When another application takes ownership of the selection, a
{\tt WE\_LOST\_SEL}
event is received for no particular window and with the selection number
as detail.
Ignored on the Macintosh.
\item[{\tt settitle(title)}]
Sets the window's title string.
\item[{\tt settimer(dsecs)}]
Schedules a timer event for the window in
{\tt dsecs/10}
seconds.
\item[{\tt show(rect)}]
Tries to ensure that the given rectangle of the document is visible in
the window.
\item[{\tt textcreate(rect)}]
Creates a text-edit object in the document at the given rectangle.
Methods of text-edit objects are described below.
\end{description}

\subsubsection{Drawing Object Methods}

Drawing objects are created exclusively by the window method
{\tt begindrawing()}.
Only one drawing object can exist at any given time; the drawing object
must be deleted to finish drawing.
No drawing object may exist when
{\tt stdwin.getevent()}
is called.
Drawing objects have the following methods:
\begin{description}
\item[{\tt box(rect)}]
Draws a box around a rectangle.
\item[{\tt circle(center, radius)}]
%.br
Draws a circle with given center point and radius.
\item[{\tt elarc(center, (rh, rv), (a1, a2))}]
%.br
Draws an elliptical arc with given center point.
{\tt (rh, rv)}
gives the half sizes of the horizontal and vertical radii.
{\tt (a1, a2)}
gives the angles (in degrees) of the begin and end points.
0 degrees is at 3 o'clock, 90 degrees is at 12 o'clock.
\item[{\tt erase(rect)}]
Erases a rectangle.
\item[{\tt invert(rect)}]
Inverts a rectangle.
\item[{\tt line(p1, p2)}]
Draws a line from point
{\tt p1}
to
{\tt p2}.
\item[{\tt paint(rect)}]
Fills a rectangle.
\item[{\tt text(p, str)}]
Draws a string starting at point p (the point specifies the
top left coordinate of the string).
\item[{\tt shade(rect, percent)}]
%.br
Fills a rectangle with a shading pattern that is about
{\tt percent}
percent filled.
\item[{\tt xorline(p1, p2)}]
Draws a line in XOR mode.
\item[{\tt baseline(), lineheight(), textbreak(), textwidth()}]
%.br
These functions are similar to the corresponding functions described
above for the
{\tt stdwin}
module, but use the current font of the window instead of the (global)
default font.
\end{description}

\subsubsection{Menu Object Methods}

A menu object represents a menu.
The menu is destroyed when the menu object is deleted.
The following methods are defined:
\begin{description}
\item[{\tt additem(text, shortcut)}]
%.br
Adds a menu item with given text.
The shortcut must be a string of length 1, or omitted (to specify no
shortcut).
\item[{\tt setitem(i, text)}]
Sets the text of item number
{\tt i}.
\item[{\tt enable(i, flag)}]
Enables or disables item
{\tt i}.
\item[{\tt check(i, flag)}]
Sets or clears the
{\em check mark}
for item
{\tt i}.
\end{description}

\subsubsection{Text-edit Object Methods}

A text-edit object represents a text-edit block.
For semantics, see the STDWIN documentation for C programmers.
The following methods exist:
\begin{description}
\item[{\tt arrow(code)}]
Passes an arrow event to the text-edit block.
The
{\tt code}
must be one of
{\tt WC\_LEFT},
{\tt WC\_RIGHT},
{\tt WC\_UP}
or
{\tt WC\_DOWN}
(see module
{\tt stdwinevents}).
\item[{\tt draw(rect)}]
Passes a draw event to the text-edit block.
The rectangle specifies the redraw area.
\item[{\tt event(type, window, detail)}]
%.br
Passes an event gotten from
{\tt stdwin.getevent()}
to the text-edit block.
Returns true if the event was handled.
\item[{\tt getfocus()}]
Returns 2 integers representing the start and end positions of the
focus, usable as slice indices on the string returned by
{\tt getfocustext()}.
\item[{\tt getfocustext()}]
Returns the text in the focus.
\item[{\tt getrect()}]
Returns a rectangle giving the actual position of the text-edit block.
(The bottom coordinate may differ from the initial position because
the block automatically shrinks or grows to fit.)
\item[{\tt gettext()}]
Returns the entire text buffer.
\item[{\tt move(rect)}]
Specifies a new position for the text-edit block in the document.
\item[{\tt replace(str)}]
Replaces the focus by the given string.
The new focus is an insert point at the end of the string.
\item[{\tt setfocus(i,~j)}]
Specifies the new focus.
Out-of-bounds values are silently clipped.
\end{description}

\subsection{Built-in Module {\tt 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
{\tt amoeba.error = 'amoeba.error'}.
The module
{\tt amoeba}
defines the following items:
\begin{description}
\item[{\tt name\_append(path,~cap)}]
%.br
Stores a capability in the Amoeba directory tree.
Arguments are the pathname (a string) and the capability (a capability
object as returned by
{\tt name\_lookup()}).
\item[{\tt name\_delete(path)}]
%.br
Deletes a capability from the Amoeba directory tree.
Argument is the pathname.
\item[{\tt name\_lookup(path)}]
%.br
Looks up a capability.
Argument is the pathname.
Returns a
{\em capability}
object, to which various interesting operations apply, described below.
\item[{\tt name\_replace(path,~cap)}]
%.br
Replaces a capability in the Amoeba directory tree.
Arguments are the pathname and the new capability.
(This differs from
{\tt name\_append()}
in the behavior when the pathname already exists:
{\tt name\_append()}
finds this an error while
{\tt name\_replace()}
allows it, as its name suggests.)
\item[{\tt 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,
{\tt amoeba.capv['ROOT']}
is the capability of your root directory, similar to
{\tt getcap("ROOT")}
in C.
\item[{\tt error = 'amoeba.error'}]
%.br
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
{\tt err\_why()}.
\item[{\tt timeout(msecs)}]
%.br
Sets the transaction timeout, in milliseconds.
Returns the previous timeout.
Initially, the timeout is set to 2 seconds by the {\Python} interpreter.
\end{description}

\subsubsection{Capability Operations}

Capabilities are written in a convenient ASCII format, also used by the
Amoeba utilities
{\em c2a}(U)
and
{\em a2c}(U).
For example:
\begin{code}\begin{verbatim}
>>> amoeba.name_lookup('/profile/cap')
aa:1c:95:52:6a:fa/14(ff)/8e:ba:5b:8:11:1a
>>> 
\end{verbatim}\end{code}
The following methods are defined for capability objects.
\begin{description}
\item[{\tt dir\_list()}]
Returns a list of the names of the entries in an Amoeba directory.
\item[{\tt b\_read(offset, maxsize)}]
%.br
Reads (at most)
{\tt maxsize}
bytes from a bullet file at offset
{\tt offset.}
The data is returned as a string.
EOF is reported as an empty string.
\item[{\tt b\_size()}]
Returns the size of a bullet file.
\item[{\tt dir\_append(), dir\_delete(), dir\_lookup(), dir\_replace()}]
%.br
Like the corresponding
{\tt 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.)
\item[{\tt std\_info()}]
Returns the standard info string of the object.
\item[{\tt tod\_gettime()}]
Returns the time (in seconds since the Epoch, in UCT, as for POSIX) from
a time server.
\item[{\tt tod\_settime(t)}]
Sets the time kept by a time server.
\end{description}

\subsection{Built-in Module {\tt audio}}

This module provides rudimentary access to the audio I/O device
{\tt /dev/audio}
on the Silicon Graphics Personal IRIS; see audio(7).
It supports the following operations:
\begin{description}
\item[{\tt setoutgain(n)}]
Sets the output gain (0-255).
\item[{\tt getoutgain()}]
Returns the output gain.
\item[{\tt setrate(n)}]
Sets the sampling rate: 1=32K/sec, 2=16K/sec, 3=8K/sec.
\item[{\tt setduration(n)}]
Sets the `sound duration' in units of 1/100 seconds.
\item[{\tt read(n)}]
Reads a chunk of
{\tt n}
sampled bytes from the audio input (line in or microphone).
The chunk is returned as a string of length n.
Each byte encodes one sample as a signed 8-bit quantity using linear
encoding.
This string can be converted to numbers using {\tt chr2num()} described
below.
\item[{\tt write(buf)}]
Writes a chunk of samples to the audio output (speaker).
\end{description}

These operations support asynchronous audio I/O:
\begin{description}
\item[{\tt start\_recording(n)}]
%.br
Starts a second thread (a process with shared memory) that begins reading
{\tt n}
bytes from the audio device.
The main thread immediately continues.
\item[{\tt wait\_recording()}]
%.br
Waits for the second thread to finish and returns the data read.
\item[{\tt stop\_recording()}]
%.br
Makes the second thread stop reading as soon as possible.
Returns the data read so far.
\item[{\tt poll\_recording()}]
%.br
Returns true if the second thread has finished reading (so
{\tt wait\_recording()} would return the data without delay).
\item[{\tt start\_playing(chunk)}, {\tt wait\_playing()},
{\tt stop\_playing()}, {\tt poll\_playing()}]
%.br
Similar but for output.
{\tt stop\_playing()}
returns a lower bound for the number of bytes actually played (not very
accurate).
\end{description}

The following operations do not affect the audio device but are
implemented in C for efficiency:
\begin{description}
\item[{\tt amplify(buf, f1, f2)}]
%.br
Amplifies a chunk of samples by a variable factor changing from
{\tt f1}/256 to {\tt f2}/256.
Negative factors are allowed.
Resulting values that are to large to fit in a byte are clipped.         
\item[{\tt reverse(buf)}]
%.br
Returns a chunk of samples backwards.
\item[{\tt add(buf1, buf2)}]
%.br
Bytewise adds two chunks of samples.
Bytes that exceed the range are clipped.
If one buffer shorter, it is assumed to be padded with zeros.
\item[{\tt chr2num(buf)}]
%.br
Converts a string of sampled bytes as returned by {\tt read()} into
a list containing the numeric values of the samples.
\item[{\tt num2chr(list)}]
%.br
Converts a list as returned by
{\tt chr2num()}
back to a buffer acceptable by
{\tt write()}.
\end{description}

\subsection{Built-in Module {\tt gl}}

This module provides access to the Silicon Graphics
{\em Graphics Library}.
It is available only on Silicon Graphics machines.

{\bf 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
All string and character arguments are represented by {\Python} strings,
e.g.,
{\tt winopen('Hi~There!')}
and
{\tt rotate(900,~'z')}.
\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
\begin{code}\begin{verbatim}
lmdef(deftype, index, np, props)
\end{verbatim}\end{code}
is translated to {\Python} as
\begin{code}\begin{verbatim}
lmdef(deftype, index, props)
\end{verbatim}\end{code}
\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
\begin{code}\begin{verbatim}
getmcolor(i, &red, &green, &blue)
\end{verbatim}\end{code}
is translated to {\Python} as
\begin{code}\begin{verbatim}
red, green, blue = getmcolor(i)
\end{verbatim}\end{code}
\end{itemize}

The following functions are non-standard or have special argument
conventions:
\begin{description}
\item[{\tt varray()}]
Equivalent to but faster than a number of
{\tt v3d()}
calls.
The argument is a list (or tuple) of points.
Each point must be a tuple of coordinates (x, y, z) or (x, 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 z=0.0 if necessary (as indicated in the man page),
and for each point
{\tt v3d()}
is called.
\item[{\tt nvarray()}]
Equivalent to but faster than a number of
{\tt n3f}
and
{\tt 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 (x, y, z).
Three coordinates must be given.
Float and int values may be mixed.
For each pair,
{\tt n3f()}
is called for the normal, and then
{\tt v3f()}
is called for the point.
\item[{\tt vnarray()}]
Similar to 
{\tt nvarray()}
but the pairs have the point first and the normal second.
\item[{\tt nurbssurface(s\_k[], t\_k[], ctl[][], s\_ord, t\_ord, type)}]
%.br
Defines a nurbs surface.
The dimensions of
{\tt ctl[][]}
are computed as follows:
{\tt [len(s\_k)~-~s\_ord]},
{\tt [len(t\_k)~-~t\_ord]}.
\item[{\tt nurbscurve(knots, ctlpoints, order, type)}]
%.br
Defines a nurbs curve.
The length of ctlpoints is
{\tt len(knots)~-~order}.
\item[{\tt pwlcurve(points, type)}]
%.br
Defines a piecewise-linear curve.
{\tt points}
is a list of points.
{\tt type}
must be
{\tt N\_ST}.
\item[{\tt pick(n), select(n)}]
%.br
The only argument to these functions specifies the desired size of the
pick or select buffer.
\item[{\tt endpick(), endselect()}]
%.br
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{description}

Here is a tiny but complete example GL program in {\Python}:
\begin{code}\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}\end{code}

\subsection{Built-in Module {\tt pnl}}

This module provides access to the
{\em Panel Library}
built by NASA Ames (write to
{\tt panel-request@nas.nasa.gov}
to get it).
All access to it should be done through the standard module
{\tt panel},
which transparantly exports most functions from
{\tt pnl}
but redefines
{\tt pnl.dopanel()}.

{\bf Warning:}
the {\Python} interpreter will dump core if you don't create a GL window
before calling
{\tt pnl.mkpanel()}.

The module is too large to document here in its entirety.

\section{Standard Modules}

The following standard modules are defined.
They are available in one of the directories in the default module
search path (try printing
{\tt sys.path}
to find out the default search path.)

\subsection{Standard Module {\tt string}}

This module defines some constants useful for checking character
classes, some exceptions, and some useful string functions.
The constants are:
\begin{description}
\item[{\tt digits}]
The string
{\tt '0123456789'}.
\item[{\tt hexdigits}]
The string
{\tt '0123456789abcdefABCDEF'}.
\item[{\tt letters}]
The concatenation of the strings
{\tt lowercase}
and
{\tt uppercase}
described below.
\item[{\tt lowercase}]
The string
{\tt 'abcdefghijklmnopqrstuvwxyz'}.
\item[{\tt octdigits}]
The string
{\tt '01234567'}.
\item[{\tt uppercase}]
The string
{\tt 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}.
\item[{\tt whitespace}]
A string containing all characters that are considered whitespace,
i.e.,
space, tab and newline.
This definition is used by
{\tt split()}
and
{\tt strip()}.
\end{description}

The exceptions are:
\begin{description}
\item[{\tt atoi\_error = 'non-numeric argument to string.atoi'}]
%.br
Exception raised by
{\tt atoi}
when a non-numeric string argument is detected.
The exception argument is the offending string.
\item[{\tt index\_error = 'substring not found in string.index'}]
%.br
Exception raised by
{\tt index}
when
{\tt sub}
is not found.
The argument are the offending arguments to index: {\tt (s, sub)}.
\end{description}

The functions are:
\begin{description}
\item[{\tt atoi(s)}]
Converts a string to a number.
The string must consist of one or more digits, optionally preceded by a
sign ({\tt '+'} or {\tt '-'}).
\item[{\tt index(s, sub)}]
Returns the lowest index in
{\tt s}
where the substring
{\tt sub}
is found.
\item[{\tt lower(s)}]
Convert letters to lower case.
\item[{\tt split(s)}]
Returns a list of the whitespace-delimited words of the string
{\tt s}.
\item[{\tt splitfields(s, sep)}]
%.br
Returns a list containing the fields of the string
{\tt s},
using the string
{\tt sep}
as a separator.
The list will have one more items than the number of non-overlapping
occurrences of the separator in the string.
Thus,
{\tt string.splitfields(s, ' ')}
is not the same as
{\tt string.split(s)},
as the latter only returns non-empty words.
\item[{\tt strip(s)}]
Removes leading and trailing whitespace from the string
{\tt s}.
\item[{\tt swapcase(s)}]
Converts lower case letters to upper case and vice versa.
\item[{\tt upper(s)}]
Convert letters to upper case.
\item[{\tt ljust(s, width), rjust(s, width),  center(s, width)}]
%.br
These functions respectively left-justify, right-justify and center a
string in a field of given width.
They return a string that is at least
{\tt width}
characters wide, created by padding the string
{\tt s}
with spaces until the given width on the right, left or both sides.
The string is never truncated.
\end{description}

\subsection{Standard Module {\tt path}}

This module implements some useful functions on POSIX pathnames.
\begin{description}
\item[{\tt basename(p)}]
Returns the base name of pathname
{\tt p}.
This is the second half of the pair returned by
{\tt path.split(p)}.
\item[{\tt cat(p, q)}]
Performs intelligent pathname concatenation on paths
{\tt p}
and
{\tt q}:
If
{\tt q}
is an absolute path, the return value is
{\tt q}.
Otherwise, the concatenation of
{\tt p}
and
{\tt q}
is returned, with a slash ({\tt '/'}) inserted unless
{\tt p}
is empty or ends in a slash.
\item[{\tt commonprefix(list)}]
%.br
Returns the longest string that is a prefix of all strings in
{\tt list}.
If
{\tt list}
is empty, the empty string ({\tt ''}) is returned.
\item[{\tt exists(p)}]
Returns true if
{\tt p}
refers to an existing path.
\item[{\tt isdir(p)}]
Returns true if
{\tt p}
refers to an existing directory.
\item[{\tt islink(p)}]
Returns true if
{\tt p}
refers to a directory entry that is a symbolic link.
Always false if symbolic links are not supported.
\item[{\tt ismount(p)}]
Returns true if
{\tt p}
is an absolute path that occurs in the mount table as output by the
{\tt /etc/mount}
utility.
This output is read once when the function is used for the first
time.%
\footnote{
Is there a better way to check for mount points?
}
\item[{\tt split(p)}]
Returns a pair
{\tt (head,~tail)}
such that
{\tt tail}
contains no slashes and
{\tt path.cat(head, tail)}
is equal to
{\tt p}.
\item[{\tt walk(p, visit, arg)}]
%.br
Calls the function
{\tt visit}
with arguments
{\tt (arg, dirname, names)}
for each directory in the directory tree rooted at
{\tt p}
(including
{\tt p}
itself, if it is a directory).
The argument
{\tt dirname}
specifies the visited directory, the argument
{\tt names}
lists the files in the directory (gotten from
{\tt posix.listdir(dirname)}).
The
{\tt visit}
function may modify
{\tt names}
to influence the set of directories visited below
{\tt dirname},
e.g.,
to avoid visiting certain parts of the tree.
(The object referred to by
{\tt names}
must be modified in place, using
{\tt del}
or slice assignment.)
\end{description}

\subsection{Standard Module {\tt getopt}}

This module helps scripts to parse the command line arguments in
{\tt sys.argv}.
It uses the same conventions as the {\UNIX}
{\tt getopt()}
function.
It defines the function
{\tt getopt.getopt(args, options)}
and the exception
{\tt getopt.error}.

The first argument to
{\tt getopt()}
is the argument list passed to the script with its first element
chopped off (i.e.,
{\tt 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}
{\tt 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.,
{\tt '-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:
\begin{code}\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}\end{code}
The exception
{\tt 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.

\subsection{Standard Module {\tt rand}}

This module implements a pseudo-random number generator similar to
{\tt rand()}
in C.
It defines the following functions:
\begin{description}
\item[{\tt rand()}]
Returns an integer random number in the range [0 ... 32768).
\item[{\tt choice(s)}]
Returns a random element from the sequence (string, tuple or list)
{\tt s.}
\item[{\tt srand(seed)}]
Initializes the random number generator with the given integral seed.
When the module is first imported, the random number is initialized with
the current time.
\end{description}

\subsection{Standard Module {\tt whrandom}}

This module implements a Wichmann-Hill pseudo-random number generator.
It defines the following functions:
\begin{description}
\item[{\tt random()}]
Returns the next random floating point number in the range [0.0 ... 1.0).
\item[{\tt seed(x, y, z)}]
Initializes the random number generator from the integers
{\tt x},
{\tt y}
and
{\tt z}.
When the module is first imported, the random number is initialized
using values derived from the current time.
\end{description}

\subsection{Standard Module {\tt stdwinevents}}

This module defines constants used by STDWIN for event types
({\tt WE\_ACTIVATE} etc.), command codes ({\tt WC\_LEFT} etc.)
and selection types ({\tt WS\_PRIMARY} etc.).
Read the file for details.
Suggested usage is
\begin{code}\begin{verbatim}
>>> from stdwinevents import *
>>> 
\end{verbatim}\end{code}

\subsection{Standard Module {\tt rect}}

This module contains useful operations on rectangles.
A rectangle is defined as in module
{\tt stdwin}:
a pair of points, where a point is a pair of integers.
For example, the rectangle
\begin{code}\begin{verbatim}
(10, 20), (90, 80)
\end{verbatim}\end{code}
is a rectangle whose left, top, right and bottom edges are 10, 20, 90
and 80, respectively.
Note that the positive vertical axis points down (as in
{\tt stdwin}).

The module defines the following objects:
\begin{description}
\item[{\tt error = 'rect.error'}]
%.br
The exception raised by functions in this module when they detect an
error.
The exception argument is a string describing the problem in more
detail.
\item[{\tt empty}]
%.br
The rectangle returned when some operations return an empty result.
This makes it possible to quickly check whether a result is empty:
\begin{code}\begin{verbatim}
>>> import rect
>>> r1 = (10, 20), (90, 80)
>>> r2 = (0, 0), (10, 20)
>>> r3 = rect.intersect(r1, r2)
>>> if r3 is rect.empty: print 'Empty intersection'
Empty intersection
>>> 
\end{verbatim}\end{code}
\item[{\tt is\_empty(r)}]
%.br
Returns true if the given rectangle is empty.
A rectangle
{\em (left,~top), (right,~bottom)}
is empty if
{\em left~$\geq$~right}
or
{\em top~$\leq$~bottom}.
\item[{\tt intersect(list)}]
%.br
Returns the intersection of all rectangles in the list argument.
It may also be called with a tuple argument or with two or more
rectangles as arguments.
Raises
{\tt rect.error}
if the list is empty.
Returns
{\tt rect.empty}
if the intersection of the rectangles is empty.
\item[{\tt union(list)}]
%.br
Returns the smallest rectangle that contains all non-empty rectangles in
the list argument.
It may also be called with a tuple argument or with two or more
rectangles as arguments.
Returns
{\tt rect.empty}
if the list is empty or all its rectangles are empty.
\item[{\tt pointinrect(point, rect)}]
%.br
Returns true if the point is inside the rectangle.
By definition, a point
{\em (h,~v)}
is inside a rectangle
{\em (left,~top),}
{\em (right,~bottom)}
if
{\em left~$\leq$~h~$<$~right}
and
{\em top~$\leq$~v~$<$~bottom}.
\item[{\tt inset(rect, (dh, dv))}]
%.br
Returns a rectangle that lies inside the
{\tt rect}
argument by
{\tt dh}
pixels horizontally
and
{\tt dv}
pixels
vertically.
If
{\tt dh}
or
{\tt dv}
is negative, the result lies outside
{\tt rect}.
\item[{\tt rect2geom(rect)}]
%.br
Converts a rectangle to geometry representation:
{\em (left,~top),}
{\em (width,~height)}.
\item[{\tt geom2rect(geom)}]
%.br
Converts a rectangle given in geometry representation back to the
standard rectangle representation
{\em (left,~top),}
{\em (right,~bottom)}.
\end{description}

\subsection{Standard Modules {\tt GL} and {\tt DEVICE}}

These modules define the constants used by the Silicon Graphics
{\em Graphics Library}
that C programmers find in the header files
{\tt <gl/gl.h>}
and
{\tt <gl/device.h>}.
Read the module files for details.

\subsection{Standard Module {\tt panel}}

This module should be used instead of the built-in module
{\tt pnl}
to interface with the
{\em Panel Library}.

The module is too large to document here in its entirety.
One interesting function:
\begin{description}
\item[{\tt defpanellist(filename)}]
%.br
Parses a panel description file containing S-expressions written by the
{\em Panel Editor}
that accompanies the Panel Library and creates the described panels.
It returns a list of panel objects.
\end{description}

{\bf Warning:}
the {\Python} interpreter will dump core if you don't create a GL window
before calling
{\tt panel.mkpanel()}
or
{\tt panel.defpanellist()}.

\subsection{Standard Module {\tt parser}}

This module defines a self-contained parser for S-expressions as output
by the Panel Editor (which is written in Scheme so it can't help writing
S-expressions).
The relevant function is
{\tt parser.parse\_file(file)}
which has a file object (not a filename!) as argument and returns a list
of parsed S-expressions.
Each S-expression is converted into a {\Python} list, with atoms converted
to {\Python} strings and sub-expressions (recursively) to {\Python} lists.
For more details, read the module file.

\subsection{P.M.}

\begin{verse}
commands

cmp?

*cache?

localtime?

calendar?

\_\_dict?
\end{verse}

\end{document}