diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile | 47 | ||||
| -rw-r--r-- | doc/README | 24 | ||||
| -rw-r--r-- | doc/SetClass.py | 17 | ||||
| -rw-r--r-- | doc/fibo.py | 15 | ||||
| -rw-r--r-- | doc/mod.tex | 62 | ||||
| -rw-r--r-- | doc/mod1.tex | 521 | ||||
| -rw-r--r-- | doc/mod2.tex | 1083 | ||||
| -rw-r--r-- | doc/mod3.tex | 484 | ||||
| -rw-r--r-- | doc/myformat.sty | 34 | ||||
| -rwxr-xr-x | doc/pytry | 20 | ||||
| -rw-r--r-- | doc/tut.tex | 1550 |
11 files changed, 3857 insertions, 0 deletions
diff --git a/doc/Makefile b/doc/Makefile new file mode 100644 index 0000000..f2a83bf --- /dev/null +++ b/doc/Makefile @@ -0,0 +1,47 @@ +# Makefile for Python documentation. + +LATEX= latex +DVIPS= dvips +TEXPREVIEW= xdvi + +PRINT= lpr + +tut: tut.dvi + $(TEXPREVIEW) tut + +tut.dvi tut.ps: tut.toc tut.tex myformat.sty + +mod: mod.dvi + $(TEXPREVIEW) mod + +mod.dvi mod.ps: mod.toc mod.tex mod1.tex mod2.tex mod3.tex myformat.sty + +ALL= tut.ps mod.ps + +all: $(ALL) + +print: $(ALL) + $(PRINT) $(ALL) + +clean: + rm -f *.dvi *.aux *.toc *.log *.ps core [#@,]* *~ + +.SUFFIXES: # Remove default suffixes + +.SUFFIXES: .tex .aux .toc .dvi .ps + +.tex.aux: + $(LATEX) $* + +.tex.toc: + $(LATEX) $* + +.tex.dvi: + $(LATEX) $* + +.dvi.ps: + $(DVIPS) $* >$*.ps + +.tex.ps: + $(LATEX) $* + $(DVIPS) $* >$*.ps diff --git a/doc/README b/doc/README new file mode 100644 index 0000000..14c3de9 --- /dev/null +++ b/doc/README @@ -0,0 +1,24 @@ +This directory contains the LaTeX source to the Python documentation. +The documentation is not all finished, but good enough to get you +started. + +The following are the important latex source files: + + tut.tex A tutorial + mod.tex The library reference + +They both read the style option file "myformat.sty". + +You can use the Makefile to format, preview and print the documents. +Type "make tut" or "make mod" to preview either document with xdvi. +Type "make print" to print them both (this only works if your print +spooler is set up just like mine...), or "make all" to create postscript +files that you can you can print using your local printing commands. +Type "make clean" to get rid of all the intermediate files produced by +the latex process, and other junk files. + +You can just as well ignore the Makefile; all you really need is: + latex tut + latex tut + dvips tut | lpr +and similar for the "mod" document. diff --git a/doc/SetClass.py b/doc/SetClass.py new file mode 100644 index 0000000..8a5fb9e --- /dev/null +++ b/doc/SetClass.py @@ -0,0 +1,17 @@ +class Set(): + def new(self): + self.elements = [] + return self + def add(self, e): + if e not in self.elements: + self.elements.append(e) + def remove(self, e): + if e in self.elements: + for i in range(len(self.elements)): + if self.elements[i] = e: + del self.elements[i] + break + def is_element(self, e): + return e in self.elements + def size(self): + return len(self.elements) diff --git a/doc/fibo.py b/doc/fibo.py new file mode 100644 index 0000000..e8cafa8 --- /dev/null +++ b/doc/fibo.py @@ -0,0 +1,15 @@ +# Fibonacci numbers demo + +def fib(n): # write Fibonacci series up to n + a, b = 0, 1 + while b <= n: + print b, + a, b = b, a+b + +def fib2(n): # return Fibonacci series up to n + ret = [] + a, b = 0, 1 + while b <= n: + ret.append(b) + a, b = b, a+b + return ret diff --git a/doc/mod.tex b/doc/mod.tex new file mode 100644 index 0000000..c2d2355 --- /dev/null +++ b/doc/mod.tex @@ -0,0 +1,62 @@ +% Format this file with latex. + +%\documentstyle[garamond,11pt,myformat]{article} +\documentstyle[11pt,myformat]{article} + +% A command to force the text after an item to start on a new line +\newcommand{\itembreak}{ + \mbox{}\\*[0mm] +} + +% A command to define a function item +\newcommand{\funcitem}[2]{\item[#1(#2)]} + +% A command to define an exception item +\newcommand{\excitem}[2]{ +\item[#1 = {\tt '#2'}] +\itembreak +} + +\title{\bf + Python Library Reference \\ + (DRAFT) +} + +\author{ + Guido van Rossum \\ + Dept. CST, CWI, Kruislaan 413 \\ + 1098 SJ Amsterdam, The Netherlands \\ + E-mail: {\tt [email protected]} +} + +\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} + +\input{mod1.tex} +\input{mod2.tex} +\input{mod3.tex} + +\end{document} diff --git a/doc/mod1.tex b/doc/mod1.tex new file mode 100644 index 0000000..2dac554 --- /dev/null +++ b/doc/mod1.tex @@ -0,0 +1,521 @@ +\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} diff --git a/doc/mod2.tex b/doc/mod2.tex new file mode 100644 index 0000000..46f6d62 --- /dev/null +++ b/doc/mod2.tex @@ -0,0 +1,1083 @@ +\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 '(' ')' '*' '+' '?'\ '|' }\verb='^' '$'= +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 [email protected]}). +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. diff --git a/doc/mod3.tex b/doc/mod3.tex new file mode 100644 index 0000000..d1a99b1 --- /dev/null +++ b/doc/mod3.tex @@ -0,0 +1,484 @@ +\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} diff --git a/doc/myformat.sty b/doc/myformat.sty new file mode 100644 index 0000000..be70239 --- /dev/null +++ b/doc/myformat.sty @@ -0,0 +1,34 @@ +% Style parameters and macros used by all documents here + +% Page lay-out parameters +\textwidth = 160mm +\textheight = 240mm +\topmargin = -11mm +\oddsidemargin = 0mm +\evensidemargin = 0mm +%\parindent = 0mm + +% Frequently used system names +\newcommand{\Python}{Python} % Sometimes I want this italicized +\newcommand{\UNIX}{U{\sc nix}} + +% Variable used by begin code command +\newlength{\codewidth} + +\newcommand{\bcode}{ + % Calculate the text width for the minipage: + \setlength{\codewidth}{\linewidth} + \addtolength{\codewidth}{-\parindent} + % + \vspace{3mm} + \par + \indent + \begin{minipage}[t]{\codewidth} +} + +\newcommand{\ecode}{ + \end{minipage} + \vspace{3mm} + \par + \noindent +} diff --git a/doc/pytry b/doc/pytry new file mode 100755 index 0000000..dcc3f84 --- /dev/null +++ b/doc/pytry @@ -0,0 +1,20 @@ +TMP=/usr/tmp/pytry$$ +trap 'rm -f $TMP; exit 1' 1 2 3 13 14 15 + +cat $* >$TMP + +( + cat $TMP + + sed ' + s/^>>> // + s/^>>>$// + s/^\.\.\. // + s/^\.\.\.$// + ' $TMP | + python + + echo '>>> ' +) 2>&1 + +rm $TMP diff --git a/doc/tut.tex b/doc/tut.tex new file mode 100644 index 0000000..ad5f56c --- /dev/null +++ b/doc/tut.tex @@ -0,0 +1,1550 @@ +% Format this file with latex. + +%\documentstyle[garamond,11pt,myformat]{article} +\documentstyle[11pt,myformat]{article} + +\title{\bf + Python Tutorial \\ + (DRAFT) +} + +\author{ + Guido van Rossum \\ + Dept. CST, CWI, Kruislaan 413 \\ + 1098 SJ Amsterdam, The Netherlands \\ + E-mail: {\tt [email protected]} +} + +\begin{document} + +\pagenumbering{roman} + +\maketitle + +\begin{abstract} + +\noindent +\Python\ is a simple, yet powerful programming language that bridges the +gap between C and shell programming, and is thus ideally suited for rapid +prototyping. +Its syntax is put together from constructs borrowed from a variety of other +languages; most prominent are influences from ABC, C, Modula-3 and Icon. + +The \Python\ interpreter is easily extended with new functions and data +types implemented in C. +\Python\ is also suitable as an extension language for highly +customizable C applications such as editors or window managers. + +\Python\ is available for various operating systems, amongst which +several flavors of \UNIX, Amoeba, and the Apple Macintosh O.S. + +This tutorial introduces the reader informally to the basic concepts and +features of the \Python\ language and system. +It helps to have a \Python\ interpreter handy for hands-on experience, +but as the examples are self-contained, the tutorial can be read +off-line as well. + +For a description of standard objects and modules, see the Library +Reference 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{Whetting Your Appetite} + +If you ever wrote a large shell script, you probably know this feeling: +you'd love to add yet another feature, but it's already so slow, and so +big, and so complicated; or the feature involves a system call or other +funcion that is only accessible from C \ldots +Usually the problem at hand isn't serious enough to warrant rewriting +the script in C; perhaps because the problem requires variable-length +strings or other data types (like sorted lists of file names) that +are easy in the shell but lots of work to implement in C; or perhaps +just because you're not sufficiently familiar with C. + +In all such cases, \Python\ is just the language for you. +\Python\ is simple to use, but it is a real programming language, offering +much more structure and support for large programs than the shell has. +On the other hand, it also offers much more error checking than C, and, +being a +{\em very-high-level language}, +it has high-level data types built in, such as flexible arrays and +dictionaries that would cost you days to implement efficiently in C. +Because of its more general data types \Python\ is applicable to a +much larger problem domain than +{\em Awk} +or even +{\em Perl}, +yet most simple things are at least as easy in \Python\ as in those +languages. + +\Python\ allows you to split up your program in modules that can be reused +in other \Python\ programs. +It comes with a large collection of standard modules that you can use as +the basis for your programs --- or as examples to start learning to +program in \Python. +There are also built-in modules that provide things like file I/O, +system calls, and even a generic interface to window systems (STDWIN). + +\Python\ is an interpreted language, which saves you considerable time +during program development because no compilation and linking is +necessary. +The interpreter can be used interactively, which makes it easy to +experiment with features of the language, to write throw-away programs, +or to test functions during bottom-up program development. +It is also a handy desk calculator. + +\Python\ allows writing very compact and readable programs. +Programs written in \Python\ are typically much shorter than equivalent C +programs: +No declarations are necessary (all type checking is +dynamic); statement grouping is done by indentation instead of begin/end +brackets; and the high-level data types allow you to express complex +operations in a single statement. + +\Python\ is +{\em extensible}: +if you know how to program in C it is easy to add a new built-in module +to the interpreter, either to perform critical operations at maximum +speed, or to link \Python\ programs to libraries that may be only available +in binary form (such as a vendor-specific graphics library). +Once you are really hooked, you can link the \Python\ interpreter into an +application written in C and use it as an extension or command language. + +\subsection{Where From Here} + +Now that you are all excited about \Python, you'll want to examine it in +some more detail. +Since the best introduction to a language is using it, you are invited +here to do so. + +In the next section, the mechanics of using the interpreter are +explained. +This is rather mundane information, but essential for trying out the +examples shown later. +The rest of the tutorial introduces various features of the \Python\ +language and system though examples, beginning with simple expressions, +statements and data types, through functions and modules, and finally +touching upon advanced concepts like exceptions and classes. + +\section{Using the Python Interpreter} + +The \Python\ interpreter is usually installed as +{\tt /usr/local/python} +on those machines where it is available; putting +{\tt /usr/local} +in your \UNIX\ shell's search path makes it possible to start it by +typing the command +\bcode\begin{verbatim} +python +\end{verbatim}\ecode +to the shell. +Since the choice of the directory where the interpreter lives is an +installation option, other places instead of +{\tt /usr/local} +are possible; check with your local \Python\ guru or system +administrator.% +\footnote{ + At CWI, at the time of writing, the interpreter can be found in + the following places: + On the Amoeba Ultrix machines, use the standard path, + {\tt /usr/local/python}. + On the Sun file servers, use + {\tt /ufs/guido/bin/}{\em arch}{\tt /python}, + where {\em arch} can be {\tt sgi} or {\tt sun4}. + On piring, use {\tt /userfs3/amoeba/bin/python}. + (If you can't find a binary advertised here, get in touch with me.) +} + +The interpreter operates somewhat like the \UNIX\ shell: when called with +standard input connected to a tty device, it reads and executes commands +interactively; when called with a file name argument or with a file as +standard input, it reads and executes a +{\em script} +from that file.% +\footnote{ + There is a difference between ``{\tt python file}'' and + ``{\tt python $<$file}''. In the latter case {\tt input()} and + {\tt raw\_input()} are satisfied from {\em file}, which has + already been read until the end by the parser, so they will read + EOF immediately. In the former case (which is usually what + you want) they are satisfied from whatever file or device is + connected to standard input of the \Python\ interpreter. +} +If available, the script name and additional arguments thereafter are +passed to the script in the variable +{\tt sys.argv}, +which is a list of strings. + +When standard input is a tty, the interpreter is said to be in +{\em interactive\ mode}. +In this mode it prompts for the next command with the +{\em primary\ prompt}, +usually three greater-than signs ({\tt >>>}); for continuation lines +it prompts with the +{\em secondary\ prompt}, +by default three dots ({\tt ...}). +Typing an EOF (Control-D) at the primary prompt causes the interpreter +to exit with a zero exit status. + +When an error occurs in interactive mode, the interpreter prints a +message and a stack trace and returns to the primary prompt; with input +from a file, it exits with a nonzero exit status. +(Exceptions handled by an +{\tt except} +clause in a +{\tt try} +statement are not errors in this context.) +Some errors are unconditionally fatal and cause an exit with a nonzero +exit; this applies to internal inconsistencies and some cases of running +out of memory. +All error messages are written to the standard error stream; normal +output from the executed commands is written to standard output. + +Typing an interrupt (normally Control-C or DEL) to the primary or +secondary prompt cancels the input and returns to the primary prompt. +Typing an interrupt while a command is being executed raises the +{\tt KeyboardInterrupt} +exception, which may be handled by a +{\tt try} +statement. + +When a module named +{\tt foo} +is imported, the interpreter searches for a file named +{\tt foo.py} +in a list of directories specified by the environment variable +{\tt PYTHONPATH}. +It has the same syntax as the \UNIX\ shell variable +{\tt PATH}, +i.e., a list of colon-separated directory names. +When +{\tt PYTHONPATH} +is not set, an installation-dependent default path is used, usually +{\tt .:/usr/local/lib/python}.% +\footnote{ + Modules are really searched in the list of directories given by + the variable {\tt sys.path} which is initialized from + {\tt PYTHONPATH} or from the installation-dependent default. + See the section on Standard Modules later. +} + +On BSD'ish \UNIX\ systems, \Python\ scripts can be made directly executable, +like shell scripts, by putting the line +\bcode\begin{verbatim} +#! /usr/local/python +\end{verbatim}\ecode +(assuming that's the name of the interpreter) at the beginning of the +script and giving the file an executable mode. +(The +{\tt \#!} +must be the first two characters of the file.) + +\subsection{Interactive Input Editing and History Substitution} + +Some versions of the \Python\ interpreter support editing of the current +input line and history substitution, similar to facilities found in the +Korn shell and the GNU Bash shell. +This is implemented using the +{\em GNU\ Readline} +library, which supports Emacs-style and vi-style editing. +This library has its own documentation which I won't duplicate here; +however, the basics are easily explained. + +If supported,% +\footnote{ + Perhaps the quickest check to see whether command line editing + is supported is typing Control-P to the first \Python\ prompt + you get. If it beeps, you have command line editing. + If not, you can skip the rest of this section. +} +input line editing is active whenever the interpreter prints a primary +or secondary prompt. +The current line can be edited using the conventional Emacs control +characters. +The most important of these are: +C-A (Control-A) moves the cursor to the beginning of the line, C-E to +the end, C-B moves it one position to the left, C-F to the right. +Backspace erases the character to the left of the cursor, C-D the +character to its right. +C-K kills (erases) the rest of the line to the right of the cursor, C-Y +yanks back the last killed string. +C-underscore undoes the last change you made; it can be repeated for +cumulative effect. + +History substitution works as follows. +All non-empty input lines issued are saved in a history buffer, +and when a new prompt is given you are positioned on a new line at the +bottom of this buffer. +C-P moves one line up (back) in the history buffer, C-N moves one down. +Any line in the history buffer can be edited; an asterisk appears in +front of the prompt to mark a line as modified. +Pressing the Return key passes the current line to the interpreter. +C-R starts an incremental reverse search; C-S starts a forward search. + +The key bindings and some other parameters of the Readline library can +be customized by placing commands in an initialization file called +{\tt \$HOME/.initrc}. +Key bindings have the form +\bcode\begin{verbatim} +key-name: function-name +\end{verbatim}\ecode +and options can be set with +\bcode\begin{verbatim} +set option-name value +\end{verbatim}\ecode +Example: +\bcode\begin{verbatim} +# I prefer vi-style editing: +set editing-mode vi +# Edit using a single line: +set horizontal-scroll-mode On +# Rebind some keys: +Meta-h: backward-kill-word +Control-u: universal-argument +\end{verbatim}\ecode +Note that the default binding for TAB in \Python\ is to insert a TAB +instead of Readline's default filename completion function. +If you insist, you can override this by putting +\bcode\begin{verbatim} +TAB: complete +\end{verbatim}\ecode +in your +{\tt \$HOME/.inputrc}. +(Of course, this makes it hard to type indented continuation lines.) + +This facility is an enormous step forward compared to previous versions of +the interpreter; however, some wishes are left: +It would be nice if the proper indentation were suggested on +continuation lines (the parser knows if an indent token is required +next). +The completion mechanism might use the interpreter's symbol table. +A function to check (or even suggest) matching parentheses, quotes +etc. would also be useful. + +\section{An Informal Introduction to Python} + +In the following examples, input and output are distinguished by the +presence or absence of prompts ({\tt >>>} and {\tt ...}): to repeat the +example, you must type everything after the prompt, when the prompt +appears; everything on lines that do not begin with a prompt is output +from the interpreter. +Note that a secondary prompt on a line by itself in an example means you +must type a blank line; this is used to end a multi-line command. + +\subsection{Using Python as a Calculator} + +Let's try some simple \Python\ commands. +Start the interpreter and wait for the primary prompt, +{\tt >>>}. +The interpreter acts as a simple calculator: you can type an expression +at it and it will write the value. +Expression syntax is straightforward: the operators +{\tt +}, +{\tt -}, +{\tt *} +and +{\tt /} +work just as in most other languages (e.g., Pascal or C); parentheses +can be used for grouping. +For example: +\bcode\begin{verbatim} +>>> # This is a comment +>>> 2+2 +4 +>>> +>>> (50-5+5*6+25)/4 +25 +>>> # Division truncates towards zero: +>>> 7/3 +2 +>>> +\end{verbatim}\ecode +As in C, the equal sign ({\tt =}) is used to assign a value to a variable. +The value of an assignment is not written: +\bcode\begin{verbatim} +>>> width = 20 +>>> height = 5*9 +>>> width * height +900 +>>> +\end{verbatim}\ecode +There is some support for floating point, but you can't mix floating +point and integral numbers in expression (yet): +\bcode\begin{verbatim} +>>> 10.0 / 3.3 +3.0303030303 +>>> +\end{verbatim}\ecode +Besides numbers, \Python\ can also manipulate strings, enclosed in single +quotes: +\bcode\begin{verbatim} +>>> 'foo bar' +'foo bar' +>>> 'doesn\'t' +'doesn\'t' +>>> +\end{verbatim}\ecode +Strings are written inside quotes and with quotes and other funny +characters escaped by backslashes, to show the precise value. +(There is also a way to write strings without quotes and escapes.) +Strings can be concatenated (glued together) with the +{\tt +} +operator, and repeated with~{\tt *}: +\bcode\begin{verbatim} +>>> word = 'Help' + 'A' +>>> word +'HelpA' +>>> '<' + word*5 + '>' +'<HelpAHelpAHelpAHelpAHelpA>' +>>> +\end{verbatim}\ecode +Strings can be subscripted; as in C, the first character of a string has +subscript 0. +There is no separate character type; a character is simply a string of +size one. +As in Icon, substrings can be specified with the +{\em slice} +notation: two subscripts (indices) separated by a colon. +\bcode\begin{verbatim} +>>> word[4] +'A' +>>> word[0:2] +'He' +>>> word[2:4] +'lp' +>>> # Slice indices have useful defaults: +>>> word[:2] # Take first two characters +'He' +>>> word[2:] # Drop first two characters +'lpA' +>>> # A useful invariant: s[:i] + s[i:] = s +>>> word[:3] + word[3:] +'HelpA' +>>> +\end{verbatim}\ecode +Degenerate cases are handled gracefully: an index that is too large is +replaced by the string size, an upper bound smaller than the lower bound +returns an empty string. +\bcode\begin{verbatim} +>>> word[1:100] +'elpA' +>>> word[10:] +'' +>>> word[2:1] +'' +>>> +\end{verbatim}\ecode +Slice indices (but not simple subscripts) may be negative numbers, to +start counting from the right. +For example: +\bcode\begin{verbatim} +>>> word[-2:] # Take last two characters +'pA' +>>> word[:-2] # Drop last two characters +'Hel' +>>> # But -0 does not count from the right! +>>> word[-0:] # (since -0 equals 0) +'HelpA' +>>> +\end{verbatim}\ecode +The best way to remember how slices work is to think of the indices as +pointing +{\em between} +characters, with the left edge of the first character numbered 0. +Then the right edge of the last character of a string of +{\tt n} +characters has index +{\tt n}, +for example: +\bcode\begin{verbatim} + +---+---+---+---+---+ + | H | e | l | p | A | + +---+---+---+---+---+ + 0 1 2 3 4 5 +-5 -4 -3 -2 -1 +\end{verbatim}\ecode +The first row of numbers gives the position of the indices 0...5 in the +string; the second row gives the corresponding negative indices. +For nonnegative indices, the length of a slice is the difference of the +indices, if both are within bounds, +e.g., +the length of +{\tt word[1:3]} +is 3--1 = 2. + +Finally, the built-in function {\tt len()} computes the length of a +string: +\bcode\begin{verbatim} +>>> s = 'supercalifragilisticexpialidocious' +>>> len(s) +34 +>>> +\end{verbatim}\ecode +\Python\ knows a number of +{\em compound} +data types, used to group together other values. +The most versatile is the +{\em list}, +which can be written as a list of comma-separated values between square +brackets: +\bcode\begin{verbatim} +>>> a = ['foo', 'bar', 100, 1234] +>>> a +['foo', 'bar', 100, 1234] +>>> +\end{verbatim}\ecode +As for strings, list subscripts start at 0: +\bcode\begin{verbatim} +>>> a[0] +'foo' +>>> a[3] +1234 +>>> +\end{verbatim}\ecode +Lists can be sliced and concatenated like strings: +\bcode\begin{verbatim} +>>> a[1:3] +['bar', 100] +>>> a[:2] + ['bletch', 2*2] +['foo', 'bar', 'bletch', 4] +>>> +\end{verbatim}\ecode +Unlike strings, which are +{\em immutable}, +it is possible to change individual elements of a list: +\bcode\begin{verbatim} +>>> a +['foo', 'bar', 100, 1234] +>>> a[2] = a[2] + 23 +>>> a +['foo', 'bar', 123, 1234] +>>> +\end{verbatim}\ecode +Assignment to slices is also possible, and this may even change the size +of the list: +\bcode\begin{verbatim} +>>> # Replace some items: +>>> a[0:2] = [1, 12] +>>> a +[1, 12, 123, 1234] +>>> # Remove some: +>>> a[0:2] = [] +>>> a +[123, 1234] +>>> # Insert some: +>>> a[1:1] = ['bletch', 'xyzzy'] +>>> a +[123, 'bletch', 'xyzzy', 1234] +>>> +\end{verbatim}\ecode +The built-in function {\tt len()} also applies to lists: +\bcode\begin{verbatim} +>>> len(a) +4 +>>> +\end{verbatim}\ecode + +\subsection{Tuples and Sequences} + +XXX To Be Done. + +\subsection{First Steps Towards Programming} + +Of course, we can use \Python\ for more complicated tasks than adding two +and two together. +For instance, we can write an initial subsequence of the +{\em Fibonacci} +series as follows: +\bcode\begin{verbatim} +>>> # Fibonacci series: +>>> # the sum of two elements defines the next +>>> a, b = 0, 1 +>>> while b < 100: +... print b +... a, b = b, a+b +... +1 +1 +2 +3 +5 +8 +13 +21 +34 +55 +89 +>>> +\end{verbatim}\ecode +This example introduces several new features. +\begin{itemize} +\item +The first line contains a +{\em multiple\ assignment}: +the variables +{\tt a} +and +{\tt b} +simultaneously get the new values 0 and 1. +On the last line this is used again, demonstrating that the expressions +on the right-hand side are all evaluated first before any of the +assignments take place. +\item +The +{\tt while} +loop executes as long as the condition (here: $b < 100$) remains true. +In \Python, as in C, any non-zero integer value is true; zero is false. +The condition may also be a string or list value, in fact any sequence; +anything with a non-zero length is true, empty sequences are false. +The test used in the example is a simple comparison. +The standard comparison operators are written as +{\tt <}, +{\tt >}, +{\tt =}, +{\tt <=}, +{\tt >=} +and +{\tt <>}.% +\footnote{ + The ambiguity of using {\tt =} + for both assignment and equality is resolved by disallowing + unparenthesized conditions at the right hand side of assignments. +} +\item +The +{\em body} +of the loop is +{\em indented}: indentation is \Python's way of grouping statements. +\Python\ does not (yet!) provide an intelligent input line editing +facility, so you have to type a tab or space(s) for each indented line. +In practice you will prepare more complicated input for \Python\ with a +text editor; most text editors have an auto-indent facility. +When a compound statement is entered interactively, it must be +followed by a blank line to indicate completion (since the parser +cannot guess when you have typed the last line). +\item +The +{\tt print} +statement writes the value of the expression(s) it is given. +It differs from just writing the expression you want to write (as we did +earlier in the calculator examples) in the way it handles multiple +expressions and strings. +Strings are written without quotes and a space is inserted between +items, so you can format things nicely, like this: +\bcode\begin{verbatim} +>>> i = 256*256 +>>> print 'The value of i is', i +The value of i is 65536 +>>> +\end{verbatim}\ecode +A trailing comma avoids the newline after the output: +\bcode\begin{verbatim} +>>> a, b = 0, 1 +>>> while b < 1000: +... print b, +... a, b = b, a+b +... +1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 +>>> +\end{verbatim}\ecode +Note that the interpreter inserts a newline before it prints the next +prompt if the last line was not completed. +\end{itemize} + +\subsection{More Control Flow Tools} + +Besides the {\tt while} statement just introduced, \Python\ knows the +usual control flow statements known from other languages, with some +twists. + +\subsubsection{If Statements} + +Perhaps the most well-known statement type is the {\tt if} statement. +For example: +\bcode\begin{verbatim} +>>> if x < 0: +... x = 0 +... print 'Negative changed to zero' +... elif x = 0: +... print 'Zero' +... elif x = 1: +... print 'Single' +... else: +... print 'More' +... +\end{verbatim}\ecode +There can be zero or more {\tt elif} parts, and the {\tt else} part is +optional. +The keyword `{\tt elif}' is short for `{\tt else if}', and is useful to +avoid excessive indentation. +An {\tt if...elif...elif...} sequence is a substitute for the +{\em switch} or {\em case} statements found in other languages. + +\subsubsection{For Statements} + +The {\tt for} statement in \Python\ differs a bit from what you may be +used to in C or Pascal. +Rather than always iterating over an arithmetic progression of numbers +(as Pascal), or leaving the user completely free in the iteration test +and step (as C), \Python's {\tt for} statement iterates over the items +of any sequence (e.g., a list or a string). +For example (no pun intended): +\bcode\begin{verbatim} +>>> # Measure some strings: +>>> a = ['cat', 'window', 'defenestrate'] +>>> for x in a: +... print x, len(x) +... +cat 3 +window 6 +defenestrate 12 +>>> +\end{verbatim}\ecode + +\subsubsection{The {\tt range()} Function} + +If you do need to iterate over a sequence of numbers, the built-in +function {\tt range()} comes in handy. +It generates lists containing arithmetic progressions, +e.g.: +\bcode\begin{verbatim} +>>> range(10) +[0, 1, 2, 3, 4, 5, 6, 7, 8, 9] +>>> +\end{verbatim}\ecode +The given end point is never part of the generated list; +{\tt range(10)} generates a list of 10 values, +exactly the legal indices for items of a sequence of length 10. +It is possible to let the range start at another number, or to specify a +different increment (even negative): +\bcode\begin{verbatim} +>>> range(5, 10) +[5, 6, 7, 8, 9] +>>> range(0, 10, 3) +[0, 3, 6, 9] +>>> range(-10, -100, -30) +[-10, -40, -70] +>>> +\end{verbatim}\ecode +To iterate over the indices of a sequence, combine {\tt range()} +and {\tt len()} as follows: +\bcode\begin{verbatim} +>>> a = ['Mary', 'had', 'a', 'little', 'boy'] +>>> for i in range(len(a)): +... print i, a[i] +... +0 Mary +1 had +2 a +3 little +4 boy +>>> +\end{verbatim}\ecode + +\subsubsection{Break Statements and Else Clauses on Loops} + +The {\tt break} statement breaks out of the smallest enclosing {\tt for} +or {\tt while} loop. +Loop statements may have an {\tt else} clause; it is executed when the +loop terminates through exhaustion of the list (with {\tt for}) or when +the condition becomes false (with {\tt while}) but not when the loop is +terminated by a {\tt break} statement. +This is exemplified by the following loop, which searches for a list +item of value 0: +\bcode\begin{verbatim} +>>> for n in range(2, 10): +... for x in range(2, n): +... if n % x = 0: +... print n, 'equals', x, '*', n/x +... break +... else: +... print n, 'is a prime number' +... +2 is a prime number +3 is a prime number +4 equals 2 * 2 +5 is a prime number +6 equals 2 * 3 +7 is a prime number +8 equals 2 * 4 +9 equals 3 * 3 +>>> +\end{verbatim}\ecode + +\subsubsection{Pass Statements} + +The {\tt pass} statement does nothing. +It can be used when a statement is required syntactically but the +program requires no action. +For example: +\bcode\begin{verbatim} +>>> while 1: +... pass # Busy-wait for keyboard interrupt +... +\end{verbatim}\ecode + +\subsubsection{Conditions Revisited} + +XXX To Be Done. + +\subsection{Defining Functions} + +We can create a function that writes the Fibonacci series to an +arbitrary boundary: +\bcode\begin{verbatim} +>>> def fib(n): # write Fibonacci series up to n +... a, b = 0, 1 +... while b <= n: +... print b, +... a, b = b, a+b +... +>>> # Now call the function we just defined: +>>> fib(2000) +1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597 +>>> +\end{verbatim}\ecode +The keyword +{\tt def} +introduces a function +{\em definition}. +It must be followed by the function name and the parenthesized list of +formal parameters. +The statements that form the body of the function starts at the next +line, indented by a tab stop. +The +{\em execution} +of a function introduces a new symbol table used for the local variables +of the function. +More precisely, all variable assignments in a function store the value +in the local symbol table; variable references first look in the local +symbol table, then in the global symbol table, and then in the table of +built-in names. +Thus, the global symbol table is +{\em read-only} +within a function. +The actual parameters (arguments) to a function call are introduced in +the local symbol table of the called function when it is called; +thus, arguments are passed using +{\em call\ by\ value}.% +\footnote{ + Actually, {\em call by object reference} would be a better + description, since if a mutable object is passed, the caller + will see any changes the callee makes to it (e.g., items + inserted into a list). +} +When a function calls another function, a new local symbol table is +created for that call. + +A function definition introduces the function name in the global symbol +table. +The value has a type that is recognized by the interpreter as a +user-defined function. +This value can be assigned to another name which can then also be used +as a function. +This serves as a general renaming mechanism: +\bcode\begin{verbatim} +>>> fib +<function object at 10042ed0> +>>> f = fib +>>> f(100) +1 1 2 3 5 8 13 21 34 55 89 +>>> +\end{verbatim}\ecode +You might object that +{\tt fib} +is not a function but a procedure. +In \Python, as in C, procedures are just functions that don't return a +value. +In fact, technically speaking, procedures do return a value, albeit a +rather boring one. +This value is called {\tt None} (it's a built-in name). +Writing the value {\tt None} is normally suppressed by the interpreter +if it would be the only value written. +You can see it if you really want to: +\bcode\begin{verbatim} +>>> print fib(0) +None +>>> +\end{verbatim}\ecode +It is simple to write a function that returns a list of the numbers of +the Fibonacci series, instead of printing it: +\bcode\begin{verbatim} +>>> def fib2(n): # return Fibonacci series up to n +... result = [] +... a, b = 0, 1 +... while b <= n: +... result.append(b) # see below +... a, b = b, a+b +... return result +... +>>> f100 = fib2(100) # call it +>>> f100 # write the result +[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89] +>>> +\end{verbatim}\ecode +This example, as usual, demonstrates some new \Python\ features: +\begin{itemize} +\item +The +{\tt return} +statement returns with a value from a function. +{\tt return} +without an expression argument is used to return from the middle of a +procedure (falling off the end also returns from a proceduce). +\item +The statement +{\tt ret.append(b)} +calls a +{\em method} +of the list object +{\tt ret}. +A method is a function that `belongs' to an object and is named +{\tt obj.methodname}, +where +{\tt obj} +is some object (this may be an expression), and +{\tt methodname} +is the name of a method that is defined by the object's type. +Different types define different methods. +Methods of different types may have the same name without causing +ambiguity. +See the section on classes, later, to find out how you can define your +own object types and methods. +The method +{\tt append} +shown in the example, is defined for list objects; it adds a new element +at the end of the list. +In this case it is equivalent to +{\tt ret = ret + [b]}, +but more efficient.% +\footnote{ + There is a subtle semantic difference if the object + is referenced from more than one place. +} +\end{itemize} +The list object type has two more methods: +\begin{description} +\item[{\tt insert(i, x)}] +Inserts an item at a given position. +The first argument is the index of the element before which to insert, +so {\tt a.insert(0, x)} inserts at the front of the list, and +{\tt a.insert(len(a), x)} is equivalent to {\tt a.append(x)}. +\item[{\tt sort()}] +Sorts the elements of the list. +\end{description} +For example: +\bcode\begin{verbatim} +>>> a = [10, 100, 1, 1000] +>>> a.insert(2, -1) +>>> a +[10, 100, -1, 1, 1000] +>>> a.sort() +>>> a +[-1, 1, 10, 100, 1000] +>>> # Strings are sorted according to ASCII: +>>> b = ['Mary', 'had', 'a', 'little', 'boy'] +>>> b.sort() +>>> b +['Mary', 'a', 'boy', 'had', 'little'] +>>> +\end{verbatim}\ecode + +\subsection{Modules} + +If you quit from the \Python\ interpreter and enter it again, the +definitions you have made (functions and variables) are lost. +Therefore, if you want to write a somewhat longer program, you are +better off using a text editor to prepare the input for the interpreter +and run it with that file as input instead. +This is known as creating a +{\em script}. +As your program gets longer, you may want to split it into several files +for easier maintenance. +You may also want to use a handy function that you've written in several +programs without copying its definition into each program. +To support this, \Python\ has a way to put definitions in a file and use +them in a script or in an interactive instance of the interpreter. +Such a file is called a +{\em module}; +definitions from a module can be +{\em imported} +into other modules or into the +{\em main} +module (the collection of variables that you have access to in +a script and in calculator mode). + +A module is a file containing \Python\ definitions and statements. +The file name is the module name with the suffix +{\tt .py} +appended. +For instance, use your favorite text editor to create a file called +{\tt fibo.py} +in the current directory with the following contents: +\bcode\begin{verbatim} +# Fibonacci numbers module + +def fib(n): # write Fibonacci series up to n + a, b = 0, 1 + while b <= n: + print b, + a, b = b, a+b + +def fib2(n): # return Fibonacci series up to n + ret = [] + a, b = 0, 1 + while b <= n: + ret.append(b) + a, b = b, a+b + return ret +\end{verbatim}\ecode +Now enter the \Python\ interpreter and import this module with the +following command: +\bcode\begin{verbatim} +>>> import fibo +>>> +\end{verbatim}\ecode +This does not enter the names of the functions defined in +{\tt fibo} +directly in the symbol table; it only enters the module name +{\tt fibo} +there. +Using the module name you can access the functions: +\bcode\begin{verbatim} +>>> fibo.fib(1000) +1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 +>>> fibo.fib2(100) +[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89] +>>> +\end{verbatim}\ecode +If you intend to use a function often you can assign it to a local name: +\bcode\begin{verbatim} +>>> fib = fibo.fib +>>> fib(500) +1 1 2 3 5 8 13 21 34 55 89 144 233 377 +>>> +\end{verbatim}\ecode + +\subsubsection{More on Modules} + +A module can contain executable statements as well as function +definitions. +These statements are intended to initialize the module. +They are executed only the +{\em first} +time the module is imported somewhere.% +\footnote{ + In fact function definitions are also `statements' that are + `executed'; the execution enters the function name in the + module's global symbol table. +} + +Each module has its own private symbol table, which is used as the +global symbol table by all functions defined in the module. +Thus, the author of a module can use global variables in the module +without worrying about accidental clashes with a user's global +variables. +On the other hand, if you know what you are doing you can touch a +module's global variables with the same notation used to refer to its +functions, +{\tt modname.itemname}. + +Modules can import other modules. +It is customary but not required to place all +{\tt import} +statements at the beginning of a module (or script, for that matter). +The imported module names are placed in the importing module's global +symbol table. + +There is a variant of the +{\tt import} +statement that imports names from a module directly into the importing +module's symbol table. +For example: +\bcode\begin{verbatim} +>>> from fibo import fib, fib2 +>>> fib(500) +1 1 2 3 5 8 13 21 34 55 89 144 233 377 +>>> +\end{verbatim}\ecode +This does not introduce the module name from which the imports are taken +in the local symbol table (so in the example, {\tt fibo} is not +defined). + +There is even a variant to import all names that a module defines: +\bcode\begin{verbatim} +>>> from fibo import * +>>> fib(500) +1 1 2 3 5 8 13 21 34 55 89 144 233 377 +>>> +\end{verbatim}\ecode +This imports all names except those beginning with an underscore +({\tt \_}). + +\subsubsection{Standard Modules} + +\Python\ comes with a library of standard modules, described in a separate +document (Python Library and Module Reference). +Some modules are built into the interpreter; these provide access to +operations that are not part of the core of the language but are +nevertheless built in, either for efficiency or to provide access to +operating system primitives such as system calls. +The set of such modules is a configuration option; e.g., the +{\tt amoeba} +module is only provided on systems that somehow support Amoeba +primitives. +One particular module deserves some attention: +{\tt sys}, +which is built into every \Python\ interpreter. +The variables +{\tt sys.ps1} +and +{\tt sys.ps2} +define the strings used as primary and secondary prompts: +\bcode\begin{verbatim} +>>> import sys +>>> sys.ps1 +'>>> ' +>>> sys.ps2 +'... ' +>>> sys.ps1 = 'C> ' +C> print 'Yuck!' +Yuck! +C> +\end{verbatim}\ecode +These two variables are only defined if the interpreter is in +interactive mode. + +The variable +{\tt sys.path} +is a list of strings that determine the interpreter's search path for +modules. +It is initialized to a default path taken from the environment variable +{\tt PYTHONPATH}, +or from a built-in default if +{\tt PYTHONPATH} +is not set. +You can modify it using standard list operations, e.g.: +\bcode\begin{verbatim} +>>> import sys +>>> sys.path.append('/ufs/guido/lib/python') +>>> +\end{verbatim}\ecode + +\subsection{Errors and Exceptions} + +Until now error messages haven't yet been mentioned, but if you have +tried out the examples you have probably seen some. +There are (at least) two distinguishable kinds of errors: +{\em syntax\ errors} +and +{\em exceptions}. + +\subsubsection{Syntax Errors} + +Syntax errors, also known as parsing errors, are perhaps the most common +kind of complaint you get while you are still learning \Python: +\bcode\begin{verbatim} +>>> while 1 print 'Hello world' +Parsing error: file <stdin>, line 1: +while 1 print 'Hello world' + ^ +Unhandled exception: run-time error: syntax error +>>> +\end{verbatim}\ecode +The parser repeats the offending line and displays a little `arrow' +pointing at the earliest point in the line where the error was detected. +The error is caused by (or at least detected at) the token +{\em preceding} +the arrow: in the example, the error is detected at the keyword +{\tt print}, since a colon ({\tt :}) is missing before it. +File name and line number are printed so you know where to look in case +the input came from a script. + +\subsubsection{Exceptions} + +Even if a statement or expression is syntactically correct, it may cause +an error when an attempt is made to execute it: +\bcode\small\begin{verbatim} +>>> 10 * (1/0) +Unhandled exception: run-time error: integer division by zero +Stack backtrace (innermost last): + File "<stdin>", line 1 +>>> 4 + foo*3 +Unhandled exception: undefined name: foo +Stack backtrace (innermost last): + File "<stdin>", line 1 +>>> '2' + 2 +Unhandled exception: type error: illegal argument type for built-in operation +Stack backtrace (innermost last): + File "<stdin>", line 1 +>>> +\end{verbatim}\ecode +Errors detected during execution are called +{\em exceptions} +and are not unconditionally fatal: you will soon learn how to handle +them in \Python\ programs. +Most exceptions are not handled by programs, however, and result +in error messages as shown here. + +The first line of the error message indicates what happened. +Exceptions come in different types, and the type is printed as part of +the message: the types in the example are +{\tt run-time error}, +{\tt undefined name} +and +{\tt type error}. +The rest of the line is a detail whose interpretation depends on the +exception type. + +The rest of the error message shows the context where the +exception happened. +In general it contains a stack backtrace listing source lines; however, +it will not display lines read from standard input. + +Here is a summary of the most common exceptions: +\begin{itemize} +\item +{\em Run-time\ errors} +are generally caused by wrong data used by the program; this can be the +programmer's fault or caused by bad input. +The detail states the cause of the error in more detail. +\item +{\em Undefined\ name} +errors are more serious: these are usually caused by misspelled +identifiers.% +\footnote{ + The parser does not check whether names used in a program are at + all defined elsewhere in the program, so such checks are + postponed until run-time. The same holds for type checking. +} +The detail is the offending identifier. +\item +{\em Type\ errors} +are also pretty serious: this is another case of using wrong data (or +better, using data the wrong way), but here the error can be glanced +from the object type(s) alone. +The detail shows in what context the error was detected. +\end{itemize} + +\subsubsection{Handling Exceptions} + +It is possible to write programs that handle selected exceptions. +Look at the following example, which prints a table of inverses of +some floating point numbers: +\bcode\begin{verbatim} +>>> numbers = [0.3333, 2.5, 0.0, 10.0] +>>> for x in numbers: +... print x, +... try: +... print 1.0 / x +... except RuntimeError: +... print '*** has no inverse ***' +... +0.3333 3.00030003 +2.5 0.4 +0 *** has no inverse *** +10 0.1 +>>> +\end{verbatim}\ecode +The {\tt try} statement works as follows. +\begin{itemize} +\item +First, the +{\em try\ clause} +(the statement(s) between the {\tt try} and {\tt except} keywords) is +executed. +\item +If no exception occurs, the +{\em except\ clause} +is skipped and execution of the {\tt try} statement is finished. +\item +If an exception occurs during execution of the try clause, and its +type matches the exception named after the {\tt except} keyword, the +rest of the try clause is skipped, the except clause is executed, and +then execution continues after the {\tt try} statement. +\item +If an exception occurs which does not match the exception named in the +except clause, it is passed on to outer try statements; if no handler is +found, it is an +{\em unhandled\ exception} +and execution stops with a message as shown above. +\end{itemize} +A {\tt try} statement may have more than one except clause, to specify +handlers for different exceptions. +At most one handler will be executed. +Handlers only handle exceptions that occur in the corresponding try +clause, not in other handlers of the same {\tt try} statement. +An except clause may name multiple exceptions as a parenthesized list, +e.g.: +\bcode\begin{verbatim} +... except (RuntimeError, TypeError, NameError): +... pass +\end{verbatim}\ecode +The last except clause may omit the exception name(s), to serve as a +wildcard. +Use this with extreme caution! + +When an exception occurs, it may have an associated value, also known as +the exceptions's +{\em argument}. +The presence and type of the argument depend on the exception type. +For exception types which have an argument, the except clause may +specify a variable after the exception name (or list) to receive the +argument's value, as follows: +\bcode\begin{verbatim} +>>> try: +... foo() +... except NameError, x: +... print 'name', x, 'undefined' +... +name foo undefined +>>> +\end{verbatim}\ecode +If an exception has an argument, it is printed as the third part +(`detail') of the message for unhandled exceptions. + +Standard exception names are built-in identifiers (not reserved +keywords). +These are in fact string objects whose +{\em object\ identity} +(not their value!) identifies the exceptions.% +\footnote{ + There should really be a separate exception type; it is pure + laziness that exceptions are identified by strings, and this may + be fixed in the future. +} +The string is printed as the second part of the message for unhandled +exceptions. +Their names and values are: +\bcode\begin{verbatim} +EOFError 'end-of-file read' +KeyboardInterrupt 'keyboard interrupt' +MemoryError 'out of memory' * +NameError 'undefined name' * +RuntimeError 'run-time error' * +SystemError 'system error' * +TypeError 'type error' * +\end{verbatim}\ecode +The meanings should be clear enough. +Those exceptions with a {\tt *} in the third column have an argument. + +Exception handlers don't just handle exceptions if they occur +immediately in the try clause, but also if they occur inside functions +that are called (even indirectly) in the try clause. +For example: +\bcode\begin{verbatim} +>>> def this_fails(): +... x = 1/0 +... +>>> try: +... this_fails() +... except RuntimeError, detail: +... print 'Handling run-time error:', detail +... +Handling run-time error: domain error or zero division +>>> +\end{verbatim}\ecode + +\subsubsection{Raising Exceptions} + +The {\tt raise} statement allows the programmer to force a specified +exception to occur. +For example: +\bcode\begin{verbatim} +>>> raise NameError, 'Hi There!' +Unhandled exception: undefined name: Hi There! +Stack backtrace (innermost last): + File "<stdin>", line 1 +>>> +\end{verbatim}\ecode +The first argument to {\tt raise} names the exception to be raised. +The optional second argument specifies the exception's argument. + +\subsubsection{User-defined Exceptions} + +Programs may name their own exceptions by assigning a string to a +variable. +For example: +\bcode\begin{verbatim} +>>> my_exc = 'nobody likes me!' +>>> try: +... raise my_exc, 2*2 +... except my_exc, val: +... print 'My exception occured, value:', val +... +My exception occured, value: 4 +>>> raise my_exc, 1 +Unhandled exception: nobody likes me!: 1 +Stack backtrace (innermost last): + File "<stdin>", line 7 +>>> +\end{verbatim}\ecode +Many standard modules use this to report errors that may occur in +functions they define. + +\subsubsection{Defining Clean-up Actions} + +The {\tt try} statement has another optional clause which is intended to +define clean-up actions that must be executed under all circumstances. +For example: +\bcode\begin{verbatim} +>>> try: +... raise KeyboardInterrupt +... finally: +... print 'Goodbye, world!' +... +Goodbye, world! +Unhandled exception: keyboard interrupt +Stack backtrace (innermost last): + File "<stdin>", line 2 +>>> +\end{verbatim}\ecode +The +{\em finally\ clause} +must follow the except clauses(s), if any. +It is executed whether or not an exception occurred. +If the exception is handled, the finally clause is executed after the +handler (and even if another exception occurred in the handler). +It is also executed when the {\tt try} statement is left via a +{\tt break} or {\tt return} statement. + +\subsection{Classes} + +Classes in \Python\ make it possible to play the game of encapsulation in a +somewhat different way than it is played with modules. +Classes are an advanced topic and are probably best skipped on the first +encounter with \Python. + +\subsubsection{Prologue} + +\Python's class mechanism is not particularly elegant, but quite powerful. +It is a mixture of the class mechanisms found in C++ and Modula-3. +As is true for modules, classes in \Python\ do not put an absolute barrier +between definition and user, but rather rely on the politeness of the +user not to ``break into the definition.'' +The most important features of classes are retained with full power, +however: the class inheritance mechanism allows multiple base classes, +a derived class can override any method of its base class(es), a method +can call the method of a base class with the same name. +Objects can contain an arbitrary amount of private data. + +In C++ terminology, all class members (including data members) are +{\em public}, +and all member functions (methods) are +{\em virtual}. +There are no special constructors or destructors. +As in Modula-3, there are no shorthands for referencing the object's +members from its methods: the method function is declared with an +explicit first argument representing the object, which is provided +implicitly by the call. +As in Smalltalk, classes themselves are objects, albeit in the wider +sense of the word: in \Python, all data types are objects. +This provides semantics for renaming or aliasing. +But, just like in C++ or Modula-3, the built-in types cannot be used as +base classes for extension by the user. +Also, like Modula-3 but unlike C++, the built-in operators with special +syntax (arithmetic operators, subscripting etc.) cannot be redefined for +class members.% +\footnote{ + They can be redefined for new object types implemented in C in + extensions to the interpreter, however. It would require only a + naming convention and a relatively small change to the + interpreter to allow operator overloading for classes, so + perhaps someday... +} + +\subsubsection{A Simple Example} + +Consider the following example, which defines a class {\tt Set} +representing a (finite) mathematical set with operations to add and +remove elements, a membership test, and a request for the size of the +set. +\bcode\begin{verbatim} +class Set(): + def new(self): + self.elements = [] + return self + def add(self, e): + if e not in self.elements: + self.elements.append(e) + def remove(self, e): + if e in self.elements: + for i in range(len(self.elements)): + if self.elements[i] = e: + del self.elements[i] + break + def is_element(self, e): + return e in self.elements + def size(self): + return len(self.elements) +\end{verbatim}\ecode +Note that the class definition looks like a big compound statement, +with all the function definitons indented repective to the +{\tt class} +keyword. + +Let's assume that this +{\em class\ definition} +is the only contents of the module file +{\tt SetClass.py}. +We can then use it in a \Python\ program as follows: +\bcode\begin{verbatim} +>>> from SetClass import Set +>>> a = Set().new() # create a Set object +>>> a.add(2) +>>> a.add(3) +>>> a.add(1) +>>> a.add(1) +>>> if a.is_element(3): print '3 is in the set' +... +3 is in the set +>>> if not a.is_element(4): print '4 is not in the set' +... +4 is not in the set +>>> print 'a has', a.size(), 'elements' +a has 3 elements +>>> a.remove(1) +>>> print 'now a has', a.size(), 'elements' +>>> +now a has 2 elements +>>> +\end{verbatim}\ecode +From the example we learn in the first place that the functions defined +in the class (e.g., +{\tt add}) +can be called using the +{\em member} +notation for the object +{\tt a}. +The member function is called with one less argument than it is defined: +the object is implicitly passed as the first argument. +Thus, the call +{\tt a.add(2)} +is equivalent to +{\tt Set.add(a, 2)}. + +XXX This section is not complete yet! + +\section{XXX P.M.} + +\begin{itemize} +\item The {\tt del} statement. +\item The {\tt dir()} function. +\item Tuples. +\item Dictionaries. +\item Objects and types in general. +\item Backquotes. +\item And/Or/Not. +\end{itemize} + +\end{document} |