diff options
Diffstat (limited to 'shar/python-0.9.1-01-21.shar')
| -rw-r--r-- | shar/python-0.9.1-01-21.shar | 1952 |
1 files changed, 1952 insertions, 0 deletions
diff --git a/shar/python-0.9.1-01-21.shar b/shar/python-0.9.1-01-21.shar new file mode 100644 index 0000000..75c124e --- /dev/null +++ b/shar/python-0.9.1-01-21.shar @@ -0,0 +1,1952 @@ +: This is a shell archive. +: Extract with 'sh this_file'. +: Extract this part first since it makes all directories +echo 'Start of pack.out, part 01 out of 21:' +echo -n 'Making directories ... ' +err="no" +test -d 'demo' || mkdir 'demo' || err="yes" +test -d 'demo/scripts' || mkdir 'demo/scripts' || err="yes" +test -d 'demo/sgi' || mkdir 'demo/sgi' || err="yes" +test -d 'demo/sgi/audio' || mkdir 'demo/sgi/audio' || err="yes" +test -d 'demo/sgi/audio_stdwin' || mkdir 'demo/sgi/audio_stdwin' || err="yes" +test -d 'demo/sgi/gl' || mkdir 'demo/sgi/gl' || err="yes" +test -d 'demo/sgi/gl_panel' || mkdir 'demo/sgi/gl_panel' || err="yes" +test -d 'demo/sgi/gl_panel/apanel' || mkdir 'demo/sgi/gl_panel/apanel' || err="yes" +test -d 'demo/sgi/gl_panel/flying' || mkdir 'demo/sgi/gl_panel/flying' || err="yes" +test -d 'demo/sgi/gl_panel/nurbs' || mkdir 'demo/sgi/gl_panel/nurbs' || err="yes" +test -d 'demo/sgi/gl_panel/twoview' || mkdir 'demo/sgi/gl_panel/twoview' || err="yes" +test -d 'demo/stdwin' || mkdir 'demo/stdwin' || err="yes" +test -d 'doc' || mkdir 'doc' || err="yes" +test -d 'lib' || mkdir 'lib' || err="yes" +test -d 'src' || mkdir 'src' || err="yes" +echo 'done' +if test "$err" = "yes" +then echo "didn't make it." +fi +if test -s 'README' +then echo '*** I will not over-write existing file README' +else +echo 'x - README' +sed 's/^X//' > 'README' << 'EOF' +XThis is Python, an extensible interpreted programming language that +Xcombines remarkable power with very clear syntax. +X +XThis is version 0.9 (the first beta release), patchlevel 1. +X +XPython can be used instead of shell, Awk or Perl scripts, to write +Xprototypes of real applications, or as an extension language of large +Xsystems, you name it. There are built-in modules that interface to +Xthe operating system and to various window systems: X11, the Mac +Xwindow system (you need STDWIN for these two), and Silicon Graphics' +XGL library. It runs on most modern versions of UNIX, on the Mac, and +XI wouldn't be surprised if it ran on MS-DOS unchanged. I developed it +Xmostly on an SGI IRIS workstation (using IRIX 3.1 and 3.2) and on the +XMac, but have tested it also on SunOS (4.1) and BSD 4.3 (tahoe). +X +XBuilding and installing Python is easy (but do read the Makefile). +XA UNIX style manual page and extensive documentation (in LaTeX format) +Xare provided. (In the beta release, the documentation is still under +Xdevelopment.) +X +XPlease try it out and send me your comments (on anything -- the +Xlanguage design, implementation, portability, installation, +Xdocumentation) and the modules you wrote for it, to make the first +Xreal release better. If you needed to hack the source to get it to +Xcompile and run on a particular machine, send me the fixes -- I'll try +Xto incorporate them into the next patch. If you can't get it to work +Xat all, send me a *detailed* description of the problem and I may look +Xinto it. +X +XIf you want to profit of the X11 or Mac window interface, you'll need +XSTDWIN. This is a portable window system interface by the same +Xauthor. The versions of STDWIN floating around on some archives are +Xnot sufficiently up-to-date for use with Python. I will distribute +Xthe latest and greatest STDWIN version at about the same time as Python. +X +XI am the author of Python: +X +X Guido van Rossum +X CWI, dept. CST +X Kruislaan 413 +X 1098 SJ Amsterdam +X The Netherlands +X +X E-mail: [email protected] +X +XThe Python source is copyrighted, but you can freely use and copy it +Xas long as you don't change or remove the copyright: +X +X/*********************************************************** +XCopyright 1991 by Stichting Mathematisch Centrum, Amsterdam, The +XNetherlands. +X +X All Rights Reserved +X +XPermission to use, copy, modify, and distribute this software and its +Xdocumentation for any purpose and without fee is hereby granted, +Xprovided that the above copyright notice appear in all copies and that +Xboth that copyright notice and this permission notice appear in +Xsupporting documentation, and that the names of Stichting Mathematisch +XCentrum or CWI not be used in advertising or publicity pertaining to +Xdistribution of the software without specific, written prior permission. +X +XSTICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO +XTHIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND +XFITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE +XFOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +XWHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +XACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT +XOF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +X +X******************************************************************/ +EOF +fi +if test -s 'python.man' +then echo '*** I will not over-write existing file python.man' +else +echo 'x - python.man' +sed 's/^X//' > 'python.man' << 'EOF' +X.TH PYTHON "19 February 1991" +X.SH NAME +Xpython \(en an extensible interpreted programming language +X.SH SYNOPSIS +X.B python +X[ +X.I X11-options +X] [ +X.I script +X[ +X.I arguments +X] ] +X.SH DESCRIPTION +XPython is an extensible interpreted programming language that +Xcombines remarkable power with very clear syntax. +XFor an introduction to programming in Python you are referred to the +XPython Tutorial. +X.PP +XThe interpreter operates somewhat like the UNIX shell: when called with +Xstandard input connected to a tty device, it reads and executes commands +Xinteractively until an EOF is read; +Xwhen called with a file name argument or with a file as standard +Xinput, it reads and executes a +X.I script +Xfrom that file. +XIf available, the script name and additional arguments thereafter are +Xpassed to the script in the variable +X.I sys.argv , +Xwhich is a list of strings. +XIn interactive mode, the primary prompt is `>>>'; the second prompt +X(which appears when a command is not complete) is `...'. +X.SH FILES AND DIRECTORIES +X.IP /usr/local/lib/python +XThis might be the directory containing the library of standard modules. +X(Installation-dependent.) +X.SH ENVIRONMENT VARIABLES +X.IP PYTHONPATH +XSets the search path for module files. +XThe format is the same as the shell's $PATH: one or more directory +Xpathnames separated by colons. +XNon-existant directories are silently ignored. +XThe default search path is installation dependent, but always begins +Xwith `.', (for example, +X.I .:/usr/local/lib/python ). +X.SH SEE ALSO +XPython Tutorial +X.br +XPython Library Reference +X.SH AUTHOR +X.nf +XGuido van Rossum +XCWI, dept. CST +XKruislaan 413 +X1098 SJ Amsterdam +XThe Netherlands +X.PP +XE-mail: [email protected] +X.fi +X.SH COPYRIGHT +XCopyright 1991 by Stichting Mathematisch Centrum, Amsterdam, The +XNetherlands. +X.IP " " +XAll Rights Reserved +X.PP +XPermission to use, copy, modify, and distribute this software and its +Xdocumentation for any purpose and without fee is hereby granted, +Xprovided that the above copyright notice appear in all copies and that +Xboth that copyright notice and this permission notice appear in +Xsupporting documentation, and that the names of Stichting Mathematisch +XCentrum or CWI not be used in advertising or publicity pertaining to +Xdistribution of the software without specific, written prior permission. +X +XSTICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO +XTHIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND +XFITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE +XFOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +XWHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +XACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT +XOF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +EOF +fi +if test -s 'demo/sgi/gl_panel/nurbs/nurbs.py' +then echo '*** I will not over-write existing file demo/sgi/gl_panel/nurbs/nurbs.py' +else +echo 'x - demo/sgi/gl_panel/nurbs/nurbs.py' +sed 's/^X//' > 'demo/sgi/gl_panel/nurbs/nurbs.py' << 'EOF' +X#! /ufs/guido/bin/sgi/python +X +X# Fancy NURBS demo. Require Z buffer and Panel Library. +X +Xfrom gl import * +Xfrom GL import * +Xfrom DEVICE import * +Xfrom nurbsdata import * +Ximport panel +X +X# +X# flags = trim_f, invis_f, cpvis_f, tpvis_f, axvis_f, freeze_f +X# +XTRIM = 0 +XVIS = 1 +XCPVIS = 2 +XTPVIS = 3 +XAXVIS = 4 +XFREEZE = 5 +Xflags = [0, 1, 0, 0, 0, 0] +X +Xdef draw_axis () : +X cpack (0x0) +X zero = (0.0, 0.0, 0.0) +X # +X one = (1.0, 0.0, 0.0) +X smallline (zero, one) +X cmov (1.0, 0.0, 0.0) +X charstr ('x') +X # +X one = (0.0, 1.0, 0.0) +X smallline (zero, one) +X cmov (0.0, 1.0, 0.0) +X charstr ('y') +X # +X one = (0.0, 0.0, 1.0) +X smallline (zero, one) +X cmov (0.0, 0.0, 1.0) +X charstr ('z') +X +XDELTA = 0.1 +X +Xdef cross (p) : +X p0 = [p[0], p[1], p[2]] +X p1 = [p[0], p[1], p[2]] +X for i in range (0, 3) : +X p0[i] = p0[i] + DELTA +X p1[i] = p1[i] - DELTA +X smallline (p0, p1) +X p0[i] = p0[i] - DELTA +X p1[i] = p1[i] + DELTA +X +Xdef smallline (p0, p1) : +X bgnline () +X v3f (p0) +X v3f (p1) +X endline () +X +Xdef draw_pts (pnts, color) : +X linewidth (2) +X cpack (color) +X for i in pnts : +X cross (i) +X +Xdef init_windows(): +X foreground() +X wid = winopen('nurbs') +X wintitle('NURBS Surface') +X doublebuffer() +X RGBmode() +X gconfig() +X lsetdepth(0x000, 0x7fffff) +X zbuffer( TRUE ) +X +Xdef init_view(): +X mmode(MPROJECTION) +X ortho( -5., 5., -5., 5., -5., 5. ) +X # +X mmode(MVIEWING) +X loadmatrix(idmat) +X # +X lmbind(MATERIAL, 1) +X +Xdef set_scene(flags): +X # +X lmbind(MATERIAL, 0) +X RGBcolor(150,150,150) +X lmbind(MATERIAL, 1) +X clear() +X zclear() +X # +X if not flags[FREEZE] : +X rotate( 100, 'y' ) +X rotate( 100, 'z' ) +X +Xdef draw_trim_surface(flags): +X pnts = ctlpoints +X if flags[VIS] : +X bgnsurface() +X nurbssurface(surfknots,surfknots,pnts,ORDER,ORDER,N_XYZ) +X if flags[TRIM]: +X bgntrim() +X nurbscurve(trimknots,trimpoints,ORDER-1,N_STW) +X endtrim() +X endsurface() +X # +X if flags[CPVIS] : +X for i in pnts : +X draw_pts (i, RED) +X # +X if flags[TPVIS] : +X tpts = trimpoints +X draw_pts (tpts, YELLOW) +X # +X if flags[AXVIS] : +X draw_axis () +X # +X swapbuffers() +X +Xdef make_lights(): +X lmdef(DEFLMODEL,1,[]) +X lmdef(DEFLIGHT,1,[]) +X # +X # define material #1 +X # +X a = [] +X a = a + [EMISSION, 0.0, 0.0, 0.0] +X a = a + [AMBIENT, 0.1, 0.1, 0.1] +X a = a + [DIFFUSE, 0.6, 0.3, 0.3] +X a = a + [SPECULAR, 0.0, 0.6, 0.0] +X a = a + [SHININESS, 2.0] +X a = a + [LMNULL] +X lmdef(DEFMATERIAL, 1, a) +X # +X # turn on lighting +X # +X lmbind(LIGHT0, 1) +X lmbind(LMODEL, 1) +X +Xdef main(): +X init_windows() +X make_lights() +X init_view() +X # +X panel.needredraw() +X panels = panel.defpanellist('nurbs.s') +X p = panels[0] +X # +X def cbtrim (a) : +X flags[TRIM:TRIM+1] = [int (a.val)] +X p.trim.upfunc = cbtrim +X # +X def cbquit (a) : +X import sys +X sys.exit (1) +X p.quit.upfunc = cbquit +X # +X def cbmotion (a) : +X flags[FREEZE:FREEZE+1] = [int (a.val)] +X p.motion.upfunc = cbmotion +X # +X def cbxyzaxis (a) : +X flags[AXVIS:AXVIS+1] = [int (a.val)] +X p.xyzaxis.upfunc = cbxyzaxis +X # +X def cbtrimpnts (a) : +X flags[TPVIS:TPVIS+1] = [int (a.val)] +X p.trimpnts.upfunc = cbtrimpnts +X # +X def cbcntlpnts (a) : +X flags[CPVIS:CPVIS+1] = [int (a.val)] +X p.cntlpnts.upfunc = cbcntlpnts +X # +X def cbnurb (a) : +X flags[VIS:VIS+1] = [int (a.val)] +X p.nurb.upfunc = cbnurb +X # +X set_scene(flags) +X setnurbsproperty( N_ERRORCHECKING, 1.0 ) +X setnurbsproperty( N_PIXEL_TOLERANCE, 50.0 ) +X draw_trim_surface(flags) +X # +X while 1: +X act = panel.dopanel() +X # +X wid = panel.userredraw () +X if wid : +X winset (wid) +X reshapeviewport() +X set_scene(flags) +X draw_trim_surface(flags) +X # +X set_scene(flags) +X draw_trim_surface(flags) +X +Xmain() +EOF +chmod +x 'demo/sgi/gl_panel/nurbs/nurbs.py' +fi +if test -s 'doc/tut.tex' +then echo '*** I will not over-write existing file doc/tut.tex' +else +echo 'x - doc/tut.tex' +sed 's/^X//' > 'doc/tut.tex' << 'EOF' +X% Format this file with latex. +X +X%\documentstyle[garamond,11pt,myformat]{article} +X\documentstyle[11pt,myformat]{article} +X +X\title{\bf +X Python Tutorial \\ +X (DRAFT) +X} +X +X\author{ +X Guido van Rossum \\ +X Dept. CST, CWI, Kruislaan 413 \\ +X 1098 SJ Amsterdam, The Netherlands \\ +X E-mail: {\tt [email protected]} +X} +X +X\begin{document} +X +X\pagenumbering{roman} +X +X\maketitle +X +X\begin{abstract} +X +X\noindent +X\Python\ is a simple, yet powerful programming language that bridges the +Xgap between C and shell programming, and is thus ideally suited for rapid +Xprototyping. +XIts syntax is put together from constructs borrowed from a variety of other +Xlanguages; most prominent are influences from ABC, C, Modula-3 and Icon. +X +XThe \Python\ interpreter is easily extended with new functions and data +Xtypes implemented in C. +X\Python\ is also suitable as an extension language for highly +Xcustomizable C applications such as editors or window managers. +X +X\Python\ is available for various operating systems, amongst which +Xseveral flavors of \UNIX, Amoeba, and the Apple Macintosh O.S. +X +XThis tutorial introduces the reader informally to the basic concepts and +Xfeatures of the \Python\ language and system. +XIt helps to have a \Python\ interpreter handy for hands-on experience, +Xbut as the examples are self-contained, the tutorial can be read +Xoff-line as well. +X +XFor a description of standard objects and modules, see the Library +XReference document. +XThe Language Reference document (XXX not yet existing) +Xgives a more formal reference to the language. +X +X\end{abstract} +X +X\pagebreak +X +X\tableofcontents +X +X\pagebreak +X +X\pagenumbering{arabic} +X +X\section{Whetting Your Appetite} +X +XIf you ever wrote a large shell script, you probably know this feeling: +Xyou'd love to add yet another feature, but it's already so slow, and so +Xbig, and so complicated; or the feature involves a system call or other +Xfuncion that is only accessible from C \ldots +XUsually the problem at hand isn't serious enough to warrant rewriting +Xthe script in C; perhaps because the problem requires variable-length +Xstrings or other data types (like sorted lists of file names) that +Xare easy in the shell but lots of work to implement in C; or perhaps +Xjust because you're not sufficiently familiar with C. +X +XIn all such cases, \Python\ is just the language for you. +X\Python\ is simple to use, but it is a real programming language, offering +Xmuch more structure and support for large programs than the shell has. +XOn the other hand, it also offers much more error checking than C, and, +Xbeing a +X{\em very-high-level language}, +Xit has high-level data types built in, such as flexible arrays and +Xdictionaries that would cost you days to implement efficiently in C. +XBecause of its more general data types \Python\ is applicable to a +Xmuch larger problem domain than +X{\em Awk} +Xor even +X{\em Perl}, +Xyet most simple things are at least as easy in \Python\ as in those +Xlanguages. +X +X\Python\ allows you to split up your program in modules that can be reused +Xin other \Python\ programs. +XIt comes with a large collection of standard modules that you can use as +Xthe basis for your programs --- or as examples to start learning to +Xprogram in \Python. +XThere are also built-in modules that provide things like file I/O, +Xsystem calls, and even a generic interface to window systems (STDWIN). +X +X\Python\ is an interpreted language, which saves you considerable time +Xduring program development because no compilation and linking is +Xnecessary. +XThe interpreter can be used interactively, which makes it easy to +Xexperiment with features of the language, to write throw-away programs, +Xor to test functions during bottom-up program development. +XIt is also a handy desk calculator. +X +X\Python\ allows writing very compact and readable programs. +XPrograms written in \Python\ are typically much shorter than equivalent C +Xprograms: +XNo declarations are necessary (all type checking is +Xdynamic); statement grouping is done by indentation instead of begin/end +Xbrackets; and the high-level data types allow you to express complex +Xoperations in a single statement. +X +X\Python\ is +X{\em extensible}: +Xif you know how to program in C it is easy to add a new built-in module +Xto the interpreter, either to perform critical operations at maximum +Xspeed, or to link \Python\ programs to libraries that may be only available +Xin binary form (such as a vendor-specific graphics library). +XOnce you are really hooked, you can link the \Python\ interpreter into an +Xapplication written in C and use it as an extension or command language. +X +X\subsection{Where From Here} +X +XNow that you are all excited about \Python, you'll want to examine it in +Xsome more detail. +XSince the best introduction to a language is using it, you are invited +Xhere to do so. +X +XIn the next section, the mechanics of using the interpreter are +Xexplained. +XThis is rather mundane information, but essential for trying out the +Xexamples shown later. +XThe rest of the tutorial introduces various features of the \Python\ +Xlanguage and system though examples, beginning with simple expressions, +Xstatements and data types, through functions and modules, and finally +Xtouching upon advanced concepts like exceptions and classes. +X +X\section{Using the Python Interpreter} +X +XThe \Python\ interpreter is usually installed as +X{\tt /usr/local/python} +Xon those machines where it is available; putting +X{\tt /usr/local} +Xin your \UNIX\ shell's search path makes it possible to start it by +Xtyping the command +X\bcode\begin{verbatim} +Xpython +X\end{verbatim}\ecode +Xto the shell. +XSince the choice of the directory where the interpreter lives is an +Xinstallation option, other places instead of +X{\tt /usr/local} +Xare possible; check with your local \Python\ guru or system +Xadministrator.% +X\footnote{ +X At CWI, at the time of writing, the interpreter can be found in +X the following places: +X On the Amoeba Ultrix machines, use the standard path, +X {\tt /usr/local/python}. +X On the Sun file servers, use +X {\tt /ufs/guido/bin/}{\em arch}{\tt /python}, +X where {\em arch} can be {\tt sgi} or {\tt sun4}. +X On piring, use {\tt /userfs3/amoeba/bin/python}. +X (If you can't find a binary advertised here, get in touch with me.) +X} +X +XThe interpreter operates somewhat like the \UNIX\ shell: when called with +Xstandard input connected to a tty device, it reads and executes commands +Xinteractively; when called with a file name argument or with a file as +Xstandard input, it reads and executes a +X{\em script} +Xfrom that file.% +X\footnote{ +X There is a difference between ``{\tt python file}'' and +X ``{\tt python $<$file}''. In the latter case {\tt input()} and +X {\tt raw\_input()} are satisfied from {\em file}, which has +X already been read until the end by the parser, so they will read +X EOF immediately. In the former case (which is usually what +X you want) they are satisfied from whatever file or device is +X connected to standard input of the \Python\ interpreter. +X} +XIf available, the script name and additional arguments thereafter are +Xpassed to the script in the variable +X{\tt sys.argv}, +Xwhich is a list of strings. +X +XWhen standard input is a tty, the interpreter is said to be in +X{\em interactive\ mode}. +XIn this mode it prompts for the next command with the +X{\em primary\ prompt}, +Xusually three greater-than signs ({\tt >>>}); for continuation lines +Xit prompts with the +X{\em secondary\ prompt}, +Xby default three dots ({\tt ...}). +XTyping an EOF (Control-D) at the primary prompt causes the interpreter +Xto exit with a zero exit status. +X +XWhen an error occurs in interactive mode, the interpreter prints a +Xmessage and a stack trace and returns to the primary prompt; with input +Xfrom a file, it exits with a nonzero exit status. +X(Exceptions handled by an +X{\tt except} +Xclause in a +X{\tt try} +Xstatement are not errors in this context.) +XSome errors are unconditionally fatal and cause an exit with a nonzero +Xexit; this applies to internal inconsistencies and some cases of running +Xout of memory. +XAll error messages are written to the standard error stream; normal +Xoutput from the executed commands is written to standard output. +X +XTyping an interrupt (normally Control-C or DEL) to the primary or +Xsecondary prompt cancels the input and returns to the primary prompt. +XTyping an interrupt while a command is being executed raises the +X{\tt KeyboardInterrupt} +Xexception, which may be handled by a +X{\tt try} +Xstatement. +X +XWhen a module named +X{\tt foo} +Xis imported, the interpreter searches for a file named +X{\tt foo.py} +Xin a list of directories specified by the environment variable +X{\tt PYTHONPATH}. +XIt has the same syntax as the \UNIX\ shell variable +X{\tt PATH}, +Xi.e., a list of colon-separated directory names. +XWhen +X{\tt PYTHONPATH} +Xis not set, an installation-dependent default path is used, usually +X{\tt .:/usr/local/lib/python}.% +X\footnote{ +X Modules are really searched in the list of directories given by +X the variable {\tt sys.path} which is initialized from +X {\tt PYTHONPATH} or from the installation-dependent default. +X See the section on Standard Modules later. +X} +X +XOn BSD'ish \UNIX\ systems, \Python\ scripts can be made directly executable, +Xlike shell scripts, by putting the line +X\bcode\begin{verbatim} +X#! /usr/local/python +X\end{verbatim}\ecode +X(assuming that's the name of the interpreter) at the beginning of the +Xscript and giving the file an executable mode. +X(The +X{\tt \#!} +Xmust be the first two characters of the file.) +X +X\subsection{Interactive Input Editing and History Substitution} +X +XSome versions of the \Python\ interpreter support editing of the current +Xinput line and history substitution, similar to facilities found in the +XKorn shell and the GNU Bash shell. +XThis is implemented using the +X{\em GNU\ Readline} +Xlibrary, which supports Emacs-style and vi-style editing. +XThis library has its own documentation which I won't duplicate here; +Xhowever, the basics are easily explained. +X +XIf supported,% +X\footnote{ +X Perhaps the quickest check to see whether command line editing +X is supported is typing Control-P to the first \Python\ prompt +X you get. If it beeps, you have command line editing. +X If not, you can skip the rest of this section. +X} +Xinput line editing is active whenever the interpreter prints a primary +Xor secondary prompt. +XThe current line can be edited using the conventional Emacs control +Xcharacters. +XThe most important of these are: +XC-A (Control-A) moves the cursor to the beginning of the line, C-E to +Xthe end, C-B moves it one position to the left, C-F to the right. +XBackspace erases the character to the left of the cursor, C-D the +Xcharacter to its right. +XC-K kills (erases) the rest of the line to the right of the cursor, C-Y +Xyanks back the last killed string. +XC-underscore undoes the last change you made; it can be repeated for +Xcumulative effect. +X +XHistory substitution works as follows. +XAll non-empty input lines issued are saved in a history buffer, +Xand when a new prompt is given you are positioned on a new line at the +Xbottom of this buffer. +XC-P moves one line up (back) in the history buffer, C-N moves one down. +XAny line in the history buffer can be edited; an asterisk appears in +Xfront of the prompt to mark a line as modified. +XPressing the Return key passes the current line to the interpreter. +XC-R starts an incremental reverse search; C-S starts a forward search. +X +XThe key bindings and some other parameters of the Readline library can +Xbe customized by placing commands in an initialization file called +X{\tt \$HOME/.initrc}. +XKey bindings have the form +X\bcode\begin{verbatim} +Xkey-name: function-name +X\end{verbatim}\ecode +Xand options can be set with +X\bcode\begin{verbatim} +Xset option-name value +X\end{verbatim}\ecode +XExample: +X\bcode\begin{verbatim} +X# I prefer vi-style editing: +Xset editing-mode vi +X# Edit using a single line: +Xset horizontal-scroll-mode On +X# Rebind some keys: +XMeta-h: backward-kill-word +XControl-u: universal-argument +X\end{verbatim}\ecode +XNote that the default binding for TAB in \Python\ is to insert a TAB +Xinstead of Readline's default filename completion function. +XIf you insist, you can override this by putting +X\bcode\begin{verbatim} +XTAB: complete +X\end{verbatim}\ecode +Xin your +X{\tt \$HOME/.inputrc}. +X(Of course, this makes it hard to type indented continuation lines.) +X +XThis facility is an enormous step forward compared to previous versions of +Xthe interpreter; however, some wishes are left: +XIt would be nice if the proper indentation were suggested on +Xcontinuation lines (the parser knows if an indent token is required +Xnext). +XThe completion mechanism might use the interpreter's symbol table. +XA function to check (or even suggest) matching parentheses, quotes +Xetc. would also be useful. +X +X\section{An Informal Introduction to Python} +X +XIn the following examples, input and output are distinguished by the +Xpresence or absence of prompts ({\tt >>>} and {\tt ...}): to repeat the +Xexample, you must type everything after the prompt, when the prompt +Xappears; everything on lines that do not begin with a prompt is output +Xfrom the interpreter. +XNote that a secondary prompt on a line by itself in an example means you +Xmust type a blank line; this is used to end a multi-line command. +X +X\subsection{Using Python as a Calculator} +X +XLet's try some simple \Python\ commands. +XStart the interpreter and wait for the primary prompt, +X{\tt >>>}. +XThe interpreter acts as a simple calculator: you can type an expression +Xat it and it will write the value. +XExpression syntax is straightforward: the operators +X{\tt +}, +X{\tt -}, +X{\tt *} +Xand +X{\tt /} +Xwork just as in most other languages (e.g., Pascal or C); parentheses +Xcan be used for grouping. +XFor example: +X\bcode\begin{verbatim} +X>>> # This is a comment +X>>> 2+2 +X4 +X>>> +X>>> (50-5+5*6+25)/4 +X25 +X>>> # Division truncates towards zero: +X>>> 7/3 +X2 +X>>> +X\end{verbatim}\ecode +XAs in C, the equal sign ({\tt =}) is used to assign a value to a variable. +XThe value of an assignment is not written: +X\bcode\begin{verbatim} +X>>> width = 20 +X>>> height = 5*9 +X>>> width * height +X900 +X>>> +X\end{verbatim}\ecode +XThere is some support for floating point, but you can't mix floating +Xpoint and integral numbers in expression (yet): +X\bcode\begin{verbatim} +X>>> 10.0 / 3.3 +X3.0303030303 +X>>> +X\end{verbatim}\ecode +XBesides numbers, \Python\ can also manipulate strings, enclosed in single +Xquotes: +X\bcode\begin{verbatim} +X>>> 'foo bar' +X'foo bar' +X>>> 'doesn\'t' +X'doesn\'t' +X>>> +X\end{verbatim}\ecode +XStrings are written inside quotes and with quotes and other funny +Xcharacters escaped by backslashes, to show the precise value. +X(There is also a way to write strings without quotes and escapes.) +XStrings can be concatenated (glued together) with the +X{\tt +} +Xoperator, and repeated with~{\tt *}: +X\bcode\begin{verbatim} +X>>> word = 'Help' + 'A' +X>>> word +X'HelpA' +X>>> '<' + word*5 + '>' +X'<HelpAHelpAHelpAHelpAHelpA>' +X>>> +X\end{verbatim}\ecode +XStrings can be subscripted; as in C, the first character of a string has +Xsubscript 0. +XThere is no separate character type; a character is simply a string of +Xsize one. +XAs in Icon, substrings can be specified with the +X{\em slice} +Xnotation: two subscripts (indices) separated by a colon. +X\bcode\begin{verbatim} +X>>> word[4] +X'A' +X>>> word[0:2] +X'He' +X>>> word[2:4] +X'lp' +X>>> # Slice indices have useful defaults: +X>>> word[:2] # Take first two characters +X'He' +X>>> word[2:] # Drop first two characters +X'lpA' +X>>> # A useful invariant: s[:i] + s[i:] = s +X>>> word[:3] + word[3:] +X'HelpA' +X>>> +X\end{verbatim}\ecode +XDegenerate cases are handled gracefully: an index that is too large is +Xreplaced by the string size, an upper bound smaller than the lower bound +Xreturns an empty string. +X\bcode\begin{verbatim} +X>>> word[1:100] +X'elpA' +X>>> word[10:] +X'' +X>>> word[2:1] +X'' +X>>> +X\end{verbatim}\ecode +XSlice indices (but not simple subscripts) may be negative numbers, to +Xstart counting from the right. +XFor example: +X\bcode\begin{verbatim} +X>>> word[-2:] # Take last two characters +X'pA' +X>>> word[:-2] # Drop last two characters +X'Hel' +X>>> # But -0 does not count from the right! +X>>> word[-0:] # (since -0 equals 0) +X'HelpA' +X>>> +X\end{verbatim}\ecode +XThe best way to remember how slices work is to think of the indices as +Xpointing +X{\em between} +Xcharacters, with the left edge of the first character numbered 0. +XThen the right edge of the last character of a string of +X{\tt n} +Xcharacters has index +X{\tt n}, +Xfor example: +X\bcode\begin{verbatim} +X +---+---+---+---+---+ +X | H | e | l | p | A | +X +---+---+---+---+---+ +X 0 1 2 3 4 5 +X-5 -4 -3 -2 -1 +X\end{verbatim}\ecode +XThe first row of numbers gives the position of the indices 0...5 in the +Xstring; the second row gives the corresponding negative indices. +XFor nonnegative indices, the length of a slice is the difference of the +Xindices, if both are within bounds, +Xe.g., +Xthe length of +X{\tt word[1:3]} +Xis 3--1 = 2. +X +XFinally, the built-in function {\tt len()} computes the length of a +Xstring: +X\bcode\begin{verbatim} +X>>> s = 'supercalifragilisticexpialidocious' +X>>> len(s) +X34 +X>>> +X\end{verbatim}\ecode +X\Python\ knows a number of +X{\em compound} +Xdata types, used to group together other values. +XThe most versatile is the +X{\em list}, +Xwhich can be written as a list of comma-separated values between square +Xbrackets: +X\bcode\begin{verbatim} +X>>> a = ['foo', 'bar', 100, 1234] +X>>> a +X['foo', 'bar', 100, 1234] +X>>> +X\end{verbatim}\ecode +XAs for strings, list subscripts start at 0: +X\bcode\begin{verbatim} +X>>> a[0] +X'foo' +X>>> a[3] +X1234 +X>>> +X\end{verbatim}\ecode +XLists can be sliced and concatenated like strings: +X\bcode\begin{verbatim} +X>>> a[1:3] +X['bar', 100] +X>>> a[:2] + ['bletch', 2*2] +X['foo', 'bar', 'bletch', 4] +X>>> +X\end{verbatim}\ecode +XUnlike strings, which are +X{\em immutable}, +Xit is possible to change individual elements of a list: +X\bcode\begin{verbatim} +X>>> a +X['foo', 'bar', 100, 1234] +X>>> a[2] = a[2] + 23 +X>>> a +X['foo', 'bar', 123, 1234] +X>>> +X\end{verbatim}\ecode +XAssignment to slices is also possible, and this may even change the size +Xof the list: +X\bcode\begin{verbatim} +X>>> # Replace some items: +X>>> a[0:2] = [1, 12] +X>>> a +X[1, 12, 123, 1234] +X>>> # Remove some: +X>>> a[0:2] = [] +X>>> a +X[123, 1234] +X>>> # Insert some: +X>>> a[1:1] = ['bletch', 'xyzzy'] +X>>> a +X[123, 'bletch', 'xyzzy', 1234] +X>>> +X\end{verbatim}\ecode +XThe built-in function {\tt len()} also applies to lists: +X\bcode\begin{verbatim} +X>>> len(a) +X4 +X>>> +X\end{verbatim}\ecode +X +X\subsection{Tuples and Sequences} +X +XXXX To Be Done. +X +X\subsection{First Steps Towards Programming} +X +XOf course, we can use \Python\ for more complicated tasks than adding two +Xand two together. +XFor instance, we can write an initial subsequence of the +X{\em Fibonacci} +Xseries as follows: +X\bcode\begin{verbatim} +X>>> # Fibonacci series: +X>>> # the sum of two elements defines the next +X>>> a, b = 0, 1 +X>>> while b < 100: +X... print b +X... a, b = b, a+b +X... +X1 +X1 +X2 +X3 +X5 +X8 +X13 +X21 +X34 +X55 +X89 +X>>> +X\end{verbatim}\ecode +XThis example introduces several new features. +X\begin{itemize} +X\item +XThe first line contains a +X{\em multiple\ assignment}: +Xthe variables +X{\tt a} +Xand +X{\tt b} +Xsimultaneously get the new values 0 and 1. +XOn the last line this is used again, demonstrating that the expressions +Xon the right-hand side are all evaluated first before any of the +Xassignments take place. +X\item +XThe +X{\tt while} +Xloop executes as long as the condition (here: $b < 100$) remains true. +XIn \Python, as in C, any non-zero integer value is true; zero is false. +XThe condition may also be a string or list value, in fact any sequence; +Xanything with a non-zero length is true, empty sequences are false. +XThe test used in the example is a simple comparison. +XThe standard comparison operators are written as +X{\tt <}, +X{\tt >}, +X{\tt =}, +X{\tt <=}, +X{\tt >=} +Xand +X{\tt <>}.% +X\footnote{ +X The ambiguity of using {\tt =} +X for both assignment and equality is resolved by disallowing +X unparenthesized conditions at the right hand side of assignments. +X} +X\item +XThe +X{\em body} +Xof the loop is +X{\em indented}: indentation is \Python's way of grouping statements. +X\Python\ does not (yet!) provide an intelligent input line editing +Xfacility, so you have to type a tab or space(s) for each indented line. +XIn practice you will prepare more complicated input for \Python\ with a +Xtext editor; most text editors have an auto-indent facility. +XWhen a compound statement is entered interactively, it must be +Xfollowed by a blank line to indicate completion (since the parser +Xcannot guess when you have typed the last line). +X\item +XThe +X{\tt print} +Xstatement writes the value of the expression(s) it is given. +XIt differs from just writing the expression you want to write (as we did +Xearlier in the calculator examples) in the way it handles multiple +Xexpressions and strings. +XStrings are written without quotes and a space is inserted between +Xitems, so you can format things nicely, like this: +X\bcode\begin{verbatim} +X>>> i = 256*256 +X>>> print 'The value of i is', i +XThe value of i is 65536 +X>>> +X\end{verbatim}\ecode +XA trailing comma avoids the newline after the output: +X\bcode\begin{verbatim} +X>>> a, b = 0, 1 +X>>> while b < 1000: +X... print b, +X... a, b = b, a+b +X... +X1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 +X>>> +X\end{verbatim}\ecode +XNote that the interpreter inserts a newline before it prints the next +Xprompt if the last line was not completed. +X\end{itemize} +X +X\subsection{More Control Flow Tools} +X +XBesides the {\tt while} statement just introduced, \Python\ knows the +Xusual control flow statements known from other languages, with some +Xtwists. +X +X\subsubsection{If Statements} +X +XPerhaps the most well-known statement type is the {\tt if} statement. +XFor example: +X\bcode\begin{verbatim} +X>>> if x < 0: +X... x = 0 +X... print 'Negative changed to zero' +X... elif x = 0: +X... print 'Zero' +X... elif x = 1: +X... print 'Single' +X... else: +X... print 'More' +X... +X\end{verbatim}\ecode +XThere can be zero or more {\tt elif} parts, and the {\tt else} part is +Xoptional. +XThe keyword `{\tt elif}' is short for `{\tt else if}', and is useful to +Xavoid excessive indentation. +XAn {\tt if...elif...elif...} sequence is a substitute for the +X{\em switch} or {\em case} statements found in other languages. +X +X\subsubsection{For Statements} +X +XThe {\tt for} statement in \Python\ differs a bit from what you may be +Xused to in C or Pascal. +XRather than always iterating over an arithmetic progression of numbers +X(as Pascal), or leaving the user completely free in the iteration test +Xand step (as C), \Python's {\tt for} statement iterates over the items +Xof any sequence (e.g., a list or a string). +XFor example (no pun intended): +X\bcode\begin{verbatim} +X>>> # Measure some strings: +X>>> a = ['cat', 'window', 'defenestrate'] +X>>> for x in a: +X... print x, len(x) +X... +Xcat 3 +Xwindow 6 +Xdefenestrate 12 +X>>> +X\end{verbatim}\ecode +X +X\subsubsection{The {\tt range()} Function} +X +XIf you do need to iterate over a sequence of numbers, the built-in +Xfunction {\tt range()} comes in handy. +XIt generates lists containing arithmetic progressions, +Xe.g.: +X\bcode\begin{verbatim} +X>>> range(10) +X[0, 1, 2, 3, 4, 5, 6, 7, 8, 9] +X>>> +X\end{verbatim}\ecode +XThe given end point is never part of the generated list; +X{\tt range(10)} generates a list of 10 values, +Xexactly the legal indices for items of a sequence of length 10. +XIt is possible to let the range start at another number, or to specify a +Xdifferent increment (even negative): +X\bcode\begin{verbatim} +X>>> range(5, 10) +X[5, 6, 7, 8, 9] +X>>> range(0, 10, 3) +X[0, 3, 6, 9] +X>>> range(-10, -100, -30) +X[-10, -40, -70] +X>>> +X\end{verbatim}\ecode +XTo iterate over the indices of a sequence, combine {\tt range()} +Xand {\tt len()} as follows: +X\bcode\begin{verbatim} +X>>> a = ['Mary', 'had', 'a', 'little', 'boy'] +X>>> for i in range(len(a)): +X... print i, a[i] +X... +X0 Mary +X1 had +X2 a +X3 little +X4 boy +X>>> +X\end{verbatim}\ecode +X +X\subsubsection{Break Statements and Else Clauses on Loops} +X +XThe {\tt break} statement breaks out of the smallest enclosing {\tt for} +Xor {\tt while} loop. +XLoop statements may have an {\tt else} clause; it is executed when the +Xloop terminates through exhaustion of the list (with {\tt for}) or when +Xthe condition becomes false (with {\tt while}) but not when the loop is +Xterminated by a {\tt break} statement. +XThis is exemplified by the following loop, which searches for a list +Xitem of value 0: +X\bcode\begin{verbatim} +X>>> for n in range(2, 10): +X... for x in range(2, n): +X... if n % x = 0: +X... print n, 'equals', x, '*', n/x +X... break +X... else: +X... print n, 'is a prime number' +X... +X2 is a prime number +X3 is a prime number +X4 equals 2 * 2 +X5 is a prime number +X6 equals 2 * 3 +X7 is a prime number +X8 equals 2 * 4 +X9 equals 3 * 3 +X>>> +X\end{verbatim}\ecode +X +X\subsubsection{Pass Statements} +X +XThe {\tt pass} statement does nothing. +XIt can be used when a statement is required syntactically but the +Xprogram requires no action. +XFor example: +X\bcode\begin{verbatim} +X>>> while 1: +X... pass # Busy-wait for keyboard interrupt +X... +X\end{verbatim}\ecode +X +X\subsubsection{Conditions Revisited} +X +XXXX To Be Done. +X +X\subsection{Defining Functions} +X +XWe can create a function that writes the Fibonacci series to an +Xarbitrary boundary: +X\bcode\begin{verbatim} +X>>> def fib(n): # write Fibonacci series up to n +X... a, b = 0, 1 +X... while b <= n: +X... print b, +X... a, b = b, a+b +X... +X>>> # Now call the function we just defined: +X>>> fib(2000) +X1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597 +X>>> +X\end{verbatim}\ecode +XThe keyword +X{\tt def} +Xintroduces a function +X{\em definition}. +XIt must be followed by the function name and the parenthesized list of +Xformal parameters. +XThe statements that form the body of the function starts at the next +Xline, indented by a tab stop. +XThe +X{\em execution} +Xof a function introduces a new symbol table used for the local variables +Xof the function. +XMore precisely, all variable assignments in a function store the value +Xin the local symbol table; variable references first look in the local +Xsymbol table, then in the global symbol table, and then in the table of +Xbuilt-in names. +XThus, the global symbol table is +X{\em read-only} +Xwithin a function. +XThe actual parameters (arguments) to a function call are introduced in +Xthe local symbol table of the called function when it is called; +Xthus, arguments are passed using +X{\em call\ by\ value}.% +X\footnote{ +X Actually, {\em call by object reference} would be a better +X description, since if a mutable object is passed, the caller +X will see any changes the callee makes to it (e.g., items +X inserted into a list). +X} +XWhen a function calls another function, a new local symbol table is +Xcreated for that call. +X +XA function definition introduces the function name in the global symbol +Xtable. +XThe value has a type that is recognized by the interpreter as a +Xuser-defined function. +XThis value can be assigned to another name which can then also be used +Xas a function. +XThis serves as a general renaming mechanism: +X\bcode\begin{verbatim} +X>>> fib +X<function object at 10042ed0> +X>>> f = fib +X>>> f(100) +X1 1 2 3 5 8 13 21 34 55 89 +X>>> +X\end{verbatim}\ecode +XYou might object that +X{\tt fib} +Xis not a function but a procedure. +XIn \Python, as in C, procedures are just functions that don't return a +Xvalue. +XIn fact, technically speaking, procedures do return a value, albeit a +Xrather boring one. +XThis value is called {\tt None} (it's a built-in name). +XWriting the value {\tt None} is normally suppressed by the interpreter +Xif it would be the only value written. +XYou can see it if you really want to: +X\bcode\begin{verbatim} +X>>> print fib(0) +XNone +X>>> +X\end{verbatim}\ecode +XIt is simple to write a function that returns a list of the numbers of +Xthe Fibonacci series, instead of printing it: +X\bcode\begin{verbatim} +X>>> def fib2(n): # return Fibonacci series up to n +X... result = [] +X... a, b = 0, 1 +X... while b <= n: +X... result.append(b) # see below +X... a, b = b, a+b +X... return result +X... +X>>> f100 = fib2(100) # call it +X>>> f100 # write the result +X[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89] +X>>> +X\end{verbatim}\ecode +XThis example, as usual, demonstrates some new \Python\ features: +X\begin{itemize} +X\item +XThe +X{\tt return} +Xstatement returns with a value from a function. +X{\tt return} +Xwithout an expression argument is used to return from the middle of a +Xprocedure (falling off the end also returns from a proceduce). +X\item +XThe statement +X{\tt ret.append(b)} +Xcalls a +X{\em method} +Xof the list object +X{\tt ret}. +XA method is a function that `belongs' to an object and is named +X{\tt obj.methodname}, +Xwhere +X{\tt obj} +Xis some object (this may be an expression), and +X{\tt methodname} +Xis the name of a method that is defined by the object's type. +XDifferent types define different methods. +XMethods of different types may have the same name without causing +Xambiguity. +XSee the section on classes, later, to find out how you can define your +Xown object types and methods. +XThe method +X{\tt append} +Xshown in the example, is defined for list objects; it adds a new element +Xat the end of the list. +XIn this case it is equivalent to +X{\tt ret = ret + [b]}, +Xbut more efficient.% +X\footnote{ +X There is a subtle semantic difference if the object +X is referenced from more than one place. +X} +X\end{itemize} +XThe list object type has two more methods: +X\begin{description} +X\item[{\tt insert(i, x)}] +XInserts an item at a given position. +XThe first argument is the index of the element before which to insert, +Xso {\tt a.insert(0, x)} inserts at the front of the list, and +X{\tt a.insert(len(a), x)} is equivalent to {\tt a.append(x)}. +X\item[{\tt sort()}] +XSorts the elements of the list. +X\end{description} +XFor example: +X\bcode\begin{verbatim} +X>>> a = [10, 100, 1, 1000] +X>>> a.insert(2, -1) +X>>> a +X[10, 100, -1, 1, 1000] +X>>> a.sort() +X>>> a +X[-1, 1, 10, 100, 1000] +X>>> # Strings are sorted according to ASCII: +X>>> b = ['Mary', 'had', 'a', 'little', 'boy'] +X>>> b.sort() +X>>> b +X['Mary', 'a', 'boy', 'had', 'little'] +X>>> +X\end{verbatim}\ecode +X +X\subsection{Modules} +X +XIf you quit from the \Python\ interpreter and enter it again, the +Xdefinitions you have made (functions and variables) are lost. +XTherefore, if you want to write a somewhat longer program, you are +Xbetter off using a text editor to prepare the input for the interpreter +Xand run it with that file as input instead. +XThis is known as creating a +X{\em script}. +XAs your program gets longer, you may want to split it into several files +Xfor easier maintenance. +XYou may also want to use a handy function that you've written in several +Xprograms without copying its definition into each program. +XTo support this, \Python\ has a way to put definitions in a file and use +Xthem in a script or in an interactive instance of the interpreter. +XSuch a file is called a +X{\em module}; +Xdefinitions from a module can be +X{\em imported} +Xinto other modules or into the +X{\em main} +Xmodule (the collection of variables that you have access to in +Xa script and in calculator mode). +X +XA module is a file containing \Python\ definitions and statements. +XThe file name is the module name with the suffix +X{\tt .py} +Xappended. +XFor instance, use your favorite text editor to create a file called +X{\tt fibo.py} +Xin the current directory with the following contents: +X\bcode\begin{verbatim} +X# Fibonacci numbers module +X +Xdef fib(n): # write Fibonacci series up to n +X a, b = 0, 1 +X while b <= n: +X print b, +X a, b = b, a+b +X +Xdef fib2(n): # return Fibonacci series up to n +X ret = [] +X a, b = 0, 1 +X while b <= n: +X ret.append(b) +X a, b = b, a+b +X return ret +X\end{verbatim}\ecode +XNow enter the \Python\ interpreter and import this module with the +Xfollowing command: +X\bcode\begin{verbatim} +X>>> import fibo +X>>> +X\end{verbatim}\ecode +XThis does not enter the names of the functions defined in +X{\tt fibo} +Xdirectly in the symbol table; it only enters the module name +X{\tt fibo} +Xthere. +XUsing the module name you can access the functions: +X\bcode\begin{verbatim} +X>>> fibo.fib(1000) +X1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 +X>>> fibo.fib2(100) +X[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89] +X>>> +X\end{verbatim}\ecode +XIf you intend to use a function often you can assign it to a local name: +X\bcode\begin{verbatim} +X>>> fib = fibo.fib +X>>> fib(500) +X1 1 2 3 5 8 13 21 34 55 89 144 233 377 +X>>> +X\end{verbatim}\ecode +X +X\subsubsection{More on Modules} +X +XA module can contain executable statements as well as function +Xdefinitions. +XThese statements are intended to initialize the module. +XThey are executed only the +X{\em first} +Xtime the module is imported somewhere.% +X\footnote{ +X In fact function definitions are also `statements' that are +X `executed'; the execution enters the function name in the +X module's global symbol table. +X} +X +XEach module has its own private symbol table, which is used as the +Xglobal symbol table by all functions defined in the module. +XThus, the author of a module can use global variables in the module +Xwithout worrying about accidental clashes with a user's global +Xvariables. +XOn the other hand, if you know what you are doing you can touch a +Xmodule's global variables with the same notation used to refer to its +Xfunctions, +X{\tt modname.itemname}. +X +XModules can import other modules. +XIt is customary but not required to place all +X{\tt import} +Xstatements at the beginning of a module (or script, for that matter). +XThe imported module names are placed in the importing module's global +Xsymbol table. +X +XThere is a variant of the +X{\tt import} +Xstatement that imports names from a module directly into the importing +Xmodule's symbol table. +XFor example: +X\bcode\begin{verbatim} +X>>> from fibo import fib, fib2 +X>>> fib(500) +X1 1 2 3 5 8 13 21 34 55 89 144 233 377 +X>>> +X\end{verbatim}\ecode +XThis does not introduce the module name from which the imports are taken +Xin the local symbol table (so in the example, {\tt fibo} is not +Xdefined). +X +XThere is even a variant to import all names that a module defines: +X\bcode\begin{verbatim} +X>>> from fibo import * +X>>> fib(500) +X1 1 2 3 5 8 13 21 34 55 89 144 233 377 +X>>> +X\end{verbatim}\ecode +XThis imports all names except those beginning with an underscore +X({\tt \_}). +X +X\subsubsection{Standard Modules} +X +X\Python\ comes with a library of standard modules, described in a separate +Xdocument (Python Library and Module Reference). +XSome modules are built into the interpreter; these provide access to +Xoperations that are not part of the core of the language but are +Xnevertheless built in, either for efficiency or to provide access to +Xoperating system primitives such as system calls. +XThe set of such modules is a configuration option; e.g., the +X{\tt amoeba} +Xmodule is only provided on systems that somehow support Amoeba +Xprimitives. +XOne particular module deserves some attention: +X{\tt sys}, +Xwhich is built into every \Python\ interpreter. +XThe variables +X{\tt sys.ps1} +Xand +X{\tt sys.ps2} +Xdefine the strings used as primary and secondary prompts: +X\bcode\begin{verbatim} +X>>> import sys +X>>> sys.ps1 +X'>>> ' +X>>> sys.ps2 +X'... ' +X>>> sys.ps1 = 'C> ' +XC> print 'Yuck!' +XYuck! +XC> +X\end{verbatim}\ecode +XThese two variables are only defined if the interpreter is in +Xinteractive mode. +X +XThe variable +X{\tt sys.path} +Xis a list of strings that determine the interpreter's search path for +Xmodules. +XIt is initialized to a default path taken from the environment variable +X{\tt PYTHONPATH}, +Xor from a built-in default if +X{\tt PYTHONPATH} +Xis not set. +XYou can modify it using standard list operations, e.g.: +X\bcode\begin{verbatim} +X>>> import sys +X>>> sys.path.append('/ufs/guido/lib/python') +X>>> +X\end{verbatim}\ecode +X +X\subsection{Errors and Exceptions} +X +XUntil now error messages haven't yet been mentioned, but if you have +Xtried out the examples you have probably seen some. +XThere are (at least) two distinguishable kinds of errors: +X{\em syntax\ errors} +Xand +X{\em exceptions}. +X +X\subsubsection{Syntax Errors} +X +XSyntax errors, also known as parsing errors, are perhaps the most common +Xkind of complaint you get while you are still learning \Python: +X\bcode\begin{verbatim} +X>>> while 1 print 'Hello world' +XParsing error: file <stdin>, line 1: +Xwhile 1 print 'Hello world' +X ^ +XUnhandled exception: run-time error: syntax error +X>>> +X\end{verbatim}\ecode +XThe parser repeats the offending line and displays a little `arrow' +Xpointing at the earliest point in the line where the error was detected. +XThe error is caused by (or at least detected at) the token +X{\em preceding} +Xthe arrow: in the example, the error is detected at the keyword +X{\tt print}, since a colon ({\tt :}) is missing before it. +XFile name and line number are printed so you know where to look in case +Xthe input came from a script. +X +X\subsubsection{Exceptions} +X +XEven if a statement or expression is syntactically correct, it may cause +Xan error when an attempt is made to execute it: +X\bcode\small\begin{verbatim} +X>>> 10 * (1/0) +XUnhandled exception: run-time error: integer division by zero +XStack backtrace (innermost last): +X File "<stdin>", line 1 +X>>> 4 + foo*3 +XUnhandled exception: undefined name: foo +XStack backtrace (innermost last): +X File "<stdin>", line 1 +X>>> '2' + 2 +XUnhandled exception: type error: illegal argument type for built-in operation +XStack backtrace (innermost last): +X File "<stdin>", line 1 +X>>> +X\end{verbatim}\ecode +XErrors detected during execution are called +X{\em exceptions} +Xand are not unconditionally fatal: you will soon learn how to handle +Xthem in \Python\ programs. +XMost exceptions are not handled by programs, however, and result +Xin error messages as shown here. +X +XThe first line of the error message indicates what happened. +XExceptions come in different types, and the type is printed as part of +Xthe message: the types in the example are +X{\tt run-time error}, +X{\tt undefined name} +Xand +X{\tt type error}. +XThe rest of the line is a detail whose interpretation depends on the +Xexception type. +X +XThe rest of the error message shows the context where the +Xexception happened. +XIn general it contains a stack backtrace listing source lines; however, +Xit will not display lines read from standard input. +X +XHere is a summary of the most common exceptions: +X\begin{itemize} +X\item +X{\em Run-time\ errors} +Xare generally caused by wrong data used by the program; this can be the +Xprogrammer's fault or caused by bad input. +XThe detail states the cause of the error in more detail. +X\item +X{\em Undefined\ name} +Xerrors are more serious: these are usually caused by misspelled +Xidentifiers.% +X\footnote{ +X The parser does not check whether names used in a program are at +X all defined elsewhere in the program, so such checks are +X postponed until run-time. The same holds for type checking. +X} +XThe detail is the offending identifier. +X\item +X{\em Type\ errors} +Xare also pretty serious: this is another case of using wrong data (or +Xbetter, using data the wrong way), but here the error can be glanced +Xfrom the object type(s) alone. +XThe detail shows in what context the error was detected. +X\end{itemize} +X +X\subsubsection{Handling Exceptions} +X +XIt is possible to write programs that handle selected exceptions. +XLook at the following example, which prints a table of inverses of +Xsome floating point numbers: +X\bcode\begin{verbatim} +X>>> numbers = [0.3333, 2.5, 0.0, 10.0] +X>>> for x in numbers: +X... print x, +X... try: +X... print 1.0 / x +X... except RuntimeError: +X... print '*** has no inverse ***' +X... +X0.3333 3.00030003 +X2.5 0.4 +X0 *** has no inverse *** +X10 0.1 +X>>> +X\end{verbatim}\ecode +XThe {\tt try} statement works as follows. +X\begin{itemize} +X\item +XFirst, the +X{\em try\ clause} +X(the statement(s) between the {\tt try} and {\tt except} keywords) is +Xexecuted. +X\item +XIf no exception occurs, the +X{\em except\ clause} +Xis skipped and execution of the {\tt try} statement is finished. +X\item +XIf an exception occurs during execution of the try clause, and its +Xtype matches the exception named after the {\tt except} keyword, the +Xrest of the try clause is skipped, the except clause is executed, and +Xthen execution continues after the {\tt try} statement. +X\item +XIf an exception occurs which does not match the exception named in the +Xexcept clause, it is passed on to outer try statements; if no handler is +Xfound, it is an +X{\em unhandled\ exception} +Xand execution stops with a message as shown above. +X\end{itemize} +XA {\tt try} statement may have more than one except clause, to specify +Xhandlers for different exceptions. +XAt most one handler will be executed. +XHandlers only handle exceptions that occur in the corresponding try +Xclause, not in other handlers of the same {\tt try} statement. +XAn except clause may name multiple exceptions as a parenthesized list, +Xe.g.: +X\bcode\begin{verbatim} +X... except (RuntimeError, TypeError, NameError): +X... pass +X\end{verbatim}\ecode +XThe last except clause may omit the exception name(s), to serve as a +Xwildcard. +XUse this with extreme caution! +X +XWhen an exception occurs, it may have an associated value, also known as +Xthe exceptions's +X{\em argument}. +XThe presence and type of the argument depend on the exception type. +XFor exception types which have an argument, the except clause may +Xspecify a variable after the exception name (or list) to receive the +Xargument's value, as follows: +X\bcode\begin{verbatim} +X>>> try: +X... foo() +X... except NameError, x: +X... print 'name', x, 'undefined' +X... +Xname foo undefined +X>>> +X\end{verbatim}\ecode +XIf an exception has an argument, it is printed as the third part +X(`detail') of the message for unhandled exceptions. +X +XStandard exception names are built-in identifiers (not reserved +Xkeywords). +XThese are in fact string objects whose +X{\em object\ identity} +X(not their value!) identifies the exceptions.% +X\footnote{ +X There should really be a separate exception type; it is pure +X laziness that exceptions are identified by strings, and this may +X be fixed in the future. +X} +XThe string is printed as the second part of the message for unhandled +Xexceptions. +XTheir names and values are: +X\bcode\begin{verbatim} +XEOFError 'end-of-file read' +XKeyboardInterrupt 'keyboard interrupt' +XMemoryError 'out of memory' * +XNameError 'undefined name' * +XRuntimeError 'run-time error' * +XSystemError 'system error' * +XTypeError 'type error' * +X\end{verbatim}\ecode +XThe meanings should be clear enough. +XThose exceptions with a {\tt *} in the third column have an argument. +X +XException handlers don't just handle exceptions if they occur +Ximmediately in the try clause, but also if they occur inside functions +Xthat are called (even indirectly) in the try clause. +XFor example: +X\bcode\begin{verbatim} +X>>> def this_fails(): +X... x = 1/0 +X... +X>>> try: +X... this_fails() +X... except RuntimeError, detail: +X... print 'Handling run-time error:', detail +X... +XHandling run-time error: domain error or zero division +X>>> +X\end{verbatim}\ecode +X +X\subsubsection{Raising Exceptions} +X +XThe {\tt raise} statement allows the programmer to force a specified +Xexception to occur. +XFor example: +X\bcode\begin{verbatim} +X>>> raise NameError, 'Hi There!' +XUnhandled exception: undefined name: Hi There! +XStack backtrace (innermost last): +X File "<stdin>", line 1 +X>>> +X\end{verbatim}\ecode +XThe first argument to {\tt raise} names the exception to be raised. +XThe optional second argument specifies the exception's argument. +X +X\subsubsection{User-defined Exceptions} +X +XPrograms may name their own exceptions by assigning a string to a +Xvariable. +XFor example: +X\bcode\begin{verbatim} +X>>> my_exc = 'nobody likes me!' +X>>> try: +X... raise my_exc, 2*2 +X... except my_exc, val: +X... print 'My exception occured, value:', val +X... +XMy exception occured, value: 4 +X>>> raise my_exc, 1 +XUnhandled exception: nobody likes me!: 1 +XStack backtrace (innermost last): +X File "<stdin>", line 7 +X>>> +X\end{verbatim}\ecode +XMany standard modules use this to report errors that may occur in +Xfunctions they define. +X +X\subsubsection{Defining Clean-up Actions} +X +XThe {\tt try} statement has another optional clause which is intended to +Xdefine clean-up actions that must be executed under all circumstances. +XFor example: +X\bcode\begin{verbatim} +X>>> try: +X... raise KeyboardInterrupt +X... finally: +X... print 'Goodbye, world!' +X... +XGoodbye, world! +XUnhandled exception: keyboard interrupt +XStack backtrace (innermost last): +X File "<stdin>", line 2 +X>>> +X\end{verbatim}\ecode +XThe +X{\em finally\ clause} +Xmust follow the except clauses(s), if any. +XIt is executed whether or not an exception occurred. +XIf the exception is handled, the finally clause is executed after the +Xhandler (and even if another exception occurred in the handler). +XIt is also executed when the {\tt try} statement is left via a +X{\tt break} or {\tt return} statement. +X +X\subsection{Classes} +X +XClasses in \Python\ make it possible to play the game of encapsulation in a +Xsomewhat different way than it is played with modules. +XClasses are an advanced topic and are probably best skipped on the first +Xencounter with \Python. +X +X\subsubsection{Prologue} +X +X\Python's class mechanism is not particularly elegant, but quite powerful. +XIt is a mixture of the class mechanisms found in C++ and Modula-3. +XAs is true for modules, classes in \Python\ do not put an absolute barrier +Xbetween definition and user, but rather rely on the politeness of the +Xuser not to ``break into the definition.'' +XThe most important features of classes are retained with full power, +Xhowever: the class inheritance mechanism allows multiple base classes, +Xa derived class can override any method of its base class(es), a method +Xcan call the method of a base class with the same name. +XObjects can contain an arbitrary amount of private data. +X +XIn C++ terminology, all class members (including data members) are +X{\em public}, +Xand all member functions (methods) are +X{\em virtual}. +XThere are no special constructors or destructors. +XAs in Modula-3, there are no shorthands for referencing the object's +Xmembers from its methods: the method function is declared with an +Xexplicit first argument representing the object, which is provided +Ximplicitly by the call. +XAs in Smalltalk, classes themselves are objects, albeit in the wider +Xsense of the word: in \Python, all data types are objects. +XThis provides semantics for renaming or aliasing. +XBut, just like in C++ or Modula-3, the built-in types cannot be used as +Xbase classes for extension by the user. +XAlso, like Modula-3 but unlike C++, the built-in operators with special +Xsyntax (arithmetic operators, subscripting etc.) cannot be redefined for +Xclass members.% +X\footnote{ +X They can be redefined for new object types implemented in C in +X extensions to the interpreter, however. It would require only a +X naming convention and a relatively small change to the +X interpreter to allow operator overloading for classes, so +X perhaps someday... +X} +X +X\subsubsection{A Simple Example} +X +XConsider the following example, which defines a class {\tt Set} +Xrepresenting a (finite) mathematical set with operations to add and +Xremove elements, a membership test, and a request for the size of the +Xset. +X\bcode\begin{verbatim} +Xclass Set(): +X def new(self): +X self.elements = [] +X return self +X def add(self, e): +X if e not in self.elements: +X self.elements.append(e) +X def remove(self, e): +X if e in self.elements: +X for i in range(len(self.elements)): +X if self.elements[i] = e: +X del self.elements[i] +X break +X def is_element(self, e): +X return e in self.elements +X def size(self): +X return len(self.elements) +X\end{verbatim}\ecode +XNote that the class definition looks like a big compound statement, +Xwith all the function definitons indented repective to the +X{\tt class} +Xkeyword. +X +XLet's assume that this +X{\em class\ definition} +Xis the only contents of the module file +X{\tt SetClass.py}. +XWe can then use it in a \Python\ program as follows: +X\bcode\begin{verbatim} +X>>> from SetClass import Set +X>>> a = Set().new() # create a Set object +X>>> a.add(2) +X>>> a.add(3) +X>>> a.add(1) +X>>> a.add(1) +X>>> if a.is_element(3): print '3 is in the set' +X... +X3 is in the set +X>>> if not a.is_element(4): print '4 is not in the set' +X... +X4 is not in the set +X>>> print 'a has', a.size(), 'elements' +Xa has 3 elements +X>>> a.remove(1) +X>>> print 'now a has', a.size(), 'elements' +X>>> +Xnow a has 2 elements +X>>> +X\end{verbatim}\ecode +XFrom the example we learn in the first place that the functions defined +Xin the class (e.g., +X{\tt add}) +Xcan be called using the +X{\em member} +Xnotation for the object +X{\tt a}. +XThe member function is called with one less argument than it is defined: +Xthe object is implicitly passed as the first argument. +XThus, the call +X{\tt a.add(2)} +Xis equivalent to +X{\tt Set.add(a, 2)}. +X +XXXX This section is not complete yet! +X +X\section{XXX P.M.} +X +X\begin{itemize} +X\item The {\tt del} statement. +X\item The {\tt dir()} function. +X\item Tuples. +X\item Dictionaries. +X\item Objects and types in general. +X\item Backquotes. +X\item And/Or/Not. +X\end{itemize} +X +X\end{document} +EOF +fi +echo 'Part 01 out of 21 of pack.out complete.' +exit 0 |