mirror of
https://github.com/python/cpython.git
synced 2024-12-14 04:17:19 +08:00
d38b7648c0
Small lay-out improvements.
2031 lines
57 KiB
TeX
2031 lines
57 KiB
TeX
% Format this file with latex.
|
|
|
|
%\documentstyle[palatino,11pt,myformat]{article}
|
|
\documentstyle[11pt,myformat]{article}
|
|
|
|
% A command to force the text after an item to start on a new line
|
|
\newcommand{\itembreak}{
|
|
\mbox{}\\*[0mm]
|
|
}
|
|
|
|
\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:
|
|
\bcode\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}\ecode
|
|
\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:
|
|
\bcode\begin{verbatim}
|
|
>>> import sys
|
|
>>> dir()
|
|
['sys']
|
|
>>> dir(sys)
|
|
['argv', 'exit', 'modules', 'path', 'stderr', 'stdin', 'stdout']
|
|
>>>
|
|
\end{verbatim}\ecode
|
|
\item[{\tt divmod(a, b)}]
|
|
%.br
|
|
Takes two integers as arguments and returns a pair of integers
|
|
consisting of their quotient and remainder.
|
|
For
|
|
\bcode\begin{verbatim}
|
|
q, r = divmod(a, b)
|
|
\end{verbatim}\ecode
|
|
the invariants are:
|
|
\bcode\begin{verbatim}
|
|
a = q*b + r
|
|
abs(r) < abs(b)
|
|
r has the same sign as b
|
|
\end{verbatim}\ecode
|
|
For example:
|
|
\bcode\begin{verbatim}
|
|
>>> divmod(100, 7)
|
|
(14, 2)
|
|
>>> divmod(-100, 7)
|
|
(-15, 5)
|
|
>>> divmod(100, -7)
|
|
(-15, -5)
|
|
>>> divmod(-100, -7)
|
|
(14, -2)
|
|
>>>
|
|
\end{verbatim}\ecode
|
|
\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:
|
|
\bcode\begin{verbatim}
|
|
>>> x = 1
|
|
>>> eval('x+1')
|
|
2
|
|
>>>
|
|
\end{verbatim}\ecode
|
|
\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:
|
|
\bcode\begin{verbatim}
|
|
>>> x = 1
|
|
>>> exec('x = x+1\n')
|
|
>>> x
|
|
2
|
|
>>>
|
|
\end{verbatim}\ecode
|
|
\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:
|
|
\bcode\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}\ecode
|
|
\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:
|
|
\bcode\begin{verbatim}
|
|
>>> raw_input('Type anything: ')
|
|
Type anything: Teenage Mutant Ninja Turtles
|
|
'Teenage Mutant Ninja Turtles'
|
|
>>>
|
|
\end{verbatim}\ecode
|
|
\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.
|
|
\end{description}
|
|
|
|
\subsubsection{Window Object Methods}
|
|
|
|
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()}]
|
|
\begin{sloppypar}
|
|
Returns a pair of integers giving the size of the document as set by
|
|
{\tt setdocsize()}.
|
|
\end{sloppypar}
|
|
\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)}]
|
|
\begin{sloppypar}
|
|
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>}).
|
|
\end{sloppypar}
|
|
\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:
|
|
\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.
|
|
\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
|
|
\itembreak
|
|
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
|
|
\begin{sloppypar}
|
|
Similar but for output.
|
|
{\tt stop\_playing()}
|
|
returns a lower bound for the number of bytes actually played (not very
|
|
accurate).
|
|
\end{sloppypar}
|
|
\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
|
|
\begin{sloppypar}
|
|
Converts a list as returned by
|
|
{\tt chr2num()}
|
|
back to a buffer acceptable by
|
|
{\tt write()}.
|
|
\end{sloppypar}
|
|
\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
|
|
\begin{sloppypar}
|
|
All string and character arguments are represented by {\Python} strings,
|
|
for instance,
|
|
{\tt winopen('Hi~There!')}
|
|
and
|
|
{\tt 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:
|
|
\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
|
|
\itembreak
|
|
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}:
|
|
\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
|
|
|
|
\subsection{Built-in Module {\tt pnl}}
|
|
|
|
This module provides access to the
|
|
{\em Panel Library}
|
|
built by NASA Ames (to get it, send e-mail to
|
|
{\tt panel-request@nas.nasa.gov}).
|
|
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:
|
|
\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
|
|
{\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
|
|
\bcode\begin{verbatim}
|
|
>>> from stdwinevents import *
|
|
>>>
|
|
\end{verbatim}\ecode
|
|
|
|
\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
|
|
\bcode\begin{verbatim}
|
|
(10, 20), (90, 80)
|
|
\end{verbatim}\ecode
|
|
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:
|
|
\bcode\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}\ecode
|
|
\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 panelparser}}
|
|
|
|
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 panelparser.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}
|