blob: 3406ac4e6d2933fba01a69d3ff8e46e999208a12 [file] [log] [blame]
Guido van Rossum37953781992-04-06 14:04:04 +00001\documentstyle[twoside,11pt,myformat]{report}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002
Guido van Rossum6938f061994-08-01 12:22:53 +00003\title{Python Tutorial}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00004
Guido van Rossum16cd7f91994-10-06 10:29:26 +00005\input{boilerplate}
Guido van Rossum83eb9621993-11-23 16:28:45 +00006
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00007\begin{document}
8
9\pagenumbering{roman}
10
11\maketitle
12
Guido van Rossum16cd7f91994-10-06 10:29:26 +000013\input{copyright}
14
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000015\begin{abstract}
16
17\noindent
Guido van Rossum4410c751991-06-04 20:22:18 +000018Python is a simple, yet powerful programming language that bridges the
Guido van Rossum6fc178f1991-08-16 09:13:42 +000019gap between C and shell programming, and is thus ideally suited for
20``throw-away programming''
21and rapid prototyping. Its syntax is put
22together from constructs borrowed from a variety of other languages;
23most prominent are influences from ABC, C, Modula-3 and Icon.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000024
Guido van Rossum4410c751991-06-04 20:22:18 +000025The Python interpreter is easily extended with new functions and data
Guido van Rossum6fc178f1991-08-16 09:13:42 +000026types implemented in C. Python is also suitable as an extension
27language for highly customizable C applications such as editors or
28window managers.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000029
Guido van Rossum4410c751991-06-04 20:22:18 +000030Python is available for various operating systems, amongst which
Fred Drake6dc2aae1996-12-13 21:56:03 +000031several flavors of \UNIX{}, the Apple Macintosh, MS-DOS, Windows
Guido van Rossum3a26dd81996-10-24 22:12:48 +000032(3.1(1), '95 and NT flavors), OS/2, and others.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000033
Guido van Rossum6fc178f1991-08-16 09:13:42 +000034This tutorial introduces the reader informally to the basic concepts
35and features of the Python language and system. It helps to have a
36Python interpreter handy for hands-on experience, but as the examples
37are self-contained, the tutorial can be read off-line as well.
Guido van Rossum2292b8e1991-01-23 16:31:24 +000038
Guido van Rossum481ae681991-11-25 17:28:03 +000039For a description of standard objects and modules, see the {\em Python
40Library Reference} document. The {\em Python Reference Manual} gives
41a more formal definition of the language.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000042
43\end{abstract}
44
45\pagebreak
Guido van Rossumcdc93551992-02-11 15:53:13 +000046{
47\parskip = 0mm
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000048\tableofcontents
Guido van Rossumcdc93551992-02-11 15:53:13 +000049}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000050
51\pagebreak
52
53\pagenumbering{arabic}
54
Guido van Rossum5e0759d1992-08-07 16:06:24 +000055
Guido van Rossum6fc178f1991-08-16 09:13:42 +000056\chapter{Whetting Your Appetite}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000057
Guido van Rossum3a26dd81996-10-24 22:12:48 +000058\section{Disclaimer}
59
60Now that there are several books out on Python, this tutorial has lost
61its role as the only introduction to Python for most new users. It
62takes time to keep a document like this up to date in the face of
63additions to the language, and I simply don't have enough time to do a
64good job. Therefore, this version of the tutorial is almost unchanged
65since the previous release. This doesn't mean that the tutorial is
66out of date --- all the examples still work exactly as before. There
67are simply some new areas of the language that aren't covered.
68
69To make up for this, there are some chapters at the end cover
70important changes in recent Python releases, and these are up to date
71with the current release.
72
73\section{Introduction}
74
Guido van Rossum6fc178f1991-08-16 09:13:42 +000075If you ever wrote a large shell script, you probably know this
76feeling: you'd love to add yet another feature, but it's already so
77slow, and so big, and so complicated; or the feature involves a system
Guido van Rossum6938f061994-08-01 12:22:53 +000078call or other function that is only accessible from C \ldots Usually
Guido van Rossum6fc178f1991-08-16 09:13:42 +000079the problem at hand isn't serious enough to warrant rewriting the
80script in C; perhaps because the problem requires variable-length
81strings or other data types (like sorted lists of file names) that are
82easy in the shell but lots of work to implement in C; or perhaps just
83because you're not sufficiently familiar with C.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000084
Guido van Rossum6fc178f1991-08-16 09:13:42 +000085In such cases, Python may be just the language for you. Python is
86simple to use, but it is a real programming language, offering much
87more structure and support for large programs than the shell has. On
88the other hand, it also offers much more error checking than C, and,
89being a {\em very-high-level language}, it has high-level data types
90built in, such as flexible arrays and dictionaries that would cost you
91days to implement efficiently in C. Because of its more general data
92types Python is applicable to a much larger problem domain than {\em
Guido van Rossuma8d754e1992-01-07 16:44:35 +000093Awk} or even {\em Perl}, yet many things are at least as easy in
94Python as in those languages.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000095
Guido van Rossum6fc178f1991-08-16 09:13:42 +000096Python allows you to split up your program in modules that can be
97reused in other Python programs. It comes with a large collection of
Guido van Rossuma8d754e1992-01-07 16:44:35 +000098standard modules that you can use as the basis of your programs --- or
99as examples to start learning to program in Python. There are also
100built-in modules that provide things like file I/O, system calls,
101sockets, and even a generic interface to window systems (STDWIN).
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000102
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000103Python is an interpreted language, which can save you considerable time
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000104during program development because no compilation and linking is
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000105necessary. The interpreter can be used interactively, which makes it
106easy to experiment with features of the language, to write throw-away
107programs, or to test functions during bottom-up program development.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000108It is also a handy desk calculator.
109
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000110Python allows writing very compact and readable programs. Programs
111written in Python are typically much shorter than equivalent C
112programs, for several reasons:
113\begin{itemize}
114\item
115the high-level data types allow you to express complex operations in a
116single statement;
117\item
118statement grouping is done by indentation instead of begin/end
119brackets;
120\item
121no variable or argument declarations are necessary.
122\end{itemize}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000123
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000124Python is {\em extensible}: if you know how to program in C it is easy
125to add a new built-in
126function or
127module to the interpreter, either to
128perform critical operations at maximum speed, or to link Python
129programs to libraries that may only be available in binary form (such
130as a vendor-specific graphics library). Once you are really hooked,
131you can link the Python interpreter into an application written in C
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000132and use it as an extension or command language for that application.
133
134By the way, the language is named after the BBC show ``Monty
135Python's Flying Circus'' and has nothing to do with nasty reptiles...
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000136
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000137\section{Where From Here}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000138
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000139Now that you are all excited about Python, you'll want to examine it
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000140in some more detail. Since the best way to learn a language is
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000141using it, you are invited here to do so.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000142
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000143In the next chapter, the mechanics of using the interpreter are
144explained. This is rather mundane information, but essential for
145trying out the examples shown later.
146
Guido van Rossum4410c751991-06-04 20:22:18 +0000147The rest of the tutorial introduces various features of the Python
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000148language and system though examples, beginning with simple
149expressions, statements and data types, through functions and modules,
Guido van Rossum6938f061994-08-01 12:22:53 +0000150and finally touching upon advanced concepts like exceptions
151and user-defined classes.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000152
Guido van Rossum6938f061994-08-01 12:22:53 +0000153When you're through with the tutorial (or just getting bored), you
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000154should read the Library Reference, which gives complete (though terse)
155reference material about built-in and standard types, functions and
156modules that can save you a lot of time when writing Python programs.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000157
Guido van Rossum5e0759d1992-08-07 16:06:24 +0000158
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000159\chapter{Using the Python Interpreter}
160
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000161\section{Invoking the Interpreter}
162
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000163The Python interpreter is usually installed as {\tt /usr/local/bin/python}
164on those machines where it is available; putting {\tt /usr/local/bin} in
Fred Drake6dc2aae1996-12-13 21:56:03 +0000165your \UNIX{} shell's search path makes it possible to start it by
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000166typing the command
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000167
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000168\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000169python
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000170\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000171%
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000172to the shell. Since the choice of the directory where the interpreter
173lives is an installation option, other places are possible; check with
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000174your local Python guru or system administrator. (E.g., {\tt
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000175/usr/local/python} is a popular alternative location.)
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000176
Fred Drake6dc2aae1996-12-13 21:56:03 +0000177The interpreter operates somewhat like the \UNIX{} shell: when called
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000178with standard input connected to a tty device, it reads and executes
179commands interactively; when called with a file name argument or with
180a file as standard input, it reads and executes a {\em script} from
181that file.
182
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000183A third way of starting the interpreter is
184``{\tt python -c command [arg] ...}'', which
185executes the statement(s) in {\tt command}, analogous to the shell's
186{\tt -c} option. Since Python statements often contain spaces or other
187characters that are special to the shell, it is best to quote {\tt
188command} in its entirety with double quotes.
189
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000190Note that there is a difference between ``{\tt python file}'' and
191``{\tt python $<$file}''. In the latter case, input requests from the
Guido van Rossum573805a1992-03-06 10:56:03 +0000192program, such as calls to {\tt input()} and {\tt raw_input()}, are
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000193satisfied from {\em file}. Since this file has already been read
194until the end by the parser before the program starts executing, the
195program will encounter EOF immediately. In the former case (which is
196usually what you want) they are satisfied from whatever file or device
197is connected to standard input of the Python interpreter.
198
Guido van Rossumb2c65561993-05-12 08:53:36 +0000199When a script file is used, it is sometimes useful to be able to run
200the script and enter interactive mode afterwards. This can be done by
201passing {\tt -i} before the script. (This does not work if the script
202is read from standard input, for the same reason as explained in the
203previous paragraph.)
204
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000205\subsection{Argument Passing}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000206
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000207When known to the interpreter, the script name and additional
208arguments thereafter are passed to the script in the variable {\tt
209sys.argv}, which is a list of strings. Its length is at least one;
210when no script and no arguments are given, {\tt sys.argv[0]} is an
211empty string. When the script name is given as {\tt '-'} (meaning
212standard input), {\tt sys.argv[0]} is set to {\tt '-'}. When {\tt -c
213command} is used, {\tt sys.argv[0]} is set to {\tt '-c'}. Options
214found after {\tt -c command} are not consumed by the Python
215interpreter's option processing but left in {\tt sys.argv} for the
216command to handle.
217
218\subsection{Interactive Mode}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000219
Guido van Rossumdd010801991-06-07 14:31:11 +0000220When commands are read from a tty, the interpreter is said to be in
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000221{\em interactive\ mode}. In this mode it prompts for the next command
222with the {\em primary\ prompt}, usually three greater-than signs ({\tt
Guido van Rossuma67dee31995-09-13 17:34:25 +0000223>>>}); for continuation lines it prompts with the
224{\em secondary\ prompt},
Guido van Rossum34e17771996-06-10 19:44:49 +0000225by default three dots ({\tt ...}). Typing an EOF character
Fred Drake6dc2aae1996-12-13 21:56:03 +0000226(Control-D on \UNIX{}, Control-Z on DOS or Windows)
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000227at the primary prompt causes the interpreter to exit with a zero exit
228status.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000229
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000230The interpreter prints a welcome message stating its version number
231and a copyright notice before printing the first prompt, e.g.:
232
233\bcode\begin{verbatim}
234python
Guido van Rossum6a05f951996-10-22 19:27:46 +0000235Python 1.4 (Oct 25 1996) [GCC 2.7.2]
Guido van Rossum97662c81996-08-23 15:35:47 +0000236Copyright 1991-1996 Stichting Mathematisch Centrum, Amsterdam
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000237>>>
238\end{verbatim}\ecode
239
240\section{The Interpreter and its Environment}
241
242\subsection{Error Handling}
243
244When an error occurs, the interpreter prints an error
245message and a stack trace. In interactive mode, it then returns to
246the primary prompt; when input came from a file, it exits with a
247nonzero exit status after printing
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000248the stack trace. (Exceptions handled by an {\tt except} clause in a
249{\tt try} statement are not errors in this context.) Some errors are
250unconditionally fatal and cause an exit with a nonzero exit; this
251applies to internal inconsistencies and some cases of running out of
252memory. All error messages are written to the standard error stream;
253normal output from the executed commands is written to standard
254output.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000255
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000256Typing the interrupt character (usually Control-C or DEL) to the
257primary or secondary prompt cancels the input and returns to the
258primary prompt.%
259\footnote{
Guido van Rossum6938f061994-08-01 12:22:53 +0000260 A problem with the GNU Readline package may prevent this.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000261}
262Typing an interrupt while a command is executing raises the {\tt
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000263KeyboardInterrupt} exception, which may be handled by a {\tt try}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000264statement.
265
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000266\subsection{The Module Search Path}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000267
Guido van Rossume5f8b601995-01-04 19:12:49 +0000268When a module named {\tt spam} is imported, the interpreter searches
Guido van Rossum58124881996-10-08 17:29:56 +0000269for a file named {\tt spam.py} in the current directory,
270and then in the list of directories specified by
271the environment variable {\tt PYTHONPATH}. This has the same syntax as
Fred Drake6dc2aae1996-12-13 21:56:03 +0000272the \UNIX{} shell variable {\tt PATH}, i.e., a list of colon-separated
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000273directory names. When {\tt PYTHONPATH} is not set, or when the file
274is not found there, the search continues in an installation-dependent
275default path, usually {\tt .:/usr/local/lib/python}.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000276
Guido van Rossum58124881996-10-08 17:29:56 +0000277Actually, modules are searched in the list of directories given by the
278variable {\tt sys.path} which is initialized from the directory
279containing the input script (or the current directory), {\tt
280PYTHONPATH} and the installation-dependent default. This allows
281Python programs that know what they're doing to modify or replace the
282module search path. See the section on Standard Modules later.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000283
284\subsection{``Compiled'' Python files}
285
286As an important speed-up of the start-up time for short programs that
Guido van Rossume5f8b601995-01-04 19:12:49 +0000287use a lot of standard modules, if a file called {\tt spam.pyc} exists
288in the directory where {\tt spam.py} is found, this is assumed to
289contain an already-``compiled'' version of the module {\tt spam}. The
290modification time of the version of {\tt spam.py} used to create {\tt
291spam.pyc} is recorded in {\tt spam.pyc}, and the file is ignored if
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000292these don't match.
293
Guido van Rossum58124881996-10-08 17:29:56 +0000294Normally, you don't need to do anything to create the {\tt spam.pyc} file.
Guido van Rossume5f8b601995-01-04 19:12:49 +0000295Whenever {\tt spam.py} is successfully compiled, an attempt is made to
296write the compiled version to {\tt spam.pyc}. It is not an error if
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000297this attempt fails; if for any reason the file is not written
Guido van Rossume5f8b601995-01-04 19:12:49 +0000298completely, the resulting {\tt spam.pyc} file will be recognized as
Guido van Rossum34e17771996-06-10 19:44:49 +0000299invalid and thus ignored later. The contents of the {\tt spam.pyc}
300file is platform independent, so a Python module directory can be
Guido van Rossum58124881996-10-08 17:29:56 +0000301shared by machines of different architectures. (Tip for experts:
302the module {\tt compileall} creates {\tt .pyc} files for all modules.)
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000303
304\subsection{Executable Python scripts}
Guido van Rossum4410c751991-06-04 20:22:18 +0000305
Fred Drake6dc2aae1996-12-13 21:56:03 +0000306On BSD'ish \UNIX{} systems, Python scripts can be made directly
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000307executable, like shell scripts, by putting the line
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000308
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000309\bcode\begin{verbatim}
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000310#! /usr/local/bin/python
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000311\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000312%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000313(assuming that's the name of the interpreter) at the beginning of the
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000314script and giving the file an executable mode. The {\tt \#!} must be
315the first two characters of the file.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000316
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000317\subsection{The Interactive Startup File}
318
319When you use Python interactively, it is frequently handy to have some
320standard commands executed every time the interpreter is started. You
321can do this by setting an environment variable named {\tt
322PYTHONSTARTUP} to the name of a file containing your start-up
Fred Drake6dc2aae1996-12-13 21:56:03 +0000323commands. This is similar to the {\tt .profile} feature of the \UNIX{}
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000324shells.
325
326This file is only read in interactive sessions, not when Python reads
327commands from a script, and not when {\tt /dev/tty} is given as the
328explicit source of commands (which otherwise behaves like an
329interactive session). It is executed in the same name space where
330interactive commands are executed, so that objects that it defines or
331imports can be used without qualification in the interactive session.
Guido van Rossum7b3c8a11992-09-08 09:20:13 +0000332You can also change the prompts {\tt sys.ps1} and {\tt sys.ps2} in
333this file.
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000334
335If you want to read an additional start-up file from the current
336directory, you can program this in the global start-up file, e.g.
337\verb\execfile('.pythonrc')\. If you want to use the startup file
338in a script, you must write this explicitly in the script, e.g.
339\verb\import os;\ \verb\execfile(os.environ['PYTHONSTARTUP'])\.
340
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000341\section{Interactive Input Editing and History Substitution}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000342
Guido van Rossum4410c751991-06-04 20:22:18 +0000343Some versions of the Python interpreter support editing of the current
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000344input line and history substitution, similar to facilities found in
345the Korn shell and the GNU Bash shell. This is implemented using the
346{\em GNU\ Readline} library, which supports Emacs-style and vi-style
347editing. This library has its own documentation which I won't
348duplicate here; however, the basics are easily explained.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000349
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000350Perhaps the quickest check to see whether command line editing is
351supported is typing Control-P to the first Python prompt you get. If
352it beeps, you have command line editing. If nothing appears to
353happen, or if \verb/^P/ is echoed, you can skip the rest of this
354section.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000355
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000356\subsection{Line Editing}
357
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000358If supported, input line editing is active whenever the interpreter
359prints a primary or secondary prompt. The current line can be edited
360using the conventional Emacs control characters. The most important
361of these are: C-A (Control-A) moves the cursor to the beginning of the
362line, C-E to the end, C-B moves it one position to the left, C-F to
363the right. Backspace erases the character to the left of the cursor,
364C-D the character to its right. C-K kills (erases) the rest of the
365line to the right of the cursor, C-Y yanks back the last killed
366string. C-underscore undoes the last change you made; it can be
367repeated for cumulative effect.
368
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000369\subsection{History Substitution}
370
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000371History substitution works as follows. All non-empty input lines
372issued are saved in a history buffer, and when a new prompt is given
373you are positioned on a new line at the bottom of this buffer. C-P
374moves one line up (back) in the history buffer, C-N moves one down.
Guido van Rossum2292b8e1991-01-23 16:31:24 +0000375Any line in the history buffer can be edited; an asterisk appears in
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000376front of the prompt to mark a line as modified. Pressing the Return
377key passes the current line to the interpreter. C-R starts an
378incremental reverse search; C-S starts a forward search.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000379
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000380\subsection{Key Bindings}
381
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000382The key bindings and some other parameters of the Readline library can
383be customized by placing commands in an initialization file called
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000384{\tt \$HOME/.inputrc}. Key bindings have the form
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000385
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000386\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000387key-name: function-name
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000388\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000389%
390or
391
392\bcode\begin{verbatim}
393"string": function-name
394\end{verbatim}\ecode
395%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000396and options can be set with
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000397
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000398\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000399set option-name value
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000400\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000401%
402For example:
403
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000404\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000405# I prefer vi-style editing:
406set editing-mode vi
407# Edit using a single line:
408set horizontal-scroll-mode On
409# Rebind some keys:
410Meta-h: backward-kill-word
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000411"\C-u": universal-argument
412"\C-x\C-r": re-read-init-file
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000413\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000414%
Guido van Rossum4410c751991-06-04 20:22:18 +0000415Note that the default binding for TAB in Python is to insert a TAB
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000416instead of Readline's default filename completion function. If you
417insist, you can override this by putting
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000418
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000419\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000420TAB: complete
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000421\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000422%
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000423in your {\tt \$HOME/.inputrc}. (Of course, this makes it hard to type
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000424indented continuation lines...)
425
426\subsection{Commentary}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000427
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000428This facility is an enormous step forward compared to previous
429versions of the interpreter; however, some wishes are left: It would
430be nice if the proper indentation were suggested on continuation lines
431(the parser knows if an indent token is required next). The
432completion mechanism might use the interpreter's symbol table. A
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000433command to check (or even suggest) matching parentheses, quotes etc.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000434would also be useful.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000435
Guido van Rossum5e0759d1992-08-07 16:06:24 +0000436
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000437\chapter{An Informal Introduction to Python}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000438
439In the following examples, input and output are distinguished by the
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000440presence or absence of prompts ({\tt >>>} and {\tt ...}): to repeat
441the example, you must type everything after the prompt, when the
442prompt appears; lines that do not begin with a prompt are output from
443the interpreter.%
444\footnote{
Guido van Rossum6938f061994-08-01 12:22:53 +0000445 I'd prefer to use different fonts to distinguish input
446 from output, but the amount of LaTeX hacking that would require
447 is currently beyond my ability.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000448}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000449Note that a secondary prompt on a line by itself in an example means
450you must type a blank line; this is used to end a multi-line command.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000451
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000452\section{Using Python as a Calculator}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000453
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000454Let's try some simple Python commands. Start the interpreter and wait
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000455for the primary prompt, {\tt >>>}. (It shouldn't take long.)
456
457\subsection{Numbers}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000458
459The interpreter acts as a simple calculator: you can type an
460expression at it and it will write the value. Expression syntax is
461straightforward: the operators {\tt +}, {\tt -}, {\tt *} and {\tt /}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000462work just like in most other languages (e.g., Pascal or C); parentheses
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000463can be used for grouping. For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000464
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000465\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000466>>> 2+2
4674
Guido van Rossum6938f061994-08-01 12:22:53 +0000468>>> # This is a comment
469... 2+2
4704
471>>> 2+2 # and a comment on the same line as code
4724
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000473>>> (50-5*6)/4
4745
Guido van Rossum6938f061994-08-01 12:22:53 +0000475>>> # Integer division returns the floor:
476... 7/3
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00004772
Guido van Rossum6938f061994-08-01 12:22:53 +0000478>>> 7/-3
479-3
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000480>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000481\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000482%
483Like in C, the equal sign ({\tt =}) is used to assign a value to a
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000484variable. The value of an assignment is not written:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000485
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000486\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000487>>> width = 20
488>>> height = 5*9
489>>> width * height
490900
491>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000492\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000493%
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000494A value can be assigned to several variables simultaneously:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000495
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000496\bcode\begin{verbatim}
Guido van Rossum6938f061994-08-01 12:22:53 +0000497>>> x = y = z = 0 # Zero x, y and z
498>>> x
4990
500>>> y
5010
502>>> z
5030
504>>>
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000505\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000506%
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000507There is full support for floating point; operators with mixed type
508operands convert the integer operand to floating point:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000509
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000510\bcode\begin{verbatim}
511>>> 4 * 2.5 / 3.3
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00005123.0303030303
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000513>>> 7.0 / 2
5143.5
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000515>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000516\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000517
518\subsection{Strings}
519
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000520Besides numbers, Python can also manipulate strings, enclosed in
Guido van Rossum6938f061994-08-01 12:22:53 +0000521single quotes or double quotes:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000522
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000523\bcode\begin{verbatim}
Guido van Rossume5f8b601995-01-04 19:12:49 +0000524>>> 'spam eggs'
525'spam eggs'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000526>>> 'doesn\'t'
Guido van Rossum6938f061994-08-01 12:22:53 +0000527"doesn't"
528>>> "doesn't"
529"doesn't"
530>>> '"Yes," he said.'
531'"Yes," he said.'
532>>> "\"Yes,\" he said."
533'"Yes," he said.'
534>>> '"Isn\'t," she said.'
535'"Isn\'t," she said.'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000536>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000537\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000538%
539Strings are written the same way as they are typed for input: inside
Guido van Rossum6938f061994-08-01 12:22:53 +0000540quotes and with quotes and other funny characters escaped by backslashes,
541to show the precise value. The string is enclosed in double quotes if
542the string contains a single quote and no double quotes, else it's
543enclosed in single quotes. (The {\tt print} statement, described later,
544can be used to write strings without quotes or escapes.)
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000545
546Strings can be concatenated (glued together) with the {\tt +}
547operator, and repeated with {\tt *}:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000548
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000549\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000550>>> word = 'Help' + 'A'
551>>> word
552'HelpA'
553>>> '<' + word*5 + '>'
554'<HelpAHelpAHelpAHelpAHelpA>'
555>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000556\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000557%
558Strings can be subscripted (indexed); like in C, the first character of
559a string has subscript (index) 0.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000560
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000561There is no separate character type; a character is simply a string of
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000562size one. Like in Icon, substrings can be specified with the {\em
563slice} notation: two indices separated by a colon.
564
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000565\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000566>>> word[4]
567'A'
568>>> word[0:2]
569'He'
570>>> word[2:4]
571'lp'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000572>>>
573\end{verbatim}\ecode
574%
575Slice indices have useful defaults; an omitted first index defaults to
576zero, an omitted second index defaults to the size of the string being
577sliced.
578
579\bcode\begin{verbatim}
580>>> word[:2] # The first two characters
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000581'He'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000582>>> word[2:] # All but the first two characters
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000583'lpA'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000584>>>
585\end{verbatim}\ecode
586%
587Here's a useful invariant of slice operations: \verb\s[:i] + s[i:]\
588equals \verb\s\.
589
590\bcode\begin{verbatim}
591>>> word[:2] + word[2:]
592'HelpA'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000593>>> word[:3] + word[3:]
594'HelpA'
595>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000596\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000597%
598Degenerate slice indices are handled gracefully: an index that is too
599large is replaced by the string size, an upper bound smaller than the
600lower bound returns an empty string.
601
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000602\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000603>>> word[1:100]
604'elpA'
605>>> word[10:]
606''
607>>> word[2:1]
608''
609>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000610\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000611%
612Indices may be negative numbers, to start counting from the right.
613For example:
614
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000615\bcode\begin{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000616>>> word[-1] # The last character
617'A'
618>>> word[-2] # The last-but-one character
619'p'
620>>> word[-2:] # The last two characters
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000621'pA'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000622>>> word[:-2] # All but the last two characters
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000623'Hel'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000624>>>
625\end{verbatim}\ecode
626%
627But note that -0 is really the same as 0, so it does not count from
628the right!
629
630\bcode\begin{verbatim}
631>>> word[-0] # (since -0 equals 0)
632'H'
633>>>
634\end{verbatim}\ecode
635%
636Out-of-range negative slice indices are truncated, but don't try this
637for single-element (non-slice) indices:
638
639\bcode\begin{verbatim}
640>>> word[-100:]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000641'HelpA'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000642>>> word[-10] # error
Guido van Rossum6938f061994-08-01 12:22:53 +0000643Traceback (innermost last):
644 File "<stdin>", line 1
645IndexError: string index out of range
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000646>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000647\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000648%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000649The best way to remember how slices work is to think of the indices as
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000650pointing {\em between} characters, with the left edge of the first
651character numbered 0. Then the right edge of the last character of a
652string of {\tt n} characters has index {\tt n}, for example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000653
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000654\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000655 +---+---+---+---+---+
656 | H | e | l | p | A |
657 +---+---+---+---+---+
658 0 1 2 3 4 5
659-5 -4 -3 -2 -1
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000660\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000661%
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000662The first row of numbers gives the position of the indices 0...5 in
663the string; the second row gives the corresponding negative indices.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000664The slice from \verb\i\ to \verb\j\ consists of all characters between
665the edges labeled \verb\i\ and \verb\j\, respectively.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000666
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000667For nonnegative indices, the length of a slice is the difference of
668the indices, if both are within bounds, e.g., the length of
669\verb\word[1:3]\ is 2.
670
671The built-in function {\tt len()} returns the length of a string:
672
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000673\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000674>>> s = 'supercalifragilisticexpialidocious'
675>>> len(s)
67634
677>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000678\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000679
680\subsection{Lists}
681
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000682Python knows a number of {\em compound} data types, used to group
683together other values. The most versatile is the {\em list}, which
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000684can be written as a list of comma-separated values (items) between
685square brackets. List items need not all have the same type.
686
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000687\bcode\begin{verbatim}
Guido van Rossume5f8b601995-01-04 19:12:49 +0000688>>> a = ['spam', 'eggs', 100, 1234]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000689>>> a
Guido van Rossume5f8b601995-01-04 19:12:49 +0000690['spam', 'eggs', 100, 1234]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000691>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000692\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000693%
694Like string indices, list indices start at 0, and lists can be sliced,
695concatenated and so on:
696
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000697\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000698>>> a[0]
Guido van Rossume5f8b601995-01-04 19:12:49 +0000699'spam'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000700>>> a[3]
7011234
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000702>>> a[-2]
703100
704>>> a[1:-1]
Guido van Rossume5f8b601995-01-04 19:12:49 +0000705['eggs', 100]
706>>> a[:2] + ['bacon', 2*2]
707['spam', 'eggs', 'bacon', 4]
Guido van Rossum4410c751991-06-04 20:22:18 +0000708>>> 3*a[:3] + ['Boe!']
Guido van Rossume5f8b601995-01-04 19:12:49 +0000709['spam', 'eggs', 100, 'spam', 'eggs', 100, 'spam', 'eggs', 100, 'Boe!']
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000710>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000711\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000712%
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000713Unlike strings, which are {\em immutable}, it is possible to change
714individual elements of a list:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000715
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000716\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000717>>> a
Guido van Rossume5f8b601995-01-04 19:12:49 +0000718['spam', 'eggs', 100, 1234]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000719>>> a[2] = a[2] + 23
720>>> a
Guido van Rossume5f8b601995-01-04 19:12:49 +0000721['spam', 'eggs', 123, 1234]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000722>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000723\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000724%
725Assignment to slices is also possible, and this can even change the size
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000726of the list:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000727
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000728\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000729>>> # Replace some items:
Guido van Rossum6938f061994-08-01 12:22:53 +0000730... a[0:2] = [1, 12]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000731>>> a
732[1, 12, 123, 1234]
733>>> # Remove some:
Guido van Rossum6938f061994-08-01 12:22:53 +0000734... a[0:2] = []
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000735>>> a
736[123, 1234]
737>>> # Insert some:
Guido van Rossum6938f061994-08-01 12:22:53 +0000738... a[1:1] = ['bletch', 'xyzzy']
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000739>>> a
740[123, 'bletch', 'xyzzy', 1234]
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000741>>> a[:0] = a # Insert (a copy of) itself at the beginning
742>>> a
743[123, 'bletch', 'xyzzy', 1234, 123, 'bletch', 'xyzzy', 1234]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000744>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000745\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000746%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000747The built-in function {\tt len()} also applies to lists:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000748
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000749\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000750>>> len(a)
Guido van Rossuma8d754e1992-01-07 16:44:35 +00007518
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000752>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000753\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000754%
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000755It is possible to nest lists (create lists containing other lists),
756for example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000757
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000758\bcode\begin{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000759>>> q = [2, 3]
760>>> p = [1, q, 4]
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000761>>> len(p)
7623
763>>> p[1]
764[2, 3]
765>>> p[1][0]
7662
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000767>>> p[1].append('xtra') # See section 5.1
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000768>>> p
769[1, [2, 3, 'xtra'], 4]
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000770>>> q
771[2, 3, 'xtra']
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000772>>>
773\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000774%
775Note that in the last example, {\tt p[1]} and {\tt q} really refer to
776the same object! We'll come back to {\em object semantics} later.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000777
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000778\section{First Steps Towards Programming}
Guido van Rossum2292b8e1991-01-23 16:31:24 +0000779
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000780Of course, we can use Python for more complicated tasks than adding
781two and two together. For instance, we can write an initial
782subsequence of the {\em Fibonacci} series as follows:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000783
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000784\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000785>>> # Fibonacci series:
Guido van Rossum6938f061994-08-01 12:22:53 +0000786... # the sum of two elements defines the next
787... a, b = 0, 1
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000788>>> while b < 10:
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000789... print b
790... a, b = b, a+b
791...
7921
7931
7942
7953
7965
7978
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000798>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000799\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000800%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000801This example introduces several new features.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000802
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000803\begin{itemize}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000804
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000805\item
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000806The first line contains a {\em multiple assignment}: the variables
807{\tt a} and {\tt b} simultaneously get the new values 0 and 1. On the
808last line this is used again, demonstrating that the expressions on
809the right-hand side are all evaluated first before any of the
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000810assignments take place.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000811
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000812\item
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000813The {\tt while} loop executes as long as the condition (here: {\tt b <
Guido van Rossum16cd7f91994-10-06 10:29:26 +000081410}) remains true. In Python, like in C, any non-zero integer value is
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000815true; zero is false. The condition may also be a string or list value,
816in fact any sequence; anything with a non-zero length is true, empty
817sequences are false. The test used in the example is a simple
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000818comparison. The standard comparison operators are written the same as
819in C: {\tt <}, {\tt >}, {\tt ==}, {\tt <=}, {\tt >=} and {\tt !=}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000820
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000821\item
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000822The {\em body} of the loop is {\em indented}: indentation is Python's
823way of grouping statements. Python does not (yet!) provide an
824intelligent input line editing facility, so you have to type a tab or
825space(s) for each indented line. In practice you will prepare more
826complicated input for Python with a text editor; most text editors have
827an auto-indent facility. When a compound statement is entered
828interactively, it must be followed by a blank line to indicate
829completion (since the parser cannot guess when you have typed the last
830line).
831
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000832\item
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000833The {\tt print} statement writes the value of the expression(s) it is
834given. It differs from just writing the expression you want to write
835(as we did earlier in the calculator examples) in the way it handles
Guido van Rossum16cd7f91994-10-06 10:29:26 +0000836multiple expressions and strings. Strings are printed without quotes,
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000837and a space is inserted between items, so you can format things nicely,
838like this:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000839
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000840\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000841>>> i = 256*256
842>>> print 'The value of i is', i
843The value of i is 65536
844>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000845\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000846%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000847A trailing comma avoids the newline after the output:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000848
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000849\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000850>>> a, b = 0, 1
851>>> while b < 1000:
852... print b,
853... a, b = b, a+b
854...
8551 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
856>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000857\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000858%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000859Note that the interpreter inserts a newline before it prints the next
860prompt if the last line was not completed.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000861
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000862\end{itemize}
863
Guido van Rossum5e0759d1992-08-07 16:06:24 +0000864
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000865\chapter{More Control Flow Tools}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000866
Guido van Rossum4410c751991-06-04 20:22:18 +0000867Besides the {\tt while} statement just introduced, Python knows the
Guido van Rossum2292b8e1991-01-23 16:31:24 +0000868usual control flow statements known from other languages, with some
869twists.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000870
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000871\section{If Statements}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000872
873Perhaps the most well-known statement type is the {\tt if} statement.
874For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000875
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000876\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000877>>> if x < 0:
878... x = 0
879... print 'Negative changed to zero'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000880... elif x == 0:
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000881... print 'Zero'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000882... elif x == 1:
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000883... print 'Single'
884... else:
885... print 'More'
886...
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000887\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000888%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000889There can be zero or more {\tt elif} parts, and the {\tt else} part is
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000890optional. The keyword `{\tt elif}' is short for `{\tt else if}', and is
891useful to avoid excessive indentation. An {\tt if...elif...elif...}
892sequence is a substitute for the {\em switch} or {\em case} statements
893found in other languages.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000894
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000895\section{For Statements}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000896
Guido van Rossum4410c751991-06-04 20:22:18 +0000897The {\tt for} statement in Python differs a bit from what you may be
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000898used to in C or Pascal. Rather than always iterating over an
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000899arithmetic progression of numbers (like in Pascal), or leaving the user
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000900completely free in the iteration test and step (as C), Python's {\tt
901for} statement iterates over the items of any sequence (e.g., a list
902or a string), in the order that they appear in the sequence. For
903example (no pun intended):
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000904
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000905\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000906>>> # Measure some strings:
Guido van Rossum6938f061994-08-01 12:22:53 +0000907... a = ['cat', 'window', 'defenestrate']
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000908>>> for x in a:
909... print x, len(x)
910...
911cat 3
912window 6
913defenestrate 12
914>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000915\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000916%
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000917It is not safe to modify the sequence being iterated over in the loop
918(this can only happen for mutable sequence types, i.e., lists). If
919you need to modify the list you are iterating over, e.g., duplicate
920selected items, you must iterate over a copy. The slice notation
921makes this particularly convenient:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000922
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000923\bcode\begin{verbatim}
924>>> for x in a[:]: # make a slice copy of the entire list
925... if len(x) > 6: a.insert(0, x)
926...
927>>> a
928['defenestrate', 'cat', 'window', 'defenestrate']
929>>>
930\end{verbatim}\ecode
Guido van Rossum2292b8e1991-01-23 16:31:24 +0000931
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000932\section{The {\tt range()} Function}
Guido van Rossum2292b8e1991-01-23 16:31:24 +0000933
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000934If you do need to iterate over a sequence of numbers, the built-in
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000935function {\tt range()} comes in handy. It generates lists containing
936arithmetic progressions, e.g.:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000937
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000938\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000939>>> range(10)
940[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
941>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000942\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000943%
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000944The given end point is never part of the generated list; {\tt range(10)}
945generates a list of 10 values, exactly the legal indices for items of a
946sequence of length 10. It is possible to let the range start at another
947number, or to specify a different increment (even negative):
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000948
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000949\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000950>>> range(5, 10)
951[5, 6, 7, 8, 9]
952>>> range(0, 10, 3)
953[0, 3, 6, 9]
954>>> range(-10, -100, -30)
955[-10, -40, -70]
956>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000957\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000958%
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000959To iterate over the indices of a sequence, combine {\tt range()} and
960{\tt len()} as follows:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000961
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000962\bcode\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000963>>> a = ['Mary', 'had', 'a', 'little', 'lamb']
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000964>>> for i in range(len(a)):
965... print i, a[i]
966...
9670 Mary
9681 had
9692 a
9703 little
Guido van Rossum6fc178f1991-08-16 09:13:42 +00009714 lamb
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000972>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000973\end{verbatim}\ecode
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000974
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000975\section{Break and Continue Statements, and Else Clauses on Loops}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000976
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000977The {\tt break} statement, like in C, breaks out of the smallest
978enclosing {\tt for} or {\tt while} loop.
979
980The {\tt continue} statement, also borrowed from C, continues with the
981next iteration of the loop.
982
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000983Loop statements may have an {\tt else} clause; it is executed when the
Guido van Rossum2292b8e1991-01-23 16:31:24 +0000984loop terminates through exhaustion of the list (with {\tt for}) or when
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000985the condition becomes false (with {\tt while}), but not when the loop is
986terminated by a {\tt break} statement. This is exemplified by the
Guido van Rossumcfb45e41994-11-10 23:04:43 +0000987following loop, which searches for prime numbers:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000988
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000989\bcode\begin{verbatim}
Guido van Rossum2292b8e1991-01-23 16:31:24 +0000990>>> for n in range(2, 10):
991... for x in range(2, n):
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000992... if n % x == 0:
Guido van Rossum2292b8e1991-01-23 16:31:24 +0000993... print n, 'equals', x, '*', n/x
994... break
995... else:
996... print n, 'is a prime number'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000997...
Guido van Rossum2292b8e1991-01-23 16:31:24 +00009982 is a prime number
9993 is a prime number
10004 equals 2 * 2
10015 is a prime number
10026 equals 2 * 3
10037 is a prime number
10048 equals 2 * 4
10059 equals 3 * 3
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001006>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001007\end{verbatim}\ecode
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001008
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001009\section{Pass Statements}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001010
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001011The {\tt pass} statement does nothing.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001012It can be used when a statement is required syntactically but the
1013program requires no action.
1014For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001015
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001016\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001017>>> while 1:
1018... pass # Busy-wait for keyboard interrupt
1019...
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001020\end{verbatim}\ecode
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001021
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001022\section{Defining Functions}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001023
1024We can create a function that writes the Fibonacci series to an
1025arbitrary boundary:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001026
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001027\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001028>>> def fib(n): # write Fibonacci series up to n
1029... a, b = 0, 1
Guido van Rossum16cd7f91994-10-06 10:29:26 +00001030... while b < n:
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001031... print b,
1032... a, b = b, a+b
1033...
1034>>> # Now call the function we just defined:
Guido van Rossum6938f061994-08-01 12:22:53 +00001035... fib(2000)
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000010361 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597
1037>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001038\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001039%
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001040The keyword {\tt def} introduces a function {\em definition}. It must
1041be followed by the function name and the parenthesized list of formal
1042parameters. The statements that form the body of the function starts at
1043the next line, indented by a tab stop.
1044
1045The {\em execution} of a function introduces a new symbol table used
1046for the local variables of the function. More precisely, all variable
1047assignments in a function store the value in the local symbol table;
1048whereas
Guido van Rossum6938f061994-08-01 12:22:53 +00001049variable references first look in the local symbol table, then
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001050in the global symbol table, and then in the table of built-in names.
1051Thus,
Guido van Rossumcfb45e41994-11-10 23:04:43 +00001052global variables cannot be directly assigned a value within a
Guido van Rossum6938f061994-08-01 12:22:53 +00001053function (unless named in a {\tt global} statement), although
1054they may be referenced.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001055
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001056The actual parameters (arguments) to a function call are introduced in
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001057the local symbol table of the called function when it is called; thus,
1058arguments are passed using {\em call\ by\ value}.%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001059\footnote{
Guido van Rossum6938f061994-08-01 12:22:53 +00001060 Actually, {\em call by object reference} would be a better
1061 description, since if a mutable object is passed, the caller
1062 will see any changes the callee makes to it (e.g., items
1063 inserted into a list).
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001064}
1065When a function calls another function, a new local symbol table is
1066created for that call.
1067
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001068A function definition introduces the function name in the
1069current
1070symbol table. The value
1071of the function name
1072has a type that is recognized by the interpreter as a user-defined
1073function. This value can be assigned to another name which can then
1074also be used as a function. This serves as a general renaming
1075mechanism:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001076
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001077\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001078>>> fib
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001079<function object at 10042ed0>
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001080>>> f = fib
1081>>> f(100)
10821 1 2 3 5 8 13 21 34 55 89
1083>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001084\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001085%
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001086You might object that {\tt fib} is not a function but a procedure. In
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001087Python, like in C, procedures are just functions that don't return a
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001088value. In fact, technically speaking, procedures do return a value,
1089albeit a rather boring one. This value is called {\tt None} (it's a
1090built-in name). Writing the value {\tt None} is normally suppressed by
1091the interpreter if it would be the only value written. You can see it
1092if you really want to:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001093
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001094\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001095>>> print fib(0)
1096None
1097>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001098\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001099%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001100It is simple to write a function that returns a list of the numbers of
1101the Fibonacci series, instead of printing it:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001102
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001103\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001104>>> def fib2(n): # return Fibonacci series up to n
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001105... result = []
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001106... a, b = 0, 1
Guido van Rossum16cd7f91994-10-06 10:29:26 +00001107... while b < n:
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001108... result.append(b) # see below
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001109... a, b = b, a+b
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001110... return result
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001111...
1112>>> f100 = fib2(100) # call it
1113>>> f100 # write the result
1114[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
1115>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001116\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001117%
Guido van Rossum4410c751991-06-04 20:22:18 +00001118This example, as usual, demonstrates some new Python features:
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001119
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001120\begin{itemize}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001121
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001122\item
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001123The {\tt return} statement returns with a value from a function. {\tt
1124return} without an expression argument is used to return from the middle
Guido van Rossum6938f061994-08-01 12:22:53 +00001125of a procedure (falling off the end also returns from a procedure), in
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001126which case the {\tt None} value is returned.
1127
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001128\item
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001129The statement {\tt result.append(b)} calls a {\em method} of the list
1130object {\tt result}. A method is a function that `belongs' to an
1131object and is named {\tt obj.methodname}, where {\tt obj} is some
1132object (this may be an expression), and {\tt methodname} is the name
1133of a method that is defined by the object's type. Different types
1134define different methods. Methods of different types may have the
1135same name without causing ambiguity. (It is possible to define your
Guido van Rossum6938f061994-08-01 12:22:53 +00001136own object types and methods, using {\em classes}, as discussed later
1137in this tutorial.)
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001138The method {\tt append} shown in the example, is defined for
1139list objects; it adds a new element at the end of the list. In this
1140example
1141it is equivalent to {\tt result = result + [b]}, but more efficient.
1142
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001143\end{itemize}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001144
Guido van Rossum5e0759d1992-08-07 16:06:24 +00001145
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001146\chapter{Odds and Ends}
1147
1148This chapter describes some things you've learned about already in
1149more detail, and adds some new things as well.
1150
1151\section{More on Lists}
1152
1153The list data type has some more methods. Here are all of the methods
1154of lists objects:
1155
Guido van Rossum7d9f8d71991-01-22 11:45:00 +00001156\begin{description}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001157
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001158\item[{\tt insert(i, x)}]
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001159Insert an item at a given position. The first argument is the index of
1160the element before which to insert, so {\tt a.insert(0, x)} inserts at
1161the front of the list, and {\tt a.insert(len(a), x)} is equivalent to
1162{\tt a.append(x)}.
1163
1164\item[{\tt append(x)}]
1165Equivalent to {\tt a.insert(len(a), x)}.
1166
1167\item[{\tt index(x)}]
1168Return the index in the list of the first item whose value is {\tt x}.
1169It is an error if there is no such item.
1170
1171\item[{\tt remove(x)}]
1172Remove the first item from the list whose value is {\tt x}.
1173It is an error if there is no such item.
1174
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001175\item[{\tt sort()}]
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001176Sort the items of the list, in place.
1177
1178\item[{\tt reverse()}]
1179Reverse the elements of the list, in place.
1180
Guido van Rossum6938f061994-08-01 12:22:53 +00001181\item[{\tt count(x)}]
1182Return the number of times {\tt x} appears in the list.
1183
Guido van Rossum7d9f8d71991-01-22 11:45:00 +00001184\end{description}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001185
1186An example that uses all list methods:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001187
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001188\bcode\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001189>>> a = [66.6, 333, 333, 1, 1234.5]
Guido van Rossum6938f061994-08-01 12:22:53 +00001190>>> print a.count(333), a.count(66.6), a.count('x')
11912 1 0
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001192>>> a.insert(2, -1)
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001193>>> a.append(333)
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001194>>> a
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001195[66.6, 333, -1, 333, 1, 1234.5, 333]
1196>>> a.index(333)
11971
1198>>> a.remove(333)
1199>>> a
1200[66.6, -1, 333, 1, 1234.5, 333]
1201>>> a.reverse()
1202>>> a
1203[333, 1234.5, 1, 333, -1, 66.6]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001204>>> a.sort()
1205>>> a
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001206[-1, 1, 66.6, 333, 333, 1234.5]
1207>>>
1208\end{verbatim}\ecode
1209
1210\section{The {\tt del} statement}
1211
1212There is a way to remove an item from a list given its index instead
1213of its value: the {\tt del} statement. This can also be used to
1214remove slices from a list (which we did earlier by assignment of an
1215empty list to the slice). For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001216
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001217\bcode\begin{verbatim}
1218>>> a
1219[-1, 1, 66.6, 333, 333, 1234.5]
1220>>> del a[0]
1221>>> a
1222[1, 66.6, 333, 333, 1234.5]
1223>>> del a[2:4]
1224>>> a
1225[1, 66.6, 1234.5]
1226>>>
1227\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001228%
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001229{\tt del} can also be used to delete entire variables:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001230
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001231\bcode\begin{verbatim}
1232>>> del a
1233>>>
1234\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001235%
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001236Referencing the name {\tt a} hereafter is an error (at least until
1237another value is assigned to it). We'll find other uses for {\tt del}
1238later.
1239
1240\section{Tuples and Sequences}
1241
1242We saw that lists and strings have many common properties, e.g.,
Guido van Rossum6938f061994-08-01 12:22:53 +00001243indexing and slicing operations. They are two examples of {\em
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001244sequence} data types. Since Python is an evolving language, other
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001245sequence data types may be added. There is also another standard
1246sequence data type: the {\em tuple}.
1247
1248A tuple consists of a number of values separated by commas, for
1249instance:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001250
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001251\bcode\begin{verbatim}
1252>>> t = 12345, 54321, 'hello!'
1253>>> t[0]
125412345
1255>>> t
1256(12345, 54321, 'hello!')
1257>>> # Tuples may be nested:
Guido van Rossum6938f061994-08-01 12:22:53 +00001258... u = t, (1, 2, 3, 4, 5)
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001259>>> u
1260((12345, 54321, 'hello!'), (1, 2, 3, 4, 5))
1261>>>
1262\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001263%
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001264As you see, on output tuples are alway enclosed in parentheses, so
1265that nested tuples are interpreted correctly; they may be input with
1266or without surrounding parentheses, although often parentheses are
1267necessary anyway (if the tuple is part of a larger expression).
1268
1269Tuples have many uses, e.g., (x, y) coordinate pairs, employee records
1270from a database, etc. Tuples, like strings, are immutable: it is not
1271possible to assign to the individual items of a tuple (you can
1272simulate much of the same effect with slicing and concatenation,
1273though).
1274
1275A special problem is the construction of tuples containing 0 or 1
Guido van Rossum6938f061994-08-01 12:22:53 +00001276items: the syntax has some extra quirks to accommodate these. Empty
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001277tuples are constructed by an empty pair of parentheses; a tuple with
1278one item is constructed by following a value with a comma
1279(it is not sufficient to enclose a single value in parentheses).
1280Ugly, but effective. For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001281
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001282\bcode\begin{verbatim}
1283>>> empty = ()
1284>>> singleton = 'hello', # <-- note trailing comma
1285>>> len(empty)
12860
1287>>> len(singleton)
12881
1289>>> singleton
1290('hello',)
1291>>>
1292\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001293%
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001294The statement {\tt t = 12345, 54321, 'hello!'} is an example of {\em
1295tuple packing}: the values {\tt 12345}, {\tt 54321} and {\tt 'hello!'}
1296are packed together in a tuple. The reverse operation is also
1297possible, e.g.:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001298
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001299\bcode\begin{verbatim}
1300>>> x, y, z = t
1301>>>
1302\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001303%
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001304This is called, appropriately enough, {\em tuple unpacking}. Tuple
1305unpacking requires that the list of variables on the left has the same
1306number of elements as the length of the tuple. Note that multiple
1307assignment is really just a combination of tuple packing and tuple
1308unpacking!
1309
1310Occasionally, the corresponding operation on lists is useful: {\em list
1311unpacking}. This is supported by enclosing the list of variables in
1312square brackets:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001313
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001314\bcode\begin{verbatim}
Guido van Rossume5f8b601995-01-04 19:12:49 +00001315>>> a = ['spam', 'eggs', 100, 1234]
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001316>>> [a1, a2, a3, a4] = a
1317>>>
1318\end{verbatim}\ecode
1319
1320\section{Dictionaries}
1321
1322Another useful data type built into Python is the {\em dictionary}.
1323Dictionaries are sometimes found in other languages as ``associative
1324memories'' or ``associative arrays''. Unlike sequences, which are
1325indexed by a range of numbers, dictionaries are indexed by {\em keys},
Guido van Rossum6938f061994-08-01 12:22:53 +00001326which are strings (the use of non-string values as keys
1327is supported, but beyond the scope of this tutorial).
1328It is best to think of a dictionary as an unordered set of
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001329{\em key:value} pairs, with the requirement that the keys are unique
1330(within one dictionary).
1331A pair of braces creates an empty dictionary: \verb/{}/.
1332Placing a comma-separated list of key:value pairs within the
1333braces adds initial key:value pairs to the dictionary; this is also the
1334way dictionaries are written on output.
1335
1336The main operations on a dictionary are storing a value with some key
1337and extracting the value given the key. It is also possible to delete
1338a key:value pair
1339with {\tt del}.
1340If you store using a key that is already in use, the old value
1341associated with that key is forgotten. It is an error to extract a
Guido van Rossum6938f061994-08-01 12:22:53 +00001342value using a non-existent key.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001343
1344The {\tt keys()} method of a dictionary object returns a list of all the
1345keys used in the dictionary, in random order (if you want it sorted,
1346just apply the {\tt sort()} method to the list of keys). To check
1347whether a single key is in the dictionary, use the \verb/has_key()/
1348method of the dictionary.
1349
1350Here is a small example using a dictionary:
1351
1352\bcode\begin{verbatim}
1353>>> tel = {'jack': 4098, 'sape': 4139}
1354>>> tel['guido'] = 4127
1355>>> tel
Guido van Rossum8f96f771991-11-12 15:45:03 +00001356{'sape': 4139, 'guido': 4127, 'jack': 4098}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001357>>> tel['jack']
13584098
1359>>> del tel['sape']
1360>>> tel['irv'] = 4127
1361>>> tel
Guido van Rossum8f96f771991-11-12 15:45:03 +00001362{'guido': 4127, 'irv': 4127, 'jack': 4098}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001363>>> tel.keys()
1364['guido', 'irv', 'jack']
1365>>> tel.has_key('guido')
13661
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001367>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001368\end{verbatim}\ecode
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001369
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001370\section{More on Conditions}
1371
1372The conditions used in {\tt while} and {\tt if} statements above can
1373contain other operators besides comparisons.
1374
1375The comparison operators {\tt in} and {\tt not in} check whether a value
1376occurs (does not occur) in a sequence. The operators {\tt is} and {\tt
1377is not} compare whether two objects are really the same object; this
1378only matters for mutable objects like lists. All comparison operators
1379have the same priority, which is lower than that of all numerical
1380operators.
1381
Guido van Rossum16cd7f91994-10-06 10:29:26 +00001382Comparisons can be chained: e.g., {\tt a < b == c} tests whether {\tt a}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001383is less than {\tt b} and moreover {\tt b} equals {\tt c}.
1384
1385Comparisons may be combined by the Boolean operators {\tt and} and {\tt
1386or}, and the outcome of a comparison (or of any other Boolean
1387expression) may be negated with {\tt not}. These all have lower
1388priorities than comparison operators again; between them, {\tt not} has
1389the highest priority, and {\tt or} the lowest, so that
1390{\tt A and not B or C} is equivalent to {\tt (A and (not B)) or C}. Of
1391course, parentheses can be used to express the desired composition.
1392
1393The Boolean operators {\tt and} and {\tt or} are so-called {\em
1394shortcut} operators: their arguments are evaluated from left to right,
1395and evaluation stops as soon as the outcome is determined. E.g., if
1396{\tt A} and {\tt C} are true but {\tt B} is false, {\tt A and B and C}
1397does not evaluate the expression C. In general, the return value of a
1398shortcut operator, when used as a general value and not as a Boolean, is
1399the last evaluated argument.
1400
1401It is possible to assign the result of a comparison or other Boolean
Guido van Rossum6938f061994-08-01 12:22:53 +00001402expression to a variable. For example,
1403
1404\bcode\begin{verbatim}
1405>>> string1, string2, string3 = '', 'Trondheim', 'Hammer Dance'
1406>>> non_null = string1 or string2 or string3
1407>>> non_null
1408'Trondheim'
1409>>>
1410\end{verbatim}\ecode
1411%
1412Note that in Python, unlike C, assignment cannot occur inside expressions.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001413
1414\section{Comparing Sequences and Other Types}
1415
1416Sequence objects may be compared to other objects with the same
1417sequence type. The comparison uses {\em lexicographical} ordering:
1418first the first two items are compared, and if they differ this
1419determines the outcome of the comparison; if they are equal, the next
1420two items are compared, and so on, until either sequence is exhausted.
1421If two items to be compared are themselves sequences of the same type,
Guido van Rossum6938f061994-08-01 12:22:53 +00001422the lexicographical comparison is carried out recursively. If all
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001423items of two sequences compare equal, the sequences are considered
1424equal. If one sequence is an initial subsequence of the other, the
1425shorted sequence is the smaller one. Lexicographical ordering for
Guido van Rossum47b4c0f1995-03-15 11:25:32 +00001426strings uses the \ASCII{} ordering for individual characters. Some
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001427examples of comparisons between sequences with the same types:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001428
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001429\bcode\begin{verbatim}
1430(1, 2, 3) < (1, 2, 4)
1431[1, 2, 3] < [1, 2, 4]
1432'ABC' < 'C' < 'Pascal' < 'Python'
1433(1, 2, 3, 4) < (1, 2, 4)
1434(1, 2) < (1, 2, -1)
1435(1, 2, 3) = (1.0, 2.0, 3.0)
1436(1, 2, ('aa', 'ab')) < (1, 2, ('abc', 'a'), 4)
1437\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001438%
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001439Note that comparing objects of different types is legal. The outcome
1440is deterministic but arbitrary: the types are ordered by their name.
1441Thus, a list is always smaller than a string, a string is always
1442smaller than a tuple, etc. Mixed numeric types are compared according
1443to their numeric value, so 0 equals 0.0, etc.%
1444\footnote{
Guido van Rossum6938f061994-08-01 12:22:53 +00001445 The rules for comparing objects of different types should
1446 not be relied upon; they may change in a future version of
1447 the language.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001448}
1449
Guido van Rossum5e0759d1992-08-07 16:06:24 +00001450
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001451\chapter{Modules}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001452
Guido van Rossum4410c751991-06-04 20:22:18 +00001453If you quit from the Python interpreter and enter it again, the
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001454definitions you have made (functions and variables) are lost.
1455Therefore, if you want to write a somewhat longer program, you are
1456better off using a text editor to prepare the input for the interpreter
Guido van Rossum16d6e711994-08-08 12:30:22 +00001457and running it with that file as input instead. This is known as creating a
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001458{\em script}. As your program gets longer, you may want to split it
1459into several files for easier maintenance. You may also want to use a
1460handy function that you've written in several programs without copying
1461its definition into each program.
1462
Guido van Rossum4410c751991-06-04 20:22:18 +00001463To support this, Python has a way to put definitions in a file and use
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001464them in a script or in an interactive instance of the interpreter.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001465Such a file is called a {\em module}; definitions from a module can be
1466{\em imported} into other modules or into the {\em main} module (the
1467collection of variables that you have access to in a script
1468executed at the top level
1469and in calculator mode).
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001470
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001471A module is a file containing Python definitions and statements. The
Guido van Rossum6938f061994-08-01 12:22:53 +00001472file name is the module name with the suffix {\tt .py} appended. Within
1473a module, the module's name (as a string) is available as the value of
1474the global variable {\tt __name__}. For instance, use your favorite text
1475editor to create a file called {\tt fibo.py} in the current directory
1476with the following contents:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001477
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001478\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001479# Fibonacci numbers module
1480
1481def fib(n): # write Fibonacci series up to n
1482 a, b = 0, 1
Guido van Rossum16cd7f91994-10-06 10:29:26 +00001483 while b < n:
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001484 print b,
1485 a, b = b, a+b
1486
1487def fib2(n): # return Fibonacci series up to n
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001488 result = []
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001489 a, b = 0, 1
Guido van Rossum16cd7f91994-10-06 10:29:26 +00001490 while b < n:
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001491 result.append(b)
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001492 a, b = b, a+b
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001493 return result
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001494\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001495%
Guido van Rossum4410c751991-06-04 20:22:18 +00001496Now enter the Python interpreter and import this module with the
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001497following command:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001498
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001499\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001500>>> import fibo
1501>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001502\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001503%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001504This does not enter the names of the functions defined in
1505{\tt fibo}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001506directly in the current symbol table; it only enters the module name
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001507{\tt fibo}
1508there.
1509Using the module name you can access the functions:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001510
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001511\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001512>>> fibo.fib(1000)
15131 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
1514>>> fibo.fib2(100)
1515[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
Guido van Rossum6938f061994-08-01 12:22:53 +00001516>>> fibo.__name__
1517'fibo'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001518>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001519\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001520%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001521If you intend to use a function often you can assign it to a local name:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001522
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001523\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001524>>> fib = fibo.fib
1525>>> fib(500)
15261 1 2 3 5 8 13 21 34 55 89 144 233 377
1527>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001528\end{verbatim}\ecode
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001529
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001530\section{More on Modules}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001531
1532A module can contain executable statements as well as function
1533definitions.
1534These statements are intended to initialize the module.
1535They are executed only the
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001536{\em first}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001537time the module is imported somewhere.%
1538\footnote{
Guido van Rossum6938f061994-08-01 12:22:53 +00001539 In fact function definitions are also `statements' that are
1540 `executed'; the execution enters the function name in the
1541 module's global symbol table.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001542}
1543
1544Each module has its own private symbol table, which is used as the
1545global symbol table by all functions defined in the module.
1546Thus, the author of a module can use global variables in the module
1547without worrying about accidental clashes with a user's global
1548variables.
1549On the other hand, if you know what you are doing you can touch a
1550module's global variables with the same notation used to refer to its
1551functions,
1552{\tt modname.itemname}.
1553
1554Modules can import other modules.
1555It is customary but not required to place all
1556{\tt import}
1557statements at the beginning of a module (or script, for that matter).
1558The imported module names are placed in the importing module's global
1559symbol table.
1560
1561There is a variant of the
1562{\tt import}
1563statement that imports names from a module directly into the importing
1564module's symbol table.
1565For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001566
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001567\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001568>>> from fibo import fib, fib2
1569>>> fib(500)
15701 1 2 3 5 8 13 21 34 55 89 144 233 377
1571>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001572\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001573%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001574This does not introduce the module name from which the imports are taken
1575in the local symbol table (so in the example, {\tt fibo} is not
1576defined).
1577
1578There is even a variant to import all names that a module defines:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001579
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001580\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001581>>> from fibo import *
1582>>> fib(500)
15831 1 2 3 5 8 13 21 34 55 89 144 233 377
1584>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001585\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001586%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001587This imports all names except those beginning with an underscore
Guido van Rossum573805a1992-03-06 10:56:03 +00001588({\tt _}).
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001589
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001590\section{Standard Modules}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001591
Guido van Rossum4410c751991-06-04 20:22:18 +00001592Python comes with a library of standard modules, described in a separate
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001593document (Python Library Reference). Some modules are built into the
1594interpreter; these provide access to operations that are not part of the
1595core of the language but are nevertheless built in, either for
1596efficiency or to provide access to operating system primitives such as
1597system calls. The set of such modules is a configuration option; e.g.,
1598the {\tt amoeba} module is only provided on systems that somehow support
1599Amoeba primitives. One particular module deserves some attention: {\tt
1600sys}, which is built into every Python interpreter. The variables {\tt
1601sys.ps1} and {\tt sys.ps2} define the strings used as primary and
1602secondary prompts:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001603
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001604\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001605>>> import sys
1606>>> sys.ps1
1607'>>> '
1608>>> sys.ps2
1609'... '
1610>>> sys.ps1 = 'C> '
1611C> print 'Yuck!'
1612Yuck!
1613C>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001614\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001615%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001616These two variables are only defined if the interpreter is in
1617interactive mode.
1618
1619The variable
1620{\tt sys.path}
1621is a list of strings that determine the interpreter's search path for
1622modules.
1623It is initialized to a default path taken from the environment variable
1624{\tt PYTHONPATH},
1625or from a built-in default if
1626{\tt PYTHONPATH}
1627is not set.
1628You can modify it using standard list operations, e.g.:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001629
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001630\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001631>>> import sys
1632>>> sys.path.append('/ufs/guido/lib/python')
1633>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001634\end{verbatim}\ecode
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001635
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001636\section{The {\tt dir()} function}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001637
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001638The built-in function {\tt dir} is used to find out which names a module
1639defines. It returns a sorted list of strings:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001640
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001641\bcode\begin{verbatim}
1642>>> import fibo, sys
1643>>> dir(fibo)
Guido van Rossum6938f061994-08-01 12:22:53 +00001644['__name__', 'fib', 'fib2']
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001645>>> dir(sys)
Guido van Rossum6938f061994-08-01 12:22:53 +00001646['__name__', 'argv', 'builtin_module_names', 'copyright', 'exit',
1647'maxint', 'modules', 'path', 'ps1', 'ps2', 'setprofile', 'settrace',
1648'stderr', 'stdin', 'stdout', 'version']
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001649>>>
1650\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001651%
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001652Without arguments, {\tt dir()} lists the names you have defined currently:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001653
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001654\bcode\begin{verbatim}
1655>>> a = [1, 2, 3, 4, 5]
1656>>> import fibo, sys
1657>>> fib = fibo.fib
1658>>> dir()
Guido van Rossum6938f061994-08-01 12:22:53 +00001659['__name__', 'a', 'fib', 'fibo', 'sys']
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001660>>>
1661\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001662%
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001663Note that it lists all types of names: variables, modules, functions, etc.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001664
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001665{\tt dir()} does not list the names of built-in functions and variables.
1666If you want a list of those, they are defined in the standard module
Guido van Rossum4bd023f1993-10-27 13:49:20 +00001667{\tt __builtin__}:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001668
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001669\bcode\begin{verbatim}
Guido van Rossum4bd023f1993-10-27 13:49:20 +00001670>>> import __builtin__
1671>>> dir(__builtin__)
Guido van Rossum6938f061994-08-01 12:22:53 +00001672['AccessError', 'AttributeError', 'ConflictError', 'EOFError', 'IOError',
1673'ImportError', 'IndexError', 'KeyError', 'KeyboardInterrupt',
1674'MemoryError', 'NameError', 'None', 'OverflowError', 'RuntimeError',
1675'SyntaxError', 'SystemError', 'SystemExit', 'TypeError', 'ValueError',
1676'ZeroDivisionError', '__name__', 'abs', 'apply', 'chr', 'cmp', 'coerce',
1677'compile', 'dir', 'divmod', 'eval', 'execfile', 'filter', 'float',
1678'getattr', 'hasattr', 'hash', 'hex', 'id', 'input', 'int', 'len', 'long',
1679'map', 'max', 'min', 'oct', 'open', 'ord', 'pow', 'range', 'raw_input',
1680'reduce', 'reload', 'repr', 'round', 'setattr', 'str', 'type', 'xrange']
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001681>>>
1682\end{verbatim}\ecode
1683
Guido van Rossum5e0759d1992-08-07 16:06:24 +00001684
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001685\chapter{Output Formatting}
1686
1687So far we've encountered two ways of writing values: {\em expression
1688statements} and the {\tt print} statement. (A third way is using the
1689{\tt write} method of file objects; the standard output file can be
1690referenced as {\tt sys.stdout}. See the Library Reference for more
1691information on this.)
1692
1693Often you'll want more control over the formatting of your output than
1694simply printing space-separated values. The key to nice formatting in
1695Python is to do all the string handling yourself; using string slicing
1696and concatenation operations you can create any lay-out you can imagine.
1697The standard module {\tt string} contains some useful operations for
1698padding strings to a given column width; these will be discussed shortly.
Guido van Rossum6938f061994-08-01 12:22:53 +00001699Finally, the \code{\%} operator (modulo) with a string left argument
1700interprets this string as a C sprintf format string to be applied to the
1701right argument, and returns the string resulting from this formatting
1702operation.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001703
1704One question remains, of course: how do you convert values to strings?
1705Luckily, Python has a way to convert any value to a string: just write
1706the value between reverse quotes (\verb/``/). Some examples:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001707
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001708\bcode\begin{verbatim}
1709>>> x = 10 * 3.14
1710>>> y = 200*200
1711>>> s = 'The value of x is ' + `x` + ', and y is ' + `y` + '...'
1712>>> print s
1713The value of x is 31.4, and y is 40000...
1714>>> # Reverse quotes work on other types besides numbers:
Guido van Rossum6938f061994-08-01 12:22:53 +00001715... p = [x, y]
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001716>>> ps = `p`
1717>>> ps
1718'[31.4, 40000]'
1719>>> # Converting a string adds string quotes and backslashes:
Guido van Rossum6938f061994-08-01 12:22:53 +00001720... hello = 'hello, world\n'
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001721>>> hellos = `hello`
1722>>> print hellos
1723'hello, world\012'
1724>>> # The argument of reverse quotes may be a tuple:
Guido van Rossume5f8b601995-01-04 19:12:49 +00001725... `x, y, ('spam', 'eggs')`
1726"(31.4, 40000, ('spam', 'eggs'))"
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001727>>>
1728\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001729%
Guido van Rossum6938f061994-08-01 12:22:53 +00001730Here are two ways to write a table of squares and cubes:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001731
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001732\bcode\begin{verbatim}
1733>>> import string
1734>>> for x in range(1, 11):
1735... print string.rjust(`x`, 2), string.rjust(`x*x`, 3),
1736... # Note trailing comma on previous line
1737... print string.rjust(`x*x*x`, 4)
1738...
1739 1 1 1
1740 2 4 8
1741 3 9 27
1742 4 16 64
1743 5 25 125
1744 6 36 216
1745 7 49 343
1746 8 64 512
1747 9 81 729
174810 100 1000
Guido van Rossum6938f061994-08-01 12:22:53 +00001749>>> for x in range(1,11):
1750... print '%2d %3d %4d' % (x, x*x, x*x*x)
1751...
1752 1 1 1
1753 2 4 8
1754 3 9 27
1755 4 16 64
1756 5 25 125
1757 6 36 216
1758 7 49 343
1759 8 64 512
1760 9 81 729
176110 100 1000
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001762>>>
1763\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001764%
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001765(Note that one space between each column was added by the way {\tt print}
1766works: it always adds spaces between its arguments.)
1767
1768This example demonstrates the function {\tt string.rjust()}, which
1769right-justifies a string in a field of a given width by padding it with
1770spaces on the left. There are similar functions {\tt string.ljust()}
1771and {\tt string.center()}. These functions do not write anything, they
1772just return a new string. If the input string is too long, they don't
1773truncate it, but return it unchanged; this will mess up your column
1774lay-out but that's usually better than the alternative, which would be
1775lying about a value. (If you really want truncation you can always add
1776a slice operation, as in {\tt string.ljust(x,~n)[0:n]}.)
1777
1778There is another function, {\tt string.zfill}, which pads a numeric
1779string on the left with zeros. It understands about plus and minus
Guido van Rossum6938f061994-08-01 12:22:53 +00001780signs:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001781
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001782\bcode\begin{verbatim}
1783>>> string.zfill('12', 5)
1784'00012'
1785>>> string.zfill('-3.14', 7)
1786'-003.14'
1787>>> string.zfill('3.14159265359', 5)
1788'3.14159265359'
1789>>>
1790\end{verbatim}\ecode
1791
Guido van Rossum5e0759d1992-08-07 16:06:24 +00001792
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001793\chapter{Errors and Exceptions}
1794
1795Until now error messages haven't been more than mentioned, but if you
1796have tried out the examples you have probably seen some. There are
1797(at least) two distinguishable kinds of errors: {\em syntax\ errors}
1798and {\em exceptions}.
1799
1800\section{Syntax Errors}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001801
1802Syntax errors, also known as parsing errors, are perhaps the most common
Guido van Rossum4410c751991-06-04 20:22:18 +00001803kind of complaint you get while you are still learning Python:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001804
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001805\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001806>>> while 1 print 'Hello world'
Guido van Rossum6938f061994-08-01 12:22:53 +00001807 File "<stdin>", line 1
1808 while 1 print 'Hello world'
1809 ^
1810SyntaxError: invalid syntax
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001811>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001812\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001813%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001814The parser repeats the offending line and displays a little `arrow'
1815pointing at the earliest point in the line where the error was detected.
1816The error is caused by (or at least detected at) the token
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001817{\em preceding}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001818the arrow: in the example, the error is detected at the keyword
1819{\tt print}, since a colon ({\tt :}) is missing before it.
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001820File name and line number are printed so you know where to look in case
1821the input came from a script.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001822
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001823\section{Exceptions}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001824
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001825Even if a statement or expression is syntactically correct, it may
1826cause an error when an attempt is made to execute it.
1827Errors detected during execution are called {\em exceptions} and are
1828not unconditionally fatal: you will soon learn how to handle them in
1829Python programs. Most exceptions are not handled by programs,
1830however, and result in error messages as shown here:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001831
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001832\bcode\small\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001833>>> 10 * (1/0)
Guido van Rossum3cbc16d1993-12-17 12:13:53 +00001834Traceback (innermost last):
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001835 File "<stdin>", line 1
Guido van Rossumb2c65561993-05-12 08:53:36 +00001836ZeroDivisionError: integer division or modulo
Guido van Rossume5f8b601995-01-04 19:12:49 +00001837>>> 4 + spam*3
Guido van Rossum6938f061994-08-01 12:22:53 +00001838Traceback (innermost last):
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001839 File "<stdin>", line 1
Guido van Rossume5f8b601995-01-04 19:12:49 +00001840NameError: spam
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001841>>> '2' + 2
Guido van Rossum6938f061994-08-01 12:22:53 +00001842Traceback (innermost last):
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001843 File "<stdin>", line 1
Guido van Rossumb2c65561993-05-12 08:53:36 +00001844TypeError: illegal argument type for built-in operation
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001845>>>
Fred Drakefd255e41996-10-29 15:50:05 +00001846\end{verbatim}\normalsize\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001847%
Guido van Rossumb2c65561993-05-12 08:53:36 +00001848The last line of the error message indicates what happened.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001849Exceptions come in different types, and the type is printed as part of
1850the message: the types in the example are
Guido van Rossumb2c65561993-05-12 08:53:36 +00001851{\tt ZeroDivisionError},
1852{\tt NameError}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001853and
Guido van Rossumb2c65561993-05-12 08:53:36 +00001854{\tt TypeError}.
1855The string printed as the exception type is the name of the built-in
1856name for the exception that occurred. This is true for all built-in
1857exceptions, but need not be true for user-defined exceptions (although
1858it is a useful convention).
1859Standard exception names are built-in identifiers (not reserved
1860keywords).
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001861
Guido van Rossumb2c65561993-05-12 08:53:36 +00001862The rest of the line is a detail whose interpretation depends on the
1863exception type; its meaning is dependent on the exception type.
1864
1865The preceding part of the error message shows the context where the
1866exception happened, in the form of a stack backtrace.
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001867In general it contains a stack backtrace listing source lines; however,
1868it will not display lines read from standard input.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001869
Guido van Rossum6a05f951996-10-22 19:27:46 +00001870The Python Library Reference Manual lists the built-in exceptions and
Guido van Rossumb2c65561993-05-12 08:53:36 +00001871their meanings.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001872
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001873\section{Handling Exceptions}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001874
1875It is possible to write programs that handle selected exceptions.
1876Look at the following example, which prints a table of inverses of
1877some floating point numbers:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001878
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001879\bcode\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001880>>> numbers = [0.3333, 2.5, 0, 10]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001881>>> for x in numbers:
1882... print x,
1883... try:
1884... print 1.0 / x
Guido van Rossumb2c65561993-05-12 08:53:36 +00001885... except ZeroDivisionError:
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001886... print '*** has no inverse ***'
1887...
18880.3333 3.00030003
18892.5 0.4
18900 *** has no inverse ***
189110 0.1
1892>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001893\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001894%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001895The {\tt try} statement works as follows.
1896\begin{itemize}
1897\item
1898First, the
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001899{\em try\ clause}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001900(the statement(s) between the {\tt try} and {\tt except} keywords) is
1901executed.
1902\item
1903If no exception occurs, the
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001904{\em except\ clause}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001905is skipped and execution of the {\tt try} statement is finished.
1906\item
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001907If an exception occurs during execution of the try clause,
1908the rest of the clause is skipped. Then if
1909its type matches the exception named after the {\tt except} keyword,
1910the rest of the try clause is skipped, the except clause is executed,
1911and then execution continues after the {\tt try} statement.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001912\item
1913If an exception occurs which does not match the exception named in the
1914except clause, it is passed on to outer try statements; if no handler is
1915found, it is an
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001916{\em unhandled\ exception}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001917and execution stops with a message as shown above.
1918\end{itemize}
1919A {\tt try} statement may have more than one except clause, to specify
1920handlers for different exceptions.
1921At most one handler will be executed.
1922Handlers only handle exceptions that occur in the corresponding try
1923clause, not in other handlers of the same {\tt try} statement.
1924An except clause may name multiple exceptions as a parenthesized list,
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001925e.g.:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001926
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001927\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001928... except (RuntimeError, TypeError, NameError):
1929... pass
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001930\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001931%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001932The last except clause may omit the exception name(s), to serve as a
1933wildcard.
Guido van Rossumb2c65561993-05-12 08:53:36 +00001934Use this with extreme caution, since it is easy to mask a real
1935programming error in this way!
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001936
1937When an exception occurs, it may have an associated value, also known as
1938the exceptions's
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001939{\em argument}.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001940The presence and type of the argument depend on the exception type.
1941For exception types which have an argument, the except clause may
1942specify a variable after the exception name (or list) to receive the
1943argument's value, as follows:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001944
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001945\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001946>>> try:
Guido van Rossume5f8b601995-01-04 19:12:49 +00001947... spam()
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001948... except NameError, x:
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001949... print 'name', x, 'undefined'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001950...
Guido van Rossume5f8b601995-01-04 19:12:49 +00001951name spam undefined
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001952>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001953\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001954%
Guido van Rossumb2c65561993-05-12 08:53:36 +00001955If an exception has an argument, it is printed as the last part
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001956(`detail') of the message for unhandled exceptions.
1957
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001958Exception handlers don't just handle exceptions if they occur
1959immediately in the try clause, but also if they occur inside functions
1960that are called (even indirectly) in the try clause.
1961For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001962
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001963\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001964>>> def this_fails():
1965... x = 1/0
1966...
1967>>> try:
1968... this_fails()
Guido van Rossumb2c65561993-05-12 08:53:36 +00001969... except ZeroDivisionError, detail:
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001970... print 'Handling run-time error:', detail
1971...
Guido van Rossumb2c65561993-05-12 08:53:36 +00001972Handling run-time error: integer division or modulo
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001973>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001974\end{verbatim}\ecode
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001975
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001976\section{Raising Exceptions}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001977
1978The {\tt raise} statement allows the programmer to force a specified
1979exception to occur.
1980For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001981
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001982\bcode\begin{verbatim}
Guido van Rossumb2c65561993-05-12 08:53:36 +00001983>>> raise NameError, 'HiThere'
Guido van Rossum6938f061994-08-01 12:22:53 +00001984Traceback (innermost last):
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001985 File "<stdin>", line 1
Guido van Rossumb2c65561993-05-12 08:53:36 +00001986NameError: HiThere
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001987>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001988\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001989%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001990The first argument to {\tt raise} names the exception to be raised.
1991The optional second argument specifies the exception's argument.
1992
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001993\section{User-defined Exceptions}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001994
1995Programs may name their own exceptions by assigning a string to a
1996variable.
1997For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001998
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001999\bcode\begin{verbatim}
Guido van Rossumb2c65561993-05-12 08:53:36 +00002000>>> my_exc = 'my_exc'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002001>>> try:
2002... raise my_exc, 2*2
2003... except my_exc, val:
Guido van Rossum67fa1601991-04-23 14:14:57 +00002004... print 'My exception occurred, value:', val
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002005...
Guido van Rossum6938f061994-08-01 12:22:53 +00002006My exception occurred, value: 4
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002007>>> raise my_exc, 1
Guido van Rossum6938f061994-08-01 12:22:53 +00002008Traceback (innermost last):
2009 File "<stdin>", line 1
Guido van Rossumb2c65561993-05-12 08:53:36 +00002010my_exc: 1
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002011>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00002012\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002013%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002014Many standard modules use this to report errors that may occur in
2015functions they define.
2016
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002017\section{Defining Clean-up Actions}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002018
2019The {\tt try} statement has another optional clause which is intended to
2020define clean-up actions that must be executed under all circumstances.
2021For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002022
Guido van Rossum5ce78f11991-01-25 13:27:18 +00002023\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002024>>> try:
2025... raise KeyboardInterrupt
2026... finally:
2027... print 'Goodbye, world!'
2028...
2029Goodbye, world!
Guido van Rossum6938f061994-08-01 12:22:53 +00002030Traceback (innermost last):
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002031 File "<stdin>", line 2
Guido van Rossumb2c65561993-05-12 08:53:36 +00002032KeyboardInterrupt
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002033>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00002034\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002035%
Guido van Rossumda8c3fd1992-08-09 13:55:25 +00002036A {\tt finally} clause is executed whether or not an exception has
2037occurred in the {\tt try} clause. When an exception has occurred, it
Guido van Rossum6938f061994-08-01 12:22:53 +00002038is re-raised after the {\tt finally} clause is executed. The
Guido van Rossumda8c3fd1992-08-09 13:55:25 +00002039{\tt finally} clause is also executed ``on the way out'' when the
2040{\tt try} statement is left via a {\tt break} or {\tt return}
2041statement.
2042
2043A {\tt try} statement must either have one or more {\tt except}
2044clauses or one {\tt finally} clause, but not both.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002045
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002046
2047\chapter{Classes}
2048
2049Python's class mechanism adds classes to the language with a minimum
2050of new syntax and semantics. It is a mixture of the class mechanisms
Guido van Rossum16d6e711994-08-08 12:30:22 +00002051found in \Cpp{} and Modula-3. As is true for modules, classes in Python
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002052do not put an absolute barrier between definition and user, but rather
2053rely on the politeness of the user not to ``break into the
2054definition.'' The most important features of classes are retained
2055with full power, however: the class inheritance mechanism allows
2056multiple base classes, a derived class can override any methods of its
2057base class(es), a method can call the method of a base class with the
2058same name. Objects can contain an arbitrary amount of private data.
2059
Guido van Rossum16d6e711994-08-08 12:30:22 +00002060In \Cpp{} terminology, all class members (including the data members) are
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002061{\em public}, and all member functions are {\em virtual}. There are
Guido van Rossum6938f061994-08-01 12:22:53 +00002062no special constructors or destructors. As in Modula-3, there are no
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002063shorthands for referencing the object's members from its methods: the
2064method function is declared with an explicit first argument
2065representing the object, which is provided implicitly by the call. As
2066in Smalltalk, classes themselves are objects, albeit in the wider
2067sense of the word: in Python, all data types are objects. This
Guido van Rossum16d6e711994-08-08 12:30:22 +00002068provides semantics for importing and renaming. But, just like in \Cpp{}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002069or Modula-3, built-in types cannot be used as base classes for
Guido van Rossum16d6e711994-08-08 12:30:22 +00002070extension by the user. Also, like in \Cpp{} but unlike in Modula-3, most
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002071built-in operators with special syntax (arithmetic operators,
Guido van Rossum6938f061994-08-01 12:22:53 +00002072subscripting etc.) can be redefined for class members.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002073
2074
2075\section{A word about terminology}
2076
2077Lacking universally accepted terminology to talk about classes, I'll
Guido van Rossum16d6e711994-08-08 12:30:22 +00002078make occasional use of Smalltalk and \Cpp{} terms. (I'd use Modula-3
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002079terms, since its object-oriented semantics are closer to those of
Guido van Rossum16d6e711994-08-08 12:30:22 +00002080Python than \Cpp{}, but I expect that few readers have heard of it...)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002081
2082I also have to warn you that there's a terminological pitfall for
2083object-oriented readers: the word ``object'' in Python does not
Guido van Rossum16d6e711994-08-08 12:30:22 +00002084necessarily mean a class instance. Like \Cpp{} and Modula-3, and unlike
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002085Smalltalk, not all types in Python are classes: the basic built-in
2086types like integers and lists aren't, and even somewhat more exotic
2087types like files aren't. However, {\em all} Python types share a little
2088bit of common semantics that is best described by using the word
2089object.
2090
2091Objects have individuality, and multiple names (in multiple scopes)
2092can be bound to the same object. This is known as aliasing in other
2093languages. This is usually not appreciated on a first glance at
2094Python, and can be safely ignored when dealing with immutable basic
2095types (numbers, strings, tuples). However, aliasing has an
Guido van Rossum6938f061994-08-01 12:22:53 +00002096(intended!) effect on the semantics of Python code involving mutable
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002097objects such as lists, dictionaries, and most types representing
2098entities outside the program (files, windows, etc.). This is usually
2099used to the benefit of the program, since aliases behave like pointers
2100in some respects. For example, passing an object is cheap since only
2101a pointer is passed by the implementation; and if a function modifies
2102an object passed as an argument, the caller will see the change --- this
2103obviates the need for two different argument passing mechanisms as in
2104Pascal.
2105
2106
2107\section{Python scopes and name spaces}
2108
2109Before introducing classes, I first have to tell you something about
2110Python's scope rules. Class definitions play some neat tricks with
2111name spaces, and you need to know how scopes and name spaces work to
2112fully understand what's going on. Incidentally, knowledge about this
2113subject is useful for any advanced Python programmer.
2114
2115Let's begin with some definitions.
2116
2117A {\em name space} is a mapping from names to objects. Most name
2118spaces are currently implemented as Python dictionaries, but that's
2119normally not noticeable in any way (except for performance), and it
2120may change in the future. Examples of name spaces are: the set of
2121built-in names (functions such as \verb\abs()\, and built-in exception
2122names); the global names in a module; and the local names in a
2123function invocation. In a sense the set of attributes of an object
Guido van Rossum16cd7f91994-10-06 10:29:26 +00002124also form a name space. The important thing to know about name
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002125spaces is that there is absolutely no relation between names in
2126different name spaces; for instance, two different modules may both
2127define a function ``maximize'' without confusion --- users of the
2128modules must prefix it with the module name.
2129
2130By the way, I use the word {\em attribute} for any name following a
2131dot --- for example, in the expression \verb\z.real\, \verb\real\ is
2132an attribute of the object \verb\z\. Strictly speaking, references to
2133names in modules are attribute references: in the expression
2134\verb\modname.funcname\, \verb\modname\ is a module object and
2135\verb\funcname\ is an attribute of it. In this case there happens to
2136be a straightforward mapping between the module's attributes and the
2137global names defined in the module: they share the same name space!%
2138\footnote{
Guido van Rossum6938f061994-08-01 12:22:53 +00002139 Except for one thing. Module objects have a secret read-only
2140 attribute called {\tt __dict__} which returns the dictionary
2141 used to implement the module's name space; the name
2142 {\tt __dict__} is an attribute but not a global name.
2143 Obviously, using this violates the abstraction of name space
2144 implementation, and should be restricted to things like
2145 post-mortem debuggers...
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002146}
2147
2148Attributes may be read-only or writable. In the latter case,
2149assignment to attributes is possible. Module attributes are writable:
2150you can write \verb\modname.the_answer = 42\. Writable attributes may
2151also be deleted with the del statement, e.g.
2152\verb\del modname.the_answer\.
2153
2154Name spaces are created at different moments and have different
2155lifetimes. The name space containing the built-in names is created
2156when the Python interpreter starts up, and is never deleted. The
2157global name space for a module is created when the module definition
2158is read in; normally, module name spaces also last until the
2159interpreter quits. The statements executed by the top-level
2160invocation of the interpreter, either read from a script file or
2161interactively, are considered part of a module called \verb\__main__\,
2162so they have their own global name space. (The built-in names
Guido van Rossum4bd023f1993-10-27 13:49:20 +00002163actually also live in a module; this is called \verb\__builtin__\.)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002164
2165The local name space for a function is created when the function is
2166called, and deleted when the function returns or raises an exception
2167that is not handled within the function. (Actually, forgetting would
2168be a better way to describe what actually happens.) Of course,
2169recursive invocations each have their own local name space.
2170
2171A {\em scope} is a textual region of a Python program where a name space
2172is directly accessible. ``Directly accessible'' here means that an
2173unqualified reference to a name attempts to find the name in the name
2174space.
2175
2176Although scopes are determined statically, they are used dynamically.
2177At any time during execution, exactly three nested scopes are in use
2178(i.e., exactly three name spaces are directly accessible): the
2179innermost scope, which is searched first, contains the local names,
2180the middle scope, searched next, contains the current module's global
2181names, and the outermost scope (searched last) is the name space
2182containing built-in names.
2183
2184Usually, the local scope references the local names of the (textually)
Guido van Rossum96628a91995-04-10 11:34:00 +00002185current function. Outside of functions, the local scope references
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002186the same name space as the global scope: the module's name space.
2187Class definitions place yet another name space in the local scope.
2188
2189It is important to realize that scopes are determined textually: the
2190global scope of a function defined in a module is that module's name
2191space, no matter from where or by what alias the function is called.
2192On the other hand, the actual search for names is done dynamically, at
Guido van Rossum96628a91995-04-10 11:34:00 +00002193run time --- however, the language definition is evolving towards
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002194static name resolution, at ``compile'' time, so don't rely on dynamic
2195name resolution! (In fact, local variables are already determined
2196statically.)
2197
2198A special quirk of Python is that assignments always go into the
2199innermost scope. Assignments do not copy data --- they just
2200bind names to objects. The same is true for deletions: the statement
2201\verb\del x\ removes the binding of x from the name space referenced by the
2202local scope. In fact, all operations that introduce new names use the
2203local scope: in particular, import statements and function definitions
2204bind the module or function name in the local scope. (The
2205\verb\global\ statement can be used to indicate that particular
2206variables live in the global scope.)
2207
2208
2209\section{A first look at classes}
2210
2211Classes introduce a little bit of new syntax, three new object types,
2212and some new semantics.
2213
2214
2215\subsection{Class definition syntax}
2216
2217The simplest form of class definition looks like this:
2218
2219\begin{verbatim}
2220 class ClassName:
2221 <statement-1>
2222 .
2223 .
2224 .
2225 <statement-N>
2226\end{verbatim}
2227
2228Class definitions, like function definitions (\verb\def\ statements)
2229must be executed before they have any effect. (You could conceivably
2230place a class definition in a branch of an \verb\if\ statement, or
2231inside a function.)
2232
2233In practice, the statements inside a class definition will usually be
2234function definitions, but other statements are allowed, and sometimes
2235useful --- we'll come back to this later. The function definitions
2236inside a class normally have a peculiar form of argument list,
2237dictated by the calling conventions for methods --- again, this is
2238explained later.
2239
2240When a class definition is entered, a new name space is created, and
2241used as the local scope --- thus, all assignments to local variables
2242go into this new name space. In particular, function definitions bind
2243the name of the new function here.
2244
2245When a class definition is left normally (via the end), a {\em class
2246object} is created. This is basically a wrapper around the contents
2247of the name space created by the class definition; we'll learn more
2248about class objects in the next section. The original local scope
2249(the one in effect just before the class definitions was entered) is
2250reinstated, and the class object is bound here to class name given in
2251the class definition header (ClassName in the example).
2252
2253
2254\subsection{Class objects}
2255
2256Class objects support two kinds of operations: attribute references
2257and instantiation.
2258
2259{\em Attribute references} use the standard syntax used for all
2260attribute references in Python: \verb\obj.name\. Valid attribute
2261names are all the names that were in the class's name space when the
2262class object was created. So, if the class definition looked like
2263this:
2264
2265\begin{verbatim}
2266 class MyClass:
2267 i = 12345
2268 def f(x):
2269 return 'hello world'
2270\end{verbatim}
2271
2272then \verb\MyClass.i\ and \verb\MyClass.f\ are valid attribute
2273references, returning an integer and a function object, respectively.
2274Class attributes can also be assigned to, so you can change the
2275value of \verb\MyClass.i\ by assignment.
2276
2277Class {\em instantiation} uses function notation. Just pretend that
2278the class object is a parameterless function that returns a new
2279instance of the class. For example, (assuming the above class):
2280
2281\begin{verbatim}
2282 x = MyClass()
2283\end{verbatim}
2284
2285creates a new {\em instance} of the class and assigns this object to
2286the local variable \verb\x\.
2287
2288
2289\subsection{Instance objects}
2290
2291Now what can we do with instance objects? The only operations
2292understood by instance objects are attribute references. There are
2293two kinds of valid attribute names.
2294
2295The first I'll call {\em data attributes}. These correspond to
Guido van Rossum16d6e711994-08-08 12:30:22 +00002296``instance variables'' in Smalltalk, and to ``data members'' in \Cpp{}.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002297Data attributes need not be declared; like local variables, they
2298spring into existence when they are first assigned to. For example,
2299if \verb\x\ in the instance of \verb\MyClass\ created above, the
2300following piece of code will print the value 16, without leaving a
2301trace:
2302
2303\begin{verbatim}
2304 x.counter = 1
2305 while x.counter < 10:
2306 x.counter = x.counter * 2
2307 print x.counter
2308 del x.counter
2309\end{verbatim}
2310
2311The second kind of attribute references understood by instance objects
2312are {\em methods}. A method is a function that ``belongs to'' an
2313object. (In Python, the term method is not unique to class instances:
2314other object types can have methods as well, e.g., list objects have
2315methods called append, insert, remove, sort, and so on. However,
2316below, we'll use the term method exclusively to mean methods of class
2317instance objects, unless explicitly stated otherwise.)
2318
2319Valid method names of an instance object depend on its class. By
2320definition, all attributes of a class that are (user-defined) function
2321objects define corresponding methods of its instances. So in our
2322example, \verb\x.f\ is a valid method reference, since
2323\verb\MyClass.f\ is a function, but \verb\x.i\ is not, since
2324\verb\MyClass.i\ is not. But \verb\x.f\ is not the
2325same thing as \verb\MyClass.f\ --- it is a {\em method object}, not a
2326function object.
2327
2328
2329\subsection{Method objects}
2330
2331Usually, a method is called immediately, e.g.:
2332
2333\begin{verbatim}
2334 x.f()
2335\end{verbatim}
2336
2337In our example, this will return the string \verb\'hello world'\.
2338However, it is not necessary to call a method right away: \verb\x.f\
2339is a method object, and can be stored away and called at a later
2340moment, for example:
2341
2342\begin{verbatim}
2343 xf = x.f
2344 while 1:
2345 print xf()
2346\end{verbatim}
2347
2348will continue to print \verb\hello world\ until the end of time.
2349
2350What exactly happens when a method is called? You may have noticed
2351that \verb\x.f()\ was called without an argument above, even though
2352the function definition for \verb\f\ specified an argument. What
2353happened to the argument? Surely Python raises an exception when a
2354function that requires an argument is called without any --- even if
2355the argument isn't actually used...
2356
2357Actually, you may have guessed the answer: the special thing about
2358methods is that the object is passed as the first argument of the
2359function. In our example, the call \verb\x.f()\ is exactly equivalent
2360to \verb\MyClass.f(x)\. In general, calling a method with a list of
2361{\em n} arguments is equivalent to calling the corresponding function
2362with an argument list that is created by inserting the method's object
2363before the first argument.
2364
2365If you still don't understand how methods work, a look at the
2366implementation can perhaps clarify matters. When an instance
2367attribute is referenced that isn't a data attribute, its class is
2368searched. If the name denotes a valid class attribute that is a
2369function object, a method object is created by packing (pointers to)
2370the instance object and the function object just found together in an
2371abstract object: this is the method object. When the method object is
2372called with an argument list, it is unpacked again, a new argument
2373list is constructed from the instance object and the original argument
2374list, and the function object is called with this new argument list.
2375
2376
2377\section{Random remarks}
2378
2379
2380[These should perhaps be placed more carefully...]
2381
2382
2383Data attributes override method attributes with the same name; to
2384avoid accidental name conflicts, which may cause hard-to-find bugs in
2385large programs, it is wise to use some kind of convention that
2386minimizes the chance of conflicts, e.g., capitalize method names,
2387prefix data attribute names with a small unique string (perhaps just
Guido van Rossum6938f061994-08-01 12:22:53 +00002388an underscore), or use verbs for methods and nouns for data attributes.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002389
2390
2391Data attributes may be referenced by methods as well as by ordinary
2392users (``clients'') of an object. In other words, classes are not
2393usable to implement pure abstract data types. In fact, nothing in
2394Python makes it possible to enforce data hiding --- it is all based
2395upon convention. (On the other hand, the Python implementation,
2396written in C, can completely hide implementation details and control
2397access to an object if necessary; this can be used by extensions to
2398Python written in C.)
2399
2400
2401Clients should use data attributes with care --- clients may mess up
2402invariants maintained by the methods by stamping on their data
2403attributes. Note that clients may add data attributes of their own to
2404an instance object without affecting the validity of the methods, as
2405long as name conflicts are avoided --- again, a naming convention can
2406save a lot of headaches here.
2407
2408
2409There is no shorthand for referencing data attributes (or other
2410methods!) from within methods. I find that this actually increases
2411the readability of methods: there is no chance of confusing local
2412variables and instance variables when glancing through a method.
2413
2414
2415Conventionally, the first argument of methods is often called
2416\verb\self\. This is nothing more than a convention: the name
2417\verb\self\ has absolutely no special meaning to Python. (Note,
2418however, that by not following the convention your code may be less
2419readable by other Python programmers, and it is also conceivable that
2420a {\em class browser} program be written which relies upon such a
2421convention.)
2422
2423
2424Any function object that is a class attribute defines a method for
2425instances of that class. It is not necessary that the function
2426definition is textually enclosed in the class definition: assigning a
2427function object to a local variable in the class is also ok. For
2428example:
2429
2430\begin{verbatim}
2431 # Function defined outside the class
2432 def f1(self, x, y):
2433 return min(x, x+y)
2434
2435 class C:
2436 f = f1
2437 def g(self):
2438 return 'hello world'
2439 h = g
2440\end{verbatim}
2441
2442Now \verb\f\, \verb\g\ and \verb\h\ are all attributes of class
2443\verb\C\ that refer to function objects, and consequently they are all
2444methods of instances of \verb\C\ --- \verb\h\ being exactly equivalent
2445to \verb\g\. Note that this practice usually only serves to confuse
2446the reader of a program.
2447
2448
2449Methods may call other methods by using method attributes of the
2450\verb\self\ argument, e.g.:
2451
2452\begin{verbatim}
2453 class Bag:
2454 def empty(self):
2455 self.data = []
2456 def add(self, x):
2457 self.data.append(x)
2458 def addtwice(self, x):
Guido van Rossum084b0b21992-08-14 09:19:56 +00002459 self.add(x)
2460 self.add(x)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002461\end{verbatim}
2462
2463
2464The instantiation operation (``calling'' a class object) creates an
2465empty object. Many classes like to create objects in a known initial
Guido van Rossumca3f6c81994-10-06 14:08:53 +00002466state. Therefore a class may define a special method named
2467\verb\__init__\, like this:
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002468
Guido van Rossum6938f061994-08-01 12:22:53 +00002469\begin{verbatim}
2470 def __init__(self):
2471 self.empty()
2472\end{verbatim}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002473
Guido van Rossum6938f061994-08-01 12:22:53 +00002474When a class defines an \verb\__init__\ method, class instantiation
2475automatically invokes \verb\__init__\ for the newly-created class
2476instance. So in the \verb\Bag\ example, a new and initialized instance
2477can be obtained by:
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002478
Guido van Rossum6938f061994-08-01 12:22:53 +00002479\begin{verbatim}
2480 x = Bag()
2481\end{verbatim}
2482
2483Of course, the \verb\__init__\ method may have arguments for greater
2484flexibility. In that case, arguments given to the class instantiation
2485operator are passed on to \verb\__init__\. For example,
2486
2487\bcode\begin{verbatim}
2488>>> class Complex:
2489... def __init__(self, realpart, imagpart):
2490... self.r = realpart
2491... self.i = imagpart
2492...
2493>>> x = Complex(3.0,-4.5)
2494>>> x.r, x.i
2495(3.0, -4.5)
2496>>>
2497\end{verbatim}\ecode
2498%
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002499Methods may reference global names in the same way as ordinary
2500functions. The global scope associated with a method is the module
2501containing the class definition. (The class itself is never used as a
2502global scope!) While one rarely encounters a good reason for using
2503global data in a method, there are many legitimate uses of the global
2504scope: for one thing, functions and modules imported into the global
2505scope can be used by methods, as well as functions and classes defined
2506in it. Usually, the class containing the method is itself defined in
2507this global scope, and in the next section we'll find some good
2508reasons why a method would want to reference its own class!
2509
2510
2511\section{Inheritance}
2512
2513Of course, a language feature would not be worthy of the name ``class''
2514without supporting inheritance. The syntax for a derived class
2515definition looks as follows:
2516
2517\begin{verbatim}
2518 class DerivedClassName(BaseClassName):
2519 <statement-1>
2520 .
2521 .
2522 .
2523 <statement-N>
2524\end{verbatim}
2525
2526The name \verb\BaseClassName\ must be defined in a scope containing
2527the derived class definition. Instead of a base class name, an
2528expression is also allowed. This is useful when the base class is
2529defined in another module, e.g.,
2530
2531\begin{verbatim}
2532 class DerivedClassName(modname.BaseClassName):
2533\end{verbatim}
2534
2535Execution of a derived class definition proceeds the same as for a
2536base class. When the class object is constructed, the base class is
2537remembered. This is used for resolving attribute references: if a
2538requested attribute is not found in the class, it is searched in the
2539base class. This rule is applied recursively if the base class itself
2540is derived from some other class.
2541
2542There's nothing special about instantiation of derived classes:
2543\verb\DerivedClassName()\ creates a new instance of the class. Method
2544references are resolved as follows: the corresponding class attribute
2545is searched, descending down the chain of base classes if necessary,
2546and the method reference is valid if this yields a function object.
2547
2548Derived classes may override methods of their base classes. Because
2549methods have no special privileges when calling other methods of the
2550same object, a method of a base class that calls another method
2551defined in the same base class, may in fact end up calling a method of
Guido van Rossum16d6e711994-08-08 12:30:22 +00002552a derived class that overrides it. (For \Cpp{} programmers: all methods
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002553in Python are ``virtual functions''.)
2554
2555An overriding method in a derived class may in fact want to extend
2556rather than simply replace the base class method of the same name.
2557There is a simple way to call the base class method directly: just
2558call \verb\BaseClassName.methodname(self, arguments)\. This is
2559occasionally useful to clients as well. (Note that this only works if
2560the base class is defined or imported directly in the global scope.)
2561
2562
2563\subsection{Multiple inheritance}
2564
Guido van Rossum6938f061994-08-01 12:22:53 +00002565Python supports a limited form of multiple inheritance as well. A
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002566class definition with multiple base classes looks as follows:
2567
2568\begin{verbatim}
2569 class DerivedClassName(Base1, Base2, Base3):
2570 <statement-1>
2571 .
2572 .
2573 .
2574 <statement-N>
2575\end{verbatim}
2576
2577The only rule necessary to explain the semantics is the resolution
2578rule used for class attribute references. This is depth-first,
2579left-to-right. Thus, if an attribute is not found in
2580\verb\DerivedClassName\, it is searched in \verb\Base1\, then
2581(recursively) in the base classes of \verb\Base1\, and only if it is
2582not found there, it is searched in \verb\Base2\, and so on.
2583
Guido van Rossum95cd2ef1992-12-08 14:37:55 +00002584(To some people breadth first---searching \verb\Base2\ and
2585\verb\Base3\ before the base classes of \verb\Base1\---looks more
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002586natural. However, this would require you to know whether a particular
2587attribute of \verb\Base1\ is actually defined in \verb\Base1\ or in
2588one of its base classes before you can figure out the consequences of
2589a name conflict with an attribute of \verb\Base2\. The depth-first
2590rule makes no differences between direct and inherited attributes of
2591\verb\Base1\.)
2592
2593It is clear that indiscriminate use of multiple inheritance is a
2594maintenance nightmare, given the reliance in Python on conventions to
2595avoid accidental name conflicts. A well-known problem with multiple
2596inheritance is a class derived from two classes that happen to have a
2597common base class. While it is easy enough to figure out what happens
2598in this case (the instance will have a single copy of ``instance
2599variables'' or data attributes used by the common base class), it is
2600not clear that these semantics are in any way useful.
2601
2602
2603\section{Odds and ends}
2604
2605Sometimes it is useful to have a data type similar to the Pascal
2606``record'' or C ``struct'', bundling together a couple of named data
2607items. An empty class definition will do nicely, e.g.:
2608
2609\begin{verbatim}
2610 class Employee:
2611 pass
2612
2613 john = Employee() # Create an empty employee record
2614
2615 # Fill the fields of the record
2616 john.name = 'John Doe'
2617 john.dept = 'computer lab'
2618 john.salary = 1000
2619\end{verbatim}
2620
2621
2622A piece of Python code that expects a particular abstract data type
2623can often be passed a class that emulates the methods of that data
2624type instead. For instance, if you have a function that formats some
2625data from a file object, you can define a class with methods
2626\verb\read()\ and \verb\readline()\ that gets the data from a string
2627buffer instead, and pass it as an argument. (Unfortunately, this
2628technique has its limitations: a class can't define operations that
2629are accessed by special syntax such as sequence subscripting or
2630arithmetic operators, and assigning such a ``pseudo-file'' to
2631\verb\sys.stdin\ will not cause the interpreter to read further input
2632from it.)
2633
2634
2635Instance method objects have attributes, too: \verb\m.im_self\ is the
2636object of which the method is an instance, and \verb\m.im_func\ is the
2637function object corresponding to the method.
2638
2639
Guido van Rossum3a26dd81996-10-24 22:12:48 +00002640\chapter{Recent Additions as of Release 1.1}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002641
Guido van Rossum6938f061994-08-01 12:22:53 +00002642Python is an evolving language. Since this tutorial was last
2643thoroughly revised, several new features have been added to the
2644language. While ideally I should revise the tutorial to incorporate
2645them in the mainline of the text, lack of time currently requires me
Guido van Rossum16cd7f91994-10-06 10:29:26 +00002646to take a more modest approach. In this chapter I will briefly list the
Guido van Rossum6938f061994-08-01 12:22:53 +00002647most important improvements to the language and how you can use them
2648to your benefit.
2649
2650\section{The Last Printed Expression}
2651
2652In interactive mode, the last printed expression is assigned to the
Guido van Rossum194e57c1995-02-15 15:51:38 +00002653variable \code{_}. This means that when you are using Python as a
Guido van Rossum6938f061994-08-01 12:22:53 +00002654desk calculator, it is somewhat easier to continue calculations, for
2655example:
2656
2657\begin{verbatim}
2658 >>> tax = 17.5 / 100
2659 >>> price = 3.50
2660 >>> price * tax
2661 0.6125
2662 >>> price + _
2663 4.1125
2664 >>> round(_, 2)
2665 4.11
2666 >>>
2667\end{verbatim}
2668
Guido van Rossum194e57c1995-02-15 15:51:38 +00002669For reasons too embarrassing to explain, this variable is implemented
2670as a built-in (living in the module \code{__builtin__}), so it should
2671be treated as read-only by the user. I.e. don't explicitly assign a
2672value to it --- you would create an independent local variable with
2673the same name masking the built-in variable with its magic behavior.
2674
Guido van Rossum6938f061994-08-01 12:22:53 +00002675\section{String Literals}
2676
2677\subsection{Double Quotes}
2678
2679Python can now also use double quotes to surround string literals,
Guido van Rossum194e57c1995-02-15 15:51:38 +00002680e.g. \verb\"this doesn't hurt a bit"\. There is no semantic
2681difference between strings surrounded by single or double quotes.
Guido van Rossum6938f061994-08-01 12:22:53 +00002682
2683\subsection{Continuation Of String Literals}
2684
2685String literals can span multiple lines by escaping newlines with
2686backslashes, e.g.
2687
2688\begin{verbatim}
2689 hello = "This is a rather long string containing\n\
2690 several lines of text just as you would do in C.\n\
2691 Note that whitespace at the beginning of the line is\
2692 significant.\n"
2693 print hello
2694\end{verbatim}
2695
2696which would print the following:
2697\begin{verbatim}
2698 This is a rather long string containing
2699 several lines of text just as you would do in C.
2700 Note that whitespace at the beginning of the line is significant.
2701\end{verbatim}
2702
2703\subsection{Triple-quoted strings}
2704
2705In some cases, when you need to include really long strings (e.g.
2706containing several paragraphs of informational text), it is annoying
2707that you have to terminate each line with \verb@\n\@, especially if
2708you would like to reformat the text occasionally with a powerful text
2709editor like Emacs. For such situations, ``triple-quoted'' strings can
2710be used, e.g.
2711
2712\begin{verbatim}
2713 hello = """
2714
2715 This string is bounded by triple double quotes (3 times ").
Guido van Rossum194e57c1995-02-15 15:51:38 +00002716 Unescaped newlines in the string are retained, though \
Guido van Rossum6938f061994-08-01 12:22:53 +00002717 it is still possible\nto use all normal escape sequences.
2718
2719 Whitespace at the beginning of a line is
2720 significant. If you need to include three opening quotes
2721 you have to escape at least one of them, e.g. \""".
2722
2723 This string ends in a newline.
2724 """
2725\end{verbatim}
2726
Guido van Rossum194e57c1995-02-15 15:51:38 +00002727Triple-quoted strings can be surrounded by three single quotes as
2728well, again without semantic difference.
Guido van Rossum6938f061994-08-01 12:22:53 +00002729
2730\subsection{String Literal Juxtaposition}
2731
2732One final twist: you can juxtapose multiple string literals. Two or
2733more adjacent string literals (but not arbitrary expressions!)
2734separated only by whitespace will be concatenated (without intervening
2735whitespace) into a single string object at compile time. This makes
2736it possible to continue a long string on the next line without
2737sacrificing indentation or performance, unlike the use of the string
2738concatenation operator \verb\+\ or the continuation of the literal
2739itself on the next line (since leading whitespace is significant
2740inside all types of string literals). Note that this feature, like
2741all string features except triple-quoted strings, is borrowed from
2742Standard C.
2743
2744\section{The Formatting Operator}
2745
2746\subsection{Basic Usage}
2747
2748The chapter on output formatting is really out of date: there is now
2749an almost complete interface to C-style printf formats. This is done
2750by overloading the modulo operator (\verb\%\) for a left operand
2751which is a string, e.g.
2752
2753\begin{verbatim}
2754 >>> import math
2755 >>> print 'The value of PI is approximately %5.3f.' % math.pi
2756 The value of PI is approximately 3.142.
2757 >>>
2758\end{verbatim}
2759
2760If there is more than one format in the string you pass a tuple as
2761right operand, e.g.
2762
2763\begin{verbatim}
2764 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
2765 >>> for name, phone in table.items():
2766 ... print '%-10s ==> %10d' % (name, phone)
2767 ...
2768 Jack ==> 4098
2769 Dcab ==> 8637678
2770 Sjoerd ==> 4127
2771 >>>
2772\end{verbatim}
2773
2774Most formats work exactly as in C and require that you pass the proper
2775type (however, if you don't you get an exception, not a core dump).
2776The \verb\%s\ format is more relaxed: if the corresponding argument is
2777not a string object, it is converted to string using the \verb\str()\
2778built-in function. Using \verb\*\ to pass the width or precision in
2779as a separate (integer) argument is supported. The C formats
2780\verb\%n\ and \verb\%p\ are not supported.
2781
2782\subsection{Referencing Variables By Name}
2783
2784If you have a really long format string that you don't want to split
2785up, it would be nice if you could reference the variables to be
2786formatted by name instead of by position. This can be done by using
2787an extension of C formats using the form \verb\%(name)format\, e.g.
2788
2789\begin{verbatim}
2790 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
2791 >>> print 'Jack: %(Jack)d; Sjoerd: %(Sjoerd)d; Dcab: %(Dcab)d' % table
2792 Jack: 4098; Sjoerd: 4127; Dcab: 8637678
2793 >>>
2794\end{verbatim}
2795
2796This is particularly useful in combination with the new built-in
2797\verb\vars()\ function, which returns a dictionary containing all
2798local variables.
2799
2800\section{Optional Function Arguments}
2801
2802It is now possible to define functions with a variable number of
2803arguments. There are two forms, which can be combined.
2804
2805\subsection{Default Argument Values}
2806
2807The most useful form is to specify a default value for one or more
2808arguments. This creates a function that can be called with fewer
2809arguments than it is defined, e.g.
2810
2811\begin{verbatim}
2812 def ask_ok(prompt, retries = 4, complaint = 'Yes or no, please!'):
2813 while 1:
2814 ok = raw_input(prompt)
2815 if ok in ('y', 'ye', 'yes'): return 1
2816 if ok in ('n', 'no', 'nop', 'nope'): return 0
2817 retries = retries - 1
2818 if retries < 0: raise IOError, 'refusenik user'
2819 print complaint
2820\end{verbatim}
2821
2822This function can be called either like this:
2823\verb\ask_ok('Do you really want to quit?')\ or like this:
2824\verb\ask_ok('OK to overwrite the file?', 2)\.
2825
2826The default values are evaluated at the point of function definition
2827in the {\em defining} scope, so that e.g.
2828
2829\begin{verbatim}
2830 i = 5
2831 def f(arg = i): print arg
2832 i = 6
2833 f()
2834\end{verbatim}
2835
2836will print \verb\5\.
2837
2838\subsection{Arbitrary Argument Lists}
2839
2840It is also possible to specify that a function can be called with an
2841arbitrary number of arguments. These arguments will be wrapped up in
2842a tuple. Before the variable number of arguments, zero or more normal
2843arguments may occur, e.g.
2844
2845\begin{verbatim}
2846 def fprintf(file, format, *args):
2847 file.write(format % args)
2848\end{verbatim}
2849
2850This feature may be combined with the previous, e.g.
2851
2852\begin{verbatim}
2853 def but_is_it_useful(required, optional = None, *remains):
2854 print "I don't know"
2855\end{verbatim}
2856
2857\section{Lambda And Functional Programming Tools}
2858
2859\subsection{Lambda Forms}
2860
Guido van Rossum16d6e711994-08-08 12:30:22 +00002861By popular demand, a few features commonly found in functional
Guido van Rossum6938f061994-08-01 12:22:53 +00002862programming languages and Lisp have been added to Python. With the
2863\verb\lambda\ keyword, small anonymous functions can be created.
2864Here's a function that returns the sum of its two arguments:
2865\verb\lambda a, b: a+b\. Lambda forms can be used wherever function
2866objects are required. They are syntactically restricted to a single
2867expression. Semantically, they are just syntactic sugar for a normal
2868function definition. Like nested function definitions, lambda forms
2869cannot reference variables from the containing scope, but this can be
2870overcome through the judicious use of default argument values, e.g.
2871
2872\begin{verbatim}
2873 def make_incrementor(n):
Guido van Rossumc1be9d51994-08-30 12:08:58 +00002874 return lambda x, incr=n: x+incr
Guido van Rossum6938f061994-08-01 12:22:53 +00002875\end{verbatim}
2876
2877\subsection{Map, Reduce and Filter}
2878
2879Three new built-in functions on sequences are good candidate to pass
2880lambda forms.
2881
2882\subsubsection{Map.}
2883
2884\verb\map(function, sequence)\ calls \verb\function(item)\ for each of
2885the sequence's items and returns a list of the return values. For
2886example, to compute some cubes:
2887
2888\begin{verbatim}
2889 >>> map(lambda x: x*x*x, range(1, 11))
2890 [1, 8, 27, 64, 125, 216, 343, 512, 729, 1000]
2891 >>>
2892\end{verbatim}
2893
2894More than one sequence may be passed; the function must then have as
2895many arguments as there are sequences and is called with the
2896corresponding item from each sequence (or \verb\None\ if some sequence
2897is shorter than another). If \verb\None\ is passed for the function,
2898a function returning its argument(s) is substituted.
2899
2900Combining these two special cases, we see that
2901\verb\map(None, list1, list2)\ is a convenient way of turning a pair
2902of lists into a list of pairs. For example:
2903
2904\begin{verbatim}
2905 >>> seq = range(8)
2906 >>> map(None, seq, map(lambda x: x*x, seq))
2907 [(0, 0), (1, 1), (2, 4), (3, 9), (4, 16), (5, 25), (6, 36), (7, 49)]
2908 >>>
2909\end{verbatim}
2910
2911\subsubsection{Filter.}
2912
2913\verb\filter(function, sequence)\ returns a sequence (of the same
2914type, if possible) consisting of those items from the sequence for
2915which \verb\function(item)\ is true. For example, to compute some
2916primes:
2917
2918\begin{verbatim}
2919 >>> filter(lambda x: x%2 != 0 and x%3 != 0, range(2, 25))
2920 [5, 7, 11, 13, 17, 19, 23]
2921 >>>
2922\end{verbatim}
2923
2924\subsubsection{Reduce.}
2925
2926\verb\reduce(function, sequence)\ returns a single value constructed
2927by calling the (binary) function on the first two items of the
2928sequence, then on the result and the next item, and so on. For
2929example, to compute the sum of the numbers 1 through 10:
2930
2931\begin{verbatim}
2932 >>> reduce(lambda x, y: x+y, range(1, 11))
2933 55
2934 >>>
2935\end{verbatim}
2936
2937If there's only one item in the sequence, its value is returned; if
2938the sequence is empty, an exception is raised.
2939
2940A third argument can be passed to indicate the starting value. In this
2941case the starting value is returned for an empty sequence, and the
2942function is first applied to the starting value and the first sequence
2943item, then to the result and the next item, and so on. For example,
2944
2945\begin{verbatim}
2946 >>> def sum(seq):
2947 ... return reduce(lambda x, y: x+y, seq, 0)
2948 ...
2949 >>> sum(range(1, 11))
2950 55
2951 >>> sum([])
2952 0
2953 >>>
2954\end{verbatim}
2955
2956\section{Continuation Lines Without Backslashes}
2957
2958While the general mechanism for continuation of a source line on the
2959next physical line remains to place a backslash on the end of the
2960line, expressions inside matched parentheses (or square brackets, or
2961curly braces) can now also be continued without using a backslash.
2962This is particularly useful for calls to functions with many
2963arguments, and for initializations of large tables.
2964
2965For example:
2966
2967\begin{verbatim}
2968 month_names = ['Januari', 'Februari', 'Maart',
2969 'April', 'Mei', 'Juni',
2970 'Juli', 'Augustus', 'September',
2971 'Oktober', 'November', 'December']
2972\end{verbatim}
2973
2974and
2975
2976\begin{verbatim}
2977 CopyInternalHyperLinks(self.context.hyperlinks,
2978 copy.context.hyperlinks,
2979 uidremap)
2980\end{verbatim}
2981
2982\section{Regular Expressions}
2983
2984While C's printf-style output formats, transformed into Python, are
2985adequate for most output formatting jobs, C's scanf-style input
2986formats are not very powerful. Instead of scanf-style input, Python
2987offers Emacs-style regular expressions as a powerful input and
2988scanning mechanism. Read the corresponding section in the Library
2989Reference for a full description.
2990
2991\section{Generalized Dictionaries}
2992
Guido van Rossum86751151995-02-28 17:14:32 +00002993The keys of dictionaries are no longer restricted to strings --- they
Guido van Rossum194e57c1995-02-15 15:51:38 +00002994can be any immutable basic type including strings, numbers, tuples, or
2995(certain) class instances. (Lists and dictionaries are not acceptable
2996as dictionary keys, in order to avoid problems when the object used as
2997a key is modified.)
Guido van Rossum6938f061994-08-01 12:22:53 +00002998
2999Dictionaries have two new methods: \verb\d.values()\ returns a list of
3000the dictionary's values, and \verb\d.items()\ returns a list of the
3001dictionary's (key, value) pairs. Like \verb\d.keys()\, these
3002operations are slow for large dictionaries. Examples:
3003
3004\begin{verbatim}
3005 >>> d = {100: 'honderd', 1000: 'duizend', 10: 'tien'}
3006 >>> d.keys()
3007 [100, 10, 1000]
3008 >>> d.values()
3009 ['honderd', 'tien', 'duizend']
3010 >>> d.items()
3011 [(100, 'honderd'), (10, 'tien'), (1000, 'duizend')]
3012 >>>
3013\end{verbatim}
3014
3015\section{Miscellaneous New Built-in Functions}
3016
3017The function \verb\vars()\ returns a dictionary containing the current
Guido van Rossum16cd7f91994-10-06 10:29:26 +00003018local variables. With a module argument, it returns that module's
Guido van Rossum6938f061994-08-01 12:22:53 +00003019global variables. The old function \verb\dir(x)\ returns
3020\verb\vars(x).keys()\.
3021
3022The function \verb\round(x)\ returns a floating point number rounded
3023to the nearest integer (but still expressed as a floating point
3024number). E.g. \verb\round(3.4) == 3.0\ and \verb\round(3.5) == 4.0\.
3025With a second argument it rounds to the specified number of digits,
3026e.g. \verb\round(math.pi, 4) == 3.1416\ or even
3027\verb\round(123.4, -2) == 100.0\.
3028
3029The function \verb\hash(x)\ returns a hash value for an object.
3030All object types acceptable as dictionary keys have a hash value (and
3031it is this hash value that the dictionary implementation uses).
3032
3033The function \verb\id(x)\ return a unique identifier for an object.
3034For two objects x and y, \verb\id(x) == id(y)\ if and only if
3035\verb\x is y\. (In fact the object's address is used.)
3036
3037The function \verb\hasattr(x, name)\ returns whether an object has an
3038attribute with the given name (a string value). The function
3039\verb\getattr(x, name)\ returns the object's attribute with the given
3040name. The function \verb\setattr(x, name, value)\ assigns a value to
3041an object's attribute with the given name. These three functions are
3042useful if the attribute names are not known beforehand. Note that
Guido van Rossume5f8b601995-01-04 19:12:49 +00003043\verb\getattr(x, 'spam')\ is equivalent to \verb\x.spam\, and
3044\verb\setattr(x, 'spam', y)\ is equivalent to \verb\x.spam = y\. By
Guido van Rossum6938f061994-08-01 12:22:53 +00003045definition, \verb\hasattr(x, name)\ returns true if and only if
3046\verb\getattr(x, name)\ returns without raising an exception.
3047
3048\section{Else Clause For Try Statement}
3049
3050The \verb\try...except\ statement now has an optional \verb\else\
3051clause, which must follow all \verb\except\ clauses. It is useful to
3052place code that must be executed if the \verb\try\ clause does not
3053raise an exception. For example:
3054
3055\begin{verbatim}
3056 for arg in sys.argv:
3057 try:
3058 f = open(arg, 'r')
3059 except IOError:
3060 print 'cannot open', arg
3061 else:
3062 print arg, 'has', len(f.readlines()), 'lines'
3063 f.close()
3064\end{verbatim}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003065
Guido van Rossumca3f6c81994-10-06 14:08:53 +00003066
3067\section{New Class Features in Release 1.1}
3068
Guido van Rossumcfb45e41994-11-10 23:04:43 +00003069Some changes have been made to classes: the operator overloading
Guido van Rossumca3f6c81994-10-06 14:08:53 +00003070mechanism is more flexible, providing more support for non-numeric use
Guido van Rossum29766b21994-10-06 15:33:25 +00003071of operators (including calling an object as if it were a function),
3072and it is possible to trap attribute accesses.
Guido van Rossumca3f6c81994-10-06 14:08:53 +00003073
3074\subsection{New Operator Overloading}
3075
3076It is no longer necessary to coerce both sides of an operator to the
3077same class or type. A class may still provide a \code{__coerce__}
3078method, but this method may return objects of different types or
3079classes if it feels like it. If no \code{__coerce__} is defined, any
3080argument type or class is acceptable.
3081
3082In order to make it possible to implement binary operators where the
3083right-hand side is a class instance but the left-hand side is not,
3084without using coercions, right-hand versions of all binary operators
3085may be defined. These have an `r' prepended to their name,
3086e.g. \code{__radd__}.
3087
3088For example, here's a very simple class for representing times. Times
3089are initialized from a number of seconds (like time.time()). Times
Guido van Rossum1133aec1995-03-15 11:34:18 +00003090are printed like this: \code{Wed Mar 15 12:28:48 1995}. Subtracting
Guido van Rossumca3f6c81994-10-06 14:08:53 +00003091two Times gives their difference in seconds. Adding or subtracting a
3092Time and a number gives a new Time. You can't add two times, nor can
3093you subtract a Time from a number.
3094
3095\begin{verbatim}
3096import time
3097
3098class Time:
3099 def __init__(self, seconds):
3100 self.seconds = seconds
3101 def __repr__(self):
3102 return time.ctime(self.seconds)
3103 def __add__(self, x):
3104 return Time(self.seconds + x)
3105 __radd__ = __add__ # support for x+t
3106 def __sub__(self, x):
3107 if hasattr(x, 'seconds'): # test if x could be a Time
3108 return self.seconds - x.seconds
3109 else:
3110 return self.seconds - x
3111
3112now = Time(time.time())
3113tomorrow = 24*3600 + now
3114yesterday = now - today
3115print tomorrow - yesterday # prints 172800
3116\end{verbatim}
3117
3118\subsection{Trapping Attribute Access}
3119
3120You can define three new ``magic'' methods in a class now:
3121\code{__getattr__(self, name)}, \code{__setattr__(self, name, value)}
3122and \code{__delattr__(self, name)}.
3123
3124The \code{__getattr__} method is called when an attribute access fails,
Guido van Rossum86751151995-02-28 17:14:32 +00003125i.e. when an attribute access would otherwise raise AttributeError ---
Guido van Rossumca3f6c81994-10-06 14:08:53 +00003126this is {\em after} the instance's dictionary and its class hierarchy
3127have been searched for the named attribute. Note that if this method
3128attempts to access any undefined instance attribute it will be called
3129recursively!
3130
3131The \code{__setattr__} and \code{__delattr__} methods are called when
3132assignment to, respectively deletion of an attribute are attempted.
3133They are called {\em instead} of the normal action (which is to insert
3134or delete the attribute in the instance dictionary). If either of
3135these methods most set or delete any attribute, they can only do so by
Guido van Rossum86751151995-02-28 17:14:32 +00003136using the instance dictionary directly --- \code{self.__dict__} --- else
Guido van Rossumca3f6c81994-10-06 14:08:53 +00003137they would be called recursively.
3138
3139For example, here's a near-universal ``Wrapper'' class that passes all
3140its attribute accesses to another object. Note how the
3141\code{__init__} method inserts the wrapped object in
3142\code{self.__dict__} in order to avoid endless recursion
3143(\code{__setattr__} would call \code{__getattr__} which would call
3144itself recursively).
3145
3146\begin{verbatim}
3147class Wrapper:
3148 def __init__(self, wrapped):
3149 self.__dict__['wrapped'] = wrapped
3150 def __getattr__(self, name):
3151 return getattr(self.wrapped, name)
3152 def __setattr__(self, name, value):
Guido van Rossumcfb45e41994-11-10 23:04:43 +00003153 setattr(self.wrapped, name, value)
Guido van Rossumca3f6c81994-10-06 14:08:53 +00003154 def __delattr__(self, name):
3155 delattr(self.wrapped, name)
3156
3157import sys
3158f = Wrapper(sys.stdout)
3159f.write('hello world\n') # prints 'hello world'
3160\end{verbatim}
3161
Guido van Rossum29766b21994-10-06 15:33:25 +00003162A simpler example of \code{__getattr__} is an attribute that is
3163computed each time (or the first time) it it accessed. For instance:
3164
3165\begin{verbatim}
3166from math import pi
3167
3168class Circle:
3169 def __init__(self, radius):
3170 self.radius = radius
3171 def __getattr__(self, name):
3172 if name == 'circumference':
3173 return 2 * pi * self.radius
3174 if name == 'diameter':
3175 return 2 * self.radius
3176 if name == 'area':
3177 return pi * pow(self.radius, 2)
3178 raise AttributeError, name
3179\end{verbatim}
3180
3181\subsection{Calling a Class Instance}
3182
3183If a class defines a method \code{__call__} it is possible to call its
3184instances as if they were functions. For example:
3185
3186\begin{verbatim}
3187class PresetSomeArguments:
3188 def __init__(self, func, *args):
3189 self.func, self.args = func, args
3190 def __call__(self, *args):
3191 return apply(self.func, self.args + args)
3192
3193f = PresetSomeArguments(pow, 2) # f(i) computes powers of 2
3194for i in range(10): print f(i), # prints 1 2 4 8 16 32 64 128 256 512
3195print # append newline
3196\end{verbatim}
3197
Guido van Rossum194e57c1995-02-15 15:51:38 +00003198
3199\chapter{New in Release 1.2}
3200
3201
3202This chapter describes even more recent additions to the Python
3203language and library.
3204
3205
3206\section{New Class Features}
3207
3208The semantics of \code{__coerce__} have been changed to be more
3209reasonable. As an example, the new standard module \code{Complex}
3210implements fairly complete complex numbers using this. Additional
3211examples of classes with and without \code{__coerce__} methods can be
3212found in the \code{Demo/classes} subdirectory, modules \code{Rat} and
3213\code{Dates}.
3214
3215If a class defines no \code{__coerce__} method, this is equivalent to
3216the following definition:
3217
3218\begin{verbatim}
3219def __coerce__(self, other): return self, other
3220\end{verbatim}
3221
3222If \code{__coerce__} coerces itself to an object of a different type,
3223the operation is carried out using that type --- in release 1.1, this
3224would cause an error.
3225
3226Comparisons involving class instances now invoke \code{__coerce__}
3227exactly as if \code{cmp(x, y)} were a binary operator like \code{+}
3228(except if \code{x} and \code{y} are the same object).
3229
3230\section{Unix Signal Handling}
3231
Fred Drake6dc2aae1996-12-13 21:56:03 +00003232On \UNIX{}, Python now supports signal handling. The module
Guido van Rossum194e57c1995-02-15 15:51:38 +00003233\code{signal} exports functions \code{signal}, \code{pause} and
Fred Drake6dc2aae1996-12-13 21:56:03 +00003234\code{alarm}, which act similar to their \UNIX{} counterparts. The
Guido van Rossum194e57c1995-02-15 15:51:38 +00003235module also exports the conventional names for the various signal
3236classes (also usable with \code{os.kill()}) and \code{SIG_IGN} and
3237\code{SIG_DFL}. See the section on \code{signal} in the Library
3238Reference Manual for more information.
3239
3240\section{Exceptions Can Be Classes}
3241
3242User-defined exceptions are no longer limited to being string objects
3243--- they can be identified by classes as well. Using this mechanism it
3244is possible to create extensible hierarchies of exceptions.
3245
3246There are two new valid (semantic) forms for the raise statement:
3247
3248\begin{verbatim}
3249raise Class, instance
3250
3251raise instance
3252\end{verbatim}
3253
3254In the first form, \code{instance} must be an instance of \code{Class}
3255or of a class derived from it. The second form is a shorthand for
3256
3257\begin{verbatim}
3258raise instance.__class__, instance
3259\end{verbatim}
3260
3261An except clause may list classes as well as string objects. A class
3262in an except clause is compatible with an exception if it is the same
3263class or a base class thereof (but not the other way around --- an
3264except clause listing a derived class is not compatible with a base
3265class). For example, the following code will print B, C, D in that
3266order:
3267
3268\begin{verbatim}
3269class B:
3270 pass
3271class C(B):
3272 pass
3273class D(C):
3274 pass
3275
3276for c in [B, C, D]:
3277 try:
3278 raise c()
3279 except D:
3280 print "D"
3281 except C:
3282 print "C"
3283 except B:
3284 print "B"
3285\end{verbatim}
3286
3287Note that if the except clauses were reversed (with ``\code{except B}''
3288first), it would have printed B, B, B --- the first matching except
3289clause is triggered.
3290
3291When an error message is printed for an unhandled exception which is a
3292class, the class name is printed, then a colon and a space, and
3293finally the instance converted to a string using the built-in function
3294\code{str()}.
3295
3296In this release, the built-in exceptions are still strings.
3297
3298
3299\section{Object Persistency and Object Copying}
3300
3301Two new modules, \code{pickle} and \code{shelve}, support storage and
3302retrieval of (almost) arbitrary Python objects on disk, using the
3303\code{dbm} package. A third module, \code{copy}, provides flexible
Guido van Rossumbcc95821995-02-16 16:28:48 +00003304object copying operations. More information on these modules is
3305provided in the Library Reference Manual.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003306
3307\subsection{Persistent Objects}
3308
3309The module \code{pickle} provides a general framework for objects to
3310disassemble themselves into a stream of bytes and to reassemble such a
3311stream back into an object. It copes with reference sharing,
3312recursive objects and instances of user-defined classes, but not
3313(directly) with objects that have ``magical'' links into the operating
3314system such as open files, sockets or windows.
3315
3316The \code{pickle} module defines a simple protocol whereby
3317user-defined classes can control how they are disassembled and
3318assembled. The method \code{__getinitargs__()}, if defined, returns
3319the argument list for the constructor to be used at assembly time (by
3320default the constructor is called without arguments). The methods
3321\code{__getstate__()} and \code{__setstate__()} are used to pass
3322additional state from disassembly to assembly; by default the
3323instance's \code{__dict__} is passed and restored.
3324
3325Note that \code{pickle} does not open or close any files --- it can be
3326used equally well for moving objects around on a network or store them
3327in a database. For ease of debugging, and the inevitable occasional
3328manual patch-up, the constructed byte streams consist of printable
Guido van Rossum47b4c0f1995-03-15 11:25:32 +00003329\ASCII{} characters only (though it's not designed to be pretty).
Guido van Rossum194e57c1995-02-15 15:51:38 +00003330
3331The module \code{shelve} provides a simple model for storing objects
3332on files. The operation \code{shelve.open(filename)} returns a
3333``shelf'', which is a simple persistent database with a
3334dictionary-like interface. Database keys are strings, objects stored
3335in the database can be anything that \code{pickle} will handle.
3336
Guido van Rossum194e57c1995-02-15 15:51:38 +00003337\subsection{Copying Objects}
3338
3339The module \code{copy} exports two functions: \code{copy()} and
3340\code{deepcopy()}. The \code{copy()} function returns a ``shallow''
3341copy of an object; \code{deepcopy()} returns a ``deep'' copy. The
3342difference between shallow and deep copying is only relevant for
3343compound objects (objects that contain other objects, like lists or
3344class instances):
3345
3346\begin{itemize}
3347
3348\item
3349A shallow copy constructs a new compound object and then (to the
3350extent possible) inserts {\em the same objects} into in that the
3351original contains.
3352
3353\item
3354A deep copy constructs a new compound object and then, recursively,
3355inserts {\em copies} into it of the objects found in the original.
3356
3357\end{itemize}
3358
3359Both functions have the same restrictions and use the same protocols
3360as \code{pickle} --- user-defined classes can control how they are
3361copied by providing methods named \code{__getinitargs__()},
3362\code{__getstate__()} and \code{__setstate__()}.
3363
Guido van Rossum194e57c1995-02-15 15:51:38 +00003364
3365\section{Documentation Strings}
3366
3367A variety of objects now have a new attribute, \code{__doc__}, which
3368is supposed to contain a documentation string (if no documentation is
3369present, the attribute is \code{None}). New syntax, compatible with
3370the old interpreter, allows for convenient initialization of the
3371\code{__doc__} attribute of modules, classes and functions by placing
3372a string literal by itself as the first statement in the suite. It
3373must be a literal --- an expression yielding a string object is not
3374accepted as a documentation string, since future tools may need to
3375derive documentation from source by parsing.
3376
3377Here is a hypothetical, amply documented module called \code{Spam}:
3378
3379\begin{verbatim}
3380"""Spam operations.
3381
3382This module exports two classes, a function and an exception:
3383
3384class Spam: full Spam functionality --- three can sizes
3385class SpamLight: limited Spam functionality --- only one can size
3386
3387def open(filename): open a file and return a corresponding Spam or
3388SpamLight object
3389
3390GoneOff: exception raised for errors; should never happen
3391
3392Note that it is always possible to convert a SpamLight object to a
3393Spam object by a simple method call, but that the reverse operation is
3394generally costly and may fail for a number of reasons.
3395"""
3396
3397class SpamLight:
3398 """Limited spam functionality.
3399
3400 Supports a single can size, no flavor, and only hard disks.
3401 """
3402
3403 def __init__(self, size=12):
3404 """Construct a new SpamLight instance.
3405
3406 Argument is the can size.
3407 """
3408 # etc.
3409
3410 # etc.
3411
3412class Spam(SpamLight):
3413 """Full spam functionality.
3414
3415 Supports three can sizes, two flavor varieties, and all floppy
3416 disk formats still supported by current hardware.
3417 """
3418
3419 def __init__(self, size1=8, size2=12, size3=20):
3420 """Construct a new Spam instance.
3421
3422 Arguments are up to three can sizes.
3423 """
3424 # etc.
3425
3426 # etc.
3427
3428def open(filename = "/dev/null"):
3429 """Open a can of Spam.
3430
3431 Argument must be an existing file.
3432 """
3433 # etc.
3434
3435class GoneOff:
3436 """Class used for Spam exceptions.
3437
3438 There shouldn't be any.
3439 """
3440 pass
3441\end{verbatim}
3442
3443After executing ``\code{import Spam}'', the following expressions
3444return the various documentation strings from the module:
3445
3446\begin{verbatim}
3447Spam.__doc__
3448Spam.SpamLight.__doc__
3449Spam.SpamLight.__init__.__doc__
3450Spam.Spam.__doc__
3451Spam.Spam.__init__.__doc__
3452Spam.open.__doc__
3453Spam.GoneOff.__doc__
3454\end{verbatim}
3455
3456There are emerging conventions about the content and formatting of
3457documentation strings.
3458
3459The first line should always be a short, concise summary of the
3460object's purpose. For brevity, it should not explicitly state the
3461object's name or type, since these are available by other means
3462(except if the name happens to be a verb describing a function's
3463operation). This line should begin with a capital letter and end with
3464a period.
3465
3466If there are more lines in the documentation string, the second line
3467should be blank, visually separating the summary from the rest of the
3468description. The following lines should be one of more of paragraphs
3469describing the objects calling conventions, its side effects, etc.
3470
3471Some people like to copy the Emacs convention of using UPPER CASE for
3472function parameters --- this often saves a few words or lines.
3473
3474The Python parser does not strip indentation from multi-line string
3475literals in Python, so tools that process documentation have to strip
3476indentation. This is done using the following convention. The first
3477non-blank line {\em after} the first line of the string determines the
3478amount of indentation for the entire documentation string. (We can't
3479use the first line since it is generally adjacent to the string's
3480opening quotes so its indentation is not apparent in the string
3481literal.) Whitespace ``equivalent'' to this indentation is then
3482stripped from the start of all lines of the string. Lines that are
3483indented less should not occur, but if they occur all their leading
3484whitespace should be stripped. Equivalence of whitespace should be
3485tested after expansion of tabs (to 8 spaces, normally).
3486
3487In this release, few of the built-in or standard functions and modules
3488have documentation strings.
3489
3490
3491\section{Customizing Import and Built-Ins}
3492
3493In preparation for a ``restricted execution mode'' which will be
3494usable to run code received from an untrusted source (such as a WWW
3495server or client), the mechanism by which modules are imported has
3496been redesigned. It is now possible to provide your own function
3497\code{__import__} which is called whenever an \code{import} statement
3498is executed. There's a built-in function \code{__import__} which
3499provides the default implementation, but more interesting, the various
3500steps it takes are available separately from the new built-in module
3501\code{imp}. (See the section on \code{imp} in the Library Reference
Guido van Rossum6a05f951996-10-22 19:27:46 +00003502Manual for more information on this module --- it also contains a
Guido van Rossumabfa2ca1995-07-07 22:57:02 +00003503complete example of how to write your own \code{__import__} function.)
Guido van Rossum194e57c1995-02-15 15:51:38 +00003504
3505When you do \code{dir()} in a fresh interactive interpreter you will
3506see another ``secret'' object that's present in every module:
3507\code{__builtins__}. This is either a dictionary or a module
3508containing the set of built-in objects used by functions defined in
3509current module. Although normally all modules are initialized with a
3510reference to the same dictionary, it is now possible to use a
3511different set of built-ins on a per-module basis. Together with the
3512fact that the \code{import} statement uses the \code{__import__}
3513function it finds in the importing modules' dictionary of built-ins,
3514this forms the basis for a future restricted execution mode.
3515
3516
3517\section{Python and the World-Wide Web}
3518
3519There is a growing number of modules available for writing WWW tools.
3520The previous release already sported modules \code{gopherlib},
Guido van Rossumbcc95821995-02-16 16:28:48 +00003521\code{ftplib}, \code{httplib} and \code{urllib} (which unifies the
3522other three) for accessing data through the commonest WWW protocols.
3523This release also provides \code{cgi}, to ease the writing of
3524server-side scripts that use the Common Gateway Interface protocol,
3525supported by most WWW servers. The module \code{urlparse} provides
3526precise parsing of a URL string into its components (address scheme,
3527network location, path, parameters, query, and fragment identifier).
Guido van Rossum194e57c1995-02-15 15:51:38 +00003528
Guido van Rossumbcc95821995-02-16 16:28:48 +00003529A rudimentary, parser for HTML files is available in the module
3530\code{htmllib}. It currently supports a subset of HTML 1.0 (if you
3531bring it up to date, I'd love to receive your fixes!). Unfortunately
3532Python seems to be too slow for real-time parsing and formatting of
Guido van Rossum86751151995-02-28 17:14:32 +00003533HTML such as required by interactive WWW browsers --- but it's good
3534enough to write a ``robot'' (an automated WWW browser that searches
3535the web for information).
Guido van Rossum194e57c1995-02-15 15:51:38 +00003536
3537
3538\section{Miscellaneous}
3539
3540\begin{itemize}
3541
3542\item
3543The \code{socket} module now exports all the needed constants used for
3544socket operations, such as \code{SO_BROADCAST}.
3545
3546\item
3547The functions \code{popen()} and \code{fdopen()} in the \code{os}
3548module now follow the pattern of the built-in function \code{open()}:
3549the default mode argument is \code{'r'} and the optional third
3550argument specifies the buffer size, where \code{0} means unbuffered,
3551\code{1} means line-buffered, and any larger number means the size of
3552the buffer in bytes.
3553
3554\end{itemize}
3555
3556
Guido van Rossumeafe32a1995-08-10 14:18:10 +00003557\chapter{New in Release 1.3}
3558
3559
3560This chapter describes yet more recent additions to the Python
3561language and library.
3562
3563
Guido van Rossum9beefa21995-10-08 00:38:51 +00003564\section{Keyword Arguments}
Guido van Rossumeafe32a1995-08-10 14:18:10 +00003565
3566Functions and methods written in Python can now be called using
3567keyword arguments of the form \code{\var{keyword} = \var{value}}. For
3568instance, the following function:
3569
3570\begin{verbatim}
3571def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
3572 print "-- This parrot wouldn't", action,
3573 print "if you put", voltage, "Volts through it."
3574 print "-- Lovely plumage, the", type
3575 print "-- It's", state, "!"
3576\end{verbatim}
3577
3578could be called in any of the following ways:
3579
3580\begin{verbatim}
3581parrot(1000)
3582parrot(action = 'VOOOOOM', voltage = 1000000)
3583parrot('a thousand', state = 'pushing up the daisies')
3584parrot('a million', 'bereft of life', 'jump')
3585\end{verbatim}
3586
3587but the following calls would all be invalid:
3588
3589\begin{verbatim}
3590parrot() # required argument missing
3591parrot(voltage=5.0, 'dead') # non-keyword argument following keyword
3592parrot(110, voltage=220) # duplicate value for argument
3593parrot(actor='John Cleese') # unknown keyword
3594\end{verbatim}
3595
3596In general, an argument list must have the form: zero or more
3597positional arguments followed by zero or more keyword arguments, where
3598the keywords must be chosen from the formal parameter names. It's not
3599important whether a formal parameter has a default value or not. No
Guido van Rossum6a05f951996-10-22 19:27:46 +00003600argument must receive a value more than once --- formal parameter names
Guido van Rossumeafe32a1995-08-10 14:18:10 +00003601corresponding to positional arguments cannot be used as keywords in
3602the same calls.
3603
3604Note that no special syntax is required to allow a function to be
3605called with keyword arguments. The additional costs incurred by
3606keyword arguments are only present when a call uses them.
3607
3608(As far as I know, these rules are exactly the same as used by
3609Modula-3, even if they are enforced by totally different means. This
3610is intentional.)
3611
3612When a final formal parameter of the form \code{**\var{name}} is
3613present, it receives a dictionary containing all keyword arguments
3614whose keyword doesn't correspond to a formal parameter. This may be
3615combined with a formal parameter of the form \code{*\var{name}} which
3616receives a tuple containing the positional arguments beyond the formal
3617parameter list. (\code{*\var{name}} must occur before
3618\code{**\var{name}}.) For example, if we define a function like this:
3619
3620\begin{verbatim}
3621def cheeseshop(kind, *arguments, **keywords):
3622 print "-- Do you have any", kind, '?'
3623 print "-- I'm sorry, we're all out of", kind
3624 for arg in arguments: print arg
3625 print '-'*40
3626 for kw in keywords.keys(): print kw, ':', keywords[kw]
3627\end{verbatim}
3628
3629It could be called like this:
3630
3631\begin{verbatim}
3632cheeseshop('Limburger', "It's very runny, sir.",
3633 "It's really very, VERY runny, sir.",
3634 client='John Cleese',
3635 shopkeeper='Michael Palin',
3636 sketch='Cheese Shop Sketch')
3637\end{verbatim}
3638
3639and of course it would print:
3640
3641\begin{verbatim}
3642-- Do you have any Limburger ?
3643-- I'm sorry, we're all out of Limburger
3644It's very runny, sir.
3645It's really very, VERY runny, sir.
3646----------------------------------------
3647client : John Cleese
3648shopkeeper : Michael Palin
3649sketch : Cheese Shop Sketch
3650\end{verbatim}
3651
Guido van Rossum691d4ec1995-10-08 01:14:57 +00003652Consequences of this change include:
Guido van Rossumeafe32a1995-08-10 14:18:10 +00003653
3654\begin{itemize}
3655
3656\item
Guido van Rossum691d4ec1995-10-08 01:14:57 +00003657The built-in function \code{apply()} now has an optional third
3658argument, which is a dictionary specifying any keyword arguments to be
3659passed. For example,
3660\begin{verbatim}
3661apply(parrot, (), {'voltage': 20, 'action': 'voomm'})
3662\end{verbatim}
3663is equivalent to
3664\begin{verbatim}
3665parrot(voltage=20, action='voomm')
3666\end{verbatim}
3667
3668\item
3669There is also a mechanism for functions and methods defined in an
3670extension module (i.e., implemented in C or C++) to receive a
3671dictionary of their keyword arguments. By default, such functions do
3672not accept keyword arguments, since the argument names are not
3673available to the interpreter.
3674
3675\item
Guido van Rossumeafe32a1995-08-10 14:18:10 +00003676In the effort of implementing keyword arguments, function and
Guido van Rossum6a05f951996-10-22 19:27:46 +00003677especially method calls have been sped up significantly --- for a
Guido van Rossumeafe32a1995-08-10 14:18:10 +00003678method with ten formal parameters, the call overhead has been cut in
3679half; for a function with one formal parameters, the overhead has been
3680reduced by a third.
3681
3682\item
3683The format of \code{.pyc} files has changed (again).
3684
Guido van Rossum9beefa21995-10-08 00:38:51 +00003685\item
3686The \code{access} statement has been disabled. The syntax is still
3687recognized but no code is generated for it. (There were some
3688unpleasant interactions with changes for keyword arguments, and my
3689plan is to get rid of \code{access} altogether in favor of a different
3690approach.)
3691
Guido van Rossumeafe32a1995-08-10 14:18:10 +00003692\end{itemize}
3693
Guido van Rossum9beefa21995-10-08 00:38:51 +00003694\section{Changes to the WWW and Internet tools}
3695
3696\begin{itemize}
3697
3698\item
3699The \code{htmllib} module has been rewritten in an incompatible
3700fashion. The new version is considerably more complete (HTML 2.0
3701except forms, but including all ISO-8859-1 entity definitions), and
3702easy to use. Small changes to \code{sgmllib} have also been made, to
3703better match the tokenization of HTML as recognized by other web
3704tools.
3705
3706\item
3707A new module \code{formatter} has been added, for use with the new
3708\code{htmllib} module.
3709
3710\item
3711The \code{urllib}and \code{httplib} modules have been changed somewhat
3712to allow overriding unknown URL types and to support authentication.
3713They now use \code{mimetools.Message} instead of \code{rfc822.Message}
3714to parse headers. The \code{endrequest()} method has been removed
3715from the HTTP class since it breaks the interaction with some servers.
3716
3717\item
3718The \code{rfc822.Message} class has been changed to allow a flag to be
3719passed in that says that the file is unseekable.
3720
3721\item
3722The \code{ftplib} module has been fixed to be (hopefully) more robust
3723on Linux.
3724
3725\item
3726Several new operations that are optionally supported by servers have
3727been added to \code{nntplib}: \code{xover}, \code{xgtitle},
3728\code{xpath} and \code{date}. % thanks to Kevan Heydon
3729
3730\end{itemize}
3731
3732\section{Other Language Changes}
3733
3734\begin{itemize}
3735
3736\item
3737The \code{raise} statement now takes an optional argument which
3738specifies the traceback to be used when printing the exception's stack
3739trace. This must be a traceback object, such as found in
3740\code{sys.exc_traceback}. When omitted or given as \code{None}, the
3741old behavior (to generate a stack trace entry for the current stack
3742frame) is used.
3743
3744\item
3745The tokenizer is now more tolerant of alien whitespace. Control-L in
3746the leading whitespace of a line resets the column number to zero,
3747while Control-R just before the end of the line is ignored.
3748
3749\end{itemize}
3750
3751\section{Changes to Built-in Operations}
Guido van Rossumeafe32a1995-08-10 14:18:10 +00003752
3753\begin{itemize}
3754
3755\item
3756For file objects, \code{\var{f}.read(0)} and
3757\code{\var{f}.readline(0)} now return an empty string rather than
3758reading an unlimited number of bytes. For the latter, omit the
3759argument altogether or pass a negative value.
3760
3761\item
3762A new system variable, \code{sys.platform}, has been added. It
3763specifies the current platform, e.g. \code{sunos5} or \code{linux1}.
3764
3765\item
3766The built-in functions \code{input()} and \code{raw_input()} now use
3767the GNU readline library when it has been configured (formerly, only
3768interactive input to the interpreter itself was read using GNU
3769readline). The GNU readline library provides elaborate line editing
3770and history. The Python debugger (\code{pdb}) is the first
3771beneficiary of this change.
3772
3773\item
3774Two new built-in functions, \code{globals()} and \code{locals()},
3775provide access to dictionaries containming current global and local
3776variables, respectively. (These augment rather than replace
3777\code{vars()}, which returns the current local variables when called
3778without an argument, and a module's global variables when called with
3779an argument of type module.)
3780
3781\item
Guido van Rossumeafe32a1995-08-10 14:18:10 +00003782The built-in function \code{compile()} now takes a third possible
3783value for the kind of code to be compiled: specifying \code{'single'}
3784generates code for a single interactive statement, which prints the
3785output of expression statements that evaluate to something else than
3786\code{None}.
3787
Guido van Rossum9beefa21995-10-08 00:38:51 +00003788\end{itemize}
3789
3790\section{Library Changes}
3791
3792\begin{itemize}
3793
Guido van Rossumeafe32a1995-08-10 14:18:10 +00003794\item
Guido van Rossum691d4ec1995-10-08 01:14:57 +00003795There are new module \code{ni} and \code{ihooks} that support
3796importing modules with hierarchical names such as \code{A.B.C}. This
3797is enabled by writing \code{import ni; ni.ni()} at the very top of the
3798main program. These modules are amply documented in the Python
3799source.
3800
3801\item
3802The module \code{rexec} has been rewritten (incompatibly) to define a
3803class and to use \code{ihooks}.
3804
3805\item
Guido van Rossum9beefa21995-10-08 00:38:51 +00003806The \code{string.split()} and \code{string.splitfields()} functions
3807are now the same function (the presence or absence of the second
3808argument determines which operation is invoked); similar for
3809\code{string.join()} and \code{string.joinfields()}.
3810
3811\item
3812The \code{Tkinter} module and its helper \code{Dialog} have been
3813revamped to use keyword arguments. Tk 4.0 is now the standard. A new
3814module \code{FileDialog} has been added which implements standard file
3815selection dialogs.
3816
3817\item
3818The optional built-in modules \code{dbm} and \code{gdbm} are more
3819coordinated --- their \code{open()} functions now take the same values
3820for their \var{flag} argument, and the \var{flag} and \var{mode}
3821argument have default values (to open the database for reading only,
3822and to create the database with mode \code{0666} minuse the umask,
3823respectively). The memory leaks have finally been fixed.
3824
3825\item
3826A new dbm-like module, \code{bsddb}, has been added, which uses the
3827BSD DB package's hash method. % thanks to David Ely
3828
3829\item
3830A portable (though slow) dbm-clone, implemented in Python, has been
3831added for systems where none of the above is provided. It is aptly
3832dubbed \code{dumbdbm}.
3833
3834\item
3835The module \code{anydbm} provides a unified interface to \code{bsddb},
3836\code{gdbm}, \code{dbm}, and \code{dumbdbm}, choosing the first one
3837available.
3838
3839\item
3840A new extension module, \code{binascii}, provides a variety of
3841operations for conversion of text-encoded binary data.
3842
3843\item
3844There are three new or rewritten companion modules implemented in
3845Python that can encode and decode the most common such formats:
3846\code{uu} (uuencode), \code{base64} and \code{binhex}.
3847
3848\item
3849A module to handle the MIME encoding quoted-printable has also been
3850added: \code{quopri}.
3851
Guido van Rossumaa93ca81995-10-11 17:47:45 +00003852\item
3853The parser module (which provides an interface to the Python parser's
3854abstract syntax trees) has been rewritten (incompatibly) by Fred
3855Drake. It now lets you change the parse tree and compile the result!
3856
Guido van Rossumbf032a91995-10-11 19:28:39 +00003857\item
3858The \code{syslog} module has been upgraded and documented.
3859% thanks to Steve Clift
3860
Guido van Rossum9beefa21995-10-08 00:38:51 +00003861\end{itemize}
3862
3863\section{Other Changes}
3864
3865\begin{itemize}
Guido van Rossumeafe32a1995-08-10 14:18:10 +00003866
3867\item
3868The dynamic module loader recognizes the fact that different filenames
3869point to the same shared library and loads the library only once, so
3870you can have a single shared library that defines multiple modules.
3871(SunOS / SVR4 style shared libraries only.)
3872
3873\item
3874Jim Fulton's ``abstract object interface'' has been incorporated into
3875the run-time API. For more detailes, read the files
3876\code{Include/abstract.h} and \code{Objects/abstract.c}.
3877
3878\item
Guido van Rossum9beefa21995-10-08 00:38:51 +00003879The Macintosh version is much more robust now.
3880
3881\item
Guido van Rossumeafe32a1995-08-10 14:18:10 +00003882Numerous things I have forgotten or that are so obscure no-one will
3883notice them anyway :-)
3884
3885\end{itemize}
3886
Guido van Rossum97662c81996-08-23 15:35:47 +00003887
3888\chapter{New in Release 1.4}
3889
3890
Guido van Rossum58124881996-10-08 17:29:56 +00003891This chapter describes the major additions to the Python language and
3892library in version 1.4. Many minor changes are not listed here;
3893it is recommended to read the file \code{Misc/NEWS} in the Python
Guido van Rossum6a05f951996-10-22 19:27:46 +00003894source distribution for a complete listing of changes. In particular,
3895changes that only affect C programmers or the build and installation
3896process are not described in this chapter (the new installation
3897lay-out is explained below under \code{sys.prefix} though).
Guido van Rossum97662c81996-08-23 15:35:47 +00003898
Guido van Rossum3a26dd81996-10-24 22:12:48 +00003899\section{Language Changes}
3900
Guido van Rossum97662c81996-08-23 15:35:47 +00003901\begin{itemize}
3902
3903\item
3904Power operator. \code{x**y} is equivalent to \code{pow(x, y)}.
Guido van Rossum58124881996-10-08 17:29:56 +00003905This operator binds more tightly than \code{*}, \code{/} or \code{\%},
3906and binds from right to left when repeated or combined with unary
3907operators. For example, \code{x**y**z} is equivalent to
3908\code{x**(y**z)}, and \code{-x**y} is \code{-(x**y)}.
Guido van Rossum97662c81996-08-23 15:35:47 +00003909
3910\item
Guido van Rossum6a05f951996-10-22 19:27:46 +00003911Complex numbers. Imaginary literals are writen with a \code{'j'}
3912suffix (\code{'J'} is allowed as well.) Complex numbers with a nonzero
3913real component are written as \code{(\var{real}+\var{imag}j)}. You
3914can also use the new built-in function \code{complex()} which takes
3915one or two arguments: \code{complex(x)} is equivalent to \code{x +
39160j}, and \code{complex(x, y)} is \code{x + y*0j}. For example,
3917\code{1j**2} yields \code{complex(-1.0)} (which is another way of
3918saying ``the real value 1.0 represented as a complex number.''
Guido van Rossum58124881996-10-08 17:29:56 +00003919
Guido van Rossum6a05f951996-10-22 19:27:46 +00003920Complex numbers are always represented as two floating point numbers,
3921the real and imaginary part.
3922To extract these parts from a complex number \code{z},
Guido van Rossum58124881996-10-08 17:29:56 +00003923use \code{z.real} and \code{z.imag}. The conversion functions to
3924floating point and integer (\code{float()}, \code{int()} and
Guido van Rossum6a05f951996-10-22 19:27:46 +00003925\code{long()}) don't work for complex numbers --- there is no one
3926correct way to convert a complex number to a real number. Use
Guido van Rossum58124881996-10-08 17:29:56 +00003927\code{abs(z)} to get its magnitude (as a float) or \code{z.real} to
3928get its real part.
3929
3930Module \code{cmath} provides versions of all math functions that take
3931complex arguments and return complex results. (Module \code{math}
3932only supports real numbers, so that \code{math.sqrt(-1)} still raises
3933a \code{ValueError} exception. Numerical experts agree that this is
Guido van Rossum6a05f951996-10-22 19:27:46 +00003934the way it should be.)
Guido van Rossum97662c81996-08-23 15:35:47 +00003935
3936\item
3937New indexing syntax. It is now possible to use a tuple as an indexing
3938expression for a mapping object without parenthesizing it,
Guido van Rossum6a05f951996-10-22 19:27:46 +00003939e.g. \code{x[1, 2, 3]} is equivalent to \code{x[(1, 2, 3)]}.
Guido van Rossum97662c81996-08-23 15:35:47 +00003940
3941\item
3942New slicing syntax. In support of the Numerical Python extension
Guido van Rossum58124881996-10-08 17:29:56 +00003943(distributed independently), slice indices of the form
Guido van Rossum97662c81996-08-23 15:35:47 +00003944\code{x[lo:hi:stride]} are possible, multiple slice indices separated by
Guido van Rossum76e47f31996-11-02 17:05:21 +00003945commas are allowed, and an index position may be replaced by an ellipsis,
Guido van Rossum97662c81996-08-23 15:35:47 +00003946as follows: \code{x[a, ..., z]}. There's also a new built-in function
3947\code{slice(lo, hi, stride)} and a new built-in object
Guido van Rossum76e47f31996-11-02 17:05:21 +00003948\code{Ellipsis}, which yield the same effect without using special
Guido van Rossum97662c81996-08-23 15:35:47 +00003949syntax. None of the standard sequence types support indexing with
Guido van Rossum6a05f951996-10-22 19:27:46 +00003950slice objects or ellipses yet.
Guido van Rossum97662c81996-08-23 15:35:47 +00003951
Guido van Rossum6a05f951996-10-22 19:27:46 +00003952Note that when this new slicing syntax is used, the mapping interface
3953will be used, not the sequence interface. In particular, when a
3954user-defined class instance is sliced using this new slicing syntax,
3955its \code{__getitem__} method is invoked --- the
Guido van Rossum58124881996-10-08 17:29:56 +00003956\code{__getslice__} method is only invoked when a single old-style
Guido van Rossum6a05f951996-10-22 19:27:46 +00003957slice is used, i.e. \code{x[lo:hi]}, with possible omission of
Guido van Rossum58124881996-10-08 17:29:56 +00003958\code{lo} and/or \code{hi}. Some examples:
3959
3960\begin{verbatim}
Guido van Rossum6a05f951996-10-22 19:27:46 +00003961x[0:10:2] -> slice(0, 10, 2)
3962x[:2:] -> slice(None, 2, None)
Guido van Rossum3a26dd81996-10-24 22:12:48 +00003963x[::-1] -> slice(None, None, -1)
Guido van Rossum6a05f951996-10-22 19:27:46 +00003964x[::] -> slice(None, None, None)
3965x[1, 2:3] -> (1, slice(2, 3, None))
3966x[1:2, 3:4] -> (slice(1, 2, None), slice(3, 4, None))
Guido van Rossum76e47f31996-11-02 17:05:21 +00003967x[1:2, ..., 3:4] -> (slice(1, 2, None), Ellipsis,
Guido van Rossum6a05f951996-10-22 19:27:46 +00003968 slice(3, 4, None))
Guido van Rossum58124881996-10-08 17:29:56 +00003969\end{verbatim}
3970
3971For more help with this you are referred to the matrix-sig.
3972
Guido van Rossum97662c81996-08-23 15:35:47 +00003973\item
Guido van Rossum58124881996-10-08 17:29:56 +00003974The \code{access} statement is now truly gone; \code{access} is no
3975longer a reserved word. This saves a few cycles here and there.
3976
3977\item
Guido van Rossum3a26dd81996-10-24 22:12:48 +00003978Private variables through name mangling.
3979There is now limited support for class-private
Guido van Rossum6a05f951996-10-22 19:27:46 +00003980identifiers. Any identifier of the form \code{__spam} (at least two
3981leading underscores, at most one trailing underscore) is now textually
3982replaced with \code{_classname__spam}, where \code{classname} is the
3983current class name with leading underscore(s) stripped. This mangling
3984is done without regard of the syntactic position of the identifier, so
3985it can be used to define class-private instance and class variables,
3986methods, as well as globals, and even to store instance variables
3987private to this class on instances of {\em other} classes. Truncation
3988may occur when the mangled name would be longer than 255 characters.
3989Outside classes, or when the class name consists of only underscores,
3990no mangling occurs.
Guido van Rossum58124881996-10-08 17:29:56 +00003991
Guido van Rossum6a05f951996-10-22 19:27:46 +00003992Name mangling is intended to give classes an easy way to define
3993``private'' instance variables and methods, without having to worry
3994about instance variables defined by derived classes, or mucking with
3995instance variables by code outside the class. Note that the mangling
3996rules are designed mostly to avoid accidents; it still is possible for
3997a determined soul to access or modify a variable that is considered
3998private. This can even be useful, e.g. for the debugger, and that's
Guido van Rossum3a26dd81996-10-24 22:12:48 +00003999one reason why this loophole is not closed. (Buglet: derivation of a
4000class with the same name as the base class makes use of private
4001variables of the base class possible.)
Guido van Rossum58124881996-10-08 17:29:56 +00004002
4003Notice that code passed to \code{exec}, \code{eval()} or
4004\code{evalfile()} does not consider the classname of the invoking
4005class to be the current class; this is similar to the effect of the
4006\code{global} statement, the effect of which is likewise restricted to
Guido van Rossum6a05f951996-10-22 19:27:46 +00004007code that is byte-compiled together. The same restriction applies to
4008\code{getattr()}, \code{setattr()} and \code{delattr()}, as well as
4009when referencing \code{__dict__} directly.
4010
4011Here's an example of a class that implements its own
4012\code{__getattr__} and \code{__setattr__} methods and stores all
4013attributes in a private variable, in a way that works in Python 1.4 as
4014well as in previous versions:
4015
4016\begin{verbatim}
4017class VirtualAttributes:
4018 __vdict = None
4019 __vdict_name = locals().keys()[0]
4020
4021 def __init__(self):
4022 self.__dict__[self.__vdict_name] = {}
4023
4024 def __getattr__(self, name):
4025 return self.__vdict[name]
4026
4027 def __setattr__(self, name, value):
4028 self.__vdict[name] = value
4029\end{verbatim}
4030
Guido van Rossum3a26dd81996-10-24 22:12:48 +00004031{\em Warning: this is an experimental feature.} To avoid all
4032potential problems, refrain from using identifiers starting with
4033double underscore except for predefined uses like \code{__init__}. To
4034use private names while maintaining future compatibility: refrain from
4035using the same private name in classes related via subclassing; avoid
4036explicit (manual) mangling/unmangling; and assume that at some point
4037in the future, leading double underscore will revert to being just a
4038naming convention. Discussion on extensive compile-time declarations
4039are currently underway, and it is impossible to predict what solution
4040will eventually be chosen for private names. Double leading
4041underscore is still a candidate, of course --- just not the only one.
4042It is placed in the distribution in the belief that it is useful, and
4043so that widespread experience with its use can be gained. It will not
4044be removed without providing a better solution and a migration path.
4045
4046\end{itemize}
4047
4048\section{Run-time Changes}
4049
4050\begin{itemize}
4051
4052\item
4053New built-in function \code{list()} converts any sequence to a new list.
4054Note that when the argument is a list, the return value is a fresh
4055copy, similar to what would be returned by \code{a[:]}.
Guido van Rossum58124881996-10-08 17:29:56 +00004056
4057\item
Guido van Rossum6a05f951996-10-22 19:27:46 +00004058Improved syntax error message. Syntax errors detected by the code
4059generation phase of the Python bytecode compiler now include a line
4060number. The line number is appended in parentheses. It is suppressed
4061if the error occurs in line 1 (this usually happens in interactive
4062use).
Guido van Rossum58124881996-10-08 17:29:56 +00004063
4064\item
Guido van Rossum6a05f951996-10-22 19:27:46 +00004065Different exception raised.
Guido van Rossum58124881996-10-08 17:29:56 +00004066Unrecognized keyword arguments now raise a \code{TypeError} exception
4067rather than \code{KeyError}.
4068
4069\item
Guido van Rossum6a05f951996-10-22 19:27:46 +00004070Exceptions in \code{__del__} methods. When a \code{__del__} method
4071raises an exception, a warning is written to \code{sys.stderr} and the
4072exception is ignored. Formerly, such exceptions were ignored without
4073warning. (Propagating the exception is not an option since it it is
Guido van Rossum3a26dd81996-10-24 22:12:48 +00004074invoked from an object finalizer, which cannot return any kind of
4075status or error.) (Buglet: The new behavior, while needed in order to
4076debug failing \code{__del__} methods, is occasionally annoying,
4077because if affects the program's standard error stream. It honors
4078assignments to \code{sys.stderr}, so it can be redirected from within
4079a program if desired.)
Guido van Rossum58124881996-10-08 17:29:56 +00004080
4081\item
Guido van Rossum3a26dd81996-10-24 22:12:48 +00004082You can now discover from which file (if any) a module was loaded by
4083inspecting its \code{__file__} attribute. This attribute is not
4084present for built-in or frozen modules. It points to the shared
4085library file for dynamically loaded modules. (Buglet: this may be a
4086relative path and is stored in the \code{.pyc} file on compilation.
4087If you manipulate the current directory with \code{os.chdir()} or move
4088\code{.pyc} files around, the value may be incorrect.)
4089
4090\end{itemize}
4091
4092\section{New or Updated Modules}
4093
4094\begin{itemize}
Guido van Rossum58124881996-10-08 17:29:56 +00004095
4096\item
Guido van Rossum6a05f951996-10-22 19:27:46 +00004097New built-in module \code{operator}. While undocumented, the concept
4098is real simply: \code{operator.__add__(x, y)} does exactly the same
4099thing as \code{x+y} (for all types --- built-in, user-defined,
4100extension-defined). As a convenience, \code{operator.add} does the
4101same thing, but beware --- you can't use \code{operator.and} and a few
4102others where the ``natural'' name for an operator is a reserved
4103keyword. You can add a single trailing underscore in such cases.
Guido van Rossum58124881996-10-08 17:29:56 +00004104
4105\item
Guido van Rossum6a05f951996-10-22 19:27:46 +00004106New built-in module \code{errno}. See the Library Reference Manual.
Guido van Rossum58124881996-10-08 17:29:56 +00004107
4108\item
Guido van Rossum6a05f951996-10-22 19:27:46 +00004109Rewritten \code{cgi} module. See the Library Reference Manual.
Guido van Rossum58124881996-10-08 17:29:56 +00004110
4111\item
4112Improved restricted execution module (\code{rexec}). New module
Guido van Rossum6a05f951996-10-22 19:27:46 +00004113\code{Bastion}. Both are now documented in a new chapter on
4114restricted execution in the Library Reference Manual.
Guido van Rossum58124881996-10-08 17:29:56 +00004115
4116\item
Guido van Rossum6a05f951996-10-22 19:27:46 +00004117New string operations (all described in the Library Reference Manual):
4118\code{lstrip()}, \code{rstrip()} (strip only the left/right
4119whitespace), \code{capitalize()} (uppercase the first character,
4120lowercase the rest), \code{capwords()} (capitalize each word,
4121delimited a la \code{string.split()}), \code{translate()} (string
4122transliteration -- this existed before but can now also delete
4123characters by specifying a third argument), \code{maketrans()} (a
4124convenience function for creating translation tables for
4125\code{translate()} and \code{regex.compile()}). The string function
4126\code{split()} has an optional third argument which specifies the
4127maximum number of separators to split;
4128e.g. \code{string.split('a=b=c', '=', 1)} yields \code{['a', 'b=c']}.
4129(Note that for a long time, \code{split()} and \code{splitfields()}
4130are synonyms.
Guido van Rossum58124881996-10-08 17:29:56 +00004131
4132\item
Guido van Rossum6a05f951996-10-22 19:27:46 +00004133New regsub operations (see the Library Reference Manual):
4134\code{regsub.capwords()} (like \code{string.capwords()} but allows you to
4135specify the word delimiter as a regular expression),
4136\code{regsub.splitx()} (like \code{regsub.split()} but returns the
4137delimiters as well as the words in the resulting list). The optional
4138\code{maxsep} argument is also supported by \code{regsub.split()}.
Guido van Rossum58124881996-10-08 17:29:56 +00004139
4140\item
Guido van Rossum6a05f951996-10-22 19:27:46 +00004141Module files \code{pdb.py} and \code{profile.py} can now be invoked as
Guido van Rossum3a26dd81996-10-24 22:12:48 +00004142scripts to debug c.q. profile other scripts easily. For example:
4143\code{python /usr/local/lib/python1.4/profile.py myscript.py}
Guido van Rossum58124881996-10-08 17:29:56 +00004144
4145\item
Guido van Rossum3a26dd81996-10-24 22:12:48 +00004146The \code{os} module now supports the \code{putenv()} function on
4147systems where it is provided in the C library (Windows NT and most
4148Unix versions). For example, \code{os.putenv('PATH',
4149'/bin:/usr/bin')} sets the environment variable \code{PATH} to the
4150string \code{'/bin:/usr/bin'}. Such changes to the environment affect
4151subprocesses started with \code{os.system()}, \code{os.popen()} or
4152\code{os.fork()} and \code{os.execv()}. When \code{putenv()} is
4153supported, assignments to items in \code{os.environ} are automatically
4154translated into corresponding calls to \code{os.putenv()}; however,
4155calls to \code{os.putenv()} don't update \code{os.environ}, so it is
4156actually preferable to assign to items of \code{os.environ}. For this
4157purpose, the type of \code{os.environ} is changed to a subclass of
4158\code{UserDict.UserDict} when \code{os.putenv()} is supported.
4159(Buglet: \code{os.execve()} still requires a real dictionary, so it
4160won't accept \code{os.environ} as its third argument. However, you
4161can now use \code{os.execv()} and it will use your changes to
4162\code{os.environ}!.)
Guido van Rossum58124881996-10-08 17:29:56 +00004163
4164\item
Guido van Rossum3a26dd81996-10-24 22:12:48 +00004165More new functions in the \code{os} module: \code{mkfifo},
4166\code{plock}, \code{remove} (== \code{unlink}), and \code{ftruncate}.
4167See the Unix manual (section 2, system calls) for these function.
4168More functions are also available under NT.
Guido van Rossum58124881996-10-08 17:29:56 +00004169
4170\item
Guido van Rossum6a05f951996-10-22 19:27:46 +00004171New functions in the fcntl module: \code{lockf()} and \code{flock()}
4172(don't ask \code{:-)}). See the Library Reference Manual.
Guido van Rossum58124881996-10-08 17:29:56 +00004173
4174\item
Guido van Rossum3a26dd81996-10-24 22:12:48 +00004175The first item of the module search path, \code{sys.path[0]}, is the
Guido van Rossum58124881996-10-08 17:29:56 +00004176directory containing the script that was used to invoke the Python
4177interpreter. If the script directory is not available (e.g. if the
4178interpreter is invoked interactively or if the script is read from
4179standard input), \code{sys.path[0]} is the empty string, which directs
4180Python to search modules in the current directory first. Notice that
4181the script directory is inserted {\em before} the entries inserted as
4182a result of \code{\$PYTHONPATH}. There is no longer an entry for the
Guido van Rossum3a26dd81996-10-24 22:12:48 +00004183current directory later in the path (unless explicitly set in
4184\code{\$PYTHONPATH} or overridden at build time).
4185
4186\end{itemize}
4187
4188\section{Configuration and Installation}
4189
4190\begin{itemize}
Guido van Rossum58124881996-10-08 17:29:56 +00004191
4192\item
Guido van Rossum3a26dd81996-10-24 22:12:48 +00004193More configuration information is now available to Python programs.
4194The variable \code{sys.prefix} gives the site-specific directory
4195prefix where the platform independent Python files are installed; by
4196default, this is the string \code{"/usr/local"}. This can be set at
4197build time with the \code{--prefix} argument to the \code{configure}
4198script. The main collection of Python library modules is installed in
4199the directory \code{sys.prefix+"/lib/python1.4"} while the platform
4200independent header files (all except \code{config.h}) are stored in
4201\code{sys.prefix+"/include/python1.4"}.
Guido van Rossum58124881996-10-08 17:29:56 +00004202
Guido van Rossum3a26dd81996-10-24 22:12:48 +00004203Similarly, the variable \code{sys.exec_prefix} gives the site-specific
4204directory prefix where the platform {\em de}pendent Python files are
4205installed; by default, this is also \code{"/usr/local"}. This can be
4206set at build time with the \code{--exec-prefix} argument to the
4207\code{configure} script. Specifically, all configuration files
4208(e.g. the \code{config.h} header file) are installed in the directory
4209\code{sys.exec_prefix+"/lib/python1.4/config"}, and shared library
4210modules are installed in
4211\code{sys.exec_prefix+"/lib/python1.4/sharedmodules"}.
4212
4213Include files are at \code{sys.prefix+"/include/python1.4"}.
4214
4215It is not yet decided what the most portable way is to come up with
4216the version number used in these pathnames. For compatibility with
4217the 1.4beta releases, sys.version[:3] can be used.
Guido van Rossum58124881996-10-08 17:29:56 +00004218
4219On non-Unix systems, these variables are meaningless.
4220
4221\item
Guido van Rossum3a26dd81996-10-24 22:12:48 +00004222While sites are strongly discouraged from modifying the standard
4223Python library (like adding site-specific modules or functions), there
4224is now a standard way to invoke site-specific features. The standard
4225module \code{site}, when imported, appends two site-specific
4226directories to the end of \code{sys.path}:
4227\code{\$prefix/lib/site-python} and
4228\code{\$exec_prefix/lib/site-python}, where \code{\$prefix} and
4229\code{\$exec_prefix} are the directories \code{sys.prefix} and
Guido van Rossum58124881996-10-08 17:29:56 +00004230\code{sys.exec_prefix} mentioned above.
4231
Guido van Rossum3a26dd81996-10-24 22:12:48 +00004232After this path manipulation has been performed, an attempt is made to
4233import the module \code{sitecustomize}. Any \code{ImportError}
4234exception raised by this attempt is silently ignored.
Guido van Rossum97662c81996-08-23 15:35:47 +00004235
4236\end{itemize}
4237
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00004238\end{document}