| % Format this file with latex. |
| |
| \documentstyle[palatino,11pt,myformat]{article} |
| %\documentstyle[11pt,myformat]{article} |
| |
| \sloppy |
| |
| \title{\bf |
| Python Library Reference \\ |
| (DRAFT) |
| } |
| |
| \author{ |
| Guido van Rossum \\ |
| Dept. CST, CWI, Kruislaan 413 \\ |
| 1098 SJ Amsterdam, The Netherlands \\ |
| E-mail: {\tt guido@cwi.nl} |
| } |
| |
| \begin{document} |
| |
| \pagenumbering{roman} |
| |
| \maketitle |
| |
| \begin{abstract} |
| |
| \noindent |
| This document describes the built-in types, exceptions and functions and |
| the standard modules that come with the {\Python} system. |
| It assumes basic knowledge about the {\Python} language. |
| For an informal introduction to the language, see the Tutorial document. |
| The Language Reference document (XXX not yet existing) |
| gives a more formal reference to the language. |
| |
| \end{abstract} |
| |
| \pagebreak |
| |
| \tableofcontents |
| |
| \pagebreak |
| |
| \pagenumbering{arabic} |
| |
| \section{Introduction} |
| |
| The {\Python} library consists of three parts, with different levels of |
| integration with the interpreter. |
| Closest to the interpreter are built-in types, exceptions and functions. |
| Next are built-in modules, which are written in C and linked statically |
| with the interpreter. |
| Finally there are standard modules that are implemented entirely in |
| {\Python}, but are always available. |
| For efficiency, some standard modules may become built-in modules in |
| future versions of the interpreter. |
| |
| \section{Built-in Types, Exceptions and Functions} |
| |
| Names for built-in exceptions and functions are found in a separate |
| read-only symbol table which cannot be modified. |
| This table is searched last, so local and global user-defined names can |
| override built-in names. |
| Built-in types have no names but are created by syntactic constructs |
| (such as constants) or built-in functions. |
| They are described together here for easy reference.% |
| \footnote{ |
| The descriptions sorely lack explanations of the exceptions that |
| may be raised---this will be fixed in a future version of this |
| document. |
| } |
| |
| \subsection{Built-in Types} |
| |
| The following sections describe the standard types that are built into the |
| interpreter. |
| \subsubsection{Numeric Types} |
| |
| There are two numeric types: integers and floating point numbers. |
| Integers are implemented using {\tt long} in C, so they have at least 32 |
| bits of precision. |
| Floating point numbers are implemented using {\tt double} in C. |
| All bets on precision are off. |
| Numbers are created by numeric constants or as the result of built-in |
| functions and operators. |
| |
| Numeric types support the following operations: |
| |
| \begin{center} |
| \begin{tabular}{|c|l|c|} |
| \hline |
| Operation & Result & Notes \\ |
| \hline |
| {\tt abs}({\em x}) & absolute value of {\em x} & \\ |
| {\tt int}({\em x}) & {\em x} converted to integer & (1) \\ |
| {\tt float}({\em x}) & {\em x} converted to floating point & \\ |
| {\tt -}{\em x} & {\em x} negated & \\ |
| {\tt +}{\em x} & {\em x} unchanged & \\ |
| {\em x}{\tt +}{\em y} & sum of {\em x} and {\em y} & \\ |
| {\em x}{\tt -}{\em y} & difference of {\em x} and {\em y} & \\ |
| {\em x}{\tt *}{\em y} & product of {\em x} and {\em y} & \\ |
| {\em x}{\tt /}{\em y} & quotient of {\em x} and {\em y} & (2) \\ |
| {\em x}{\tt \%}{\em y} & remainder of {\em x}{\tt /}{\em y} & (3) \\ |
| \hline |
| \end{tabular} |
| \end{center} |
| |
| \noindent |
| Notes: |
| \begin{description} |
| \item[(1)] |
| This may round or truncate as in C; see functions {\tt floor} and |
| {\tt ceil} in module {\tt math}. |
| \item[(2)] |
| Integer division is defined as in C: the result is an integer; with |
| positive operands, it truncates towards zero; with a negative operand, |
| the result is unspecified. |
| \item[(3)] |
| Only defined for integers. |
| \end{description} |
| |
| Mixed arithmetic is not supported; both operands must have the same type. |
| Mixed comparisons return the wrong result (floats always compare smaller |
| than integers).% |
| \footnote{ |
| These restrictions are bugs in the language definitions and will be |
| fixed in the future. |
| } |
| \subsubsection{Sequence Types} |
| |
| There are three sequence types: strings, lists and tuples. |
| Strings constants are written in single quotes: {\tt 'xyzzy'}. |
| Lists are constructed with square brackets: {\tt [a,~b,~c]}. |
| Tuples are constructed by the comma operator or with an empty set of |
| parentheses: {\tt a,~b,~c} or {\tt ()}. |
| |
| Sequence types support the following operations ({\em s} and {\em t} are |
| sequences of the same type; {\em n}, {\em i} and {\em j} are integers): |
| |
| \begin{center} |
| \begin{tabular}{|c|l|c|} |
| \hline |
| Operation & Result & Notes \\ |
| \hline |
| {\tt len}({\em s}) & length of {\em s} & \\ |
| {\tt min}({\em s}) & smallest item of {\em s} & \\ |
| {\tt max}({\em s}) & largest item of {\em s} & \\ |
| {\em x} {\tt in} {\em s} & |
| true if an item of {\em s} is equal to {\em x} & \\ |
| {\em x} {\tt not} {\tt in} {\em s} & |
| false if an item of {\em s} is equal to {\em x} & \\ |
| {\em s}{\tt +}{\em t} & the concatenation of {\em s} and {\em t} & \\ |
| {\em s}{\tt *}{\em n}, {\em n}*{\em s} & |
| {\em n} copies of {\em s} concatenated & (1) \\ |
| {\em s}[{\em i}] & {\em i}'th item of {\em s} & \\ |
| {\em s}[{\em i}:{\em j}] & |
| slice of {\em s} from {\em i} to {\em j} & (2) \\ |
| \hline |
| \end{tabular} |
| \end{center} |
| |
| \noindent |
| Notes: |
| \begin{description} |
| \item[(1)] |
| Sequence repetition is only supported for strings. |
| \item[(2)] |
| The slice of $s$ from $i$ to $j$ is defined as the sequence |
| of items with index $k$ such that $i \leq k < j$. |
| Special rules apply for negative and omitted indices; see the Tutorial |
| or the Reference Manual. |
| \end{description} |
| |
| \paragraph{Mutable Sequence Types.} |
| |
| List objects support additional operations that allow in-place |
| modification of the object. |
| These operations would be supported by other mutable sequence types |
| (when added to the language) as well. |
| Strings and tuples are immutable sequence types and such objects cannot |
| be modified once created. |
| The following operations are defined on mutable sequence types (where |
| {\em x} is an arbitrary object): |
| |
| \begin{center} |
| \begin{tabular}{|c|l|} |
| \hline |
| Operation & Result \\ |
| \hline |
| {\em s}[{\em i}] = {\em x} & |
| item {\em i} of {\em s} is replaced by {\em x} \\ |
| {\em s}[{\em i}:{\em j}] = {\em t} & |
| slice of {\em s} from {\em i} to {\em j} is replaced by {\em t} \\ |
| {\tt del} {\em s}[{\em i}:{\em j}] & |
| same as {\em s}[{\em i}:{\em j}] = [] \\ |
| {\em s}.{\tt append}({\em x}) & |
| same as {\em s}[{\tt len}({\em x}):{\tt len}({\em x})] = [{\em x}] \\ |
| {\em s}.{\tt insert}({\em i}, {\em x}) & |
| same as {\em s}[{\em i}:{\em i}] = [{\em x}] \\ |
| {\em s}.{\tt sort}() & |
| the items of {\em s} are permuted to satisfy \\ |
| & |
| $s[i] \leq s[j]$ for $i < j$\\ |
| \hline |
| \end{tabular} |
| \end{center} |
| |
| \subsubsection{Mapping Types} |
| |
| A |
| {\em mapping} |
| object maps values of one type (the key type) to arbitrary objects. |
| Mappings are mutable objects. |
| There is currently only one mapping type, the |
| {\em dictionary}. |
| A dictionary's keys are strings. |
| An empty dictionary is created by the expression \verb"{}". |
| An extension of this notation is used to display dictionaries when |
| written (see the example below). |
| |
| The following operations are defined on mappings (where {\em a} is a |
| mapping, {\em k} is a key and {\em x} is an arbitrary object): |
| |
| \begin{center} |
| \begin{tabular}{|c|l|c|} |
| \hline |
| Operation & Result & Notes\\ |
| \hline |
| {\tt len}({\em a}) & the number of elements in {\em a} & \\ |
| {\em a}[{\em k}] & the item of {\em a} with key {\em k} & \\ |
| {\em a}[{\em k}] = {\em x} & set {\em a}[{\em k}] to {\em x} & \\ |
| {\tt del} {\em a}[{\em k}] & remove {\em a}[{\em k}] from {\em a} & \\ |
| {\em a}.{\tt keys}() & a copy of {\em a}'s list of keys & (1) \\ |
| {\em a}.{\tt has\_key}({\em k}) & true if {\em a} has a key {\em k} & \\ |
| \hline |
| \end{tabular} |
| \end{center} |
| |
| \noindent |
| Notes: |
| \begin{description} |
| \item[(1)] |
| Keys are listed in random order. |
| \end{description} |
| |
| A small example using a dictionary: |
| \begin{code}\begin{verbatim} |
| >>> tel = {} |
| >>> tel['jack'] = 4098 |
| >>> tel['sape'] = 4139 |
| >>> tel['guido'] = 4127 |
| >>> tel['jack'] |
| 4098 |
| >>> tel |
| {'sape': 4139; 'guido': 4127; 'jack': 4098} |
| >>> del tel['sape'] |
| >>> tel['irv'] = 4127 |
| >>> tel |
| {'guido': 4127; 'irv': 4127; 'jack': 4098} |
| >>> tel.keys() |
| ['guido', 'irv', 'jack'] |
| >>> tel.has_key('guido') |
| 1 |
| >>> |
| \end{verbatim}\end{code} |
| \subsubsection{Other Built-in Types} |
| |
| The interpreter supports several other kinds of objects. |
| Most of these support only one or two operations. |
| |
| \paragraph{Modules.} |
| |
| The only operation on a module is member acces: {\em m}{\tt .}{\em name}, |
| where {\em m} is a module and {\em name} accesses a name defined in |
| {\em m}'s symbol table. |
| Module members can be assigned to. |
| |
| \paragraph{Classes and Class Objects.} |
| |
| XXX Classes will be explained at length in a later version of this |
| document. |
| |
| \paragraph{Functions.} |
| |
| Function objects are created by function definitions. |
| The only operation on a function object is to call it: |
| {\em func}({\em optional-arguments}). |
| |
| Built-in functions have a different type than user-defined functions, |
| but they support the same operation. |
| |
| \paragraph{Methods.} |
| |
| Methods are functions that are called using the member acces notation. |
| There are two flavors: built-in methods (such as {\tt append()} on |
| lists) and class member methods. |
| Built-in methods are described with the types that support them. |
| XXX Class member methods will be described in a later version of this |
| document. |
| |
| \paragraph{Type Objects.} |
| |
| Type objects represent the various object types. |
| An object's type is accessed by the built-in function |
| {\tt type()}. |
| There are no operations on type objects. |
| |
| \paragraph{The Null Object.} |
| |
| This object is returned by functions that don't explicitly return a |
| value. |
| It supports no operations. |
| There is exactly one null object. |
| |
| \paragraph{File Objects.} |
| |
| File objects are implemented using C's |
| {\em stdio} |
| package and can be created with the built-in function |
| {\tt open()}. |
| They have the following methods: |
| \begin{description} |
| \item[{\tt close()}] |
| Closes the file. |
| A closed file cannot be read or written anymore. |
| \item[{\tt read(size)}] |
| Reads at most |
| {\tt size} |
| bytes from the file (less if the read hits EOF). |
| The bytes are returned as a string object. |
| An empty string is returned when EOF is hit immediately. |
| (For certain files, like ttys, it makes sense to continue reading after |
| an EOF is hit.) |
| \item[{\tt readline(size)}] |
| Reads a line of at most |
| {\tt size} |
| bytes from the file. |
| A trailing newline character, if present, is kept in the string. |
| The size is optional and defaults to a large number (but not infinity). |
| EOF is reported as by |
| {\tt read().} |
| \item[{\tt write(str)}] |
| Writes a string to the file. |
| Returns no value. |
| \end{description} |
| |
| \subsection{Built-in Exceptions} |
| |
| The following exceptions can be generated by the interpreter or |
| built-in functions. |
| Except where mentioned, they have a string argument (also known as the |
| `associated value' of an exception) indicating the detailed cause of the |
| error. |
| The strings listed with the exception names are their values when used |
| in an expression or printed. |
| \begin{description} |
| \item[{\tt EOFError = 'end-of-file read'} (no argument)] |
| %.br |
| Raised when a built-in function ({\tt input()} or {\tt raw\_input()}) |
| hits an end-of-file condition (EOF) without reading any data. |
| (N.B.: the {\tt read()} and {\tt readline()} methods of file objects |
| return an empty string when they hit EOF.) |
| \item[{\tt KeyboardInterrupt = 'end-of-file read'} (no argument)] |
| %.br |
| Raised when the user hits the interrupt key (normally Control-C or DEL). |
| During execution, a check for interrupts is made regularly. |
| Interrupts typed when a built-in function ({\tt input()} or |
| {\tt raw\_input()}) is waiting for input also raise this exception. |
| \item[{\tt MemoryError = 'out of memory'}] |
| %.br |
| Raised when an operation runs out of memory but the situation |
| may still be rescued (by deleting some objects). |
| \item[{\tt NameError = 'undefined name'}] |
| %.br |
| Raised when a name is not found. |
| This applies to unqualified names, module names (on {\tt import}), |
| module members and object methods. |
| The string argument is the name that could not be found. |
| \item[{\tt RuntimeError = 'run-time error'}] |
| %.br |
| Raised for a variety of reasons, e.g., division by zero or index out of |
| range. |
| \item[{\tt SystemError = 'system error'}] |
| %.br |
| Raised when the interpreter finds an internal error, but the situation |
| does not look so serious to cause it to abandon all hope. |
| \item[{\tt TypeError = 'type error'}] |
| %.br |
| Raised when an operation or built-in function is applied to an object of |
| inappropriate type. |
| \end{description} |
| |
| \subsection{Built-in Functions} |
| |
| The {\Python} interpreter has a small number of functions built into it that |
| are always available. |
| They are listed here in alphabetical order. |
| \begin{description} |
| \item[{\tt abs(x)}] |
| Returns the absolute value of a number. |
| The argument may be an integer or floating point number. |
| \item[{\tt dir()}] |
| Without arguments, this function returns the list of names in the |
| current local symbol table, sorted alphabetically. |
| With a module object as argument, it returns the sorted list of names in |
| that module's global symbol table. |
| For example: |
| \begin{code}\begin{verbatim} |
| >>> import sys |
| >>> dir() |
| ['sys'] |
| >>> dir(sys) |
| ['argv', 'exit', 'modules', 'path', 'stderr', 'stdin', 'stdout'] |
| >>> |
| \end{verbatim}\end{code} |
| \item[{\tt divmod(a, b)}] |
| %.br |
| Takes two integers as arguments and returns a pair of integers |
| consisting of their quotient and remainder. |
| For |
| \begin{code}\begin{verbatim} |
| q, r = divmod(a, b) |
| \end{verbatim}\end{code} |
| the invariants are: |
| \begin{code}\begin{verbatim} |
| a = q*b + r |
| abs(r) < abs(b) |
| r has the same sign as b |
| \end{verbatim}\end{code} |
| For example: |
| \begin{code}\begin{verbatim} |
| >>> divmod(100, 7) |
| (14, 2) |
| >>> divmod(-100, 7) |
| (-15, 5) |
| >>> divmod(100, -7) |
| (-15, -5) |
| >>> divmod(-100, -7) |
| (14, -2) |
| >>> |
| \end{verbatim}\end{code} |
| \item[{\tt eval(s)}] |
| Takes a string as argument and parses and evaluates it as a {\Python} |
| expression. |
| The expression is executed using the current local and global symbol |
| tables. |
| Syntax errors are reported as exceptions. |
| For example: |
| \begin{code}\begin{verbatim} |
| >>> x = 1 |
| >>> eval('x+1') |
| 2 |
| >>> |
| \end{verbatim}\end{code} |
| \item[{\tt exec(s)}] |
| Takes a string as argument and parses and evaluates it as a sequence of |
| {\Python} statements. |
| The string should end with a newline (\verb"'\n'"). |
| The statement is executed using the current local and global symbol |
| tables. |
| Syntax errors are reported as exceptions. |
| For example: |
| \begin{code}\begin{verbatim} |
| >>> x = 1 |
| >>> exec('x = x+1\n') |
| >>> x |
| 2 |
| >>> |
| \end{verbatim}\end{code} |
| \item[{\tt float(x)}] |
| Converts a number to floating point. |
| The argument may be an integer or floating point number. |
| \item[{\tt input(s)}] |
| Equivalent to |
| {\tt eval(raw\_input(s))}. |
| As for |
| {\tt raw\_input()}, |
| the argument is optional. |
| \item[{\tt len(s)}] |
| Returns the length (the number of items) of an object. |
| The argument may be a sequence (string, tuple or list) or a mapping |
| (dictionary). |
| \item[{\tt max(s)}] |
| Returns the largest item of a non-empty sequence (string, tuple or list). |
| \item[{\tt min(s)}] |
| Returns the smallest item of a non-empty sequence (string, tuple or list). |
| \item[{\tt open(name, mode)}] |
| %.br |
| Returns a file object (described earlier under Built-in Types). |
| The string arguments are the same as for stdio's |
| {\tt fopen()}: |
| {\tt 'r'} |
| opens the file for reading, |
| {\tt 'w'} |
| opens it for writing (truncating an existing file), |
| {\tt 'a'} |
| opens it for appending.% |
| \footnote{ |
| This function should go into a built-in module |
| {\tt io}. |
| } |
| \item[{\tt range()}] |
| This is a versatile function to create lists containing arithmetic |
| progressions of integers. |
| With two integer arguments, it returns the ascending sequence of |
| integers starting at the first and ending one before the second |
| argument. |
| A single argument is used as the end point of the sequence, with 0 used |
| as the starting point. |
| A third argument specifies the step size; negative steps are allowed and |
| work as expected, but don't specify a zero step. |
| The resulting list may be empty. |
| For example: |
| \begin{code}\begin{verbatim} |
| >>> range(10) |
| [0, 1, 2, 3, 4, 5, 6, 7, 8, 9] |
| >>> range(1, 1+10) |
| [1, 2, 3, 4, 5, 6, 7, 8, 9, 10] |
| >>> range(0, 30, 5) |
| [0, 5, 10, 15, 20, 25] |
| >>> range(0, 10, 3) |
| [0, 3, 6, 9] |
| >>> range(0, -10, -1) |
| [0, -1, -2, -3, -4, -5, -6, -7, -8, -9] |
| >>> range(0) |
| [] |
| >>> range(1, 0) |
| [] |
| >>> |
| \end{verbatim}\end{code} |
| \item[{\tt raw\_input(s)}] |
| %.br |
| The argument is optional; if present, it is written to standard output |
| without a trailing newline. |
| The function then reads a line from input, converts it to a string |
| (stripping a trailing newline), and returns that. |
| EOF is reported as an exception. |
| For example: |
| \begin{code}\begin{verbatim} |
| >>> raw_input('Type anything: ') |
| Type anything: Teenage Mutant Ninja Turtles |
| 'Teenage Mutant Ninja Turtles' |
| >>> |
| \end{verbatim}\end{code} |
| \item[{\tt type(x)}] |
| Returns the type of an object. |
| Types are objects themselves: |
| the type of a type object is its own type. |
| \end{description} |
| |
| \section{Built-in Modules} |
| |
| The modules described in this section are built into the interpreter. |
| They must be imported using |
| {\tt import}. |
| Some modules are not always available; it is a configuration option to |
| provide them. |
| Details are listed with the descriptions, but the best way to see if |
| a module exists in a particular implementation is to attempt to import |
| it. |
| |
| \subsection{Built-in Module {\tt sys}} |
| |
| This module provides access to some variables used or maintained by the |
| interpreter and to functions that interact strongly with the interpreter. |
| It is always available. |
| \begin{description} |
| \item[{\tt argv}] |
| The list of command line arguments passed to a {\Python} script. |
| {\tt sys.argv[0]} |
| is the script name. |
| If no script name was passed to the {\Python} interpreter, |
| {\tt sys.argv} |
| is empty. |
| \item[{\tt exit(n)}] |
| Exits from {\Python} with numeric exit status |
| {\tt n}. |
| This closes all open files and performs other cleanup-actions required by |
| the interpreter (but |
| {\em finally clauses} |
| of |
| {\tt try} |
| statements are not executed!). |
| \item[{\tt modules}] |
| Gives the list of modules that have already been loaded. |
| This can be manipulated to force reloading of modules and other tricks. |
| \item[{\tt path}] |
| A list of strings that specifies the search path for modules. |
| Initialized from the environment variable {\tt PYTHONPATH}, or an |
| installation-dependent default. |
| \item[{\tt ps1,~ps2}] |
| Strings specifying the primary and secondary prompt of the interpreter. |
| These are only defined if the interpreter is in interactive mode. |
| Their initial values in this case are |
| {\tt '>>> '} |
| and |
| {\tt '... '}. |
| \item[{\tt stdin, stdout, stderr}] |
| %.br |
| File objects corresponding to the interpreter's standard input, output |
| and error streams. |
| {\tt sys.stdin} |
| is used for all interpreter input except for scripts but including calls |
| to |
| {\tt input()} |
| and |
| {\tt raw\_input()}. |
| {\tt sys.stdout} |
| is used for the output of |
| {\tt print} and expression statements |
| and for the prompts of |
| {\tt input()} |
| and |
| {\tt raw\_input()}. |
| The interpreter's own prompts and its error messages are written to |
| stderr. |
| Assigning to |
| {\tt sys.stderr} |
| has no effect on the interpreter; it can be used to write error messages |
| to stderr using |
| {\tt print}. |
| \end{description} |
| |
| \subsection{Built-in Module {\tt math}} |
| |
| This module is always available. |
| It provides access to the mathematical functions defined by the C |
| standard. |
| They are: |
| {\tt acos(x)}, |
| {\tt asin(x)}, |
| {\tt atan(x)}, |
| {\tt atan2(x,y)}, |
| {\tt ceil(x)}, |
| {\tt cos(x)}, |
| {\tt cosh(x)}, |
| {\tt exp(x)}, |
| {\tt fabs(x)}, |
| {\tt floor(x)}, |
| %{\tt fmod(...)} XXX not yet |
| %{\tt frexp(...)} XXX not yet |
| %{\tt ldexp(...)} XXX not yet |
| {\tt log(x)}, |
| {\tt log10(x)}, |
| %{\tt modf(...)} XXX not yet |
| {\tt pow(x,y)}, |
| {\tt sin(x)}, |
| {\tt sinh(x)}, |
| {\tt sqrt(x)}, |
| {\tt tan(x)}, |
| {\tt tanh(x)}. |
| |
| It also defines two mathematical constants: |
| {\tt pi} |
| and |
| {\tt e}. |
| |
| \subsection{Built-in Module {\tt time}} |
| |
| This module provides various time-related functions. |
| It is always available. |
| Functions are: |
| \begin{description} |
| \item[{\tt sleep(secs)}] |
| Suspends execution for the given number of seconds. |
| \item[{\tt time()}] |
| Returns the time in seconds since the Epoch (Thursday January 1, |
| 00:00:00, 1970 UCT on \UNIX\ machines). |
| \end{description} |
| |
| \noindent |
| In some versions (Amoeba, Mac) the following functions also exist: |
| \begin{description} |
| \item[{\tt millisleep(msecs)}] |
| Suspends execution for the given number of milliseconds. |
| \item[{\tt millitimer()}] |
| Returns the number of milliseconds of real time elapsed since some point |
| in the past that is fixed per execution of the python interpreter (but |
| may change in each following run). |
| \end{description} |
| |
| \noindent |
| The granularity of the milliseconds functions may be more than a |
| millisecond (100 msecs on Amoeba, 1/60 sec on the Mac). |
| |
| \subsection{Built-in Module {\tt posix}} |
| |
| This module provides access to operating system functionality that is |
| standardized by the C Standard and the POSIX standard (a thinly diguised |
| {\UNIX} interface). |
| It is available in all {\Python} versions except on the Macintosh. |
| Errors are reported exceptions. |
| It defines the following items: |
| \begin{description} |
| \item[{\tt chdir(path)}] |
| Changes the current directory to |
| {\tt path}. |
| \item[{\tt chmod(path, mode)}] |
| Change the mode of |
| {\tt path} |
| to the numeric |
| {\tt mode}. |
| \item[{\tt environ}] |
| A dictionary representing the string environment at the time |
| the interpreter was started. |
| (Modifying this dictionary does not affect the string environment of the |
| interpreter.) |
| For example, |
| {\tt posix.environ['HOME']} |
| is the pathname of your home directory, equivalent to |
| {\tt getenv("HOME")} |
| in C. |
| \item[{\tt error = 'posix.error'}] |
| %.br |
| The exception raised when an POSIX function returns an error. |
| The value accompanying this exception is a pair containing the numeric |
| error code from |
| {\tt errno} |
| and the corresponding string, as would be printed by the C function |
| {\tt perror()}. |
| \item[{\tt getcwd()}] |
| Returns a string representing the current working directory. |
| \item[{\tt link(src, dst)}] |
| Creates a hard link pointing to |
| {\tt src} |
| named |
| {\tt dst}. |
| \item[{\tt listdir(path)}] |
| Returns a list containing the names of the entries in the |
| directory. |
| The list is in arbitrary order. |
| It includes the special entries |
| {\tt '.'} |
| and |
| {\tt '..'} |
| if they are present in the directory. |
| \item[{\tt mkdir(path, mode)}] |
| Creates a directory named |
| {\tt path} |
| with numeric mode |
| {\tt mode}. |
| \item[{\tt rename(src, dst)}] |
| Renames the file or directory |
| {\tt src} |
| to |
| {\tt dst}. |
| \item[{\tt rmdir(path)}] |
| Removes the directory |
| {\tt path}. |
| \item[{\tt stat(path)}] |
| Performs a |
| {\em stat} |
| system call on the given path. |
| The return value is a tuple of at least 10 integers giving the most |
| important (and portable) members of the |
| {\em stat} |
| structure, in the order |
| {\tt st\_mode}, |
| {\tt st\_ino}, |
| {\tt st\_dev}, |
| {\tt st\_nlink}, |
| {\tt st\_uid}, |
| {\tt st\_gid}, |
| {\tt st\_size}, |
| {\tt st\_atime}, |
| {\tt st\_mtime}, |
| {\tt st\_ctime}. |
| More items may be added at the end by some implementations. |
| \item[{\tt system(command)}] |
| Executes the command (a string) in a subshell. |
| This is implemented by calling the Standard C function |
| {\tt system()}, |
| and has the same limitations. |
| Changes to |
| {\tt posix.environ}, |
| {\tt sys.stdin} |
| etc. are not reflected in the environment of the executed command. |
| The return value is the exit status of the process as returned by |
| Standard C |
| {\tt system()}. |
| \item[{\tt umask(mask)}] |
| Sets the current numeric umask and returns the previous umask. |
| \item[{\tt unlink(path)}] |
| Unlinks the file |
| {\tt path}. |
| \item[{\tt utimes(path, (atime, mtime))}] |
| %.br |
| Sets the access and modified time of the file to the given values. |
| (The second argument is a tuple of two items.) |
| \end{description} |
| |
| The following functions are only available on systems that support |
| symbolic links: |
| \begin{description} |
| \item[{\tt lstat(path)}] |
| Like |
| {\tt stat()}, |
| but does not follow symbolic links. |
| \item[{\tt readlink(path)}] |
| Returns a string representing the path to which the symbolic link |
| points. |
| \item[{\tt symlink(src, dst)}] |
| Creates a symbolic link pointing to |
| {\tt src} |
| named |
| {\tt dst}. |
| \end{description} |
| |
| \subsection{Built-in Module {\tt stdwin}} |
| |
| This module defines several new object types and functions that |
| provide access to the functionality of the Standard Window System |
| Interface, STDWIN [CWI report CR-R8817]. |
| It is available on systems to which STDWIN has been ported (which is |
| most systems). |
| It is only available if the {\tt DISPLAY} environment variable is set |
| or an explicit `{\tt -display \it displayname}' argument is passed to |
| the interpreter. |
| |
| Functions have names that usually resemble their C STDWIN counterparts |
| with the initial `w' dropped. |
| Points are represented by pairs of integers; rectangles |
| by pairs of points. |
| For a complete description of STDWIN please refer to the documentation |
| of STDWIN for C programmers (aforementioned CWI report). |
| \subsubsection{Functions Defined in Module {\tt stdwin}} |
| |
| The following functions are defined in the {\tt stdwin} module: |
| \begin{description} |
| \item[{\tt open(title)}] |
| %.br |
| Opens a new window whose initial title is given by the string argument. |
| Returns a window object; window object methods are described below.% |
| \footnote{ |
| The {\Python} version of STDWIN does not support draw procedures; all |
| drawing requests are reported as draw events. |
| } |
| \item[{\tt getevent()}] |
| %.br |
| Waits for and returns the next event. |
| An event is returned as a triple: the first element is the event |
| type, a small integer; the second element is the window object to which |
| the event applies, or |
| {\tt None} |
| if it applies to no window in particular; |
| the third element is type-dependent. |
| Names for event types and command codes are defined in the standard |
| module |
| {\tt stdwinevent}. |
| \item[{\tt setdefwinpos(h, v)}] |
| %.br |
| Sets the default window position. |
| \item[{\tt setdefwinsize(width, height)}] |
| %.br |
| Sets the default window size. |
| \item[{\tt menucreate(title)}] |
| %.br |
| Creates a menu object referring to a global menu (a menu that appears in |
| all windows). |
| Methods of menu objects are described below. |
| \item[{\tt fleep()}] |
| %.br |
| Causes a beep or bell (or perhaps a `visual bell' or flash, hence the |
| name). |
| \item[{\tt message(string)}] |
| %.br |
| Displays a dialog box containing the string. |
| The user must click OK before the function returns. |
| \item[{\tt askync(prompt, default)}] |
| %.br |
| Displays a dialog that prompts the user to answer a question with yes or |
| no. |
| The function returns 0 for no, 1 for yes. |
| If the user hits the Return key, the default (which must be 0 or 1) is |
| returned. |
| If the user cancels the dialog, the |
| {\tt KeyboardInterrupt} |
| exception is raised. |
| \item[{\tt askstr(prompt, default)}] |
| %.br |
| Displays a dialog that prompts the user for a string. |
| If the user hits the Return key, the default string is returned. |
| If the user cancels the dialog, the |
| {\tt KeyboardInterrupt} |
| exception is raised. |
| \item[{\tt askfile(prompt, default, new)}] |
| %.br |
| Asks the user to specify a filename. |
| If |
| {\tt new} |
| is zero it must be an existing file; otherwise, it must be a new file. |
| If the user cancels the dialog, the |
| {\tt KeyboardInterrupt} |
| exception is raised. |
| \item[{\tt setcutbuffer(i, string)}] |
| %.br |
| Stores the string in the system's cut buffer number |
| {\tt i}, |
| where it can be found (for pasting) by other applications. |
| On X11, there are 8 cut buffers (numbered 0..7). |
| Cut buffer number 0 is the `clipboard' on the Macintosh. |
| \item[{\tt getcutbuffer(i)}] |
| %.br |
| Returns the contents of the system's cut buffer number |
| {\tt i}. |
| \item[{\tt rotatebutbuffers(n)}] |
| %.br |
| On X11, this rotates the 8 cut buffers by |
| {\tt n}. |
| Ignored on the Macintosh. |
| \item[{\tt getselection(i)}] |
| %.br |
| Returns X11 selection number |
| {\tt i.} |
| Selections are not cut buffers. |
| Selection numbers are defined in module |
| {\tt stdwinevents}. |
| Selection {\tt WS\_PRIMARY} is the |
| {\em primary} |
| selection (used by |
| xterm, |
| for instance); |
| selection {\tt WS\_SECONDARY} is the |
| {\em secondary} |
| selection; selection {\tt WS\_CLIPBOARD} is the |
| {\em clipboard} |
| selection (used by |
| xclipboard). |
| On the Macintosh, this always returns an empty string. |
| \item[{\tt resetselection(i)}] |
| %.br |
| Resets selection number |
| {\tt i}, |
| if this process owns it. |
| (See window method |
| {\tt setselection()}). |
| \item[{\tt baseline()}] |
| %.br |
| Return the baseline of the current font (defined by STDWIN as the |
| vertical distance between the baseline and the top of the |
| characters).% |
| \footnote{ |
| There is no way yet to set the current font. |
| This will change in a future version. |
| } |
| \item[{\tt lineheight()}] |
| %.br |
| Return the total line height of the current font. |
| \item[{\tt textbreak(str, width)}] |
| %.br |
| Return the number of characters of the string that fit into a space of |
| {\tt width} |
| bits wide when drawn in the curent font. |
| \item[{\tt textwidth(str)}] |
| %.br |
| Return the width in bits of the string when drawn in the current font. |
| \subsubsection{Window Object Methods} |
| \end{description} |
| |
| Window objects are created by |
| {\tt stdwin.open()}. |
| There is no explicit function to close a window; windows are closed when |
| they are garbage-collected. |
| Window objects have the following methods: |
| \begin{description} |
| \item[{\tt begindrawing()}] |
| Returns a drawing object, whose methods (described below) allow drawing |
| in the window. |
| \item[{\tt change(rect)}] |
| Invalidates the given rectangle; this may cause a draw event. |
| \item[{\tt gettitle()}] |
| Returns the window's title string. |
| \item[{\tt getdocsize()}] |
| Returns a pair of integers giving the size of the document as set by |
| {\tt setdocsize()}. |
| \item[{\tt getorigin()}] |
| Returns a pair of integers giving the origin of the window with respect |
| to the document. |
| \item[{\tt getwinsize()}] |
| Returns a pair of integers giving the size of the window. |
| \item[{\tt menucreate(title)}] |
| Creates a menu object referring to a local menu (a menu that appears |
| only in this window). |
| Methods menu objects are described below. |
| \item[{\tt scroll(rect,~point)}] |
| Scrolls the given rectangle by the vector given by the point. |
| \item[{\tt setwincursor(name)}] |
| Sets the window cursor to a cursor of the given name. |
| It raises the |
| {\tt Runtime\-Error} |
| exception if no cursor of the given name exists. |
| Suitable names are |
| {\tt 'ibeam'}, |
| {\tt 'arrow'}, |
| {\tt 'cross'}, |
| {\tt 'watch'} |
| and |
| {\tt 'plus'}. |
| On X11, there are many more (see |
| {\tt <X11/cursorfont.h>}). |
| \item[{\tt setdocsize(point)}] |
| Sets the size of the drawing document. |
| \item[{\tt setorigin(point)}] |
| Moves the origin of the window to the given point in the document. |
| \item[{\tt setselection(i, str)}] |
| Attempts to set X11 selection number |
| {\tt i} |
| to the string |
| {\tt str}. |
| (See stdwin method |
| {\tt getselection()} |
| for the meaning of |
| {\tt i}.) |
| Returns true if it succeeds. |
| If it succeeds, the window ``owns'' the selection until |
| (a) another applications takes ownership of the selection; or |
| (b) the window is deleted; or |
| (c) the application clears ownership by calling |
| {\tt stdwin.resetselection(i)}. |
| When another application takes ownership of the selection, a |
| {\tt WE\_LOST\_SEL} |
| event is received for no particular window and with the selection number |
| as detail. |
| Ignored on the Macintosh. |
| \item[{\tt settitle(title)}] |
| Sets the window's title string. |
| \item[{\tt settimer(dsecs)}] |
| Schedules a timer event for the window in |
| {\tt dsecs/10} |
| seconds. |
| \item[{\tt show(rect)}] |
| Tries to ensure that the given rectangle of the document is visible in |
| the window. |
| \item[{\tt textcreate(rect)}] |
| Creates a text-edit object in the document at the given rectangle. |
| Methods of text-edit objects are described below. |
| \end{description} |
| |
| \subsubsection{Drawing Object Methods} |
| |
| Drawing objects are created exclusively by the window method |
| {\tt begindrawing()}. |
| Only one drawing object can exist at any given time; the drawing object |
| must be deleted to finish drawing. |
| No drawing object may exist when |
| {\tt stdwin.getevent()} |
| is called. |
| Drawing objects have the following methods: |
| \begin{description} |
| \item[{\tt box(rect)}] |
| Draws a box around a rectangle. |
| \item[{\tt circle(center, radius)}] |
| %.br |
| Draws a circle with given center point and radius. |
| \item[{\tt elarc(center, (rh, rv), (a1, a2))}] |
| %.br |
| Draws an elliptical arc with given center point. |
| {\tt (rh, rv)} |
| gives the half sizes of the horizontal and vertical radii. |
| {\tt (a1, a2)} |
| gives the angles (in degrees) of the begin and end points. |
| 0 degrees is at 3 o'clock, 90 degrees is at 12 o'clock. |
| \item[{\tt erase(rect)}] |
| Erases a rectangle. |
| \item[{\tt invert(rect)}] |
| Inverts a rectangle. |
| \item[{\tt line(p1, p2)}] |
| Draws a line from point |
| {\tt p1} |
| to |
| {\tt p2}. |
| \item[{\tt paint(rect)}] |
| Fills a rectangle. |
| \item[{\tt text(p, str)}] |
| Draws a string starting at point p (the point specifies the |
| top left coordinate of the string). |
| \item[{\tt shade(rect, percent)}] |
| %.br |
| Fills a rectangle with a shading pattern that is about |
| {\tt percent} |
| percent filled. |
| \item[{\tt xorline(p1, p2)}] |
| Draws a line in XOR mode. |
| \item[{\tt baseline(), lineheight(), textbreak(), textwidth()}] |
| %.br |
| These functions are similar to the corresponding functions described |
| above for the |
| {\tt stdwin} |
| module, but use the current font of the window instead of the (global) |
| default font. |
| \end{description} |
| |
| \subsubsection{Menu Object Methods} |
| |
| A menu object represents a menu. |
| The menu is destroyed when the menu object is deleted. |
| The following methods are defined: |
| \begin{description} |
| \item[{\tt additem(text, shortcut)}] |
| %.br |
| Adds a menu item with given text. |
| The shortcut must be a string of length 1, or omitted (to specify no |
| shortcut). |
| \item[{\tt setitem(i, text)}] |
| Sets the text of item number |
| {\tt i}. |
| \item[{\tt enable(i, flag)}] |
| Enables or disables item |
| {\tt i}. |
| \item[{\tt check(i, flag)}] |
| Sets or clears the |
| {\em check mark} |
| for item |
| {\tt i}. |
| \end{description} |
| |
| \subsubsection{Text-edit Object Methods} |
| |
| A text-edit object represents a text-edit block. |
| For semantics, see the STDWIN documentation for C programmers. |
| The following methods exist: |
| \begin{description} |
| \item[{\tt arrow(code)}] |
| Passes an arrow event to the text-edit block. |
| The |
| {\tt code} |
| must be one of |
| {\tt WC\_LEFT}, |
| {\tt WC\_RIGHT}, |
| {\tt WC\_UP} |
| or |
| {\tt WC\_DOWN} |
| (see module |
| {\tt stdwinevents}). |
| \item[{\tt draw(rect)}] |
| Passes a draw event to the text-edit block. |
| The rectangle specifies the redraw area. |
| \item[{\tt event(type, window, detail)}] |
| %.br |
| Passes an event gotten from |
| {\tt stdwin.getevent()} |
| to the text-edit block. |
| Returns true if the event was handled. |
| \item[{\tt getfocus()}] |
| Returns 2 integers representing the start and end positions of the |
| focus, usable as slice indices on the string returned by |
| {\tt getfocustext()}. |
| \item[{\tt getfocustext()}] |
| Returns the text in the focus. |
| \item[{\tt getrect()}] |
| Returns a rectangle giving the actual position of the text-edit block. |
| (The bottom coordinate may differ from the initial position because |
| the block automatically shrinks or grows to fit.) |
| \item[{\tt gettext()}] |
| Returns the entire text buffer. |
| \item[{\tt move(rect)}] |
| Specifies a new position for the text-edit block in the document. |
| \item[{\tt replace(str)}] |
| Replaces the focus by the given string. |
| The new focus is an insert point at the end of the string. |
| \item[{\tt setfocus(i,~j)}] |
| Specifies the new focus. |
| Out-of-bounds values are silently clipped. |
| \end{description} |
| |
| \subsection{Built-in Module {\tt amoeba}} |
| |
| This module provides some object types and operations useful for |
| Amoeba applications. |
| It is only available on systems that support Amoeba operations. |
| RPC errors and other Amoeba errors are reported as the exception |
| {\tt amoeba.error = 'amoeba.error'}. |
| The module |
| {\tt amoeba} |
| defines the following items: |
| \begin{description} |
| \item[{\tt name\_append(path,~cap)}] |
| %.br |
| Stores a capability in the Amoeba directory tree. |
| Arguments are the pathname (a string) and the capability (a capability |
| object as returned by |
| {\tt name\_lookup()}). |
| \item[{\tt name\_delete(path)}] |
| %.br |
| Deletes a capability from the Amoeba directory tree. |
| Argument is the pathname. |
| \item[{\tt name\_lookup(path)}] |
| %.br |
| Looks up a capability. |
| Argument is the pathname. |
| Returns a |
| {\em capability} |
| object, to which various interesting operations apply, described below. |
| \item[{\tt name\_replace(path,~cap)}] |
| %.br |
| Replaces a capability in the Amoeba directory tree. |
| Arguments are the pathname and the new capability. |
| (This differs from |
| {\tt name\_append()} |
| in the behavior when the pathname already exists: |
| {\tt name\_append()} |
| finds this an error while |
| {\tt name\_replace()} |
| allows it, as its name suggests.) |
| \item[{\tt capv}] |
| A table representing the capability environment at the time the |
| interpreter was started. |
| (Alas, modifying this table does not affect the capability environment |
| of the interpreter.) |
| For example, |
| {\tt amoeba.capv['ROOT']} |
| is the capability of your root directory, similar to |
| {\tt getcap("ROOT")} |
| in C. |
| \item[{\tt error = 'amoeba.error'}] |
| %.br |
| The exception raised when an Amoeba function returns an error. |
| The value accompanying this exception is a pair containing the numeric |
| error code and the corresponding string, as returned by the C function |
| {\tt err\_why()}. |
| \item[{\tt timeout(msecs)}] |
| %.br |
| Sets the transaction timeout, in milliseconds. |
| Returns the previous timeout. |
| Initially, the timeout is set to 2 seconds by the {\Python} interpreter. |
| \end{description} |
| |
| \subsubsection{Capability Operations} |
| |
| Capabilities are written in a convenient ASCII format, also used by the |
| Amoeba utilities |
| {\em c2a}(U) |
| and |
| {\em a2c}(U). |
| For example: |
| \begin{code}\begin{verbatim} |
| >>> amoeba.name_lookup('/profile/cap') |
| aa:1c:95:52:6a:fa/14(ff)/8e:ba:5b:8:11:1a |
| >>> |
| \end{verbatim}\end{code} |
| The following methods are defined for capability objects. |
| \begin{description} |
| \item[{\tt dir\_list()}] |
| Returns a list of the names of the entries in an Amoeba directory. |
| \item[{\tt b\_read(offset, maxsize)}] |
| %.br |
| Reads (at most) |
| {\tt maxsize} |
| bytes from a bullet file at offset |
| {\tt offset.} |
| The data is returned as a string. |
| EOF is reported as an empty string. |
| \item[{\tt b\_size()}] |
| Returns the size of a bullet file. |
| \item[{\tt dir\_append(), dir\_delete(), dir\_lookup(), dir\_replace()}] |
| %.br |
| Like the corresponding |
| {\tt name\_*} |
| functions, but with a path relative to the capability. |
| (For paths beginning with a slash the capability is ignored, since this |
| is the defined semantics for Amoeba.) |
| \item[{\tt std\_info()}] |
| Returns the standard info string of the object. |
| \item[{\tt tod\_gettime()}] |
| Returns the time (in seconds since the Epoch, in UCT, as for POSIX) from |
| a time server. |
| \item[{\tt tod\_settime(t)}] |
| Sets the time kept by a time server. |
| \end{description} |
| |
| \subsection{Built-in Module {\tt audio}} |
| |
| This module provides rudimentary access to the audio I/O device |
| {\tt /dev/audio} |
| on the Silicon Graphics Personal IRIS; see audio(7). |
| It supports the following operations: |
| \begin{description} |
| \item[{\tt setoutgain(n)}] |
| Sets the output gain (0-255). |
| \item[{\tt getoutgain()}] |
| Returns the output gain. |
| \item[{\tt setrate(n)}] |
| Sets the sampling rate: 1=32K/sec, 2=16K/sec, 3=8K/sec. |
| \item[{\tt setduration(n)}] |
| Sets the `sound duration' in units of 1/100 seconds. |
| \item[{\tt read(n)}] |
| Reads a chunk of |
| {\tt n} |
| sampled bytes from the audio input (line in or microphone). |
| The chunk is returned as a string of length n. |
| Each byte encodes one sample as a signed 8-bit quantity using linear |
| encoding. |
| This string can be converted to numbers using {\tt chr2num()} described |
| below. |
| \item[{\tt write(buf)}] |
| Writes a chunk of samples to the audio output (speaker). |
| \end{description} |
| |
| These operations support asynchronous audio I/O: |
| \begin{description} |
| \item[{\tt start\_recording(n)}] |
| %.br |
| Starts a second thread (a process with shared memory) that begins reading |
| {\tt n} |
| bytes from the audio device. |
| The main thread immediately continues. |
| \item[{\tt wait\_recording()}] |
| %.br |
| Waits for the second thread to finish and returns the data read. |
| \item[{\tt stop\_recording()}] |
| %.br |
| Makes the second thread stop reading as soon as possible. |
| Returns the data read so far. |
| \item[{\tt poll\_recording()}] |
| %.br |
| Returns true if the second thread has finished reading (so |
| {\tt wait\_recording()} would return the data without delay). |
| \item[{\tt start\_playing(chunk)}, {\tt wait\_playing()}, |
| {\tt stop\_playing()}, {\tt poll\_playing()}] |
| %.br |
| Similar but for output. |
| {\tt stop\_playing()} |
| returns a lower bound for the number of bytes actually played (not very |
| accurate). |
| \end{description} |
| |
| The following operations do not affect the audio device but are |
| implemented in C for efficiency: |
| \begin{description} |
| \item[{\tt amplify(buf, f1, f2)}] |
| %.br |
| Amplifies a chunk of samples by a variable factor changing from |
| {\tt f1}/256 to {\tt f2}/256. |
| Negative factors are allowed. |
| Resulting values that are to large to fit in a byte are clipped. |
| \item[{\tt reverse(buf)}] |
| %.br |
| Returns a chunk of samples backwards. |
| \item[{\tt add(buf1, buf2)}] |
| %.br |
| Bytewise adds two chunks of samples. |
| Bytes that exceed the range are clipped. |
| If one buffer shorter, it is assumed to be padded with zeros. |
| \item[{\tt chr2num(buf)}] |
| %.br |
| Converts a string of sampled bytes as returned by {\tt read()} into |
| a list containing the numeric values of the samples. |
| \item[{\tt num2chr(list)}] |
| %.br |
| Converts a list as returned by |
| {\tt chr2num()} |
| back to a buffer acceptable by |
| {\tt write()}. |
| \end{description} |
| |
| \subsection{Built-in Module {\tt gl}} |
| |
| This module provides access to the Silicon Graphics |
| {\em Graphics Library}. |
| It is available only on Silicon Graphics machines. |
| |
| {\bf Warning:} |
| Some illegal calls to the GL library cause the {\Python} interpreter to dump |
| core. |
| In particular, the use of most GL calls is unsafe before the first |
| window is opened. |
| |
| The module is too large to document here in its entirety, but the |
| following should help you to get started. |
| The parameter conventions for the C functions are translated to {\Python} as |
| follows: |
| |
| \begin{itemize} |
| \item |
| All (short, long, unsigned) int values are represented by {\Python} |
| integers. |
| \item |
| All float and double values are represented by {\Python} floating point |
| numbers. |
| In most cases, {\Python} integers are also allowed. |
| \item |
| All arrays are represented by one-dimensional {\Python} lists. |
| In most cases, tuples are also allowed. |
| \item |
| All string and character arguments are represented by {\Python} strings, |
| e.g., |
| {\tt winopen('Hi~There!')} |
| and |
| {\tt rotate(900,~'z')}. |
| \item |
| All (short, long, unsigned) integer arguments or return values that are |
| only used to specify the length of an array argument are omitted. |
| For example, the C call |
| \begin{code}\begin{verbatim} |
| lmdef(deftype, index, np, props) |
| \end{verbatim}\end{code} |
| is translated to {\Python} as |
| \begin{code}\begin{verbatim} |
| lmdef(deftype, index, props) |
| \end{verbatim}\end{code} |
| \item |
| Output arguments are omitted from the argument list; they are |
| transmitted as function return values instead. |
| If more than one value must be returned, the return value is a tuple. |
| If the C function has both a regular return value (that is not omitted |
| because of the previous rule) and an output argument, the return value |
| comes first in the tuple. |
| Examples: the C call |
| \begin{code}\begin{verbatim} |
| getmcolor(i, &red, &green, &blue) |
| \end{verbatim}\end{code} |
| is translated to {\Python} as |
| \begin{code}\begin{verbatim} |
| red, green, blue = getmcolor(i) |
| \end{verbatim}\end{code} |
| \end{itemize} |
| |
| The following functions are non-standard or have special argument |
| conventions: |
| \begin{description} |
| \item[{\tt varray()}] |
| Equivalent to but faster than a number of |
| {\tt v3d()} |
| calls. |
| The argument is a list (or tuple) of points. |
| Each point must be a tuple of coordinates (x, y, z) or (x, y). |
| The points may be 2- or 3-dimensional but must all have the |
| same dimension. |
| Float and int values may be mixed however. |
| The points are always converted to 3D double precision points |
| by assuming z=0.0 if necessary (as indicated in the man page), |
| and for each point |
| {\tt v3d()} |
| is called. |
| \item[{\tt nvarray()}] |
| Equivalent to but faster than a number of |
| {\tt n3f} |
| and |
| {\tt v3f} |
| calls. |
| The argument is an array (list or tuple) of pairs of normals and points. |
| Each pair is a tuple of a point and a normal for that point. |
| Each point or normal must be a tuple of coordinates (x, y, z). |
| Three coordinates must be given. |
| Float and int values may be mixed. |
| For each pair, |
| {\tt n3f()} |
| is called for the normal, and then |
| {\tt v3f()} |
| is called for the point. |
| \item[{\tt vnarray()}] |
| Similar to |
| {\tt nvarray()} |
| but the pairs have the point first and the normal second. |
| \item[{\tt nurbssurface(s\_k[], t\_k[], ctl[][], s\_ord, t\_ord, type)}] |
| %.br |
| Defines a nurbs surface. |
| The dimensions of |
| {\tt ctl[][]} |
| are computed as follows: |
| {\tt [len(s\_k)~-~s\_ord]}, |
| {\tt [len(t\_k)~-~t\_ord]}. |
| \item[{\tt nurbscurve(knots, ctlpoints, order, type)}] |
| %.br |
| Defines a nurbs curve. |
| The length of ctlpoints is |
| {\tt len(knots)~-~order}. |
| \item[{\tt pwlcurve(points, type)}] |
| %.br |
| Defines a piecewise-linear curve. |
| {\tt points} |
| is a list of points. |
| {\tt type} |
| must be |
| {\tt N\_ST}. |
| \item[{\tt pick(n), select(n)}] |
| %.br |
| The only argument to these functions specifies the desired size of the |
| pick or select buffer. |
| \item[{\tt endpick(), endselect()}] |
| %.br |
| These functions have no arguments. |
| They return a list of integers representing the used part of the |
| pick/select buffer. |
| No method is provided to detect buffer overrun. |
| \end{description} |
| |
| Here is a tiny but complete example GL program in {\Python}: |
| \begin{code}\begin{verbatim} |
| import gl, GL, time |
| |
| def main(): |
| gl.foreground() |
| gl.prefposition(500, 900, 500, 900) |
| w = gl.winopen('CrissCross') |
| gl.ortho2(0.0, 400.0, 0.0, 400.0) |
| gl.color(GL.WHITE) |
| gl.clear() |
| gl.color(GL.RED) |
| gl.bgnline() |
| gl.v2f(0.0, 0.0) |
| gl.v2f(400.0, 400.0) |
| gl.endline() |
| gl.bgnline() |
| gl.v2f(400.0, 0.0) |
| gl.v2f(0.0, 400.0) |
| gl.endline() |
| time.sleep(5) |
| |
| main() |
| \end{verbatim}\end{code} |
| |
| \subsection{Built-in Module {\tt pnl}} |
| |
| This module provides access to the |
| {\em Panel Library} |
| built by NASA Ames (write to |
| {\tt panel-request@nas.nasa.gov} |
| to get it). |
| All access to it should be done through the standard module |
| {\tt panel}, |
| which transparantly exports most functions from |
| {\tt pnl} |
| but redefines |
| {\tt pnl.dopanel()}. |
| |
| {\bf Warning:} |
| the {\Python} interpreter will dump core if you don't create a GL window |
| before calling |
| {\tt pnl.mkpanel()}. |
| |
| The module is too large to document here in its entirety. |
| |
| \section{Standard Modules} |
| |
| The following standard modules are defined. |
| They are available in one of the directories in the default module |
| search path (try printing |
| {\tt sys.path} |
| to find out the default search path.) |
| |
| \subsection{Standard Module {\tt string}} |
| |
| This module defines some constants useful for checking character |
| classes, some exceptions, and some useful string functions. |
| The constants are: |
| \begin{description} |
| \item[{\tt digits}] |
| The string |
| {\tt '0123456789'}. |
| \item[{\tt hexdigits}] |
| The string |
| {\tt '0123456789abcdefABCDEF'}. |
| \item[{\tt letters}] |
| The concatenation of the strings |
| {\tt lowercase} |
| and |
| {\tt uppercase} |
| described below. |
| \item[{\tt lowercase}] |
| The string |
| {\tt 'abcdefghijklmnopqrstuvwxyz'}. |
| \item[{\tt octdigits}] |
| The string |
| {\tt '01234567'}. |
| \item[{\tt uppercase}] |
| The string |
| {\tt 'ABCDEFGHIJKLMNOPQRSTUVWXYZ'}. |
| \item[{\tt whitespace}] |
| A string containing all characters that are considered whitespace, |
| i.e., |
| space, tab and newline. |
| This definition is used by |
| {\tt split()} |
| and |
| {\tt strip()}. |
| \end{description} |
| |
| The exceptions are: |
| \begin{description} |
| \item[{\tt atoi\_error = 'non-numeric argument to string.atoi'}] |
| %.br |
| Exception raised by |
| {\tt atoi} |
| when a non-numeric string argument is detected. |
| The exception argument is the offending string. |
| \item[{\tt index\_error = 'substring not found in string.index'}] |
| %.br |
| Exception raised by |
| {\tt index} |
| when |
| {\tt sub} |
| is not found. |
| The argument are the offending arguments to index: {\tt (s, sub)}. |
| \end{description} |
| |
| The functions are: |
| \begin{description} |
| \item[{\tt atoi(s)}] |
| Converts a string to a number. |
| The string must consist of one or more digits, optionally preceded by a |
| sign ({\tt '+'} or {\tt '-'}). |
| \item[{\tt index(s, sub)}] |
| Returns the lowest index in |
| {\tt s} |
| where the substring |
| {\tt sub} |
| is found. |
| \item[{\tt lower(s)}] |
| Convert letters to lower case. |
| \item[{\tt split(s)}] |
| Returns a list of the whitespace-delimited words of the string |
| {\tt s}. |
| \item[{\tt splitfields(s, sep)}] |
| %.br |
| Returns a list containing the fields of the string |
| {\tt s}, |
| using the string |
| {\tt sep} |
| as a separator. |
| The list will have one more items than the number of non-overlapping |
| occurrences of the separator in the string. |
| Thus, |
| {\tt string.splitfields(s, ' ')} |
| is not the same as |
| {\tt string.split(s)}, |
| as the latter only returns non-empty words. |
| \item[{\tt strip(s)}] |
| Removes leading and trailing whitespace from the string |
| {\tt s}. |
| \item[{\tt swapcase(s)}] |
| Converts lower case letters to upper case and vice versa. |
| \item[{\tt upper(s)}] |
| Convert letters to upper case. |
| \item[{\tt ljust(s, width), rjust(s, width), center(s, width)}] |
| %.br |
| These functions respectively left-justify, right-justify and center a |
| string in a field of given width. |
| They return a string that is at least |
| {\tt width} |
| characters wide, created by padding the string |
| {\tt s} |
| with spaces until the given width on the right, left or both sides. |
| The string is never truncated. |
| \end{description} |
| |
| \subsection{Standard Module {\tt path}} |
| |
| This module implements some useful functions on POSIX pathnames. |
| \begin{description} |
| \item[{\tt basename(p)}] |
| Returns the base name of pathname |
| {\tt p}. |
| This is the second half of the pair returned by |
| {\tt path.split(p)}. |
| \item[{\tt cat(p, q)}] |
| Performs intelligent pathname concatenation on paths |
| {\tt p} |
| and |
| {\tt q}: |
| If |
| {\tt q} |
| is an absolute path, the return value is |
| {\tt q}. |
| Otherwise, the concatenation of |
| {\tt p} |
| and |
| {\tt q} |
| is returned, with a slash ({\tt '/'}) inserted unless |
| {\tt p} |
| is empty or ends in a slash. |
| \item[{\tt commonprefix(list)}] |
| %.br |
| Returns the longest string that is a prefix of all strings in |
| {\tt list}. |
| If |
| {\tt list} |
| is empty, the empty string ({\tt ''}) is returned. |
| \item[{\tt exists(p)}] |
| Returns true if |
| {\tt p} |
| refers to an existing path. |
| \item[{\tt isdir(p)}] |
| Returns true if |
| {\tt p} |
| refers to an existing directory. |
| \item[{\tt islink(p)}] |
| Returns true if |
| {\tt p} |
| refers to a directory entry that is a symbolic link. |
| Always false if symbolic links are not supported. |
| \item[{\tt ismount(p)}] |
| Returns true if |
| {\tt p} |
| is an absolute path that occurs in the mount table as output by the |
| {\tt /etc/mount} |
| utility. |
| This output is read once when the function is used for the first |
| time.% |
| \footnote{ |
| Is there a better way to check for mount points? |
| } |
| \item[{\tt split(p)}] |
| Returns a pair |
| {\tt (head,~tail)} |
| such that |
| {\tt tail} |
| contains no slashes and |
| {\tt path.cat(head, tail)} |
| is equal to |
| {\tt p}. |
| \item[{\tt walk(p, visit, arg)}] |
| %.br |
| Calls the function |
| {\tt visit} |
| with arguments |
| {\tt (arg, dirname, names)} |
| for each directory in the directory tree rooted at |
| {\tt p} |
| (including |
| {\tt p} |
| itself, if it is a directory). |
| The argument |
| {\tt dirname} |
| specifies the visited directory, the argument |
| {\tt names} |
| lists the files in the directory (gotten from |
| {\tt posix.listdir(dirname)}). |
| The |
| {\tt visit} |
| function may modify |
| {\tt names} |
| to influence the set of directories visited below |
| {\tt dirname}, |
| e.g., |
| to avoid visiting certain parts of the tree. |
| (The object referred to by |
| {\tt names} |
| must be modified in place, using |
| {\tt del} |
| or slice assignment.) |
| \end{description} |
| |
| \subsection{Standard Module {\tt getopt}} |
| |
| This module helps scripts to parse the command line arguments in |
| {\tt sys.argv}. |
| It uses the same conventions as the {\UNIX} |
| {\tt getopt()} |
| function. |
| It defines the function |
| {\tt getopt.getopt(args, options)} |
| and the exception |
| {\tt getopt.error}. |
| |
| The first argument to |
| {\tt getopt()} |
| is the argument list passed to the script with its first element |
| chopped off (i.e., |
| {\tt sys.argv[1:]}). |
| The second argument is the string of option letters that the |
| script wants to recognize, with options that require an argument |
| followed by a colon (i.e., the same format that {\UNIX} |
| {\tt getopt()} |
| uses). |
| The return value consists of two elements: the first is a list of |
| option-and-value pairs; the second is the list of program arguments |
| left after the option list was stripped (this is a trailing slice of the |
| first argument). |
| Each option-and-value pair returned has the option as its first element, |
| prefixed with a hyphen (e.g., |
| {\tt '-x'}), |
| and the option argument as its second element, or an empty string if the |
| option has no argument. |
| The options occur in the list in the same order in which they were |
| found, thus allowing multiple occurrences. |
| Example: |
| \begin{code}\begin{verbatim} |
| >>> import getopt, string |
| >>> args = string.split('-a -b -cfoo -d bar a1 a2') |
| >>> args |
| ['-a', '-b', '-cfoo', '-d', 'bar', 'a1', 'a2'] |
| >>> optlist, args = getopt.getopt(args, 'abc:d:') |
| >>> optlist |
| [('-a', ''), ('-b', ''), ('-c', 'foo'), ('-d', 'bar')] |
| >>> args |
| ['a1', 'a2'] |
| >>> |
| \end{verbatim}\end{code} |
| The exception |
| {\tt getopt.error = 'getopt error'} |
| is raised when an unrecognized option is found in the argument list or |
| when an option requiring an argument is given none. |
| The argument to the exception is a string indicating the cause of the |
| error. |
| |
| \subsection{Standard Module {\tt rand}} |
| |
| This module implements a pseudo-random number generator similar to |
| {\tt rand()} |
| in C. |
| It defines the following functions: |
| \begin{description} |
| \item[{\tt rand()}] |
| Returns an integer random number in the range [0 ... 32768). |
| \item[{\tt choice(s)}] |
| Returns a random element from the sequence (string, tuple or list) |
| {\tt s.} |
| \item[{\tt srand(seed)}] |
| Initializes the random number generator with the given integral seed. |
| When the module is first imported, the random number is initialized with |
| the current time. |
| \end{description} |
| |
| \subsection{Standard Module {\tt whrandom}} |
| |
| This module implements a Wichmann-Hill pseudo-random number generator. |
| It defines the following functions: |
| \begin{description} |
| \item[{\tt random()}] |
| Returns the next random floating point number in the range [0.0 ... 1.0). |
| \item[{\tt seed(x, y, z)}] |
| Initializes the random number generator from the integers |
| {\tt x}, |
| {\tt y} |
| and |
| {\tt z}. |
| When the module is first imported, the random number is initialized |
| using values derived from the current time. |
| \end{description} |
| |
| \subsection{Standard Module {\tt stdwinevents}} |
| |
| This module defines constants used by STDWIN for event types |
| ({\tt WE\_ACTIVATE} etc.), command codes ({\tt WC\_LEFT} etc.) |
| and selection types ({\tt WS\_PRIMARY} etc.). |
| Read the file for details. |
| Suggested usage is |
| \begin{code}\begin{verbatim} |
| >>> from stdwinevents import * |
| >>> |
| \end{verbatim}\end{code} |
| |
| \subsection{Standard Module {\tt rect}} |
| |
| This module contains useful operations on rectangles. |
| A rectangle is defined as in module |
| {\tt stdwin}: |
| a pair of points, where a point is a pair of integers. |
| For example, the rectangle |
| \begin{code}\begin{verbatim} |
| (10, 20), (90, 80) |
| \end{verbatim}\end{code} |
| is a rectangle whose left, top, right and bottom edges are 10, 20, 90 |
| and 80, respectively. |
| Note that the positive vertical axis points down (as in |
| {\tt stdwin}). |
| |
| The module defines the following objects: |
| \begin{description} |
| \item[{\tt error = 'rect.error'}] |
| %.br |
| The exception raised by functions in this module when they detect an |
| error. |
| The exception argument is a string describing the problem in more |
| detail. |
| \item[{\tt empty}] |
| %.br |
| The rectangle returned when some operations return an empty result. |
| This makes it possible to quickly check whether a result is empty: |
| \begin{code}\begin{verbatim} |
| >>> import rect |
| >>> r1 = (10, 20), (90, 80) |
| >>> r2 = (0, 0), (10, 20) |
| >>> r3 = rect.intersect(r1, r2) |
| >>> if r3 is rect.empty: print 'Empty intersection' |
| Empty intersection |
| >>> |
| \end{verbatim}\end{code} |
| \item[{\tt is\_empty(r)}] |
| %.br |
| Returns true if the given rectangle is empty. |
| A rectangle |
| {\em (left,~top), (right,~bottom)} |
| is empty if |
| {\em left~$\geq$~right} |
| or |
| {\em top~$\leq$~bottom}. |
| \item[{\tt intersect(list)}] |
| %.br |
| Returns the intersection of all rectangles in the list argument. |
| It may also be called with a tuple argument or with two or more |
| rectangles as arguments. |
| Raises |
| {\tt rect.error} |
| if the list is empty. |
| Returns |
| {\tt rect.empty} |
| if the intersection of the rectangles is empty. |
| \item[{\tt union(list)}] |
| %.br |
| Returns the smallest rectangle that contains all non-empty rectangles in |
| the list argument. |
| It may also be called with a tuple argument or with two or more |
| rectangles as arguments. |
| Returns |
| {\tt rect.empty} |
| if the list is empty or all its rectangles are empty. |
| \item[{\tt pointinrect(point, rect)}] |
| %.br |
| Returns true if the point is inside the rectangle. |
| By definition, a point |
| {\em (h,~v)} |
| is inside a rectangle |
| {\em (left,~top),} |
| {\em (right,~bottom)} |
| if |
| {\em left~$\leq$~h~$<$~right} |
| and |
| {\em top~$\leq$~v~$<$~bottom}. |
| \item[{\tt inset(rect, (dh, dv))}] |
| %.br |
| Returns a rectangle that lies inside the |
| {\tt rect} |
| argument by |
| {\tt dh} |
| pixels horizontally |
| and |
| {\tt dv} |
| pixels |
| vertically. |
| If |
| {\tt dh} |
| or |
| {\tt dv} |
| is negative, the result lies outside |
| {\tt rect}. |
| \item[{\tt rect2geom(rect)}] |
| %.br |
| Converts a rectangle to geometry representation: |
| {\em (left,~top),} |
| {\em (width,~height)}. |
| \item[{\tt geom2rect(geom)}] |
| %.br |
| Converts a rectangle given in geometry representation back to the |
| standard rectangle representation |
| {\em (left,~top),} |
| {\em (right,~bottom)}. |
| \end{description} |
| |
| \subsection{Standard Modules {\tt GL} and {\tt DEVICE}} |
| |
| These modules define the constants used by the Silicon Graphics |
| {\em Graphics Library} |
| that C programmers find in the header files |
| {\tt <gl/gl.h>} |
| and |
| {\tt <gl/device.h>}. |
| Read the module files for details. |
| |
| \subsection{Standard Module {\tt panel}} |
| |
| This module should be used instead of the built-in module |
| {\tt pnl} |
| to interface with the |
| {\em Panel Library}. |
| |
| The module is too large to document here in its entirety. |
| One interesting function: |
| \begin{description} |
| \item[{\tt defpanellist(filename)}] |
| %.br |
| Parses a panel description file containing S-expressions written by the |
| {\em Panel Editor} |
| that accompanies the Panel Library and creates the described panels. |
| It returns a list of panel objects. |
| \end{description} |
| |
| {\bf Warning:} |
| the {\Python} interpreter will dump core if you don't create a GL window |
| before calling |
| {\tt panel.mkpanel()} |
| or |
| {\tt panel.defpanellist()}. |
| |
| \subsection{Standard Module {\tt panelparser}} |
| |
| This module defines a self-contained parser for S-expressions as output |
| by the Panel Editor (which is written in Scheme so it can't help writing |
| S-expressions). |
| The relevant function is |
| {\tt panelparser.parse\_file(file)} |
| which has a file object (not a filename!) as argument and returns a list |
| of parsed S-expressions. |
| Each S-expression is converted into a {\Python} list, with atoms converted |
| to {\Python} strings and sub-expressions (recursively) to {\Python} lists. |
| For more details, read the module file. |
| |
| \subsection{P.M.} |
| |
| \begin{verse} |
| commands |
| |
| cmp? |
| |
| *cache? |
| |
| localtime? |
| |
| calendar? |
| |
| \_\_dict? |
| \end{verse} |
| |
| \end{document} |