diff options
| -rw-r--r-- | Doc/lib.tex | 2092 | ||||
| -rw-r--r-- | Doc/lib/lib.tex | 2092 |
2 files changed, 6 insertions, 4178 deletions
diff --git a/Doc/lib.tex b/Doc/lib.tex index 8e36427..f0b649a 100644 --- a/Doc/lib.tex +++ b/Doc/lib.tex @@ -55,2094 +55,8 @@ gives a more formal reference to the language. \pagenumbering{arabic} -\section{Introduction} - -The {\Python} library consists of three parts, with different levels of -integration with the interpreter. -Closest to the interpreter are built-in types, exceptions and functions. -Next are built-in modules, which are written in C and linked statically -with the interpreter. -Finally there are standard modules that are implemented entirely in -{\Python}, but are always available. -For efficiency, some standard modules may become built-in modules in -future versions of the interpreter. - -\section{Built-in Types, Exceptions and Functions} - -Names for built-in exceptions and functions are found in a separate -read-only symbol table which cannot be modified. -This table is searched last, so local and global user-defined names can -override built-in names. -Built-in types have no names but are created by syntactic constructs -(such as constants) or built-in functions. -They are described together here for easy reference.% -\footnote{ -The descriptions sorely lack explanations of the exceptions that -may be raised---this will be fixed in a future version of this -document. -} - -\subsection{Built-in Types} - -The following sections describe the standard types that are built into the -interpreter. -\subsubsection{Numeric Types} - -There are two numeric types: integers and floating point numbers. -Integers are implemented using {\tt long} in C, so they have at least 32 -bits of precision. -Floating point numbers are implemented using {\tt double} in C. -All bets on precision are off. -Numbers are created by numeric constants or as the result of built-in -functions and operators. - -Numeric types support the following operations: - -\begin{center} -\begin{tabular}{|c|l|c|} -\hline -Operation & Result & Notes \\ -\hline -{\tt abs}({\em x}) & absolute value of {\em x} & \\ -{\tt int}({\em x}) & {\em x} converted to integer & (1) \\ -{\tt float}({\em x}) & {\em x} converted to floating point & \\ -{\tt -}{\em x} & {\em x} negated & \\ -{\tt +}{\em x} & {\em x} unchanged & \\ -{\em x}{\tt +}{\em y} & sum of {\em x} and {\em y} & \\ -{\em x}{\tt -}{\em y} & difference of {\em x} and {\em y} & \\ -{\em x}{\tt *}{\em y} & product of {\em x} and {\em y} & \\ -{\em x}{\tt /}{\em y} & quotient of {\em x} and {\em y} & (2) \\ -{\em x}{\tt \%}{\em y} & remainder of {\em x}{\tt /}{\em y} & (3) \\ -\hline -\end{tabular} -\end{center} - -\noindent -Notes: -\begin{description} -\item[(1)] -This may round or truncate as in C; see functions {\tt floor} and -{\tt ceil} in module {\tt math}. -\item[(2)] -Integer division is defined as in C: the result is an integer; with -positive operands, it truncates towards zero; with a negative operand, -the result is unspecified. -\item[(3)] -Only defined for integers. -\end{description} - -Mixed arithmetic is not supported; both operands must have the same type. -Mixed comparisons return the wrong result (floats always compare smaller -than integers).% -\footnote{ -These restrictions are bugs in the language definitions and will be -fixed in the future. -} -\subsubsection{Sequence Types} - -There are three sequence types: strings, lists and tuples. -Strings constants are written in single quotes: {\tt 'xyzzy'}. -Lists are constructed with square brackets: {\tt [a,~b,~c]}. -Tuples are constructed by the comma operator or with an empty set of -parentheses: {\tt a,~b,~c} or {\tt ()}. - -Sequence types support the following operations ({\em s} and {\em t} are -sequences of the same type; {\em n}, {\em i} and {\em j} are integers): - -\begin{center} -\begin{tabular}{|c|l|c|} -\hline -Operation & Result & Notes \\ -\hline -{\tt len}({\em s}) & length of {\em s} & \\ -{\tt min}({\em s}) & smallest item of {\em s} & \\ -{\tt max}({\em s}) & largest item of {\em s} & \\ -{\em x} {\tt in} {\em s} & - true if an item of {\em s} is equal to {\em x} & \\ -{\em x} {\tt not} {\tt in} {\em s} & - false if an item of {\em s} is equal to {\em x} & \\ -{\em s}{\tt +}{\em t} & the concatenation of {\em s} and {\em t} & \\ -{\em s}{\tt *}{\em n}, {\em n}*{\em s} & - {\em n} copies of {\em s} concatenated & (1) \\ -{\em s}[{\em i}] & {\em i}'th item of {\em s} & \\ -{\em s}[{\em i}:{\em j}] & - slice of {\em s} from {\em i} to {\em j} & (2) \\ -\hline -\end{tabular} -\end{center} - -\noindent -Notes: -\begin{description} -\item[(1)] -Sequence repetition is only supported for strings. -\item[(2)] -The slice of $s$ from $i$ to $j$ is defined as the sequence -of items with index $k$ such that $i \leq k < j$. -Special rules apply for negative and omitted indices; see the Tutorial -or the Reference Manual. -\end{description} - -\paragraph{Mutable Sequence Types.} - -List objects support additional operations that allow in-place -modification of the object. -These operations would be supported by other mutable sequence types -(when added to the language) as well. -Strings and tuples are immutable sequence types and such objects cannot -be modified once created. -The following operations are defined on mutable sequence types (where -{\em x} is an arbitrary object): - -\begin{center} -\begin{tabular}{|c|l|} -\hline -Operation & Result \\ -\hline -{\em s}[{\em i}] = {\em x} & - item {\em i} of {\em s} is replaced by {\em x} \\ -{\em s}[{\em i}:{\em j}] = {\em t} & - slice of {\em s} from {\em i} to {\em j} is replaced by {\em t} \\ -{\tt del} {\em s}[{\em i}:{\em j}] & - same as {\em s}[{\em i}:{\em j}] = [] \\ -{\em s}.{\tt append}({\em x}) & - same as {\em s}[{\tt len}({\em x}):{\tt len}({\em x})] = [{\em x}] \\ -{\em s}.{\tt insert}({\em i}, {\em x}) & - same as {\em s}[{\em i}:{\em i}] = [{\em x}] \\ -{\em s}.{\tt sort}() & - the items of {\em s} are permuted to satisfy \\ - & - $s[i] \leq s[j]$ for $i < j$\\ -\hline -\end{tabular} -\end{center} - -\subsubsection{Mapping Types} - -A -{\em mapping} -object maps values of one type (the key type) to arbitrary objects. -Mappings are mutable objects. -There is currently only one mapping type, the -{\em dictionary}. -A dictionary's keys are strings. -An empty dictionary is created by the expression \verb"{}". -An extension of this notation is used to display dictionaries when -written (see the example below). - -The following operations are defined on mappings (where {\em a} is a -mapping, {\em k} is a key and {\em x} is an arbitrary object): - -\begin{center} -\begin{tabular}{|c|l|c|} -\hline -Operation & Result & Notes\\ -\hline -{\tt len}({\em a}) & the number of elements in {\em a} & \\ -{\em a}[{\em k}] & the item of {\em a} with key {\em k} & \\ -{\em a}[{\em k}] = {\em x} & set {\em a}[{\em k}] to {\em x} & \\ -{\tt del} {\em a}[{\em k}] & remove {\em a}[{\em k}] from {\em a} & \\ -{\em a}.{\tt keys}() & a copy of {\em a}'s list of keys & (1) \\ -{\em a}.{\tt has\_key}({\em k}) & true if {\em a} has a key {\em k} & \\ -\hline -\end{tabular} -\end{center} - -\noindent -Notes: -\begin{description} -\item[(1)] -Keys are listed in random order. -\end{description} - -A small example using a dictionary: -\bcode\begin{verbatim} ->>> tel = {} ->>> tel['jack'] = 4098 ->>> tel['sape'] = 4139 ->>> tel['guido'] = 4127 ->>> tel['jack'] -4098 ->>> tel -{'sape': 4139; 'guido': 4127; 'jack': 4098} ->>> del tel['sape'] ->>> tel['irv'] = 4127 ->>> tel -{'guido': 4127; 'irv': 4127; 'jack': 4098} ->>> tel.keys() -['guido', 'irv', 'jack'] ->>> tel.has_key('guido') -1 ->>> -\end{verbatim}\ecode -\subsubsection{Other Built-in Types} - -The interpreter supports several other kinds of objects. -Most of these support only one or two operations. - -\paragraph{Modules.} - -The only operation on a module is member acces: {\em m}{\tt .}{\em name}, -where {\em m} is a module and {\em name} accesses a name defined in -{\em m}'s symbol table. -Module members can be assigned to. - -\paragraph{Classes and Class Objects.} - -XXX Classes will be explained at length in a later version of this -document. - -\paragraph{Functions.} - -Function objects are created by function definitions. -The only operation on a function object is to call it: -{\em func}({\em optional-arguments}). - -Built-in functions have a different type than user-defined functions, -but they support the same operation. - -\paragraph{Methods.} - -Methods are functions that are called using the member acces notation. -There are two flavors: built-in methods (such as {\tt append()} on -lists) and class member methods. -Built-in methods are described with the types that support them. -XXX Class member methods will be described in a later version of this -document. - -\paragraph{Type Objects.} - -Type objects represent the various object types. -An object's type is accessed by the built-in function -{\tt type()}. -There are no operations on type objects. - -\paragraph{The Null Object.} - -This object is returned by functions that don't explicitly return a -value. -It supports no operations. -There is exactly one null object, named {\tt None} -(a built-in name). - -\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} -\funcitem{close}{} -Closes the file. -A closed file cannot be read or written anymore. -\funcitem{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.) -\funcitem{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().} -\funcitem{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} -\excitem{EOFError}{end-of-file read} -(No argument.) -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.) -\excitem{KeyboardInterrupt}{end-of-file read} -(No argument.) -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. -\excitem{MemoryError}{out of memory} -%.br -Raised when an operation runs out of memory but the situation -may still be rescued (by deleting some objects). -\excitem{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. -\excitem{RuntimeError}{run-time error} -%.br -Raised for a variety of reasons, e.g., division by zero or index out of -range. -\excitem{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. -\excitem{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} -\funcitem{abs}{x} -Returns the absolute value of a number. -The argument may be an integer or floating point number. -\funcitem{chr}{i} -Returns a string of one character -whose ASCII code is the integer {\tt i}, -e.g., {\tt chr(97)} returns the string {\tt 'a'}. -This is the inverse of {\tt ord()}. -\funcitem{dir}{} -Without arguments, this function returns the list of names in the -current local symbol table, sorted alphabetically. -With a module object as argument, it returns the sorted list of names in -that module's global symbol table. -For example: -\bcode\begin{verbatim} ->>> import sys ->>> dir() -['sys'] ->>> dir(sys) -['argv', 'exit', 'modules', 'path', 'stderr', 'stdin', 'stdout'] ->>> -\end{verbatim}\ecode -\funcitem{divmod}{a, b} -%.br -Takes two integers as arguments and returns a pair of integers -consisting of their quotient and remainder. -For -\bcode\begin{verbatim} -q, r = divmod(a, b) -\end{verbatim}\ecode -the invariants are: -\bcode\begin{verbatim} -a = q*b + r -abs(r) < abs(b) -r has the same sign as b -\end{verbatim}\ecode -For example: -\bcode\begin{verbatim} ->>> divmod(100, 7) -(14, 2) ->>> divmod(-100, 7) -(-15, 5) ->>> divmod(100, -7) -(-15, -5) ->>> divmod(-100, -7) -(14, -2) ->>> -\end{verbatim}\ecode -\funcitem{eval}{s} -Takes a string as argument and parses and evaluates it as a {\Python} -expression. -The expression is executed using the current local and global symbol -tables. -Syntax errors are reported as exceptions. -For example: -\bcode\begin{verbatim} ->>> x = 1 ->>> eval('x+1') -2 ->>> -\end{verbatim}\ecode -\funcitem{exec}{s} -Takes a string as argument and parses and evaluates it as a sequence of -{\Python} statements. -The string should end with a newline (\verb"'\n'"). -The statement is executed using the current local and global symbol -tables. -Syntax errors are reported as exceptions. -For example: -\bcode\begin{verbatim} ->>> x = 1 ->>> exec('x = x+1\n') ->>> x -2 ->>> -\end{verbatim}\ecode -\funcitem{float}{x} -Converts a number to floating point. -The argument may be an integer or floating point number. -\funcitem{input}{s} -Equivalent to -{\tt eval(raw\_input(s))}. -As for -{\tt raw\_input()}, -the argument is optional. -\funcitem{int}{x} -Converts a number to integer. -The argument may be an integer or floating point number. -\funcitem{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). -\funcitem{max}{s} -Returns the largest item of a non-empty sequence (string, tuple or list). -\funcitem{min}{s} -Returns the smallest item of a non-empty sequence (string, tuple or list). -\funcitem{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}. -} -\funcitem{ord}{c} -Takes a string of one character and returns its -ASCII value, e.g., {\tt ord('a')} returns the integer {\tt 97}. -This is the inverse of {\tt chr()}. -\funcitem{range}{} -This is a versatile function to create lists containing arithmetic -progressions of integers. -With two integer arguments, it returns the ascending sequence of -integers starting at the first and ending one before the second -argument. -A single argument is used as the end point of the sequence, with 0 used -as the starting point. -A third argument specifies the step size; negative steps are allowed and -work as expected, but don't specify a zero step. -The resulting list may be empty. -For example: -\bcode\begin{verbatim} ->>> range(10) -[0, 1, 2, 3, 4, 5, 6, 7, 8, 9] ->>> range(1, 1+10) -[1, 2, 3, 4, 5, 6, 7, 8, 9, 10] ->>> range(0, 30, 5) -[0, 5, 10, 15, 20, 25] ->>> range(0, 10, 3) -[0, 3, 6, 9] ->>> range(0, -10, -1) -[0, -1, -2, -3, -4, -5, -6, -7, -8, -9] ->>> range(0) -[] ->>> range(1, 0) -[] ->>> -\end{verbatim}\ecode -\funcitem{raw\_input}{s} -%.br -The argument is optional; if present, it is written to standard output -without a trailing newline. -The function then reads a line from input, converts it to a string -(stripping a trailing newline), and returns that. -EOF is reported as an exception. -For example: -\bcode\begin{verbatim} ->>> raw_input('Type anything: ') -Type anything: Mutant Teenage Ninja Turtles -'Mutant Teenage Ninja Turtles' ->>> -\end{verbatim}\ecode -\funcitem{reload}{module} -Causes an already imported module to be re-parsed and re-initialized. -This is useful if you have edited the module source file and want to -try out the new version without leaving {\Python}. -\funcitem{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} -\funcitem{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. -\funcitem{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!). -\funcitem{modules} -Gives the list of modules that have already been loaded. -This can be manipulated to force reloading of modules and other tricks. -\funcitem{path} -A list of strings that specifies the search path for modules. -Initialized from the environment variable {\tt PYTHONPATH}, or an -installation-dependent default. -\funcitem{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 '... '}. -\funcitem{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} -\funcitem{sleep}{secs} -Suspends execution for the given number of seconds. -\funcitem{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} -\funcitem{millisleep}{msecs} -Suspends execution for the given number of milliseconds. -\funcitem{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 regexp}} - -This module provides a regular expression matching operation. -It is always available. - -The module defines a function and an exception: - -\begin{description} - -\funcitem{compile}{pattern} - -Compile a regular expression given as a string into a regular -expression object. -The string must be an egrep-style regular expression; -this means that the characters {\tt '(' ')' '*' '+' '?' '|' '^' '$'} -are special. -(It is implemented using Henry Spencer's regular expression matching -functions.) - -excitem{error}{regexp.error} - -Exception raised when a string passed to {\tt compile()} is not a -valid regular expression (e.g., unmatched parentheses) or when some other -error occurs during compilation or matching -(``no match found'' is not an error). - -\end{description} - -Compiled regular expression objects support a single method: - -\begin{description} - -\funcitem{exec}{str} - -Find the first occurrence of the compiled regular expression in the -string {\tt str}. -The return value is a tuple of pairs specifying where a match was -found and where matches were found for subpatterns specified with -{\tt '('} and {\tt ')'} in the pattern. -If no match is found, an empty tuple is returned; otherwise the first -item of the tuple is a pair of slice indices into the search string -giving the match found. -If there were any subpatterns in the pattern, the returned tuple has an -additional item for each subpattern, giving the slice indices into the -search string where that subpattern was found. - -\end{description} - -For example: -\bcode\begin{verbatim} ->>> import regexp ->>> r = regexp.compile('--(.*)--') ->>> s = 'a--b--c' ->>> r.exec(s) -((1, 6), (3, 4)) ->>> s[1:6] # The entire match -'--b--' ->>> s[3:4] # The subpattern -'b' ->>> -\end{verbatim}\ecode - -\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} -\funcitem{chdir}{path} -Changes the current directory to -{\tt path}. -\funcitem{chmod}{path, mode} -Change the mode of -{\tt path} -to the numeric -{\tt mode}. -\funcitem{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. -\excitem{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()}. -\funcitem{getcwd}{} -Returns a string representing the current working directory. -\funcitem{link}{src, dst} -Creates a hard link pointing to -{\tt src} -named -{\tt dst}. -\funcitem{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. -\funcitem{mkdir}{path, mode} -Creates a directory named -{\tt path} -with numeric mode -{\tt mode}. -\funcitem{rename}{src, dst} -Renames the file or directory -{\tt src} -to -{\tt dst}. -\funcitem{rmdir}{path} -Removes the directory -{\tt path}. -\funcitem{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. -\funcitem{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()}. -\funcitem{umask}{mask} -Sets the current numeric umask and returns the previous umask. -\funcitem{unlink}{path} -Unlinks the file -{\tt path}. -\funcitem{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} -\funcitem{lstat}{path} -Like -{\tt stat()}, -but does not follow symbolic links. -\funcitem{readlink}{path} -Returns a string representing the path to which the symbolic link -points. -\funcitem{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} -\funcitem{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. -} -\funcitem{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}. -\funcitem{setdefwinpos}{h, v} -%.br -Sets the default window position. -\funcitem{setdefwinsize}{width, height} -%.br -Sets the default window size. -\funcitem{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. -\funcitem{fleep}{} -%.br -Causes a beep or bell (or perhaps a `visual bell' or flash, hence the -name). -\funcitem{message}{string} -%.br -Displays a dialog box containing the string. -The user must click OK before the function returns. -\funcitem{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. -\funcitem{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. -\funcitem{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. -\funcitem{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. -\funcitem{getcutbuffer}{i} -%.br -Returns the contents of the system's cut buffer number -{\tt i}. -\funcitem{rotatebutbuffers}{n} -%.br -On X11, this rotates the 8 cut buffers by -{\tt n}. -Ignored on the Macintosh. -\funcitem{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. -\funcitem{resetselection}{i} -%.br -Resets selection number -{\tt i}, -if this process owns it. -(See window method -{\tt setselection()}). -\funcitem{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. -} -\funcitem{lineheight}{} -%.br -Return the total line height of the current font. -\funcitem{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. -\funcitem{textwidth}{str} -%.br -Return the width in bits of the string when drawn in the current font. -\end{description} - -\subsubsection{Window Object Methods} - -Window objects are created by -{\tt stdwin.open()}. -There is no explicit function to close a window; windows are closed when -they are garbage-collected. -Window objects have the following methods: -\begin{description} -\funcitem{begindrawing}{} -Returns a drawing object, whose methods (described below) allow drawing -in the window. -\funcitem{change}{rect} -Invalidates the given rectangle; this may cause a draw event. -\funcitem{gettitle}{} -Returns the window's title string. -\funcitem{getdocsize}{} -\begin{sloppypar} -Returns a pair of integers giving the size of the document as set by -{\tt setdocsize()}. -\end{sloppypar} -\funcitem{getorigin}{} -Returns a pair of integers giving the origin of the window with respect -to the document. -\funcitem{getwinsize}{} -Returns a pair of integers giving the size of the window. -\funcitem{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. -\funcitem{scroll}{rect,~point} -Scrolls the given rectangle by the vector given by the point. -\funcitem{setwincursor}{name} -\begin{sloppypar} -Sets the window cursor to a cursor of the given name. -It raises the -{\tt Runtime\-Error} -exception if no cursor of the given name exists. -Suitable names are -{\tt 'ibeam'}, -{\tt 'arrow'}, -{\tt 'cross'}, -{\tt 'watch'} -and -{\tt 'plus'}. -On X11, there are many more (see -{\tt <X11/cursorfont.h>}). -\end{sloppypar} -\funcitem{setdocsize}{point} -Sets the size of the drawing document. -\funcitem{setorigin}{point} -Moves the origin of the window to the given point in the document. -\funcitem{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. -\funcitem{settitle}{title} -Sets the window's title string. -\funcitem{settimer}{dsecs} -Schedules a timer event for the window in -{\tt dsecs/10} -seconds. -\funcitem{show}{rect} -Tries to ensure that the given rectangle of the document is visible in -the window. -\funcitem{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} -\funcitem{box}{rect} -Draws a box around a rectangle. -\funcitem{circle}{center, radius} -%.br -Draws a circle with given center point and radius. -\funcitem{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. -\funcitem{erase}{rect} -Erases a rectangle. -\funcitem{invert}{rect} -Inverts a rectangle. -\funcitem{line}{p1, p2} -Draws a line from point -{\tt p1} -to -{\tt p2}. -\funcitem{paint}{rect} -Fills a rectangle. -\funcitem{text}{p, str} -Draws a string starting at point p (the point specifies the -top left coordinate of the string). -\funcitem{shade}{rect, percent} -%.br -Fills a rectangle with a shading pattern that is about -{\tt percent} -percent filled. -\funcitem{xorline}{p1, p2} -Draws a line in XOR mode. -\funcitem{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} -\funcitem{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). -\funcitem{setitem}{i, text} -Sets the text of item number -{\tt i}. -\funcitem{enable}{i, flag} -Enables or disables item -{\tt i}. -\funcitem{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} -\funcitem{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}). -\funcitem{draw}{rect} -Passes a draw event to the text-edit block. -The rectangle specifies the redraw area. -\funcitem{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. -\funcitem{getfocus}{} -Returns 2 integers representing the start and end positions of the -focus, usable as slice indices on the string returned by -{\tt getfocustext()}. -\funcitem{getfocustext}{} -Returns the text in the focus. -\funcitem{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.) -\funcitem{gettext}{} -Returns the entire text buffer. -\funcitem{move}{rect} -Specifies a new position for the text-edit block in the document. -\funcitem{replace}{str} -Replaces the focus by the given string. -The new focus is an insert point at the end of the string. -\funcitem{setfocus}{i,~j} -Specifies the new focus. -Out-of-bounds values are silently clipped. -\end{description} - -\subsubsection{Example} - -Here is a simple example of using STDWIN in Python. -It creates a window and draws the string ``Hello world'' in the top -left corner of the window. -The window will be correctly redrawn when covered and re-exposed. -The program quits when the close icon or menu item is requested. -\bcode\begin{verbatim} -import stdwin -from stdwinevents import * - -def main(): - mywin = stdwin.open('Hello') - # - while 1: - (type, win, detail) = stdwin.getevent() - if type = WE_DRAW: - draw = win.begindrawing() - draw.text((0, 0), 'Hello, world') - del draw - elif type = WE_CLOSE: - break - -main() -\end{verbatim}\ecode - -\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} -\funcitem{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()}). -\funcitem{name\_delete}{path} -%.br -Deletes a capability from the Amoeba directory tree. -Argument is the pathname. -\funcitem{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. -\funcitem{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.) -\funcitem{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. -\excitem{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()}. -\funcitem{timeout}{msecs} -%.br -Sets the transaction timeout, in milliseconds. -Returns the previous timeout. -Initially, the timeout is set to 2 seconds by the {\Python} interpreter. -\end{description} - -\subsubsection{Capability Operations} - -Capabilities are written in a convenient ASCII format, also used by the -Amoeba utilities -{\em c2a}(U) -and -{\em a2c}(U). -For example: -\bcode\begin{verbatim} ->>> amoeba.name_lookup('/profile/cap') -aa:1c:95:52:6a:fa/14(ff)/8e:ba:5b:8:11:1a ->>> -\end{verbatim}\ecode -The following methods are defined for capability objects. -\begin{description} -\funcitem{dir\_list}{} -Returns a list of the names of the entries in an Amoeba directory. -\funcitem{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. -\funcitem{b\_size}{} -Returns the size of a bullet file. -\funcitem{dir\_append(), dir\_delete(), dir\_lookup(), dir\_replace}{} -%.br -\itembreak -Like the corresponding -{\tt name\_*} -functions, but with a path relative to the capability. -(For paths beginning with a slash the capability is ignored, since this -is the defined semantics for Amoeba.) -\funcitem{std\_info}{} -Returns the standard info string of the object. -\funcitem{tod\_gettime}{} -Returns the time (in seconds since the Epoch, in UCT, as for POSIX) from -a time server. -\funcitem{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} -\funcitem{setoutgain}{n} -Sets the output gain (0-255). -\funcitem{getoutgain}{} -Returns the output gain. -\funcitem{setrate}{n} -Sets the sampling rate: 1=32K/sec, 2=16K/sec, 3=8K/sec. -\funcitem{setduration}{n} -Sets the `sound duration' in units of 1/100 seconds. -\funcitem{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. -\funcitem{write}{buf} -Writes a chunk of samples to the audio output (speaker). -\end{description} - -These operations support asynchronous audio I/O: -\begin{description} -\funcitem{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. -\funcitem{wait\_recording}{} -%.br -Waits for the second thread to finish and returns the data read. -\funcitem{stop\_recording}{} -%.br -Makes the second thread stop reading as soon as possible. -Returns the data read so far. -\funcitem{poll\_recording}{} -%.br -Returns true if the second thread has finished reading (so -{\tt wait\_recording()} would return the data without delay). -\item[{\tt start\_playing(chunk)}, {\tt wait\_playing()}, -{\tt stop\_playing()}, {\tt poll\_playing()}] -%.br -\begin{sloppypar} -Similar but for output. -{\tt stop\_playing()} -returns a lower bound for the number of bytes actually played (not very -accurate). -\end{sloppypar} -\end{description} - -The following operations do not affect the audio device but are -implemented in C for efficiency: -\begin{description} -\funcitem{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. -\funcitem{reverse}{buf} -%.br -Returns a chunk of samples backwards. -\funcitem{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. -\funcitem{chr2num}{buf} -%.br -Converts a string of sampled bytes as returned by {\tt read()} into -a list containing the numeric values of the samples. -\funcitem{num2chr}{list} -%.br -\begin{sloppypar} -Converts a list as returned by -{\tt chr2num()} -back to a buffer acceptable by -{\tt write()}. -\end{sloppypar} -\end{description} - -\subsection{Built-in Module {\tt gl}} - -This module provides access to the Silicon Graphics -{\em Graphics Library}. -It is available only on Silicon Graphics machines. - -{\bf Warning:} -Some illegal calls to the GL library cause the {\Python} interpreter to dump -core. -In particular, the use of most GL calls is unsafe before the first -window is opened. - -The module is too large to document here in its entirety, but the -following should help you to get started. -The parameter conventions for the C functions are translated to {\Python} as -follows: - -\begin{itemize} -\item -All (short, long, unsigned) int values are represented by {\Python} -integers. -\item -All float and double values are represented by {\Python} floating point -numbers. -In most cases, {\Python} integers are also allowed. -\item -All arrays are represented by one-dimensional {\Python} lists. -In most cases, tuples are also allowed. -\item -\begin{sloppypar} -All string and character arguments are represented by {\Python} strings, -for instance, -{\tt winopen('Hi~There!')} -and -{\tt rotate(900,~'z')}. -\end{sloppypar} -\item -All (short, long, unsigned) integer arguments or return values that are -only used to specify the length of an array argument are omitted. -For example, the C call -\bcode\begin{verbatim} -lmdef(deftype, index, np, props) -\end{verbatim}\ecode -is translated to {\Python} as -\bcode\begin{verbatim} -lmdef(deftype, index, props) -\end{verbatim}\ecode -\item -Output arguments are omitted from the argument list; they are -transmitted as function return values instead. -If more than one value must be returned, the return value is a tuple. -If the C function has both a regular return value (that is not omitted -because of the previous rule) and an output argument, the return value -comes first in the tuple. -Examples: the C call -\bcode\begin{verbatim} -getmcolor(i, &red, &green, &blue) -\end{verbatim}\ecode -is translated to {\Python} as -\bcode\begin{verbatim} -red, green, blue = getmcolor(i) -\end{verbatim}\ecode -\end{itemize} - -The following functions are non-standard or have special argument -conventions: -\begin{description} -\funcitem{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. -\funcitem{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. -\funcitem{vnarray}{} -Similar to -{\tt nvarray()} -but the pairs have the point first and the normal second. -\funcitem{nurbssurface}{s\_k[], t\_k[], ctl[][], s\_ord, t\_ord, type} -%.br -\itembreak -Defines a nurbs surface. -The dimensions of -{\tt ctl[][]} -are computed as follows: -{\tt [len(s\_k)~-~s\_ord]}, -{\tt [len(t\_k)~-~t\_ord]}. -\funcitem{nurbscurve}{knots, ctlpoints, order, type} -%.br -Defines a nurbs curve. -The length of ctlpoints is -{\tt len(knots)~-~order}. -\funcitem{pwlcurve}{points, type} -%.br -Defines a piecewise-linear curve. -{\tt points} -is a list of points. -{\tt type} -must be -{\tt N\_ST}. -\funcitem{pick(n), select}{n} -%.br -The only argument to these functions specifies the desired size of the -pick or select buffer. -\funcitem{endpick(), endselect}{} -%.br -These functions have no arguments. -They return a list of integers representing the used part of the -pick/select buffer. -No method is provided to detect buffer overrun. -\end{description} - -Here is a tiny but complete example GL program in {\Python}: -\bcode\begin{verbatim} -import gl, GL, time - -def main(): - gl.foreground() - gl.prefposition(500, 900, 500, 900) - w = gl.winopen('CrissCross') - gl.ortho2(0.0, 400.0, 0.0, 400.0) - gl.color(GL.WHITE) - gl.clear() - gl.color(GL.RED) - gl.bgnline() - gl.v2f(0.0, 0.0) - gl.v2f(400.0, 400.0) - gl.endline() - gl.bgnline() - gl.v2f(400.0, 0.0) - gl.v2f(0.0, 400.0) - gl.endline() - time.sleep(5) - -main() -\end{verbatim}\ecode - -\subsection{Built-in Module {\tt pnl}} - -This module provides access to the -{\em Panel Library} -built by NASA Ames (to get it, send e-mail to -{\tt panel-request@nas.nasa.gov}). -All access to it should be done through the standard module -{\tt panel}, -which transparantly exports most functions from -{\tt pnl} -but redefines -{\tt pnl.dopanel()}. - -{\bf Warning:} -the {\Python} interpreter will dump core if you don't create a GL window -before calling -{\tt pnl.mkpanel()}. - -The module is too large to document here in its entirety. - -\section{Standard Modules} - -The following standard modules are defined. -They are available in one of the directories in the default module -search path (try printing -{\tt sys.path} -to find out the default search path.) - -\subsection{Standard Module {\tt string}} - -This module defines some constants useful for checking character -classes, some exceptions, and some useful string functions. -The constants are: -\begin{description} -\funcitem{digits} -The string -{\tt '0123456789'}. -\funcitem{hexdigits} -The string -{\tt '0123456789abcdefABCDEF'}. -\funcitem{letters} -The concatenation of the strings -{\tt lowercase} -and -{\tt uppercase} -described below. -\funcitem{lowercase} -The string -{\tt 'abcdefghijklmnopqrstuvwxyz'}. -\funcitem{octdigits} -The string -{\tt '01234567'}. -\funcitem{uppercase} -The string -{\tt 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}. -\funcitem{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} -\excitem{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. -\excitem{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} -\funcitem{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 '-'}). -\funcitem{index}{s, sub} -Returns the lowest index in -{\tt s} -where the substring -{\tt sub} -is found. -\funcitem{lower}{s} -Convert letters to lower case. -\funcitem{split}{s} -Returns a list of the whitespace-delimited words of the string -{\tt s}. -\funcitem{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. -\funcitem{strip}{s} -Removes leading and trailing whitespace from the string -{\tt s}. -\funcitem{swapcase}{s} -Converts lower case letters to upper case and vice versa. -\funcitem{upper}{s} -Convert letters to upper case. -\funcitem{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} -\funcitem{basename}{p} -Returns the base name of pathname -{\tt p}. -This is the second half of the pair returned by -{\tt path.split(p)}. -\funcitem{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. -\funcitem{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. -\funcitem{exists}{p} -Returns true if -{\tt p} -refers to an existing path. -\funcitem{isdir}{p} -Returns true if -{\tt p} -refers to an existing directory. -\funcitem{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. -\funcitem{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? -} -\funcitem{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}. -\funcitem{walk}{p, visit, arg} -%.br -Calls the function -{\tt visit} -with arguments -{\tt (arg, dirname, names)} -for each directory in the directory tree rooted at -{\tt p} -(including -{\tt p} -itself, if it is a directory). -The argument -{\tt dirname} -specifies the visited directory, the argument -{\tt names} -lists the files in the directory (gotten from -{\tt posix.listdir(dirname)}). -The -{\tt visit} -function may modify -{\tt names} -to influence the set of directories visited below -{\tt dirname}, -e.g., -to avoid visiting certain parts of the tree. -(The object referred to by -{\tt names} -must be modified in place, using -{\tt del} -or slice assignment.) -\end{description} - -\subsection{Standard Module {\tt getopt}} - -This module helps scripts to parse the command line arguments in -{\tt sys.argv}. -It uses the same conventions as the {\UNIX} -{\tt getopt()} -function. -It defines the function -{\tt getopt.getopt(args, options)} -and the exception -{\tt getopt.error}. - -The first argument to -{\tt getopt()} -is the argument list passed to the script with its first element -chopped off (i.e., -{\tt sys.argv[1:]}). -The second argument is the string of option letters that the -script wants to recognize, with options that require an argument -followed by a colon (i.e., the same format that {\UNIX} -{\tt getopt()} -uses). -The return value consists of two elements: the first is a list of -option-and-value pairs; the second is the list of program arguments -left after the option list was stripped (this is a trailing slice of the -first argument). -Each option-and-value pair returned has the option as its first element, -prefixed with a hyphen (e.g., -{\tt '-x'}), -and the option argument as its second element, or an empty string if the -option has no argument. -The options occur in the list in the same order in which they were -found, thus allowing multiple occurrences. -Example: -\bcode\begin{verbatim} ->>> import getopt, string ->>> args = string.split('-a -b -cfoo -d bar a1 a2') ->>> args -['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2'] ->>> optlist, args = getopt.getopt(args, 'abc:d:') ->>> optlist -[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')] ->>> args -['a1', 'a2'] ->>> -\end{verbatim}\ecode -The exception -{\tt getopt.error = 'getopt error'} -is raised when an unrecognized option is found in the argument list or -when an option requiring an argument is given none. -The argument to the exception is a string indicating the cause of the -error. - -\subsection{Standard Module {\tt rand}} - -This module implements a pseudo-random number generator similar to -{\tt rand()} -in C. -It defines the following functions: -\begin{description} -\funcitem{rand}{} -Returns an integer random number in the range [0 ... 32768). -\funcitem{choice}{s} -Returns a random element from the sequence (string, tuple or list) -{\tt s.} -\funcitem{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} -\funcitem{random}{} -Returns the next random floating point number in the range [0.0 ... 1.0). -\funcitem{seed}{x, y, z} -Initializes the random number generator from the integers -{\tt x}, -{\tt y} -and -{\tt z}. -When the module is first imported, the random number is initialized -using values derived from the current time. -\end{description} - -\subsection{Standard Module {\tt stdwinevents}} - -This module defines constants used by STDWIN for event types -({\tt WE\_ACTIVATE} etc.), command codes ({\tt WC\_LEFT} etc.) -and selection types ({\tt WS\_PRIMARY} etc.). -Read the file for details. -Suggested usage is -\bcode\begin{verbatim} ->>> from stdwinevents import * ->>> -\end{verbatim}\ecode - -\subsection{Standard Module {\tt rect}} - -This module contains useful operations on rectangles. -A rectangle is defined as in module -{\tt stdwin}: -a pair of points, where a point is a pair of integers. -For example, the rectangle -\bcode\begin{verbatim} -(10, 20), (90, 80) -\end{verbatim}\ecode -is a rectangle whose left, top, right and bottom edges are 10, 20, 90 -and 80, respectively. -Note that the positive vertical axis points down (as in -{\tt stdwin}). - -The module defines the following objects: -\begin{description} -\excitem{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. -\funcitem{empty} -%.br -The rectangle returned when some operations return an empty result. -This makes it possible to quickly check whether a result is empty: -\bcode\begin{verbatim} ->>> import rect ->>> r1 = (10, 20), (90, 80) ->>> r2 = (0, 0), (10, 20) ->>> r3 = rect.intersect(r1, r2) ->>> if r3 is rect.empty: print 'Empty intersection' -Empty intersection ->>> -\end{verbatim}\ecode -\funcitem{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}. -\funcitem{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. -\funcitem{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. -\funcitem{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}. -\funcitem{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}. -\funcitem{rect2geom}{rect} -%.br -Converts a rectangle to geometry representation: -{\em (left,~top),} -{\em (width,~height)}. -\funcitem{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} -\funcitem{defpanellist}{filename} -%.br -Parses a panel description file containing S-expressions written by the -{\em Panel Editor} -that accompanies the Panel Library and creates the described panels. -It returns a list of panel objects. -\end{description} - -{\bf Warning:} -the {\Python} interpreter will dump core if you don't create a GL window -before calling -{\tt panel.mkpanel()} -or -{\tt panel.defpanellist()}. - -\subsection{Standard Module {\tt panelparser}} - -This module defines a self-contained parser for S-expressions as output -by the Panel Editor (which is written in Scheme so it can't help writing -S-expressions). -The relevant function is -{\tt panelparser.parse\_file(file)} -which has a file object (not a filename!) as argument and returns a list -of parsed S-expressions. -Each S-expression is converted into a {\Python} list, with atoms converted -to {\Python} strings and sub-expressions (recursively) to {\Python} lists. -For more details, read the module file. - -\section{P.M.} - -\begin{verse} - -commands - -cmp? - -*cache? - -localtime? - -calendar? - -\_\_dict? - -mac? - -\end{verse} +\input{mod1.tex} +\input{mod2.tex} +\input{mod3.tex} \end{document} diff --git a/Doc/lib/lib.tex b/Doc/lib/lib.tex index 8e36427..f0b649a 100644 --- a/Doc/lib/lib.tex +++ b/Doc/lib/lib.tex @@ -55,2094 +55,8 @@ gives a more formal reference to the language. \pagenumbering{arabic} -\section{Introduction} - -The {\Python} library consists of three parts, with different levels of -integration with the interpreter. -Closest to the interpreter are built-in types, exceptions and functions. -Next are built-in modules, which are written in C and linked statically -with the interpreter. -Finally there are standard modules that are implemented entirely in -{\Python}, but are always available. -For efficiency, some standard modules may become built-in modules in -future versions of the interpreter. - -\section{Built-in Types, Exceptions and Functions} - -Names for built-in exceptions and functions are found in a separate -read-only symbol table which cannot be modified. -This table is searched last, so local and global user-defined names can -override built-in names. -Built-in types have no names but are created by syntactic constructs -(such as constants) or built-in functions. -They are described together here for easy reference.% -\footnote{ -The descriptions sorely lack explanations of the exceptions that -may be raised---this will be fixed in a future version of this -document. -} - -\subsection{Built-in Types} - -The following sections describe the standard types that are built into the -interpreter. -\subsubsection{Numeric Types} - -There are two numeric types: integers and floating point numbers. -Integers are implemented using {\tt long} in C, so they have at least 32 -bits of precision. -Floating point numbers are implemented using {\tt double} in C. -All bets on precision are off. -Numbers are created by numeric constants or as the result of built-in -functions and operators. - -Numeric types support the following operations: - -\begin{center} -\begin{tabular}{|c|l|c|} -\hline -Operation & Result & Notes \\ -\hline -{\tt abs}({\em x}) & absolute value of {\em x} & \\ -{\tt int}({\em x}) & {\em x} converted to integer & (1) \\ -{\tt float}({\em x}) & {\em x} converted to floating point & \\ -{\tt -}{\em x} & {\em x} negated & \\ -{\tt +}{\em x} & {\em x} unchanged & \\ -{\em x}{\tt +}{\em y} & sum of {\em x} and {\em y} & \\ -{\em x}{\tt -}{\em y} & difference of {\em x} and {\em y} & \\ -{\em x}{\tt *}{\em y} & product of {\em x} and {\em y} & \\ -{\em x}{\tt /}{\em y} & quotient of {\em x} and {\em y} & (2) \\ -{\em x}{\tt \%}{\em y} & remainder of {\em x}{\tt /}{\em y} & (3) \\ -\hline -\end{tabular} -\end{center} - -\noindent -Notes: -\begin{description} -\item[(1)] -This may round or truncate as in C; see functions {\tt floor} and -{\tt ceil} in module {\tt math}. -\item[(2)] -Integer division is defined as in C: the result is an integer; with -positive operands, it truncates towards zero; with a negative operand, -the result is unspecified. -\item[(3)] -Only defined for integers. -\end{description} - -Mixed arithmetic is not supported; both operands must have the same type. -Mixed comparisons return the wrong result (floats always compare smaller -than integers).% -\footnote{ -These restrictions are bugs in the language definitions and will be -fixed in the future. -} -\subsubsection{Sequence Types} - -There are three sequence types: strings, lists and tuples. -Strings constants are written in single quotes: {\tt 'xyzzy'}. -Lists are constructed with square brackets: {\tt [a,~b,~c]}. -Tuples are constructed by the comma operator or with an empty set of -parentheses: {\tt a,~b,~c} or {\tt ()}. - -Sequence types support the following operations ({\em s} and {\em t} are -sequences of the same type; {\em n}, {\em i} and {\em j} are integers): - -\begin{center} -\begin{tabular}{|c|l|c|} -\hline -Operation & Result & Notes \\ -\hline -{\tt len}({\em s}) & length of {\em s} & \\ -{\tt min}({\em s}) & smallest item of {\em s} & \\ -{\tt max}({\em s}) & largest item of {\em s} & \\ -{\em x} {\tt in} {\em s} & - true if an item of {\em s} is equal to {\em x} & \\ -{\em x} {\tt not} {\tt in} {\em s} & - false if an item of {\em s} is equal to {\em x} & \\ -{\em s}{\tt +}{\em t} & the concatenation of {\em s} and {\em t} & \\ -{\em s}{\tt *}{\em n}, {\em n}*{\em s} & - {\em n} copies of {\em s} concatenated & (1) \\ -{\em s}[{\em i}] & {\em i}'th item of {\em s} & \\ -{\em s}[{\em i}:{\em j}] & - slice of {\em s} from {\em i} to {\em j} & (2) \\ -\hline -\end{tabular} -\end{center} - -\noindent -Notes: -\begin{description} -\item[(1)] -Sequence repetition is only supported for strings. -\item[(2)] -The slice of $s$ from $i$ to $j$ is defined as the sequence -of items with index $k$ such that $i \leq k < j$. -Special rules apply for negative and omitted indices; see the Tutorial -or the Reference Manual. -\end{description} - -\paragraph{Mutable Sequence Types.} - -List objects support additional operations that allow in-place -modification of the object. -These operations would be supported by other mutable sequence types -(when added to the language) as well. -Strings and tuples are immutable sequence types and such objects cannot -be modified once created. -The following operations are defined on mutable sequence types (where -{\em x} is an arbitrary object): - -\begin{center} -\begin{tabular}{|c|l|} -\hline -Operation & Result \\ -\hline -{\em s}[{\em i}] = {\em x} & - item {\em i} of {\em s} is replaced by {\em x} \\ -{\em s}[{\em i}:{\em j}] = {\em t} & - slice of {\em s} from {\em i} to {\em j} is replaced by {\em t} \\ -{\tt del} {\em s}[{\em i}:{\em j}] & - same as {\em s}[{\em i}:{\em j}] = [] \\ -{\em s}.{\tt append}({\em x}) & - same as {\em s}[{\tt len}({\em x}):{\tt len}({\em x})] = [{\em x}] \\ -{\em s}.{\tt insert}({\em i}, {\em x}) & - same as {\em s}[{\em i}:{\em i}] = [{\em x}] \\ -{\em s}.{\tt sort}() & - the items of {\em s} are permuted to satisfy \\ - & - $s[i] \leq s[j]$ for $i < j$\\ -\hline -\end{tabular} -\end{center} - -\subsubsection{Mapping Types} - -A -{\em mapping} -object maps values of one type (the key type) to arbitrary objects. -Mappings are mutable objects. -There is currently only one mapping type, the -{\em dictionary}. -A dictionary's keys are strings. -An empty dictionary is created by the expression \verb"{}". -An extension of this notation is used to display dictionaries when -written (see the example below). - -The following operations are defined on mappings (where {\em a} is a -mapping, {\em k} is a key and {\em x} is an arbitrary object): - -\begin{center} -\begin{tabular}{|c|l|c|} -\hline -Operation & Result & Notes\\ -\hline -{\tt len}({\em a}) & the number of elements in {\em a} & \\ -{\em a}[{\em k}] & the item of {\em a} with key {\em k} & \\ -{\em a}[{\em k}] = {\em x} & set {\em a}[{\em k}] to {\em x} & \\ -{\tt del} {\em a}[{\em k}] & remove {\em a}[{\em k}] from {\em a} & \\ -{\em a}.{\tt keys}() & a copy of {\em a}'s list of keys & (1) \\ -{\em a}.{\tt has\_key}({\em k}) & true if {\em a} has a key {\em k} & \\ -\hline -\end{tabular} -\end{center} - -\noindent -Notes: -\begin{description} -\item[(1)] -Keys are listed in random order. -\end{description} - -A small example using a dictionary: -\bcode\begin{verbatim} ->>> tel = {} ->>> tel['jack'] = 4098 ->>> tel['sape'] = 4139 ->>> tel['guido'] = 4127 ->>> tel['jack'] -4098 ->>> tel -{'sape': 4139; 'guido': 4127; 'jack': 4098} ->>> del tel['sape'] ->>> tel['irv'] = 4127 ->>> tel -{'guido': 4127; 'irv': 4127; 'jack': 4098} ->>> tel.keys() -['guido', 'irv', 'jack'] ->>> tel.has_key('guido') -1 ->>> -\end{verbatim}\ecode -\subsubsection{Other Built-in Types} - -The interpreter supports several other kinds of objects. -Most of these support only one or two operations. - -\paragraph{Modules.} - -The only operation on a module is member acces: {\em m}{\tt .}{\em name}, -where {\em m} is a module and {\em name} accesses a name defined in -{\em m}'s symbol table. -Module members can be assigned to. - -\paragraph{Classes and Class Objects.} - -XXX Classes will be explained at length in a later version of this -document. - -\paragraph{Functions.} - -Function objects are created by function definitions. -The only operation on a function object is to call it: -{\em func}({\em optional-arguments}). - -Built-in functions have a different type than user-defined functions, -but they support the same operation. - -\paragraph{Methods.} - -Methods are functions that are called using the member acces notation. -There are two flavors: built-in methods (such as {\tt append()} on -lists) and class member methods. -Built-in methods are described with the types that support them. -XXX Class member methods will be described in a later version of this -document. - -\paragraph{Type Objects.} - -Type objects represent the various object types. -An object's type is accessed by the built-in function -{\tt type()}. -There are no operations on type objects. - -\paragraph{The Null Object.} - -This object is returned by functions that don't explicitly return a -value. -It supports no operations. -There is exactly one null object, named {\tt None} -(a built-in name). - -\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} -\funcitem{close}{} -Closes the file. -A closed file cannot be read or written anymore. -\funcitem{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.) -\funcitem{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().} -\funcitem{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} -\excitem{EOFError}{end-of-file read} -(No argument.) -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.) -\excitem{KeyboardInterrupt}{end-of-file read} -(No argument.) -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. -\excitem{MemoryError}{out of memory} -%.br -Raised when an operation runs out of memory but the situation -may still be rescued (by deleting some objects). -\excitem{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. -\excitem{RuntimeError}{run-time error} -%.br -Raised for a variety of reasons, e.g., division by zero or index out of -range. -\excitem{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. -\excitem{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} -\funcitem{abs}{x} -Returns the absolute value of a number. -The argument may be an integer or floating point number. -\funcitem{chr}{i} -Returns a string of one character -whose ASCII code is the integer {\tt i}, -e.g., {\tt chr(97)} returns the string {\tt 'a'}. -This is the inverse of {\tt ord()}. -\funcitem{dir}{} -Without arguments, this function returns the list of names in the -current local symbol table, sorted alphabetically. -With a module object as argument, it returns the sorted list of names in -that module's global symbol table. -For example: -\bcode\begin{verbatim} ->>> import sys ->>> dir() -['sys'] ->>> dir(sys) -['argv', 'exit', 'modules', 'path', 'stderr', 'stdin', 'stdout'] ->>> -\end{verbatim}\ecode -\funcitem{divmod}{a, b} -%.br -Takes two integers as arguments and returns a pair of integers -consisting of their quotient and remainder. -For -\bcode\begin{verbatim} -q, r = divmod(a, b) -\end{verbatim}\ecode -the invariants are: -\bcode\begin{verbatim} -a = q*b + r -abs(r) < abs(b) -r has the same sign as b -\end{verbatim}\ecode -For example: -\bcode\begin{verbatim} ->>> divmod(100, 7) -(14, 2) ->>> divmod(-100, 7) -(-15, 5) ->>> divmod(100, -7) -(-15, -5) ->>> divmod(-100, -7) -(14, -2) ->>> -\end{verbatim}\ecode -\funcitem{eval}{s} -Takes a string as argument and parses and evaluates it as a {\Python} -expression. -The expression is executed using the current local and global symbol -tables. -Syntax errors are reported as exceptions. -For example: -\bcode\begin{verbatim} ->>> x = 1 ->>> eval('x+1') -2 ->>> -\end{verbatim}\ecode -\funcitem{exec}{s} -Takes a string as argument and parses and evaluates it as a sequence of -{\Python} statements. -The string should end with a newline (\verb"'\n'"). -The statement is executed using the current local and global symbol -tables. -Syntax errors are reported as exceptions. -For example: -\bcode\begin{verbatim} ->>> x = 1 ->>> exec('x = x+1\n') ->>> x -2 ->>> -\end{verbatim}\ecode -\funcitem{float}{x} -Converts a number to floating point. -The argument may be an integer or floating point number. -\funcitem{input}{s} -Equivalent to -{\tt eval(raw\_input(s))}. -As for -{\tt raw\_input()}, -the argument is optional. -\funcitem{int}{x} -Converts a number to integer. -The argument may be an integer or floating point number. -\funcitem{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). -\funcitem{max}{s} -Returns the largest item of a non-empty sequence (string, tuple or list). -\funcitem{min}{s} -Returns the smallest item of a non-empty sequence (string, tuple or list). -\funcitem{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}. -} -\funcitem{ord}{c} -Takes a string of one character and returns its -ASCII value, e.g., {\tt ord('a')} returns the integer {\tt 97}. -This is the inverse of {\tt chr()}. -\funcitem{range}{} -This is a versatile function to create lists containing arithmetic -progressions of integers. -With two integer arguments, it returns the ascending sequence of -integers starting at the first and ending one before the second -argument. -A single argument is used as the end point of the sequence, with 0 used -as the starting point. -A third argument specifies the step size; negative steps are allowed and -work as expected, but don't specify a zero step. -The resulting list may be empty. -For example: -\bcode\begin{verbatim} ->>> range(10) -[0, 1, 2, 3, 4, 5, 6, 7, 8, 9] ->>> range(1, 1+10) -[1, 2, 3, 4, 5, 6, 7, 8, 9, 10] ->>> range(0, 30, 5) -[0, 5, 10, 15, 20, 25] ->>> range(0, 10, 3) -[0, 3, 6, 9] ->>> range(0, -10, -1) -[0, -1, -2, -3, -4, -5, -6, -7, -8, -9] ->>> range(0) -[] ->>> range(1, 0) -[] ->>> -\end{verbatim}\ecode -\funcitem{raw\_input}{s} -%.br -The argument is optional; if present, it is written to standard output -without a trailing newline. -The function then reads a line from input, converts it to a string -(stripping a trailing newline), and returns that. -EOF is reported as an exception. -For example: -\bcode\begin{verbatim} ->>> raw_input('Type anything: ') -Type anything: Mutant Teenage Ninja Turtles -'Mutant Teenage Ninja Turtles' ->>> -\end{verbatim}\ecode -\funcitem{reload}{module} -Causes an already imported module to be re-parsed and re-initialized. -This is useful if you have edited the module source file and want to -try out the new version without leaving {\Python}. -\funcitem{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} -\funcitem{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. -\funcitem{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!). -\funcitem{modules} -Gives the list of modules that have already been loaded. -This can be manipulated to force reloading of modules and other tricks. -\funcitem{path} -A list of strings that specifies the search path for modules. -Initialized from the environment variable {\tt PYTHONPATH}, or an -installation-dependent default. -\funcitem{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 '... '}. -\funcitem{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} -\funcitem{sleep}{secs} -Suspends execution for the given number of seconds. -\funcitem{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} -\funcitem{millisleep}{msecs} -Suspends execution for the given number of milliseconds. -\funcitem{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 regexp}} - -This module provides a regular expression matching operation. -It is always available. - -The module defines a function and an exception: - -\begin{description} - -\funcitem{compile}{pattern} - -Compile a regular expression given as a string into a regular -expression object. -The string must be an egrep-style regular expression; -this means that the characters {\tt '(' ')' '*' '+' '?' '|' '^' '$'} -are special. -(It is implemented using Henry Spencer's regular expression matching -functions.) - -excitem{error}{regexp.error} - -Exception raised when a string passed to {\tt compile()} is not a -valid regular expression (e.g., unmatched parentheses) or when some other -error occurs during compilation or matching -(``no match found'' is not an error). - -\end{description} - -Compiled regular expression objects support a single method: - -\begin{description} - -\funcitem{exec}{str} - -Find the first occurrence of the compiled regular expression in the -string {\tt str}. -The return value is a tuple of pairs specifying where a match was -found and where matches were found for subpatterns specified with -{\tt '('} and {\tt ')'} in the pattern. -If no match is found, an empty tuple is returned; otherwise the first -item of the tuple is a pair of slice indices into the search string -giving the match found. -If there were any subpatterns in the pattern, the returned tuple has an -additional item for each subpattern, giving the slice indices into the -search string where that subpattern was found. - -\end{description} - -For example: -\bcode\begin{verbatim} ->>> import regexp ->>> r = regexp.compile('--(.*)--') ->>> s = 'a--b--c' ->>> r.exec(s) -((1, 6), (3, 4)) ->>> s[1:6] # The entire match -'--b--' ->>> s[3:4] # The subpattern -'b' ->>> -\end{verbatim}\ecode - -\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} -\funcitem{chdir}{path} -Changes the current directory to -{\tt path}. -\funcitem{chmod}{path, mode} -Change the mode of -{\tt path} -to the numeric -{\tt mode}. -\funcitem{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. -\excitem{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()}. -\funcitem{getcwd}{} -Returns a string representing the current working directory. -\funcitem{link}{src, dst} -Creates a hard link pointing to -{\tt src} -named -{\tt dst}. -\funcitem{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. -\funcitem{mkdir}{path, mode} -Creates a directory named -{\tt path} -with numeric mode -{\tt mode}. -\funcitem{rename}{src, dst} -Renames the file or directory -{\tt src} -to -{\tt dst}. -\funcitem{rmdir}{path} -Removes the directory -{\tt path}. -\funcitem{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. -\funcitem{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()}. -\funcitem{umask}{mask} -Sets the current numeric umask and returns the previous umask. -\funcitem{unlink}{path} -Unlinks the file -{\tt path}. -\funcitem{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} -\funcitem{lstat}{path} -Like -{\tt stat()}, -but does not follow symbolic links. -\funcitem{readlink}{path} -Returns a string representing the path to which the symbolic link -points. -\funcitem{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} -\funcitem{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. -} -\funcitem{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}. -\funcitem{setdefwinpos}{h, v} -%.br -Sets the default window position. -\funcitem{setdefwinsize}{width, height} -%.br -Sets the default window size. -\funcitem{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. -\funcitem{fleep}{} -%.br -Causes a beep or bell (or perhaps a `visual bell' or flash, hence the -name). -\funcitem{message}{string} -%.br -Displays a dialog box containing the string. -The user must click OK before the function returns. -\funcitem{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. -\funcitem{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. -\funcitem{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. -\funcitem{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. -\funcitem{getcutbuffer}{i} -%.br -Returns the contents of the system's cut buffer number -{\tt i}. -\funcitem{rotatebutbuffers}{n} -%.br -On X11, this rotates the 8 cut buffers by -{\tt n}. -Ignored on the Macintosh. -\funcitem{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. -\funcitem{resetselection}{i} -%.br -Resets selection number -{\tt i}, -if this process owns it. -(See window method -{\tt setselection()}). -\funcitem{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. -} -\funcitem{lineheight}{} -%.br -Return the total line height of the current font. -\funcitem{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. -\funcitem{textwidth}{str} -%.br -Return the width in bits of the string when drawn in the current font. -\end{description} - -\subsubsection{Window Object Methods} - -Window objects are created by -{\tt stdwin.open()}. -There is no explicit function to close a window; windows are closed when -they are garbage-collected. -Window objects have the following methods: -\begin{description} -\funcitem{begindrawing}{} -Returns a drawing object, whose methods (described below) allow drawing -in the window. -\funcitem{change}{rect} -Invalidates the given rectangle; this may cause a draw event. -\funcitem{gettitle}{} -Returns the window's title string. -\funcitem{getdocsize}{} -\begin{sloppypar} -Returns a pair of integers giving the size of the document as set by -{\tt setdocsize()}. -\end{sloppypar} -\funcitem{getorigin}{} -Returns a pair of integers giving the origin of the window with respect -to the document. -\funcitem{getwinsize}{} -Returns a pair of integers giving the size of the window. -\funcitem{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. -\funcitem{scroll}{rect,~point} -Scrolls the given rectangle by the vector given by the point. -\funcitem{setwincursor}{name} -\begin{sloppypar} -Sets the window cursor to a cursor of the given name. -It raises the -{\tt Runtime\-Error} -exception if no cursor of the given name exists. -Suitable names are -{\tt 'ibeam'}, -{\tt 'arrow'}, -{\tt 'cross'}, -{\tt 'watch'} -and -{\tt 'plus'}. -On X11, there are many more (see -{\tt <X11/cursorfont.h>}). -\end{sloppypar} -\funcitem{setdocsize}{point} -Sets the size of the drawing document. -\funcitem{setorigin}{point} -Moves the origin of the window to the given point in the document. -\funcitem{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. -\funcitem{settitle}{title} -Sets the window's title string. -\funcitem{settimer}{dsecs} -Schedules a timer event for the window in -{\tt dsecs/10} -seconds. -\funcitem{show}{rect} -Tries to ensure that the given rectangle of the document is visible in -the window. -\funcitem{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} -\funcitem{box}{rect} -Draws a box around a rectangle. -\funcitem{circle}{center, radius} -%.br -Draws a circle with given center point and radius. -\funcitem{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. -\funcitem{erase}{rect} -Erases a rectangle. -\funcitem{invert}{rect} -Inverts a rectangle. -\funcitem{line}{p1, p2} -Draws a line from point -{\tt p1} -to -{\tt p2}. -\funcitem{paint}{rect} -Fills a rectangle. -\funcitem{text}{p, str} -Draws a string starting at point p (the point specifies the -top left coordinate of the string). -\funcitem{shade}{rect, percent} -%.br -Fills a rectangle with a shading pattern that is about -{\tt percent} -percent filled. -\funcitem{xorline}{p1, p2} -Draws a line in XOR mode. -\funcitem{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} -\funcitem{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). -\funcitem{setitem}{i, text} -Sets the text of item number -{\tt i}. -\funcitem{enable}{i, flag} -Enables or disables item -{\tt i}. -\funcitem{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} -\funcitem{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}). -\funcitem{draw}{rect} -Passes a draw event to the text-edit block. -The rectangle specifies the redraw area. -\funcitem{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. -\funcitem{getfocus}{} -Returns 2 integers representing the start and end positions of the -focus, usable as slice indices on the string returned by -{\tt getfocustext()}. -\funcitem{getfocustext}{} -Returns the text in the focus. -\funcitem{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.) -\funcitem{gettext}{} -Returns the entire text buffer. -\funcitem{move}{rect} -Specifies a new position for the text-edit block in the document. -\funcitem{replace}{str} -Replaces the focus by the given string. -The new focus is an insert point at the end of the string. -\funcitem{setfocus}{i,~j} -Specifies the new focus. -Out-of-bounds values are silently clipped. -\end{description} - -\subsubsection{Example} - -Here is a simple example of using STDWIN in Python. -It creates a window and draws the string ``Hello world'' in the top -left corner of the window. -The window will be correctly redrawn when covered and re-exposed. -The program quits when the close icon or menu item is requested. -\bcode\begin{verbatim} -import stdwin -from stdwinevents import * - -def main(): - mywin = stdwin.open('Hello') - # - while 1: - (type, win, detail) = stdwin.getevent() - if type = WE_DRAW: - draw = win.begindrawing() - draw.text((0, 0), 'Hello, world') - del draw - elif type = WE_CLOSE: - break - -main() -\end{verbatim}\ecode - -\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} -\funcitem{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()}). -\funcitem{name\_delete}{path} -%.br -Deletes a capability from the Amoeba directory tree. -Argument is the pathname. -\funcitem{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. -\funcitem{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.) -\funcitem{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. -\excitem{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()}. -\funcitem{timeout}{msecs} -%.br -Sets the transaction timeout, in milliseconds. -Returns the previous timeout. -Initially, the timeout is set to 2 seconds by the {\Python} interpreter. -\end{description} - -\subsubsection{Capability Operations} - -Capabilities are written in a convenient ASCII format, also used by the -Amoeba utilities -{\em c2a}(U) -and -{\em a2c}(U). -For example: -\bcode\begin{verbatim} ->>> amoeba.name_lookup('/profile/cap') -aa:1c:95:52:6a:fa/14(ff)/8e:ba:5b:8:11:1a ->>> -\end{verbatim}\ecode -The following methods are defined for capability objects. -\begin{description} -\funcitem{dir\_list}{} -Returns a list of the names of the entries in an Amoeba directory. -\funcitem{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. -\funcitem{b\_size}{} -Returns the size of a bullet file. -\funcitem{dir\_append(), dir\_delete(), dir\_lookup(), dir\_replace}{} -%.br -\itembreak -Like the corresponding -{\tt name\_*} -functions, but with a path relative to the capability. -(For paths beginning with a slash the capability is ignored, since this -is the defined semantics for Amoeba.) -\funcitem{std\_info}{} -Returns the standard info string of the object. -\funcitem{tod\_gettime}{} -Returns the time (in seconds since the Epoch, in UCT, as for POSIX) from -a time server. -\funcitem{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} -\funcitem{setoutgain}{n} -Sets the output gain (0-255). -\funcitem{getoutgain}{} -Returns the output gain. -\funcitem{setrate}{n} -Sets the sampling rate: 1=32K/sec, 2=16K/sec, 3=8K/sec. -\funcitem{setduration}{n} -Sets the `sound duration' in units of 1/100 seconds. -\funcitem{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. -\funcitem{write}{buf} -Writes a chunk of samples to the audio output (speaker). -\end{description} - -These operations support asynchronous audio I/O: -\begin{description} -\funcitem{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. -\funcitem{wait\_recording}{} -%.br -Waits for the second thread to finish and returns the data read. -\funcitem{stop\_recording}{} -%.br -Makes the second thread stop reading as soon as possible. -Returns the data read so far. -\funcitem{poll\_recording}{} -%.br -Returns true if the second thread has finished reading (so -{\tt wait\_recording()} would return the data without delay). -\item[{\tt start\_playing(chunk)}, {\tt wait\_playing()}, -{\tt stop\_playing()}, {\tt poll\_playing()}] -%.br -\begin{sloppypar} -Similar but for output. -{\tt stop\_playing()} -returns a lower bound for the number of bytes actually played (not very -accurate). -\end{sloppypar} -\end{description} - -The following operations do not affect the audio device but are -implemented in C for efficiency: -\begin{description} -\funcitem{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. -\funcitem{reverse}{buf} -%.br -Returns a chunk of samples backwards. -\funcitem{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. -\funcitem{chr2num}{buf} -%.br -Converts a string of sampled bytes as returned by {\tt read()} into -a list containing the numeric values of the samples. -\funcitem{num2chr}{list} -%.br -\begin{sloppypar} -Converts a list as returned by -{\tt chr2num()} -back to a buffer acceptable by -{\tt write()}. -\end{sloppypar} -\end{description} - -\subsection{Built-in Module {\tt gl}} - -This module provides access to the Silicon Graphics -{\em Graphics Library}. -It is available only on Silicon Graphics machines. - -{\bf Warning:} -Some illegal calls to the GL library cause the {\Python} interpreter to dump -core. -In particular, the use of most GL calls is unsafe before the first -window is opened. - -The module is too large to document here in its entirety, but the -following should help you to get started. -The parameter conventions for the C functions are translated to {\Python} as -follows: - -\begin{itemize} -\item -All (short, long, unsigned) int values are represented by {\Python} -integers. -\item -All float and double values are represented by {\Python} floating point -numbers. -In most cases, {\Python} integers are also allowed. -\item -All arrays are represented by one-dimensional {\Python} lists. -In most cases, tuples are also allowed. -\item -\begin{sloppypar} -All string and character arguments are represented by {\Python} strings, -for instance, -{\tt winopen('Hi~There!')} -and -{\tt rotate(900,~'z')}. -\end{sloppypar} -\item -All (short, long, unsigned) integer arguments or return values that are -only used to specify the length of an array argument are omitted. -For example, the C call -\bcode\begin{verbatim} -lmdef(deftype, index, np, props) -\end{verbatim}\ecode -is translated to {\Python} as -\bcode\begin{verbatim} -lmdef(deftype, index, props) -\end{verbatim}\ecode -\item -Output arguments are omitted from the argument list; they are -transmitted as function return values instead. -If more than one value must be returned, the return value is a tuple. -If the C function has both a regular return value (that is not omitted -because of the previous rule) and an output argument, the return value -comes first in the tuple. -Examples: the C call -\bcode\begin{verbatim} -getmcolor(i, &red, &green, &blue) -\end{verbatim}\ecode -is translated to {\Python} as -\bcode\begin{verbatim} -red, green, blue = getmcolor(i) -\end{verbatim}\ecode -\end{itemize} - -The following functions are non-standard or have special argument -conventions: -\begin{description} -\funcitem{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. -\funcitem{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. -\funcitem{vnarray}{} -Similar to -{\tt nvarray()} -but the pairs have the point first and the normal second. -\funcitem{nurbssurface}{s\_k[], t\_k[], ctl[][], s\_ord, t\_ord, type} -%.br -\itembreak -Defines a nurbs surface. -The dimensions of -{\tt ctl[][]} -are computed as follows: -{\tt [len(s\_k)~-~s\_ord]}, -{\tt [len(t\_k)~-~t\_ord]}. -\funcitem{nurbscurve}{knots, ctlpoints, order, type} -%.br -Defines a nurbs curve. -The length of ctlpoints is -{\tt len(knots)~-~order}. -\funcitem{pwlcurve}{points, type} -%.br -Defines a piecewise-linear curve. -{\tt points} -is a list of points. -{\tt type} -must be -{\tt N\_ST}. -\funcitem{pick(n), select}{n} -%.br -The only argument to these functions specifies the desired size of the -pick or select buffer. -\funcitem{endpick(), endselect}{} -%.br -These functions have no arguments. -They return a list of integers representing the used part of the -pick/select buffer. -No method is provided to detect buffer overrun. -\end{description} - -Here is a tiny but complete example GL program in {\Python}: -\bcode\begin{verbatim} -import gl, GL, time - -def main(): - gl.foreground() - gl.prefposition(500, 900, 500, 900) - w = gl.winopen('CrissCross') - gl.ortho2(0.0, 400.0, 0.0, 400.0) - gl.color(GL.WHITE) - gl.clear() - gl.color(GL.RED) - gl.bgnline() - gl.v2f(0.0, 0.0) - gl.v2f(400.0, 400.0) - gl.endline() - gl.bgnline() - gl.v2f(400.0, 0.0) - gl.v2f(0.0, 400.0) - gl.endline() - time.sleep(5) - -main() -\end{verbatim}\ecode - -\subsection{Built-in Module {\tt pnl}} - -This module provides access to the -{\em Panel Library} -built by NASA Ames (to get it, send e-mail to -{\tt panel-request@nas.nasa.gov}). -All access to it should be done through the standard module -{\tt panel}, -which transparantly exports most functions from -{\tt pnl} -but redefines -{\tt pnl.dopanel()}. - -{\bf Warning:} -the {\Python} interpreter will dump core if you don't create a GL window -before calling -{\tt pnl.mkpanel()}. - -The module is too large to document here in its entirety. - -\section{Standard Modules} - -The following standard modules are defined. -They are available in one of the directories in the default module -search path (try printing -{\tt sys.path} -to find out the default search path.) - -\subsection{Standard Module {\tt string}} - -This module defines some constants useful for checking character -classes, some exceptions, and some useful string functions. -The constants are: -\begin{description} -\funcitem{digits} -The string -{\tt '0123456789'}. -\funcitem{hexdigits} -The string -{\tt '0123456789abcdefABCDEF'}. -\funcitem{letters} -The concatenation of the strings -{\tt lowercase} -and -{\tt uppercase} -described below. -\funcitem{lowercase} -The string -{\tt 'abcdefghijklmnopqrstuvwxyz'}. -\funcitem{octdigits} -The string -{\tt '01234567'}. -\funcitem{uppercase} -The string -{\tt 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}. -\funcitem{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} -\excitem{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. -\excitem{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} -\funcitem{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 '-'}). -\funcitem{index}{s, sub} -Returns the lowest index in -{\tt s} -where the substring -{\tt sub} -is found. -\funcitem{lower}{s} -Convert letters to lower case. -\funcitem{split}{s} -Returns a list of the whitespace-delimited words of the string -{\tt s}. -\funcitem{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. -\funcitem{strip}{s} -Removes leading and trailing whitespace from the string -{\tt s}. -\funcitem{swapcase}{s} -Converts lower case letters to upper case and vice versa. -\funcitem{upper}{s} -Convert letters to upper case. -\funcitem{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} -\funcitem{basename}{p} -Returns the base name of pathname -{\tt p}. -This is the second half of the pair returned by -{\tt path.split(p)}. -\funcitem{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. -\funcitem{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. -\funcitem{exists}{p} -Returns true if -{\tt p} -refers to an existing path. -\funcitem{isdir}{p} -Returns true if -{\tt p} -refers to an existing directory. -\funcitem{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. -\funcitem{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? -} -\funcitem{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}. -\funcitem{walk}{p, visit, arg} -%.br -Calls the function -{\tt visit} -with arguments -{\tt (arg, dirname, names)} -for each directory in the directory tree rooted at -{\tt p} -(including -{\tt p} -itself, if it is a directory). -The argument -{\tt dirname} -specifies the visited directory, the argument -{\tt names} -lists the files in the directory (gotten from -{\tt posix.listdir(dirname)}). -The -{\tt visit} -function may modify -{\tt names} -to influence the set of directories visited below -{\tt dirname}, -e.g., -to avoid visiting certain parts of the tree. -(The object referred to by -{\tt names} -must be modified in place, using -{\tt del} -or slice assignment.) -\end{description} - -\subsection{Standard Module {\tt getopt}} - -This module helps scripts to parse the command line arguments in -{\tt sys.argv}. -It uses the same conventions as the {\UNIX} -{\tt getopt()} -function. -It defines the function -{\tt getopt.getopt(args, options)} -and the exception -{\tt getopt.error}. - -The first argument to -{\tt getopt()} -is the argument list passed to the script with its first element -chopped off (i.e., -{\tt sys.argv[1:]}). -The second argument is the string of option letters that the -script wants to recognize, with options that require an argument -followed by a colon (i.e., the same format that {\UNIX} -{\tt getopt()} -uses). -The return value consists of two elements: the first is a list of -option-and-value pairs; the second is the list of program arguments -left after the option list was stripped (this is a trailing slice of the -first argument). -Each option-and-value pair returned has the option as its first element, -prefixed with a hyphen (e.g., -{\tt '-x'}), -and the option argument as its second element, or an empty string if the -option has no argument. -The options occur in the list in the same order in which they were -found, thus allowing multiple occurrences. -Example: -\bcode\begin{verbatim} ->>> import getopt, string ->>> args = string.split('-a -b -cfoo -d bar a1 a2') ->>> args -['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2'] ->>> optlist, args = getopt.getopt(args, 'abc:d:') ->>> optlist -[('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')] ->>> args -['a1', 'a2'] ->>> -\end{verbatim}\ecode -The exception -{\tt getopt.error = 'getopt error'} -is raised when an unrecognized option is found in the argument list or -when an option requiring an argument is given none. -The argument to the exception is a string indicating the cause of the -error. - -\subsection{Standard Module {\tt rand}} - -This module implements a pseudo-random number generator similar to -{\tt rand()} -in C. -It defines the following functions: -\begin{description} -\funcitem{rand}{} -Returns an integer random number in the range [0 ... 32768). -\funcitem{choice}{s} -Returns a random element from the sequence (string, tuple or list) -{\tt s.} -\funcitem{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} -\funcitem{random}{} -Returns the next random floating point number in the range [0.0 ... 1.0). -\funcitem{seed}{x, y, z} -Initializes the random number generator from the integers -{\tt x}, -{\tt y} -and -{\tt z}. -When the module is first imported, the random number is initialized -using values derived from the current time. -\end{description} - -\subsection{Standard Module {\tt stdwinevents}} - -This module defines constants used by STDWIN for event types -({\tt WE\_ACTIVATE} etc.), command codes ({\tt WC\_LEFT} etc.) -and selection types ({\tt WS\_PRIMARY} etc.). -Read the file for details. -Suggested usage is -\bcode\begin{verbatim} ->>> from stdwinevents import * ->>> -\end{verbatim}\ecode - -\subsection{Standard Module {\tt rect}} - -This module contains useful operations on rectangles. -A rectangle is defined as in module -{\tt stdwin}: -a pair of points, where a point is a pair of integers. -For example, the rectangle -\bcode\begin{verbatim} -(10, 20), (90, 80) -\end{verbatim}\ecode -is a rectangle whose left, top, right and bottom edges are 10, 20, 90 -and 80, respectively. -Note that the positive vertical axis points down (as in -{\tt stdwin}). - -The module defines the following objects: -\begin{description} -\excitem{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. -\funcitem{empty} -%.br -The rectangle returned when some operations return an empty result. -This makes it possible to quickly check whether a result is empty: -\bcode\begin{verbatim} ->>> import rect ->>> r1 = (10, 20), (90, 80) ->>> r2 = (0, 0), (10, 20) ->>> r3 = rect.intersect(r1, r2) ->>> if r3 is rect.empty: print 'Empty intersection' -Empty intersection ->>> -\end{verbatim}\ecode -\funcitem{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}. -\funcitem{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. -\funcitem{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. -\funcitem{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}. -\funcitem{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}. -\funcitem{rect2geom}{rect} -%.br -Converts a rectangle to geometry representation: -{\em (left,~top),} -{\em (width,~height)}. -\funcitem{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} -\funcitem{defpanellist}{filename} -%.br -Parses a panel description file containing S-expressions written by the -{\em Panel Editor} -that accompanies the Panel Library and creates the described panels. -It returns a list of panel objects. -\end{description} - -{\bf Warning:} -the {\Python} interpreter will dump core if you don't create a GL window -before calling -{\tt panel.mkpanel()} -or -{\tt panel.defpanellist()}. - -\subsection{Standard Module {\tt panelparser}} - -This module defines a self-contained parser for S-expressions as output -by the Panel Editor (which is written in Scheme so it can't help writing -S-expressions). -The relevant function is -{\tt panelparser.parse\_file(file)} -which has a file object (not a filename!) as argument and returns a list -of parsed S-expressions. -Each S-expression is converted into a {\Python} list, with atoms converted -to {\Python} strings and sub-expressions (recursively) to {\Python} lists. -For more details, read the module file. - -\section{P.M.} - -\begin{verse} - -commands - -cmp? - -*cache? - -localtime? - -calendar? - -\_\_dict? - -mac? - -\end{verse} +\input{mod1.tex} +\input{mod2.tex} +\input{mod3.tex} \end{document} |