Source Code 1992 March/Source_Code_CD-ROM_Walnut_Creek_March_1992.iso/usenet/altsrcs/2/2789

Internet Message Format | 1991-02-20 | 60.7 KB

From: [e-mail] (Guido van Rossum)
Newsgroups: alt.sources
Subject: Python 0.9.1 part 01/21
Message-ID: <[e-mail]>
Date: 19 Feb 91 17:35:26 GMT

: 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: [e-mail]
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: [e-mail]
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 [e-mail]}
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