diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/lib.tex | 2015 | ||||
| -rw-r--r-- | Doc/lib/lib.tex | 2015 | ||||
| -rw-r--r-- | Doc/myformat.sty | 24 |
3 files changed, 4054 insertions, 0 deletions
diff --git a/Doc/lib.tex b/Doc/lib.tex new file mode 100644 index 0000000..b12e6e1 --- /dev/null +++ b/Doc/lib.tex @@ -0,0 +1,2015 @@ +% 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} diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex new file mode 100644 index 0000000..b12e6e1 --- /dev/null +++ b/Doc/lib/lib.tex @@ -0,0 +1,2015 @@ +% 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} diff --git a/Doc/myformat.sty b/Doc/myformat.sty new file mode 100644 index 0000000..623316e --- /dev/null +++ b/Doc/myformat.sty @@ -0,0 +1,24 @@ +% Style parameters and macros used by all documents here + +% Page lay-out parameters +\textwidth = 150mm +\textheight = 240mm +\topmargin = -11mm +\oddsidemargin = 5mm +\evensidemargin = 5mm + +% Macros for e.g. and E.g. if you want them italicized: +% \newcommand{\eg}{{\it e.g.}} +% \newcommand{\Eg}{{\it E.g.}} +% If you don't want them italicized: +\newcommand{\eg}{e.g.} +\newcommand{\Eg}{E.g.} + +% Frequently used system names +\newcommand{\Python}{Python} +\newcommand{\UNIX}{U{\sc nix}} + +% Code environment (use together with verbatim!) +\newenvironment{code}% +{\nopagebreak\begin{list}{\nopagebreak}{\nopagebreak}\nopagebreak}% +{\nopagebreak\end{list}\nopagebreak} |