blob: 4abd47051bbc1e1abb029e9b14c2b65a63070e1c [file] [log] [blame]
Fred Drake1f8449a1998-01-09 05:36:43 +00001\documentclass[twoside]{report}
2\usepackage{myformat}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003
Guido van Rossum02455691997-07-17 16:21:52 +00004% Things to do:
5% Add a section on file I/O
6% Write a chapter entitled ``Some Useful Modules''
7% --regex, math+cmath
8% Should really move the Python startup file info to an appendix
Guido van Rossum02455691997-07-17 16:21:52 +00009
Guido van Rossumdccc2981997-12-30 04:40:25 +000010\title{Python Tutorial}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000011
Guido van Rossum16cd7f91994-10-06 10:29:26 +000012\input{boilerplate}
Guido van Rossum83eb9621993-11-23 16:28:45 +000013
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000014\begin{document}
15
16\pagenumbering{roman}
17
18\maketitle
19
Guido van Rossum16cd7f91994-10-06 10:29:26 +000020\input{copyright}
21
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000022\begin{abstract}
23
24\noindent
Guido van Rossumdccc2981997-12-30 04:40:25 +000025Python is an easy to learn, powerful programming language. It has
26efficient high-level data structures and a simple but effective
27approach to object-oriented programming. Python's elegant syntax and
28dynamic typing, together with its interpreted nature, make it an ideal
29language for scripting and rapid application development in many areas
30on most platforms.
31
32The Python interpreter and the extensive standard library are freely
33available in source or binary form for all major platforms from the
34Python web site, \file{http://www.python.org}, and can be freely
35distributed. The same site also contains distributions of and
36pointers to many free third party Python modules, programs and tools,
37and additional documentation.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000038
Guido van Rossum4410c751991-06-04 20:22:18 +000039The Python interpreter is easily extended with new functions and data
Guido van Rossumdccc2981997-12-30 04:40:25 +000040types implemented in C or C++ (or other languages callable from C).
41Python is also suitable as an extension language for customizable
42applications.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000043
Guido van Rossum6fc178f1991-08-16 09:13:42 +000044This tutorial introduces the reader informally to the basic concepts
45and features of the Python language and system. It helps to have a
Guido van Rossumdccc2981997-12-30 04:40:25 +000046Python interpreter handy for hands-on experience, but all examples are
47self-contained, so the tutorial can be read off-line as well.
Guido van Rossum2292b8e1991-01-23 16:31:24 +000048
Guido van Rossumdccc2981997-12-30 04:40:25 +000049For a description of standard objects and modules, see the
50\emph{Python Library Reference} document. The \emph{Python Reference
51Manual} gives a more formal definition of the language. To write
52extensions in C or C++, read the \emph{Extending and Embedding} and
53\emph{Python/C API} manuals. There are also several books covering
54Python in depth.
55
56This tutorial does not attempt to be comprehensive and cover every
57single feature, or even every commonly used feature. Instead, it
58introduces many of Python's most noteworthy features, and will give
59you a good idea of the language's flavor and style. After reading it,
60you will be able to read and write Python modules and programs, and
61you will be ready to learn more about the various Python library
62modules described in the \emph{Python Library Reference}.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000063
64\end{abstract}
65
Fred Drake1f8449a1998-01-09 05:36:43 +000066\mytableofcontents
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000067
68\pagenumbering{arabic}
69
Guido van Rossum5e0759d1992-08-07 16:06:24 +000070
Guido van Rossum6fc178f1991-08-16 09:13:42 +000071\chapter{Whetting Your Appetite}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000072
Guido van Rossum3a26dd81996-10-24 22:12:48 +000073\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 Rossum02455691997-07-17 16:21:52 +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
Guido van Rossum02455691997-07-17 16:21:52 +000080script in C; perhaps the problem requires variable-length strings or
81other data types (like sorted lists of file names) that are easy in
82the shell but lots of work to implement in C, or perhaps you're not
83sufficiently familiar with C.
84
85Another situation: perhaps you have to work with several C libraries,
86and the usual C write/compile/test/re-compile cycle is too slow. You
87need to develop software more quickly. Possibly perhaps you've
88written a program that could use an extension language, and you don't
89want to design a language, write and debug an interpreter for it, then
90tie it into your application.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000091
Guido van Rossum6fc178f1991-08-16 09:13:42 +000092In such cases, Python may be just the language for you. Python is
93simple to use, but it is a real programming language, offering much
94more structure and support for large programs than the shell has. On
95the other hand, it also offers much more error checking than C, and,
Fred Drakeeee08cd1997-12-04 15:43:15 +000096being a \emph{very-high-level language}, it has high-level data types
Guido van Rossum6fc178f1991-08-16 09:13:42 +000097built in, such as flexible arrays and dictionaries that would cost you
98days to implement efficiently in C. Because of its more general data
Fred Drakeeee08cd1997-12-04 15:43:15 +000099types Python is applicable to a much larger problem domain than
100\emph{Awk} or even \emph{Perl}, yet many things are at least as easy
101in Python as in those languages.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000102
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000103Python allows you to split up your program in modules that can be
104reused in other Python programs. It comes with a large collection of
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000105standard modules that you can use as the basis of your programs --- or
106as examples to start learning to program in Python. There are also
107built-in modules that provide things like file I/O, system calls,
Guido van Rossum02455691997-07-17 16:21:52 +0000108sockets, and even interfaces to GUI toolkits like Tk.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000109
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000110Python is an interpreted language, which can save you considerable time
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000111during program development because no compilation and linking is
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000112necessary. The interpreter can be used interactively, which makes it
113easy to experiment with features of the language, to write throw-away
114programs, or to test functions during bottom-up program development.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000115It is also a handy desk calculator.
116
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000117Python allows writing very compact and readable programs. Programs
118written in Python are typically much shorter than equivalent C
119programs, for several reasons:
120\begin{itemize}
121\item
122the high-level data types allow you to express complex operations in a
123single statement;
124\item
125statement grouping is done by indentation instead of begin/end
126brackets;
127\item
128no variable or argument declarations are necessary.
129\end{itemize}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000130
Fred Drakeeee08cd1997-12-04 15:43:15 +0000131Python is \emph{extensible}: if you know how to program in C it is easy
Guido van Rossum02455691997-07-17 16:21:52 +0000132to add a new built-in function or module to the interpreter, either to
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000133perform critical operations at maximum speed, or to link Python
134programs to libraries that may only be available in binary form (such
135as a vendor-specific graphics library). Once you are really hooked,
136you can link the Python interpreter into an application written in C
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000137and use it as an extension or command language for that application.
138
Guido van Rossum02455691997-07-17 16:21:52 +0000139By the way, the language is named after the BBC show ``Monty Python's
140Flying Circus'' and has nothing to do with nasty reptiles. Making
141references to Monty Python skits in documentation is not only allowed,
Guido van Rossumdccc2981997-12-30 04:40:25 +0000142it is encouraged!
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000143
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000144\section{Where From Here}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000145
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000146Now that you are all excited about Python, you'll want to examine it
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000147in some more detail. Since the best way to learn a language is
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000148using it, you are invited here to do so.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000149
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000150In the next chapter, the mechanics of using the interpreter are
151explained. This is rather mundane information, but essential for
152trying out the examples shown later.
153
Guido van Rossum4410c751991-06-04 20:22:18 +0000154The rest of the tutorial introduces various features of the Python
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000155language and system though examples, beginning with simple
156expressions, statements and data types, through functions and modules,
Guido van Rossum6938f061994-08-01 12:22:53 +0000157and finally touching upon advanced concepts like exceptions
158and user-defined classes.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000159
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000160\chapter{Using the Python Interpreter}
161
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000162\section{Invoking the Interpreter}
163
Fred Drakeeee08cd1997-12-04 15:43:15 +0000164The Python interpreter is usually installed as \file{/usr/local/bin/python}
165on those machines where it is available; putting \file{/usr/local/bin} in
Fred Drake6dc2aae1996-12-13 21:56:03 +0000166your \UNIX{} shell's search path makes it possible to start it by
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000167typing the command
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000168
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000169\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000170python
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000171\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000172%
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000173to the shell. Since the choice of the directory where the interpreter
174lives is an installation option, other places are possible; check with
Fred Drakeeee08cd1997-12-04 15:43:15 +0000175your local Python guru or system administrator. (E.g.,
176\file{/usr/local/python} is a popular alternative location.)
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000177
Guido van Rossum02455691997-07-17 16:21:52 +0000178Typing an EOF character (Control-D on \UNIX{}, Control-Z or F6 on DOS
179or Windows) at the primary prompt causes the interpreter to exit with
180a zero exit status. If that doesn't work, you can exit the
181interpreter by typing the following commands: \code{import sys ;
182sys.exit()}.
183
184The interpreter's line-editing features usually aren't very
185sophisticated. On Unix, whoever installed the interpreter may have
186enabled support for the GNU readline library, which adds more
187elaborate interactive editing and history features. Perhaps the
188quickest check to see whether command line editing is supported is
189typing Control-P to the first Python prompt you get. If it beeps, you
190have command line editing; see Appendix A for an introduction to the
Fred Drakeeee08cd1997-12-04 15:43:15 +0000191keys. If nothing appears to happen, or if \code{\^P} is echoed,
Guido van Rossum02455691997-07-17 16:21:52 +0000192command line editing isn't available; you'll only be able to use
193backspace to remove characters from the current line.
194
Fred Drake6dc2aae1996-12-13 21:56:03 +0000195The interpreter operates somewhat like the \UNIX{} shell: when called
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000196with standard input connected to a tty device, it reads and executes
197commands interactively; when called with a file name argument or with
Fred Drakeeee08cd1997-12-04 15:43:15 +0000198a file as standard input, it reads and executes a \emph{script} from
Guido van Rossum02455691997-07-17 16:21:52 +0000199that file.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000200
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000201A third way of starting the interpreter is
Fred Drakeeee08cd1997-12-04 15:43:15 +0000202\samp{python -c command [arg] ...}, which
203executes the statement(s) in \code{command}, analogous to the shell's
204\code{-c} option. Since Python statements often contain spaces or other
205characters that are special to the shell, it is best to quote
206\code{command} in its entirety with double quotes.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000207
Fred Drakeeee08cd1997-12-04 15:43:15 +0000208Note that there is a difference between \samp{python file} and
209\samp{python <file}. In the latter case, input requests from the
210program, such as calls to \code{input()} and \code{raw_input()}, are
211satisfied from \emph{file}. Since this file has already been read
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000212until the end by the parser before the program starts executing, the
213program will encounter EOF immediately. In the former case (which is
214usually what you want) they are satisfied from whatever file or device
215is connected to standard input of the Python interpreter.
216
Guido van Rossumb2c65561993-05-12 08:53:36 +0000217When a script file is used, it is sometimes useful to be able to run
218the script and enter interactive mode afterwards. This can be done by
Fred Drakeeee08cd1997-12-04 15:43:15 +0000219passing \code{-i} before the script. (This does not work if the script
Guido van Rossumb2c65561993-05-12 08:53:36 +0000220is read from standard input, for the same reason as explained in the
221previous paragraph.)
222
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000223\subsection{Argument Passing}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000224
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000225When known to the interpreter, the script name and additional
Fred Drakeeee08cd1997-12-04 15:43:15 +0000226arguments thereafter are passed to the script in the variable
227\code{sys.argv}, which is a list of strings. Its length is at least
228one; when no script and no arguments are given, \code{sys.argv[0]} is
229an empty string. When the script name is given as \code{'-'} (meaning
230standard input), \code{sys.argv[0]} is set to \code{'-'}. When \code{-c
231command} is used, \code{sys.argv[0]} is set to \code{'-c'}. Options
232found after \code{-c command} are not consumed by the Python
233interpreter's option processing but left in \code{sys.argv} for the
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000234command to handle.
235
236\subsection{Interactive Mode}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000237
Guido van Rossumdd010801991-06-07 14:31:11 +0000238When commands are read from a tty, the interpreter is said to be in
Fred Drakeeee08cd1997-12-04 15:43:15 +0000239\emph{interactive mode}. In this mode it prompts for the next command
240with the \emph{primary prompt}, usually three greater-than signs
241(\code{>>>}); for continuation lines it prompts with the
242\emph{secondary prompt},
243by default three dots (\code{...}).
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000244
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000245The interpreter prints a welcome message stating its version number
246and a copyright notice before printing the first prompt, e.g.:
247
248\bcode\begin{verbatim}
249python
Fred Drakeeee08cd1997-12-04 15:43:15 +0000250Python 1.5b1 (#1, Dec 3 1997, 00:02:06) [GCC 2.7.2.2] on sunos5
251Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000252>>>
253\end{verbatim}\ecode
254
255\section{The Interpreter and its Environment}
256
257\subsection{Error Handling}
258
259When an error occurs, the interpreter prints an error
260message and a stack trace. In interactive mode, it then returns to
261the primary prompt; when input came from a file, it exits with a
262nonzero exit status after printing
Fred Drakeeee08cd1997-12-04 15:43:15 +0000263the stack trace. (Exceptions handled by an \code{except} clause in a
264\code{try} statement are not errors in this context.) Some errors are
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000265unconditionally fatal and cause an exit with a nonzero exit; this
266applies to internal inconsistencies and some cases of running out of
267memory. All error messages are written to the standard error stream;
268normal output from the executed commands is written to standard
269output.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000270
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000271Typing the interrupt character (usually Control-C or DEL) to the
272primary or secondary prompt cancels the input and returns to the
273primary prompt.%
274\footnote{
Guido van Rossum6938f061994-08-01 12:22:53 +0000275 A problem with the GNU Readline package may prevent this.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000276}
Fred Drakeeee08cd1997-12-04 15:43:15 +0000277Typing an interrupt while a command is executing raises the
278\code{KeyboardInterrupt} exception, which may be handled by a
279\code{try} statement.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000280
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000281\subsection{Executable Python scripts}
Guido van Rossum4410c751991-06-04 20:22:18 +0000282
Fred Drake6dc2aae1996-12-13 21:56:03 +0000283On BSD'ish \UNIX{} systems, Python scripts can be made directly
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000284executable, like shell scripts, by putting the line
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000285
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000286\bcode\begin{verbatim}
Fred Drake9e63faa1997-10-15 14:37:24 +0000287#! /usr/bin/env python
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000288\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000289%
Fred Drake9e63faa1997-10-15 14:37:24 +0000290(assuming that the interpreter is on the user's PATH) at the beginning
Fred Drakeeee08cd1997-12-04 15:43:15 +0000291of the script and giving the file an executable mode. The \code{\#!}
Fred Drake9e63faa1997-10-15 14:37:24 +0000292must be the first two characters of the file.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000293
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000294\subsection{The Interactive Startup File}
295
Guido van Rossum02455691997-07-17 16:21:52 +0000296XXX This should probably be dumped in an appendix, since most people
297don't use Python interactively in non-trivial ways.
298
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000299When you use Python interactively, it is frequently handy to have some
300standard commands executed every time the interpreter is started. You
Fred Drakeeee08cd1997-12-04 15:43:15 +0000301can do this by setting an environment variable named
302\code{PYTHONSTARTUP} to the name of a file containing your start-up
303commands. This is similar to the \file{.profile} feature of the \UNIX{}
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000304shells.
305
306This file is only read in interactive sessions, not when Python reads
Fred Drakeeee08cd1997-12-04 15:43:15 +0000307commands from a script, and not when \file{/dev/tty} is given as the
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000308explicit source of commands (which otherwise behaves like an
309interactive session). It is executed in the same name space where
310interactive commands are executed, so that objects that it defines or
311imports can be used without qualification in the interactive session.
Fred Drakeeee08cd1997-12-04 15:43:15 +0000312You can also change the prompts \code{sys.ps1} and \code{sys.ps2} in
Guido van Rossum7b3c8a11992-09-08 09:20:13 +0000313this file.
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000314
315If you want to read an additional start-up file from the current
316directory, you can program this in the global start-up file, e.g.
Fred Drakeeee08cd1997-12-04 15:43:15 +0000317\code{execfile('.pythonrc')}. If you want to use the startup file
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000318in a script, you must write this explicitly in the script, e.g.
Fred Drakeeee08cd1997-12-04 15:43:15 +0000319\code{import os;} \code{execfile(os.environ['PYTHONSTARTUP'])}.
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000320
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000321\chapter{An Informal Introduction to Python}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000322
323In the following examples, input and output are distinguished by the
Fred Drakeeee08cd1997-12-04 15:43:15 +0000324presence or absence of prompts (\code{>>>} and \code{...}): to repeat
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000325the example, you must type everything after the prompt, when the
326prompt appears; lines that do not begin with a prompt are output from
327the interpreter.%
Guido van Rossum02455691997-07-17 16:21:52 +0000328%\footnote{
329% I'd prefer to use different fonts to distinguish input
330% from output, but the amount of LaTeX hacking that would require
331% is currently beyond my ability.
332%}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000333Note that a secondary prompt on a line by itself in an example means
334you must type a blank line; this is used to end a multi-line command.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000335
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000336\section{Using Python as a Calculator}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000337
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000338Let's try some simple Python commands. Start the interpreter and wait
Fred Drakeeee08cd1997-12-04 15:43:15 +0000339for the primary prompt, \code{>>>}. (It shouldn't take long.)
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000340
341\subsection{Numbers}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000342
343The interpreter acts as a simple calculator: you can type an
344expression at it and it will write the value. Expression syntax is
Fred Drakeeee08cd1997-12-04 15:43:15 +0000345straightforward: the operators \code{+}, \code{-}, \code{*} and \code{/}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000346work just like in most other languages (e.g., Pascal or C); parentheses
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000347can be used for grouping. For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000348
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000349\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000350>>> 2+2
3514
Guido van Rossum6938f061994-08-01 12:22:53 +0000352>>> # This is a comment
353... 2+2
3544
355>>> 2+2 # and a comment on the same line as code
3564
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000357>>> (50-5*6)/4
3585
Guido van Rossum6938f061994-08-01 12:22:53 +0000359>>> # Integer division returns the floor:
360... 7/3
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003612
Guido van Rossum6938f061994-08-01 12:22:53 +0000362>>> 7/-3
363-3
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000364>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000365\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000366%
Fred Drakeeee08cd1997-12-04 15:43:15 +0000367Like in C, the equal sign (\code{=}) is used to assign a value to a
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000368variable. The value of an assignment is not written:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000369
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000370\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000371>>> width = 20
372>>> height = 5*9
373>>> width * height
374900
375>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000376\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000377%
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000378A value can be assigned to several variables simultaneously:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000379
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000380\bcode\begin{verbatim}
Guido van Rossum6938f061994-08-01 12:22:53 +0000381>>> x = y = z = 0 # Zero x, y and z
382>>> x
3830
384>>> y
3850
386>>> z
3870
388>>>
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000389\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000390%
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000391There is full support for floating point; operators with mixed type
392operands convert the integer operand to floating point:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000393
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000394\bcode\begin{verbatim}
395>>> 4 * 2.5 / 3.3
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003963.0303030303
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000397>>> 7.0 / 2
3983.5
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000399\end{verbatim}\ecode
Guido van Rossum02455691997-07-17 16:21:52 +0000400%
401Complex numbers are also supported; imaginary numbers are written with
402a suffix of \code{'j'} or \code{'J'}. Complex numbers with a nonzero
403real component are written as \code{(\var{real}+\var{imag}j)}, or can
404be created with the \code{complex(\var{real}, \var{imag})} function.
405
406\bcode\begin{verbatim}
407>>> 1j * 1J
408(-1+0j)
409>>> 1j * complex(0,1)
410(-1+0j)
411>>> 3+1j*3
412(3+3j)
413>>> (3+1j)*3
414(9+3j)
415>>> (1+2j)/(1+1j)
416(1.5+0.5j)
417\end{verbatim}\ecode
418%
419Complex numbers are always represented as two floating point numbers,
420the real and imaginary part. To extract these parts from a complex
421number \code{z}, use \code{z.real} and \code{z.imag}.
422
423\bcode\begin{verbatim}
424>>> a=1.5+0.5j
425>>> a.real
4261.5
427>>> a.imag
4280.5
429\end{verbatim}\ecode
430%
431The conversion functions to floating point and integer
432(\code{float()}, \code{int()} and \code{long()}) don't work for
433complex numbers --- there is no one correct way to convert a complex
434number to a real number. Use \code{abs(z)} to get its magnitude (as a
435float) or \code{z.real} to get its real part.
436
437\bcode\begin{verbatim}
438>>> a=1.5+0.5j
439>>> float(a)
440Traceback (innermost last):
441 File "<stdin>", line 1, in ?
442TypeError: can't convert complex to float; use e.g. abs(z)
443>>> a.real
4441.5
445>>> abs(a)
4461.58113883008
447\end{verbatim}\ecode
448%
449In interactive mode, the last printed expression is assigned to the
450variable \code{_}. This means that when you are using Python as a
451desk calculator, it is somewhat easier to continue calculations, for
452example:
453
454\begin{verbatim}
455>>> tax = 17.5 / 100
456>>> price = 3.50
457>>> price * tax
4580.6125
459>>> price + _
4604.1125
461>>> round(_, 2)
4624.11
463\end{verbatim}
464
465This variable should be treated as read-only by the user. Don't
466explicitly assign a value to it --- you would create an independent
467local variable with the same name masking the built-in variable with
468its magic behavior.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000469
470\subsection{Strings}
471
Guido van Rossum02455691997-07-17 16:21:52 +0000472Besides numbers, Python can also manipulate strings, which can be
473expressed in several ways. They can be enclosed in single quotes or
474double quotes:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000475
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000476\bcode\begin{verbatim}
Guido van Rossume5f8b601995-01-04 19:12:49 +0000477>>> 'spam eggs'
478'spam eggs'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000479>>> 'doesn\'t'
Guido van Rossum6938f061994-08-01 12:22:53 +0000480"doesn't"
481>>> "doesn't"
482"doesn't"
483>>> '"Yes," he said.'
484'"Yes," he said.'
485>>> "\"Yes,\" he said."
486'"Yes," he said.'
487>>> '"Isn\'t," she said.'
488'"Isn\'t," she said.'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000489>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000490\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000491%
Guido van Rossum02455691997-07-17 16:21:52 +0000492String literals can span multiple lines in several ways. Newlines can be escaped with backslashes, e.g.
493
494\begin{verbatim}
495hello = "This is a rather long string containing\n\
496several lines of text just as you would do in C.\n\
497 Note that whitespace at the beginning of the line is\
498 significant.\n"
499print hello
500\end{verbatim}
501
502which would print the following:
503\begin{verbatim}
504This is a rather long string containing
505several lines of text just as you would do in C.
506 Note that whitespace at the beginning of the line is significant.
507\end{verbatim}
508
509Or, strings can be surrounded in a pair of matching triple-quotes:
510\code{"""} or \code {'''}. End of lines do not need to be escaped
511when using triple-quotes, but they will be included in the string.
512
513\begin{verbatim}
514print """
515Usage: thingy [OPTIONS]
516 -h Display this usage message
517 -H hostname Hostname to connect to
518"""
519\end{verbatim}
520
521produces the following output:
522
523\bcode\begin{verbatim}
524Usage: thingy [OPTIONS]
525 -h Display this usage message
526 -H hostname Hostname to connect to
527\end{verbatim}\ecode
528%
529The interpreter prints the result of string operations in the same way
530as they are typed for input: inside quotes, and with quotes and other
531funny characters escaped by backslashes, to show the precise
532value. The string is enclosed in double quotes if the string contains
533a single quote and no double quotes, else it's enclosed in single
Fred Drakeeee08cd1997-12-04 15:43:15 +0000534quotes. (The \code{print} statement, described later, can be used to
Guido van Rossum02455691997-07-17 16:21:52 +0000535write strings without quotes or escapes.)
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000536
Fred Drakeeee08cd1997-12-04 15:43:15 +0000537Strings can be concatenated (glued together) with the \code{+}
538operator, and repeated with \code{*}:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000539
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000540\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000541>>> word = 'Help' + 'A'
542>>> word
543'HelpA'
544>>> '<' + word*5 + '>'
545'<HelpAHelpAHelpAHelpAHelpA>'
546>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000547\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000548%
Guido van Rossum02455691997-07-17 16:21:52 +0000549Two string literals next to each other are automatically concatenated;
550the first line above could also have been written \code{word = 'Help'
551'A'}; this only works with two literals, not with arbitrary string expressions.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000552
Guido van Rossum02455691997-07-17 16:21:52 +0000553Strings can be subscripted (indexed); like in C, the first character
554of a string has subscript (index) 0. There is no separate character
555type; a character is simply a string of size one. Like in Icon,
Fred Drakeeee08cd1997-12-04 15:43:15 +0000556substrings can be specified with the \emph{slice} notation: two indices
Guido van Rossum02455691997-07-17 16:21:52 +0000557separated by a colon.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000558
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000559\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000560>>> word[4]
561'A'
562>>> word[0:2]
563'He'
564>>> word[2:4]
565'lp'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000566>>>
567\end{verbatim}\ecode
568%
569Slice indices have useful defaults; an omitted first index defaults to
570zero, an omitted second index defaults to the size of the string being
571sliced.
572
573\bcode\begin{verbatim}
574>>> word[:2] # The first two characters
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000575'He'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000576>>> word[2:] # All but the first two characters
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000577'lpA'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000578>>>
579\end{verbatim}\ecode
580%
Fred Drakeeee08cd1997-12-04 15:43:15 +0000581Here's a useful invariant of slice operations: \code{s[:i] + s[i:]}
582equals \code{s}.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000583
584\bcode\begin{verbatim}
585>>> word[:2] + word[2:]
586'HelpA'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000587>>> word[:3] + word[3:]
588'HelpA'
589>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000590\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000591%
592Degenerate slice indices are handled gracefully: an index that is too
593large is replaced by the string size, an upper bound smaller than the
594lower bound returns an empty string.
595
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000596\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000597>>> word[1:100]
598'elpA'
599>>> word[10:]
600''
601>>> word[2:1]
602''
603>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000604\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000605%
606Indices may be negative numbers, to start counting from the right.
607For example:
608
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000609\bcode\begin{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000610>>> word[-1] # The last character
611'A'
612>>> word[-2] # The last-but-one character
613'p'
614>>> word[-2:] # The last two characters
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000615'pA'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000616>>> word[:-2] # All but the last two characters
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000617'Hel'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000618>>>
619\end{verbatim}\ecode
620%
621But note that -0 is really the same as 0, so it does not count from
622the right!
623
624\bcode\begin{verbatim}
625>>> word[-0] # (since -0 equals 0)
626'H'
627>>>
628\end{verbatim}\ecode
629%
630Out-of-range negative slice indices are truncated, but don't try this
631for single-element (non-slice) indices:
632
633\bcode\begin{verbatim}
634>>> word[-100:]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000635'HelpA'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000636>>> word[-10] # error
Guido van Rossum6938f061994-08-01 12:22:53 +0000637Traceback (innermost last):
638 File "<stdin>", line 1
639IndexError: string index out of range
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000640>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000641\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000642%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000643The best way to remember how slices work is to think of the indices as
Fred Drakeeee08cd1997-12-04 15:43:15 +0000644pointing \emph{between} characters, with the left edge of the first
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000645character numbered 0. Then the right edge of the last character of a
Fred Drakeeee08cd1997-12-04 15:43:15 +0000646string of \var{n} characters has index \var{n}, for example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000647
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000648\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000649 +---+---+---+---+---+
650 | H | e | l | p | A |
651 +---+---+---+---+---+
652 0 1 2 3 4 5
653-5 -4 -3 -2 -1
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000654\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000655%
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000656The first row of numbers gives the position of the indices 0...5 in
657the string; the second row gives the corresponding negative indices.
Fred Drakeeee08cd1997-12-04 15:43:15 +0000658The slice from \var{i} to \var{j} consists of all characters between
659the edges labeled \var{i} and \var{j}, respectively.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000660
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000661For nonnegative indices, the length of a slice is the difference of
662the indices, if both are within bounds, e.g., the length of
Fred Drakeeee08cd1997-12-04 15:43:15 +0000663\code{word[1:3]} is 2.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000664
Fred Drakeeee08cd1997-12-04 15:43:15 +0000665The built-in function \code{len()} returns the length of a string:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000666
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000667\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000668>>> s = 'supercalifragilisticexpialidocious'
669>>> len(s)
67034
671>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000672\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000673
674\subsection{Lists}
675
Fred Drakeeee08cd1997-12-04 15:43:15 +0000676Python knows a number of \emph{compound} data types, used to group
677together other values. The most versatile is the \emph{list}, which
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000678can be written as a list of comma-separated values (items) between
679square brackets. List items need not all have the same type.
680
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000681\bcode\begin{verbatim}
Guido van Rossume5f8b601995-01-04 19:12:49 +0000682>>> a = ['spam', 'eggs', 100, 1234]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000683>>> a
Guido van Rossume5f8b601995-01-04 19:12:49 +0000684['spam', 'eggs', 100, 1234]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000685>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000686\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000687%
688Like string indices, list indices start at 0, and lists can be sliced,
689concatenated and so on:
690
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000691\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000692>>> a[0]
Guido van Rossume5f8b601995-01-04 19:12:49 +0000693'spam'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000694>>> a[3]
6951234
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000696>>> a[-2]
697100
698>>> a[1:-1]
Guido van Rossume5f8b601995-01-04 19:12:49 +0000699['eggs', 100]
700>>> a[:2] + ['bacon', 2*2]
701['spam', 'eggs', 'bacon', 4]
Guido van Rossum4410c751991-06-04 20:22:18 +0000702>>> 3*a[:3] + ['Boe!']
Guido van Rossume5f8b601995-01-04 19:12:49 +0000703['spam', 'eggs', 100, 'spam', 'eggs', 100, 'spam', 'eggs', 100, 'Boe!']
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000704>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000705\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000706%
Fred Drakeeee08cd1997-12-04 15:43:15 +0000707Unlike strings, which are \emph{immutable}, it is possible to change
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000708individual elements of a list:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000709
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000710\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000711>>> a
Guido van Rossume5f8b601995-01-04 19:12:49 +0000712['spam', 'eggs', 100, 1234]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000713>>> a[2] = a[2] + 23
714>>> a
Guido van Rossume5f8b601995-01-04 19:12:49 +0000715['spam', 'eggs', 123, 1234]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000716>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000717\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000718%
719Assignment to slices is also possible, and this can even change the size
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000720of the list:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000721
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000722\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000723>>> # Replace some items:
Guido van Rossum6938f061994-08-01 12:22:53 +0000724... a[0:2] = [1, 12]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000725>>> a
726[1, 12, 123, 1234]
727>>> # Remove some:
Guido van Rossum6938f061994-08-01 12:22:53 +0000728... a[0:2] = []
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000729>>> a
730[123, 1234]
731>>> # Insert some:
Guido van Rossum6938f061994-08-01 12:22:53 +0000732... a[1:1] = ['bletch', 'xyzzy']
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000733>>> a
734[123, 'bletch', 'xyzzy', 1234]
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000735>>> a[:0] = a # Insert (a copy of) itself at the beginning
736>>> a
737[123, 'bletch', 'xyzzy', 1234, 123, 'bletch', 'xyzzy', 1234]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000738>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000739\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000740%
Fred Drakeeee08cd1997-12-04 15:43:15 +0000741The built-in function \code{len()} also applies to lists:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000742
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000743\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000744>>> len(a)
Guido van Rossuma8d754e1992-01-07 16:44:35 +00007458
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000746>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000747\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000748%
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000749It is possible to nest lists (create lists containing other lists),
750for example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000751
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000752\bcode\begin{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000753>>> q = [2, 3]
754>>> p = [1, q, 4]
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000755>>> len(p)
7563
757>>> p[1]
758[2, 3]
759>>> p[1][0]
7602
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000761>>> p[1].append('xtra') # See section 5.1
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000762>>> p
763[1, [2, 3, 'xtra'], 4]
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000764>>> q
765[2, 3, 'xtra']
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000766>>>
767\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000768%
Fred Drakeeee08cd1997-12-04 15:43:15 +0000769Note that in the last example, \code{p[1]} and \code{q} really refer to
770the same object! We'll come back to \emph{object semantics} later.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000771
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000772\section{First Steps Towards Programming}
Guido van Rossum2292b8e1991-01-23 16:31:24 +0000773
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000774Of course, we can use Python for more complicated tasks than adding
775two and two together. For instance, we can write an initial
Fred Drakeeee08cd1997-12-04 15:43:15 +0000776subsequence of the \emph{Fibonacci} series as follows:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000777
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000778\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000779>>> # Fibonacci series:
Guido van Rossum6938f061994-08-01 12:22:53 +0000780... # the sum of two elements defines the next
781... a, b = 0, 1
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000782>>> while b < 10:
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000783... print b
784... a, b = b, a+b
785...
7861
7871
7882
7893
7905
7918
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000792>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000793\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000794%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000795This example introduces several new features.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000796
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000797\begin{itemize}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000798
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000799\item
Fred Drakeeee08cd1997-12-04 15:43:15 +0000800The first line contains a \emph{multiple assignment}: the variables
801\code{a} and \code{b} simultaneously get the new values 0 and 1. On the
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000802last line this is used again, demonstrating that the expressions on
803the right-hand side are all evaluated first before any of the
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000804assignments take place.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000805
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000806\item
Fred Drakeeee08cd1997-12-04 15:43:15 +0000807The \code{while} loop executes as long as the condition (here: \code{b <
Guido van Rossum16cd7f91994-10-06 10:29:26 +000080810}) remains true. In Python, like in C, any non-zero integer value is
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000809true; zero is false. The condition may also be a string or list value,
810in fact any sequence; anything with a non-zero length is true, empty
811sequences are false. The test used in the example is a simple
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000812comparison. The standard comparison operators are written the same as
Fred Drakeeee08cd1997-12-04 15:43:15 +0000813in C: \code{<}, \code{>}, \code{==}, \code{<=}, \code{>=} and \code{!=}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000814
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000815\item
Fred Drakeeee08cd1997-12-04 15:43:15 +0000816The \emph{body} of the loop is \emph{indented}: indentation is Python's
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000817way of grouping statements. Python does not (yet!) provide an
818intelligent input line editing facility, so you have to type a tab or
819space(s) for each indented line. In practice you will prepare more
820complicated input for Python with a text editor; most text editors have
821an auto-indent facility. When a compound statement is entered
822interactively, it must be followed by a blank line to indicate
823completion (since the parser cannot guess when you have typed the last
824line).
825
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000826\item
Fred Drakeeee08cd1997-12-04 15:43:15 +0000827The \code{print} statement writes the value of the expression(s) it is
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000828given. It differs from just writing the expression you want to write
829(as we did earlier in the calculator examples) in the way it handles
Guido van Rossum16cd7f91994-10-06 10:29:26 +0000830multiple expressions and strings. Strings are printed without quotes,
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000831and a space is inserted between items, so you can format things nicely,
832like this:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000833
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000834\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000835>>> i = 256*256
836>>> print 'The value of i is', i
837The value of i is 65536
838>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000839\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000840%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000841A trailing comma avoids the newline after the output:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000842
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000843\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000844>>> a, b = 0, 1
845>>> while b < 1000:
846... print b,
847... a, b = b, a+b
848...
8491 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
850>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000851\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000852%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000853Note that the interpreter inserts a newline before it prints the next
854prompt if the last line was not completed.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000855
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000856\end{itemize}
857
Guido van Rossum5e0759d1992-08-07 16:06:24 +0000858
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000859\chapter{More Control Flow Tools}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000860
Fred Drakeeee08cd1997-12-04 15:43:15 +0000861Besides the \code{while} statement just introduced, Python knows the
Guido van Rossum2292b8e1991-01-23 16:31:24 +0000862usual control flow statements known from other languages, with some
863twists.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000864
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000865\section{If Statements}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000866
Fred Drakeeee08cd1997-12-04 15:43:15 +0000867Perhaps the most well-known statement type is the \code{if} statement.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000868For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000869
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000870\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000871>>> if x < 0:
872... x = 0
873... print 'Negative changed to zero'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000874... elif x == 0:
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000875... print 'Zero'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000876... elif x == 1:
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000877... print 'Single'
878... else:
879... print 'More'
880...
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000881\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000882%
Fred Drakeeee08cd1997-12-04 15:43:15 +0000883There can be zero or more \code{elif} parts, and the \code{else} part is
884optional. The keyword `\code{elif}' is short for `\code{else if}', and is
885useful to avoid excessive indentation. An \code{if...elif...elif...}
886sequence is a substitute for the \emph{switch} or \emph{case} statements
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000887found in other languages.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000888
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000889\section{For Statements}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000890
Fred Drakeeee08cd1997-12-04 15:43:15 +0000891The \code{for} statement in Python differs a bit from what you may be
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000892used to in C or Pascal. Rather than always iterating over an
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000893arithmetic progression of numbers (like in Pascal), or leaving the user
Fred Drakeeee08cd1997-12-04 15:43:15 +0000894completely free in the iteration test and step (as C), Python's
895\code{for} statement iterates over the items of any sequence (e.g., a
896list or a string), in the order that they appear in the sequence. For
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000897example (no pun intended):
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000898
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000899\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000900>>> # Measure some strings:
Guido van Rossum6938f061994-08-01 12:22:53 +0000901... a = ['cat', 'window', 'defenestrate']
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000902>>> for x in a:
903... print x, len(x)
904...
905cat 3
906window 6
907defenestrate 12
908>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000909\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000910%
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000911It is not safe to modify the sequence being iterated over in the loop
912(this can only happen for mutable sequence types, i.e., lists). If
913you need to modify the list you are iterating over, e.g., duplicate
914selected items, you must iterate over a copy. The slice notation
915makes this particularly convenient:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000916
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000917\bcode\begin{verbatim}
918>>> for x in a[:]: # make a slice copy of the entire list
919... if len(x) > 6: a.insert(0, x)
920...
921>>> a
922['defenestrate', 'cat', 'window', 'defenestrate']
923>>>
924\end{verbatim}\ecode
Guido van Rossum2292b8e1991-01-23 16:31:24 +0000925
Fred Drakeeee08cd1997-12-04 15:43:15 +0000926\section{The \sectcode{range()} Function}
Guido van Rossum2292b8e1991-01-23 16:31:24 +0000927
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000928If you do need to iterate over a sequence of numbers, the built-in
Fred Drakeeee08cd1997-12-04 15:43:15 +0000929function \code{range()} comes in handy. It generates lists containing
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000930arithmetic progressions, e.g.:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000931
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000932\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000933>>> range(10)
934[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
935>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000936\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000937%
Fred Drakeeee08cd1997-12-04 15:43:15 +0000938The given end point is never part of the generated list; \code{range(10)}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000939generates a list of 10 values, exactly the legal indices for items of a
940sequence of length 10. It is possible to let the range start at another
941number, or to specify a different increment (even negative):
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000942
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000943\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000944>>> range(5, 10)
945[5, 6, 7, 8, 9]
946>>> range(0, 10, 3)
947[0, 3, 6, 9]
948>>> range(-10, -100, -30)
949[-10, -40, -70]
950>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000951\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000952%
Fred Drakeeee08cd1997-12-04 15:43:15 +0000953To iterate over the indices of a sequence, combine \code{range()} and
954\code{len()} as follows:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000955
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000956\bcode\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000957>>> a = ['Mary', 'had', 'a', 'little', 'lamb']
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000958>>> for i in range(len(a)):
959... print i, a[i]
960...
9610 Mary
9621 had
9632 a
9643 little
Guido van Rossum6fc178f1991-08-16 09:13:42 +00009654 lamb
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000966>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000967\end{verbatim}\ecode
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000968
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000969\section{Break and Continue Statements, and Else Clauses on Loops}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000970
Fred Drakeeee08cd1997-12-04 15:43:15 +0000971The \code{break} statement, like in C, breaks out of the smallest
972enclosing \code{for} or \code{while} loop.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000973
Fred Drakeeee08cd1997-12-04 15:43:15 +0000974The \code{continue} statement, also borrowed from C, continues with the
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000975next iteration of the loop.
976
Fred Drakeeee08cd1997-12-04 15:43:15 +0000977Loop statements may have an \code{else} clause; it is executed when the
978loop terminates through exhaustion of the list (with \code{for}) or when
979the condition becomes false (with \code{while}), but not when the loop is
980terminated by a \code{break} statement. This is exemplified by the
Guido van Rossumcfb45e41994-11-10 23:04:43 +0000981following loop, which searches for prime numbers:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000982
Guido van Rossum5ce78f11991-01-25 13:27:18 +0000983\bcode\begin{verbatim}
Guido van Rossum2292b8e1991-01-23 16:31:24 +0000984>>> for n in range(2, 10):
985... for x in range(2, n):
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000986... if n % x == 0:
Guido van Rossum2292b8e1991-01-23 16:31:24 +0000987... print n, 'equals', x, '*', n/x
988... break
989... else:
990... print n, 'is a prime number'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000991...
Guido van Rossum2292b8e1991-01-23 16:31:24 +00009922 is a prime number
9933 is a prime number
9944 equals 2 * 2
9955 is a prime number
9966 equals 2 * 3
9977 is a prime number
9988 equals 2 * 4
9999 equals 3 * 3
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001000>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001001\end{verbatim}\ecode
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001002
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001003\section{Pass Statements}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001004
Fred Drakeeee08cd1997-12-04 15:43:15 +00001005The \code{pass} statement does nothing.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001006It can be used when a statement is required syntactically but the
1007program requires no action.
1008For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001009
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001010\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001011>>> while 1:
1012... pass # Busy-wait for keyboard interrupt
1013...
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001014\end{verbatim}\ecode
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001015
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001016\section{Defining Functions}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001017
1018We can create a function that writes the Fibonacci series to an
1019arbitrary boundary:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001020
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001021\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001022>>> def fib(n): # write Fibonacci series up to n
Guido van Rossum02455691997-07-17 16:21:52 +00001023... "Print a Fibonacci series up to n"
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001024... a, b = 0, 1
Guido van Rossum16cd7f91994-10-06 10:29:26 +00001025... while b < n:
Fred Drakeeee08cd1997-12-04 15:43:15 +00001026... print b,
1027... a, b = b, a+b
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001028...
1029>>> # Now call the function we just defined:
Guido van Rossum6938f061994-08-01 12:22:53 +00001030... fib(2000)
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000010311 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597
1032>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001033\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001034%
Fred Drakeeee08cd1997-12-04 15:43:15 +00001035The keyword \code{def} introduces a function \emph{definition}. It must
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001036be followed by the function name and the parenthesized list of formal
Guido van Rossum02455691997-07-17 16:21:52 +00001037parameters. The statements that form the body of the function start
1038at the next line, indented by a tab stop. The first statement of the
1039function body can optionally be a string literal; this string literal
1040is the function's documentation string, or \dfn{docstring}. There are
1041tools which use docstrings to automatically produce printed
1042documentation, or to let the user interactively browse through code;
1043it's good practice to include docstrings in code that you write, so
1044try to make a habit of it.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001045
Fred Drakeeee08cd1997-12-04 15:43:15 +00001046The \emph{execution} of a function introduces a new symbol table used
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001047for the local variables of the function. More precisely, all variable
1048assignments in a function store the value in the local symbol table;
Guido van Rossum02455691997-07-17 16:21:52 +00001049whereas variable 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.
Guido van Rossum02455691997-07-17 16:21:52 +00001051Thus,
Guido van Rossumcfb45e41994-11-10 23:04:43 +00001052global variables cannot be directly assigned a value within a
Fred Drakeeee08cd1997-12-04 15:43:15 +00001053function (unless named in a \code{global} statement), although
Guido van Rossum6938f061994-08-01 12:22:53 +00001054they 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,
Fred Drakeeee08cd1997-12-04 15:43:15 +00001058arguments are passed using \emph{call by value}.%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001059\footnote{
Fred Drakeeee08cd1997-12-04 15:43:15 +00001060 Actually, \emph{call by object reference} would be a better
Guido van Rossum6938f061994-08-01 12:22:53 +00001061 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%
Fred Drakeeee08cd1997-12-04 15:43:15 +00001086You might object that \code{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,
Fred Drakeeee08cd1997-12-04 15:43:15 +00001089albeit a rather boring one. This value is called \code{None} (it's a
1090built-in name). Writing the value \code{None} is normally suppressed by
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001091the 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 Rossum02455691997-07-17 16:21:52 +00001105... "Return a list containing the Fibonacci series up to n"
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001106... result = []
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001107... a, b = 0, 1
Guido van Rossum16cd7f91994-10-06 10:29:26 +00001108... while b < n:
Fred Drakeeee08cd1997-12-04 15:43:15 +00001109... result.append(b) # see below
1110... a, b = b, a+b
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001111... return result
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001112...
1113>>> f100 = fib2(100) # call it
1114>>> f100 # write the result
1115[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
1116>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001117\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001118%
Guido van Rossum4410c751991-06-04 20:22:18 +00001119This example, as usual, demonstrates some new Python features:
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001120
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001121\begin{itemize}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001122
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001123\item
Fred Drakeeee08cd1997-12-04 15:43:15 +00001124The \code{return} statement returns with a value from a function.
1125\code{return} without an expression argument is used to return from
1126the middle of a procedure (falling off the end also returns from a
1127procedure), in which case the \code{None} value is returned.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001128
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001129\item
Fred Drakeeee08cd1997-12-04 15:43:15 +00001130The statement \code{result.append(b)} calls a \emph{method} of the list
1131object \code{result}. A method is a function that `belongs' to an
1132object and is named \code{obj.methodname}, where \code{obj} is some
1133object (this may be an expression), and \code{methodname} is the name
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001134of a method that is defined by the object's type. Different types
1135define different methods. Methods of different types may have the
1136same name without causing ambiguity. (It is possible to define your
Fred Drakeeee08cd1997-12-04 15:43:15 +00001137own object types and methods, using \emph{classes}, as discussed later
Guido van Rossum6938f061994-08-01 12:22:53 +00001138in this tutorial.)
Fred Drakeeee08cd1997-12-04 15:43:15 +00001139The method \code{append} shown in the example, is defined for
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001140list objects; it adds a new element at the end of the list. In this
1141example
Fred Drakeeee08cd1997-12-04 15:43:15 +00001142it is equivalent to \code{result = result + [b]}, but more efficient.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001143
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001144\end{itemize}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001145
Guido van Rossum02455691997-07-17 16:21:52 +00001146\section{More on Defining Functions}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00001147
Guido van Rossum02455691997-07-17 16:21:52 +00001148It is also possible to define functions with a variable number of
1149arguments. There are three forms, which can be combined.
1150
1151\subsection{Default Argument Values}
1152
1153The most useful form is to specify a default value for one or more
1154arguments. This creates a function that can be called with fewer
1155arguments than it is defined, e.g.
1156
1157\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00001158 def ask_ok(prompt, retries=4, complaint='Yes or no, please!'):
1159 while 1:
1160 ok = raw_input(prompt)
1161 if ok in ('y', 'ye', 'yes'): return 1
1162 if ok in ('n', 'no', 'nop', 'nope'): return 0
1163 retries = retries - 1
1164 if retries < 0: raise IOError, 'refusenik user'
1165 print complaint
Guido van Rossum02455691997-07-17 16:21:52 +00001166\end{verbatim}
1167
1168This function can be called either like this:
Fred Drakeeee08cd1997-12-04 15:43:15 +00001169\code{ask_ok('Do you really want to quit?')} or like this:
1170\code{ask_ok('OK to overwrite the file?', 2)}.
Guido van Rossum02455691997-07-17 16:21:52 +00001171
1172The default values are evaluated at the point of function definition
Fred Drakeeee08cd1997-12-04 15:43:15 +00001173in the \emph{defining} scope, so that e.g.
Guido van Rossum02455691997-07-17 16:21:52 +00001174
1175\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00001176 i = 5
1177 def f(arg = i): print arg
1178 i = 6
1179 f()
Guido van Rossum02455691997-07-17 16:21:52 +00001180\end{verbatim}
1181
Fred Drakeeee08cd1997-12-04 15:43:15 +00001182will print \code{5}.
Guido van Rossum02455691997-07-17 16:21:52 +00001183
1184\subsection{Keyword Arguments}
1185
1186Functions can also be called using
1187keyword arguments of the form \code{\var{keyword} = \var{value}}. For
1188instance, the following function:
1189
1190\begin{verbatim}
1191def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
1192 print "-- This parrot wouldn't", action,
1193 print "if you put", voltage, "Volts through it."
1194 print "-- Lovely plumage, the", type
1195 print "-- It's", state, "!"
1196\end{verbatim}
1197
1198could be called in any of the following ways:
1199
1200\begin{verbatim}
1201parrot(1000)
1202parrot(action = 'VOOOOOM', voltage = 1000000)
1203parrot('a thousand', state = 'pushing up the daisies')
1204parrot('a million', 'bereft of life', 'jump')
1205\end{verbatim}
1206
1207but the following calls would all be invalid:
1208
1209\begin{verbatim}
1210parrot() # required argument missing
1211parrot(voltage=5.0, 'dead') # non-keyword argument following keyword
1212parrot(110, voltage=220) # duplicate value for argument
1213parrot(actor='John Cleese') # unknown keyword
1214\end{verbatim}
1215
1216In general, an argument list must have any positional arguments
1217followed by any keyword arguments, where the keywords must be chosen
1218from the formal parameter names. It's not important whether a formal
1219parameter has a default value or not. No argument must receive a
1220value more than once --- formal parameter names corresponding to
1221positional arguments cannot be used as keywords in the same calls.
1222
1223When a final formal parameter of the form \code{**\var{name}} is
1224present, it receives a dictionary containing all keyword arguments
1225whose keyword doesn't correspond to a formal parameter. This may be
1226combined with a formal parameter of the form \code{*\var{name}}
1227(described in the next subsection) which receives a tuple containing
1228the positional arguments beyond the formal parameter list.
1229(\code{*\var{name}} must occur before \code{**\var{name}}.) For
1230example, if we define a function like this:
1231
1232\begin{verbatim}
1233def cheeseshop(kind, *arguments, **keywords):
1234 print "-- Do you have any", kind, '?'
1235 print "-- I'm sorry, we're all out of", kind
1236 for arg in arguments: print arg
1237 print '-'*40
1238 for kw in keywords.keys(): print kw, ':', keywords[kw]
1239\end{verbatim}
1240
1241It could be called like this:
1242
1243\begin{verbatim}
1244cheeseshop('Limburger', "It's very runny, sir.",
1245 "It's really very, VERY runny, sir.",
1246 client='John Cleese',
1247 shopkeeper='Michael Palin',
1248 sketch='Cheese Shop Sketch')
1249\end{verbatim}
1250
1251and of course it would print:
1252
1253\begin{verbatim}
1254-- Do you have any Limburger ?
1255-- I'm sorry, we're all out of Limburger
1256It's very runny, sir.
1257It's really very, VERY runny, sir.
1258----------------------------------------
1259client : John Cleese
1260shopkeeper : Michael Palin
1261sketch : Cheese Shop Sketch
1262\end{verbatim}
1263
1264\subsection{Arbitrary Argument Lists}
1265
1266Finally, the least frequently used option is to specify that a
1267function can be called with an arbitrary number of arguments. These
1268arguments will be wrapped up in a tuple. Before the variable number
1269of arguments, zero or more normal arguments may occur.
1270
1271\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00001272 def fprintf(file, format, *args):
1273 file.write(format % args)
Guido van Rossum02455691997-07-17 16:21:52 +00001274\end{verbatim}
1275
1276\chapter{Data Structures}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001277
1278This chapter describes some things you've learned about already in
1279more detail, and adds some new things as well.
1280
1281\section{More on Lists}
1282
1283The list data type has some more methods. Here are all of the methods
1284of lists objects:
1285
Guido van Rossum7d9f8d71991-01-22 11:45:00 +00001286\begin{description}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001287
Fred Drakeeee08cd1997-12-04 15:43:15 +00001288\item[\code{insert(i, x)}]
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001289Insert an item at a given position. The first argument is the index of
Fred Drakeeee08cd1997-12-04 15:43:15 +00001290the element before which to insert, so \code{a.insert(0, x)} inserts at
1291the front of the list, and \code{a.insert(len(a), x)} is equivalent to
1292\code{a.append(x)}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001293
Fred Drakeeee08cd1997-12-04 15:43:15 +00001294\item[\code{append(x)}]
1295Equivalent to \code{a.insert(len(a), x)}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001296
Fred Drakeeee08cd1997-12-04 15:43:15 +00001297\item[\code{index(x)}]
1298Return the index in the list of the first item whose value is \code{x}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001299It is an error if there is no such item.
1300
Fred Drakeeee08cd1997-12-04 15:43:15 +00001301\item[\code{remove(x)}]
1302Remove the first item from the list whose value is \code{x}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001303It is an error if there is no such item.
1304
Fred Drakeeee08cd1997-12-04 15:43:15 +00001305\item[\code{sort()}]
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001306Sort the items of the list, in place.
1307
Fred Drakeeee08cd1997-12-04 15:43:15 +00001308\item[\code{reverse()}]
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001309Reverse the elements of the list, in place.
1310
Fred Drakeeee08cd1997-12-04 15:43:15 +00001311\item[\code{count(x)}]
1312Return the number of times \code{x} appears in the list.
Guido van Rossum6938f061994-08-01 12:22:53 +00001313
Guido van Rossum7d9f8d71991-01-22 11:45:00 +00001314\end{description}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001315
1316An example that uses all list methods:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001317
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001318\bcode\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001319>>> a = [66.6, 333, 333, 1, 1234.5]
Guido van Rossum6938f061994-08-01 12:22:53 +00001320>>> print a.count(333), a.count(66.6), a.count('x')
13212 1 0
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001322>>> a.insert(2, -1)
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001323>>> a.append(333)
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001324>>> a
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001325[66.6, 333, -1, 333, 1, 1234.5, 333]
1326>>> a.index(333)
13271
1328>>> a.remove(333)
1329>>> a
1330[66.6, -1, 333, 1, 1234.5, 333]
1331>>> a.reverse()
1332>>> a
1333[333, 1234.5, 1, 333, -1, 66.6]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001334>>> a.sort()
1335>>> a
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001336[-1, 1, 66.6, 333, 333, 1234.5]
1337>>>
1338\end{verbatim}\ecode
1339
Guido van Rossum02455691997-07-17 16:21:52 +00001340\subsection{Functional Programming Tools}
1341
1342There are three built-in functions that are very useful when used with
Fred Drakeeee08cd1997-12-04 15:43:15 +00001343lists: \code{filter()}, \code{map()}, and \code{reduce()}.
Guido van Rossum02455691997-07-17 16:21:52 +00001344
Fred Drakeeee08cd1997-12-04 15:43:15 +00001345\code{filter(function, sequence)} returns a sequence (of the same
Guido van Rossum02455691997-07-17 16:21:52 +00001346type, if possible) consisting of those items from the sequence for
Fred Drakeeee08cd1997-12-04 15:43:15 +00001347which \code{function(item)} is true. For example, to compute some
Guido van Rossum02455691997-07-17 16:21:52 +00001348primes:
1349
1350\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00001351 >>> def f(x): return x%2 != 0 and x%3 != 0
1352 ...
1353 >>> filter(f, range(2, 25))
1354 [5, 7, 11, 13, 17, 19, 23]
1355 >>>
Guido van Rossum02455691997-07-17 16:21:52 +00001356\end{verbatim}
1357
Fred Drakeeee08cd1997-12-04 15:43:15 +00001358\code{map(function, sequence)} calls \code{function(item)} for each of
Guido van Rossum02455691997-07-17 16:21:52 +00001359the sequence's items and returns a list of the return values. For
1360example, to compute some cubes:
1361
1362\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00001363 >>> def cube(x): return x*x*x
1364 ...
1365 >>> map(cube, range(1, 11))
1366 [1, 8, 27, 64, 125, 216, 343, 512, 729, 1000]
1367 >>>
Guido van Rossum02455691997-07-17 16:21:52 +00001368\end{verbatim}
1369
1370More than one sequence may be passed; the function must then have as
1371many arguments as there are sequences and is called with the
1372corresponding item from each sequence (or \verb\None\ if some sequence
1373is shorter than another). If \verb\None\ is passed for the function,
1374a function returning its argument(s) is substituted.
1375
1376Combining these two special cases, we see that
1377\verb\map(None, list1, list2)\ is a convenient way of turning a pair
1378of lists into a list of pairs. For example:
1379
1380\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00001381 >>> seq = range(8)
1382 >>> def square(x): return x*x
1383 ...
1384 >>> map(None, seq, map(square, seq))
1385 [(0, 0), (1, 1), (2, 4), (3, 9), (4, 16), (5, 25), (6, 36), (7, 49)]
1386 >>>
Guido van Rossum02455691997-07-17 16:21:52 +00001387\end{verbatim}
1388
1389\verb\reduce(func, sequence)\ returns a single value constructed
1390by calling the binary function \verb\func\ on the first two items of the
1391sequence, then on the result and the next item, and so on. For
1392example, to compute the sum of the numbers 1 through 10:
1393
1394\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00001395 >>> def add(x,y): return x+y
1396 ...
1397 >>> reduce(add, range(1, 11))
1398 55
1399 >>>
Guido van Rossum02455691997-07-17 16:21:52 +00001400\end{verbatim}
1401
1402If there's only one item in the sequence, its value is returned; if
1403the sequence is empty, an exception is raised.
1404
1405A third argument can be passed to indicate the starting value. In this
1406case the starting value is returned for an empty sequence, and the
1407function is first applied to the starting value and the first sequence
1408item, then to the result and the next item, and so on. For example,
1409
1410\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00001411 >>> def sum(seq):
1412 ... def add(x,y): return x+y
1413 ... return reduce(add, seq, 0)
1414 ...
1415 >>> sum(range(1, 11))
1416 55
1417 >>> sum([])
1418 0
1419 >>>
Guido van Rossum02455691997-07-17 16:21:52 +00001420\end{verbatim}
1421
Fred Drakeeee08cd1997-12-04 15:43:15 +00001422\section{The \sectcode{del} statement}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001423
1424There is a way to remove an item from a list given its index instead
Fred Drakeeee08cd1997-12-04 15:43:15 +00001425of its value: the \code{del} statement. This can also be used to
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001426remove slices from a list (which we did earlier by assignment of an
1427empty list to the slice). For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001428
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001429\bcode\begin{verbatim}
1430>>> a
1431[-1, 1, 66.6, 333, 333, 1234.5]
1432>>> del a[0]
1433>>> a
1434[1, 66.6, 333, 333, 1234.5]
1435>>> del a[2:4]
1436>>> a
1437[1, 66.6, 1234.5]
1438>>>
1439\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001440%
Fred Drakeeee08cd1997-12-04 15:43:15 +00001441\code{del} can also be used to delete entire variables:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001442
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001443\bcode\begin{verbatim}
1444>>> del a
1445>>>
1446\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001447%
Fred Drakeeee08cd1997-12-04 15:43:15 +00001448Referencing the name \code{a} hereafter is an error (at least until
1449another value is assigned to it). We'll find other uses for \code{del}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001450later.
1451
1452\section{Tuples and Sequences}
1453
1454We saw that lists and strings have many common properties, e.g.,
Fred Drakeeee08cd1997-12-04 15:43:15 +00001455indexing and slicing operations. They are two examples of
1456\emph{sequence} data types. Since Python is an evolving language,
1457other sequence data types may be added. There is also another
1458standard sequence data type: the \emph{tuple}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001459
1460A tuple consists of a number of values separated by commas, for
1461instance:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001462
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001463\bcode\begin{verbatim}
1464>>> t = 12345, 54321, 'hello!'
1465>>> t[0]
146612345
1467>>> t
1468(12345, 54321, 'hello!')
1469>>> # Tuples may be nested:
Guido van Rossum6938f061994-08-01 12:22:53 +00001470... u = t, (1, 2, 3, 4, 5)
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001471>>> u
1472((12345, 54321, 'hello!'), (1, 2, 3, 4, 5))
1473>>>
1474\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001475%
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001476As you see, on output tuples are alway enclosed in parentheses, so
1477that nested tuples are interpreted correctly; they may be input with
1478or without surrounding parentheses, although often parentheses are
1479necessary anyway (if the tuple is part of a larger expression).
1480
1481Tuples have many uses, e.g., (x, y) coordinate pairs, employee records
1482from a database, etc. Tuples, like strings, are immutable: it is not
1483possible to assign to the individual items of a tuple (you can
1484simulate much of the same effect with slicing and concatenation,
1485though).
1486
1487A special problem is the construction of tuples containing 0 or 1
Guido van Rossum6938f061994-08-01 12:22:53 +00001488items: the syntax has some extra quirks to accommodate these. Empty
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001489tuples are constructed by an empty pair of parentheses; a tuple with
1490one item is constructed by following a value with a comma
1491(it is not sufficient to enclose a single value in parentheses).
1492Ugly, but effective. For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001493
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001494\bcode\begin{verbatim}
1495>>> empty = ()
1496>>> singleton = 'hello', # <-- note trailing comma
1497>>> len(empty)
14980
1499>>> len(singleton)
15001
1501>>> singleton
1502('hello',)
1503>>>
1504\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001505%
Fred Drakeeee08cd1997-12-04 15:43:15 +00001506The statement \code{t = 12345, 54321, 'hello!'} is an example of
1507\emph{tuple packing}: the values \code{12345}, \code{54321} and
1508\code{'hello!'} are packed together in a tuple. The reverse operation
1509is also possible, e.g.:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001510
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001511\bcode\begin{verbatim}
1512>>> x, y, z = t
1513>>>
1514\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001515%
Fred Drakeeee08cd1997-12-04 15:43:15 +00001516This is called, appropriately enough, \emph{tuple unpacking}. Tuple
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001517unpacking requires that the list of variables on the left has the same
1518number of elements as the length of the tuple. Note that multiple
1519assignment is really just a combination of tuple packing and tuple
1520unpacking!
1521
Fred Drakeeee08cd1997-12-04 15:43:15 +00001522Occasionally, the corresponding operation on lists is useful: \emph{list
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001523unpacking}. This is supported by enclosing the list of variables in
1524square brackets:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001525
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001526\bcode\begin{verbatim}
Guido van Rossume5f8b601995-01-04 19:12:49 +00001527>>> a = ['spam', 'eggs', 100, 1234]
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001528>>> [a1, a2, a3, a4] = a
1529>>>
1530\end{verbatim}\ecode
1531
1532\section{Dictionaries}
1533
Fred Drakeeee08cd1997-12-04 15:43:15 +00001534Another useful data type built into Python is the \emph{dictionary}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001535Dictionaries are sometimes found in other languages as ``associative
1536memories'' or ``associative arrays''. Unlike sequences, which are
Fred Drakeeee08cd1997-12-04 15:43:15 +00001537indexed by a range of numbers, dictionaries are indexed by \emph{keys},
Guido van Rossum02455691997-07-17 16:21:52 +00001538which can be any non-mutable type; strings and numbers can always be
1539keys. Tuples can be used as keys if they contain only strings,
1540numbers, or tuples. You can't use lists as keys, since lists can be
1541modified in place using their \code{append()} method.
1542
Guido van Rossum6938f061994-08-01 12:22:53 +00001543It is best to think of a dictionary as an unordered set of
Fred Drakeeee08cd1997-12-04 15:43:15 +00001544\emph{key:value} pairs, with the requirement that the keys are unique
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001545(within one dictionary).
Fred Drakeeee08cd1997-12-04 15:43:15 +00001546A pair of braces creates an empty dictionary: \code{\{\}}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001547Placing a comma-separated list of key:value pairs within the
1548braces adds initial key:value pairs to the dictionary; this is also the
1549way dictionaries are written on output.
1550
1551The main operations on a dictionary are storing a value with some key
1552and extracting the value given the key. It is also possible to delete
1553a key:value pair
Fred Drakeeee08cd1997-12-04 15:43:15 +00001554with \code{del}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001555If you store using a key that is already in use, the old value
1556associated with that key is forgotten. It is an error to extract a
Guido van Rossum6938f061994-08-01 12:22:53 +00001557value using a non-existent key.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001558
Fred Drakeeee08cd1997-12-04 15:43:15 +00001559The \code{keys()} method of a dictionary object returns a list of all the
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001560keys used in the dictionary, in random order (if you want it sorted,
Fred Drakeeee08cd1997-12-04 15:43:15 +00001561just apply the \code{sort()} method to the list of keys). To check
1562whether a single key is in the dictionary, use the \code{has_key()}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001563method of the dictionary.
1564
1565Here is a small example using a dictionary:
1566
1567\bcode\begin{verbatim}
1568>>> tel = {'jack': 4098, 'sape': 4139}
1569>>> tel['guido'] = 4127
1570>>> tel
Guido van Rossum8f96f771991-11-12 15:45:03 +00001571{'sape': 4139, 'guido': 4127, 'jack': 4098}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001572>>> tel['jack']
15734098
1574>>> del tel['sape']
1575>>> tel['irv'] = 4127
1576>>> tel
Guido van Rossum8f96f771991-11-12 15:45:03 +00001577{'guido': 4127, 'irv': 4127, 'jack': 4098}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001578>>> tel.keys()
1579['guido', 'irv', 'jack']
1580>>> tel.has_key('guido')
15811
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001582>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001583\end{verbatim}\ecode
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001584
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001585\section{More on Conditions}
1586
Fred Drakeeee08cd1997-12-04 15:43:15 +00001587The conditions used in \code{while} and \code{if} statements above can
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001588contain other operators besides comparisons.
1589
Fred Drakeeee08cd1997-12-04 15:43:15 +00001590The comparison operators \code{in} and \code{not in} check whether a value
1591occurs (does not occur) in a sequence. The operators \code{is} and
1592\code{is not} compare whether two objects are really the same object; this
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001593only matters for mutable objects like lists. All comparison operators
1594have the same priority, which is lower than that of all numerical
1595operators.
1596
Fred Drakeeee08cd1997-12-04 15:43:15 +00001597Comparisons can be chained: e.g., \code{a < b == c} tests whether \code{a}
1598is less than \code{b} and moreover \code{b} equals \code{c}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001599
Fred Drakeeee08cd1997-12-04 15:43:15 +00001600Comparisons may be combined by the Boolean operators \code{and} and
1601\code{or}, and the outcome of a comparison (or of any other Boolean
1602expression) may be negated with \code{not}. These all have lower
1603priorities than comparison operators again; between them, \code{not} has
1604the highest priority, and \code{or} the lowest, so that
1605\code{A and not B or C} is equivalent to \code{(A and (not B)) or C}. Of
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001606course, parentheses can be used to express the desired composition.
1607
Fred Drakeeee08cd1997-12-04 15:43:15 +00001608The Boolean operators \code{and} and \code{or} are so-called
1609\emph{shortcut} operators: their arguments are evaluated from left to
1610right, and evaluation stops as soon as the outcome is determined.
1611E.g., if \code{A} and \code{C} are true but \code{B} is false, \code{A
1612and B and C} does not evaluate the expression C. In general, the
1613return value of a shortcut operator, when used as a general value and
1614not as a Boolean, is the last evaluated argument.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001615
1616It is possible to assign the result of a comparison or other Boolean
Guido van Rossum6938f061994-08-01 12:22:53 +00001617expression to a variable. For example,
1618
1619\bcode\begin{verbatim}
1620>>> string1, string2, string3 = '', 'Trondheim', 'Hammer Dance'
1621>>> non_null = string1 or string2 or string3
1622>>> non_null
1623'Trondheim'
1624>>>
1625\end{verbatim}\ecode
1626%
1627Note that in Python, unlike C, assignment cannot occur inside expressions.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001628
1629\section{Comparing Sequences and Other Types}
1630
1631Sequence objects may be compared to other objects with the same
Fred Drakeeee08cd1997-12-04 15:43:15 +00001632sequence type. The comparison uses \emph{lexicographical} ordering:
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001633first the first two items are compared, and if they differ this
1634determines the outcome of the comparison; if they are equal, the next
1635two items are compared, and so on, until either sequence is exhausted.
1636If two items to be compared are themselves sequences of the same type,
Guido van Rossum6938f061994-08-01 12:22:53 +00001637the lexicographical comparison is carried out recursively. If all
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001638items of two sequences compare equal, the sequences are considered
1639equal. If one sequence is an initial subsequence of the other, the
1640shorted sequence is the smaller one. Lexicographical ordering for
Guido van Rossum47b4c0f1995-03-15 11:25:32 +00001641strings uses the \ASCII{} ordering for individual characters. Some
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001642examples of comparisons between sequences with the same types:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001643
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001644\bcode\begin{verbatim}
1645(1, 2, 3) < (1, 2, 4)
1646[1, 2, 3] < [1, 2, 4]
1647'ABC' < 'C' < 'Pascal' < 'Python'
1648(1, 2, 3, 4) < (1, 2, 4)
1649(1, 2) < (1, 2, -1)
1650(1, 2, 3) = (1.0, 2.0, 3.0)
1651(1, 2, ('aa', 'ab')) < (1, 2, ('abc', 'a'), 4)
1652\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001653%
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001654Note that comparing objects of different types is legal. The outcome
1655is deterministic but arbitrary: the types are ordered by their name.
1656Thus, a list is always smaller than a string, a string is always
1657smaller than a tuple, etc. Mixed numeric types are compared according
1658to their numeric value, so 0 equals 0.0, etc.%
1659\footnote{
Guido van Rossum6938f061994-08-01 12:22:53 +00001660 The rules for comparing objects of different types should
1661 not be relied upon; they may change in a future version of
1662 the language.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001663}
1664
Guido van Rossum5e0759d1992-08-07 16:06:24 +00001665
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001666\chapter{Modules}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001667
Guido van Rossum4410c751991-06-04 20:22:18 +00001668If you quit from the Python interpreter and enter it again, the
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001669definitions you have made (functions and variables) are lost.
1670Therefore, if you want to write a somewhat longer program, you are
1671better off using a text editor to prepare the input for the interpreter
Guido van Rossum16d6e711994-08-08 12:30:22 +00001672and running it with that file as input instead. This is known as creating a
Fred Drakeeee08cd1997-12-04 15:43:15 +00001673\emph{script}. As your program gets longer, you may want to split it
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001674into several files for easier maintenance. You may also want to use a
1675handy function that you've written in several programs without copying
1676its definition into each program.
1677
Guido van Rossum4410c751991-06-04 20:22:18 +00001678To support this, Python has a way to put definitions in a file and use
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001679them in a script or in an interactive instance of the interpreter.
Fred Drakeeee08cd1997-12-04 15:43:15 +00001680Such a file is called a \emph{module}; definitions from a module can be
1681\emph{imported} into other modules or into the \emph{main} module (the
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001682collection of variables that you have access to in a script
1683executed at the top level
1684and in calculator mode).
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001685
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001686A module is a file containing Python definitions and statements. The
Fred Drakeeee08cd1997-12-04 15:43:15 +00001687file name is the module name with the suffix \file{.py} appended. Within
Guido van Rossum6938f061994-08-01 12:22:53 +00001688a module, the module's name (as a string) is available as the value of
Fred Drakeeee08cd1997-12-04 15:43:15 +00001689the global variable \code{__name__}. For instance, use your favorite text
1690editor to create a file called \file{fibo.py} in the current directory
Guido van Rossum6938f061994-08-01 12:22:53 +00001691with the following contents:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001692
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001693\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001694# Fibonacci numbers module
1695
1696def fib(n): # write Fibonacci series up to n
1697 a, b = 0, 1
Guido van Rossum16cd7f91994-10-06 10:29:26 +00001698 while b < n:
Fred Drakeeee08cd1997-12-04 15:43:15 +00001699 print b,
1700 a, b = b, a+b
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001701
1702def fib2(n): # return Fibonacci series up to n
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001703 result = []
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001704 a, b = 0, 1
Guido van Rossum16cd7f91994-10-06 10:29:26 +00001705 while b < n:
Fred Drakeeee08cd1997-12-04 15:43:15 +00001706 result.append(b)
1707 a, b = b, a+b
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001708 return result
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001709\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001710%
Guido van Rossum4410c751991-06-04 20:22:18 +00001711Now enter the Python interpreter and import this module with the
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001712following command:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001713
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001714\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001715>>> import fibo
1716>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001717\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001718%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001719This does not enter the names of the functions defined in
Fred Drakeeee08cd1997-12-04 15:43:15 +00001720\code{fibo}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001721directly in the current symbol table; it only enters the module name
Fred Drakeeee08cd1997-12-04 15:43:15 +00001722\code{fibo}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001723there.
1724Using the module name you can access the functions:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001725
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001726\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001727>>> fibo.fib(1000)
17281 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
1729>>> fibo.fib2(100)
1730[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
Guido van Rossum6938f061994-08-01 12:22:53 +00001731>>> fibo.__name__
1732'fibo'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001733>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001734\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001735%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001736If you intend to use a function often you can assign it to a local name:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001737
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001738\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001739>>> fib = fibo.fib
1740>>> fib(500)
17411 1 2 3 5 8 13 21 34 55 89 144 233 377
1742>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001743\end{verbatim}\ecode
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001744
Guido van Rossum02455691997-07-17 16:21:52 +00001745
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001746\section{More on Modules}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001747
1748A module can contain executable statements as well as function
1749definitions.
1750These statements are intended to initialize the module.
1751They are executed only the
Fred Drakeeee08cd1997-12-04 15:43:15 +00001752\emph{first}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001753time the module is imported somewhere.%
1754\footnote{
Guido van Rossum6938f061994-08-01 12:22:53 +00001755 In fact function definitions are also `statements' that are
1756 `executed'; the execution enters the function name in the
1757 module's global symbol table.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001758}
1759
1760Each module has its own private symbol table, which is used as the
1761global symbol table by all functions defined in the module.
1762Thus, the author of a module can use global variables in the module
1763without worrying about accidental clashes with a user's global
1764variables.
1765On the other hand, if you know what you are doing you can touch a
1766module's global variables with the same notation used to refer to its
1767functions,
Fred Drakeeee08cd1997-12-04 15:43:15 +00001768\code{modname.itemname}.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001769
1770Modules can import other modules.
1771It is customary but not required to place all
Fred Drakeeee08cd1997-12-04 15:43:15 +00001772\code{import}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001773statements at the beginning of a module (or script, for that matter).
1774The imported module names are placed in the importing module's global
1775symbol table.
1776
1777There is a variant of the
Fred Drakeeee08cd1997-12-04 15:43:15 +00001778\code{import}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001779statement that imports names from a module directly into the importing
1780module's symbol table.
1781For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001782
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001783\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001784>>> from fibo import fib, fib2
1785>>> fib(500)
17861 1 2 3 5 8 13 21 34 55 89 144 233 377
1787>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001788\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001789%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001790This does not introduce the module name from which the imports are taken
Fred Drakeeee08cd1997-12-04 15:43:15 +00001791in the local symbol table (so in the example, \code{fibo} is not
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001792defined).
1793
1794There is even a variant to import all names that a module defines:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001795
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001796\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001797>>> from fibo import *
1798>>> fib(500)
17991 1 2 3 5 8 13 21 34 55 89 144 233 377
1800>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001801\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001802%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001803This imports all names except those beginning with an underscore
Fred Drakeeee08cd1997-12-04 15:43:15 +00001804(\code{_}).
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001805
Guido van Rossum02455691997-07-17 16:21:52 +00001806\subsection{The Module Search Path}
1807
Fred Drakeeee08cd1997-12-04 15:43:15 +00001808When a module named \code{spam} is imported, the interpreter searches
1809for a file named \file{spam.py} in the current directory,
Guido van Rossum02455691997-07-17 16:21:52 +00001810and then in the list of directories specified by
Fred Drakeeee08cd1997-12-04 15:43:15 +00001811the environment variable \code{PYTHONPATH}. This has the same syntax as
1812the \UNIX{} shell variable \code{PATH}, i.e., a list of colon-separated
1813directory names. When \code{PYTHONPATH} is not set, or when the file
Guido van Rossum02455691997-07-17 16:21:52 +00001814is not found there, the search continues in an installation-dependent
Fred Drakeeee08cd1997-12-04 15:43:15 +00001815default path, usually \code{.:/usr/local/lib/python}.
Guido van Rossum02455691997-07-17 16:21:52 +00001816
1817Actually, modules are searched in the list of directories given by the
Fred Drakeeee08cd1997-12-04 15:43:15 +00001818variable \code{sys.path} which is initialized from the directory
1819containing the input script (or the current directory),
1820\code{PYTHONPATH} and the installation-dependent default. This allows
Guido van Rossum02455691997-07-17 16:21:52 +00001821Python programs that know what they're doing to modify or replace the
1822module search path. See the section on Standard Modules later.
1823
1824\subsection{``Compiled'' Python files}
1825
1826As an important speed-up of the start-up time for short programs that
Fred Drakeeee08cd1997-12-04 15:43:15 +00001827use a lot of standard modules, if a file called \file{spam.pyc} exists
1828in the directory where \file{spam.py} is found, this is assumed to
1829contain an already-``compiled'' version of the module \code{spam}. The
1830modification time of the version of \file{spam.py} used to create
1831\file{spam.pyc} is recorded in \file{spam.pyc}, and the file is
1832ignored if these don't match.
Guido van Rossum02455691997-07-17 16:21:52 +00001833
Fred Drakeeee08cd1997-12-04 15:43:15 +00001834Normally, you don't need to do anything to create the \file{spam.pyc} file.
1835Whenever \file{spam.py} is successfully compiled, an attempt is made to
1836write the compiled version to \file{spam.pyc}. It is not an error if
Guido van Rossum02455691997-07-17 16:21:52 +00001837this attempt fails; if for any reason the file is not written
Fred Drakeeee08cd1997-12-04 15:43:15 +00001838completely, the resulting \file{spam.pyc} file will be recognized as
1839invalid and thus ignored later. The contents of the \file{spam.pyc}
Guido van Rossum02455691997-07-17 16:21:52 +00001840file is platform independent, so a Python module directory can be
1841shared by machines of different architectures. (Tip for experts:
Fred Drakeeee08cd1997-12-04 15:43:15 +00001842the module \code{compileall} creates file{.pyc} files for all modules.)
Guido van Rossum02455691997-07-17 16:21:52 +00001843
1844XXX Should optimization with -O be covered here?
1845
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001846\section{Standard Modules}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001847
Guido van Rossum4410c751991-06-04 20:22:18 +00001848Python comes with a library of standard modules, described in a separate
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001849document (Python Library Reference). Some modules are built into the
1850interpreter; these provide access to operations that are not part of the
1851core of the language but are nevertheless built in, either for
1852efficiency or to provide access to operating system primitives such as
1853system calls. The set of such modules is a configuration option; e.g.,
Fred Drakeeee08cd1997-12-04 15:43:15 +00001854the \code{amoeba} module is only provided on systems that somehow support
1855Amoeba primitives. One particular module deserves some attention:
1856\code{sys}, which is built into every Python interpreter. The
1857variables \code{sys.ps1} and \code{sys.ps2} define the strings used as
1858primary and secondary prompts:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001859
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001860\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001861>>> import sys
1862>>> sys.ps1
1863'>>> '
1864>>> sys.ps2
1865'... '
1866>>> sys.ps1 = 'C> '
1867C> print 'Yuck!'
1868Yuck!
1869C>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001870\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001871%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001872These two variables are only defined if the interpreter is in
1873interactive mode.
1874
1875The variable
Fred Drakeeee08cd1997-12-04 15:43:15 +00001876\code{sys.path}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001877is a list of strings that determine the interpreter's search path for
1878modules.
1879It is initialized to a default path taken from the environment variable
Fred Drakeeee08cd1997-12-04 15:43:15 +00001880\code{PYTHONPATH},
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001881or from a built-in default if
Fred Drakeeee08cd1997-12-04 15:43:15 +00001882\code{PYTHONPATH}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001883is not set.
1884You can modify it using standard list operations, e.g.:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001885
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001886\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001887>>> import sys
1888>>> sys.path.append('/ufs/guido/lib/python')
1889>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00001890\end{verbatim}\ecode
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001891
Fred Drakeeee08cd1997-12-04 15:43:15 +00001892\section{The \sectcode{dir()} function}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001893
Fred Drakeeee08cd1997-12-04 15:43:15 +00001894The built-in function \code{dir()} is used to find out which names a module
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001895defines. It returns a sorted list of strings:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001896
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001897\bcode\begin{verbatim}
1898>>> import fibo, sys
1899>>> dir(fibo)
Guido van Rossum6938f061994-08-01 12:22:53 +00001900['__name__', 'fib', 'fib2']
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001901>>> dir(sys)
Guido van Rossum6938f061994-08-01 12:22:53 +00001902['__name__', 'argv', 'builtin_module_names', 'copyright', 'exit',
1903'maxint', 'modules', 'path', 'ps1', 'ps2', 'setprofile', 'settrace',
1904'stderr', 'stdin', 'stdout', 'version']
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001905>>>
1906\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001907%
Fred Drakeeee08cd1997-12-04 15:43:15 +00001908Without arguments, \code{dir()} lists the names you have defined currently:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001909
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001910\bcode\begin{verbatim}
1911>>> a = [1, 2, 3, 4, 5]
1912>>> import fibo, sys
1913>>> fib = fibo.fib
1914>>> dir()
Guido van Rossum6938f061994-08-01 12:22:53 +00001915['__name__', 'a', 'fib', 'fibo', 'sys']
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001916>>>
1917\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001918%
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001919Note that it lists all types of names: variables, modules, functions, etc.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001920
Fred Drakeeee08cd1997-12-04 15:43:15 +00001921\code{dir()} does not list the names of built-in functions and variables.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001922If you want a list of those, they are defined in the standard module
Fred Drakeeee08cd1997-12-04 15:43:15 +00001923\code{__builtin__}:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001924
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001925\bcode\begin{verbatim}
Guido van Rossum4bd023f1993-10-27 13:49:20 +00001926>>> import __builtin__
1927>>> dir(__builtin__)
Guido van Rossum6938f061994-08-01 12:22:53 +00001928['AccessError', 'AttributeError', 'ConflictError', 'EOFError', 'IOError',
1929'ImportError', 'IndexError', 'KeyError', 'KeyboardInterrupt',
1930'MemoryError', 'NameError', 'None', 'OverflowError', 'RuntimeError',
1931'SyntaxError', 'SystemError', 'SystemExit', 'TypeError', 'ValueError',
1932'ZeroDivisionError', '__name__', 'abs', 'apply', 'chr', 'cmp', 'coerce',
1933'compile', 'dir', 'divmod', 'eval', 'execfile', 'filter', 'float',
1934'getattr', 'hasattr', 'hash', 'hex', 'id', 'input', 'int', 'len', 'long',
1935'map', 'max', 'min', 'oct', 'open', 'ord', 'pow', 'range', 'raw_input',
1936'reduce', 'reload', 'repr', 'round', 'setattr', 'str', 'type', 'xrange']
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001937>>>
1938\end{verbatim}\ecode
1939
Guido van Rossum5e0759d1992-08-07 16:06:24 +00001940
Guido van Rossum02455691997-07-17 16:21:52 +00001941\chapter{Input and Output}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001942
Guido van Rossum02455691997-07-17 16:21:52 +00001943There are several ways to present the output of a program; data can be
1944printed in a human-readable form, or written to a file for future use.
1945This chapter will discuss some of the possibilities.
1946
1947\section{Fancier Output Formatting}
Fred Drakeeee08cd1997-12-04 15:43:15 +00001948So far we've encountered two ways of writing values: \emph{expression
1949statements} and the \code{print} statement. (A third way is using the
1950\code{write} method of file objects; the standard output file can be
1951referenced as \code{sys.stdout}. See the Library Reference for more
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001952information on this.)
1953
1954Often you'll want more control over the formatting of your output than
Guido van Rossum02455691997-07-17 16:21:52 +00001955simply printing space-separated values. There are two ways to format
1956your output; the first way is to do all the string handling yourself;
1957using string slicing and concatenation operations you can create any
Fred Drakeeee08cd1997-12-04 15:43:15 +00001958lay-out you can imagine. The standard module \code{string} contains
Guido van Rossum02455691997-07-17 16:21:52 +00001959some useful operations for padding strings to a given column width;
1960these will be discussed shortly. The second way is to use the
1961\code{\%} operator with a string as the left argument. \code{\%}
Fred Drakeeee08cd1997-12-04 15:43:15 +00001962interprets the left argument as a \C{} \code{sprintf()}-style format
Guido van Rossum02455691997-07-17 16:21:52 +00001963string to be applied to the right argument, and returns the string
1964resulting from this formatting operation.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001965
1966One question remains, of course: how do you convert values to strings?
Guido van Rossum02455691997-07-17 16:21:52 +00001967Luckily, Python has a way to convert any value to a string: pass it to
Fred Drakeeee08cd1997-12-04 15:43:15 +00001968the \code{repr()} function, or just write the value between reverse
1969quotes (\code{``}). Some examples:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001970
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001971\bcode\begin{verbatim}
1972>>> x = 10 * 3.14
1973>>> y = 200*200
1974>>> s = 'The value of x is ' + `x` + ', and y is ' + `y` + '...'
1975>>> print s
1976The value of x is 31.4, and y is 40000...
1977>>> # Reverse quotes work on other types besides numbers:
Guido van Rossum6938f061994-08-01 12:22:53 +00001978... p = [x, y]
Guido van Rossum02455691997-07-17 16:21:52 +00001979>>> ps = repr(p)
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001980>>> ps
1981'[31.4, 40000]'
1982>>> # Converting a string adds string quotes and backslashes:
Guido van Rossum6938f061994-08-01 12:22:53 +00001983... hello = 'hello, world\n'
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001984>>> hellos = `hello`
1985>>> print hellos
1986'hello, world\012'
1987>>> # The argument of reverse quotes may be a tuple:
Guido van Rossume5f8b601995-01-04 19:12:49 +00001988... `x, y, ('spam', 'eggs')`
1989"(31.4, 40000, ('spam', 'eggs'))"
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001990>>>
1991\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001992%
Guido van Rossum6938f061994-08-01 12:22:53 +00001993Here are two ways to write a table of squares and cubes:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001994
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001995\bcode\begin{verbatim}
1996>>> import string
1997>>> for x in range(1, 11):
1998... print string.rjust(`x`, 2), string.rjust(`x*x`, 3),
1999... # Note trailing comma on previous line
2000... print string.rjust(`x*x*x`, 4)
2001...
2002 1 1 1
2003 2 4 8
2004 3 9 27
2005 4 16 64
2006 5 25 125
2007 6 36 216
2008 7 49 343
2009 8 64 512
2010 9 81 729
201110 100 1000
Guido van Rossum6938f061994-08-01 12:22:53 +00002012>>> for x in range(1,11):
2013... print '%2d %3d %4d' % (x, x*x, x*x*x)
2014...
2015 1 1 1
2016 2 4 8
2017 3 9 27
2018 4 16 64
2019 5 25 125
2020 6 36 216
2021 7 49 343
2022 8 64 512
2023 9 81 729
202410 100 1000
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002025>>>
2026\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002027%
Fred Drakeeee08cd1997-12-04 15:43:15 +00002028(Note that one space between each column was added by the way \code{print}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002029works: it always adds spaces between its arguments.)
2030
Fred Drakeeee08cd1997-12-04 15:43:15 +00002031This example demonstrates the function \code{string.rjust()}, which
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002032right-justifies a string in a field of a given width by padding it with
Fred Drakeeee08cd1997-12-04 15:43:15 +00002033spaces on the left. There are similar functions \code{string.ljust()}
2034and \code{string.center()}. These functions do not write anything, they
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002035just return a new string. If the input string is too long, they don't
2036truncate it, but return it unchanged; this will mess up your column
2037lay-out but that's usually better than the alternative, which would be
2038lying about a value. (If you really want truncation you can always add
Fred Drakeeee08cd1997-12-04 15:43:15 +00002039a slice operation, as in \code{string.ljust(x,~n)[0:n]}.)
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002040
Fred Drakeeee08cd1997-12-04 15:43:15 +00002041There is another function, \code{string.zfill()}, which pads a numeric
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002042string on the left with zeros. It understands about plus and minus
Guido van Rossum6938f061994-08-01 12:22:53 +00002043signs:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002044
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002045\bcode\begin{verbatim}
2046>>> string.zfill('12', 5)
2047'00012'
2048>>> string.zfill('-3.14', 7)
2049'-003.14'
2050>>> string.zfill('3.14159265359', 5)
2051'3.14159265359'
2052>>>
2053\end{verbatim}\ecode
Guido van Rossum02455691997-07-17 16:21:52 +00002054%
2055Using the \code{\%} operator looks like this:
2056
2057\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00002058 >>> import math
2059 >>> print 'The value of PI is approximately %5.3f.' % math.pi
2060 The value of PI is approximately 3.142.
2061 >>>
Guido van Rossum02455691997-07-17 16:21:52 +00002062\end{verbatim}
2063
2064If there is more than one format in the string you pass a tuple as
2065right operand, e.g.
2066
2067\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00002068 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
2069 >>> for name, phone in table.items():
2070 ... print '%-10s ==> %10d' % (name, phone)
2071 ...
2072 Jack ==> 4098
2073 Dcab ==> 8637678
2074 Sjoerd ==> 4127
2075 >>>
Guido van Rossum02455691997-07-17 16:21:52 +00002076\end{verbatim}
2077
2078Most formats work exactly as in C and require that you pass the proper
2079type; however, if you don't you get an exception, not a core dump.
2080The \verb\%s\ format is more relaxed: if the corresponding argument is
2081not a string object, it is converted to string using the \verb\str()\
2082built-in function. Using \verb\*\ to pass the width or precision in
2083as a separate (integer) argument is supported. The C formats
2084\verb\%n\ and \verb\%p\ are not supported.
2085
2086If you have a really long format string that you don't want to split
2087up, it would be nice if you could reference the variables to be
2088formatted by name instead of by position. This can be done by using
2089an extension of C formats using the form \verb\%(name)format\, e.g.
2090
2091\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00002092 >>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
2093 >>> print 'Jack: %(Jack)d; Sjoerd: %(Sjoerd)d; Dcab: %(Dcab)d' % table
2094 Jack: 4098; Sjoerd: 4127; Dcab: 8637678
2095 >>>
Guido van Rossum02455691997-07-17 16:21:52 +00002096\end{verbatim}
2097
2098This is particularly useful in combination with the new built-in
2099\verb\vars()\ function, which returns a dictionary containing all
2100local variables.
2101
2102\section{Reading and Writing Files}
2103% Opening files
2104\code{open()} returns a file object, and is most commonly used with
2105two arguments: \code{open(\var{filename},\var{mode})}.
2106
2107\bcode\begin{verbatim}
2108>>> f=open('/tmp/workfile', 'w')
2109>>> print f
2110<open file '/tmp/workfile', mode 'w' at 80a0960>
2111\end{verbatim}\ecode
2112%
2113The first argument is a string containing the filename. The second
2114argument is another string containing a few characters describing the
2115way in which the file will be used. \var{mode} can be \code{'r'} when
2116the file will only be read, \code{'w'} for only writing (an existing
2117file with the same name will be erased), and \code{'a'} opens the file
2118for appending; any data written to the file is automatically added to
2119the end. \code{'r+'} opens the file for both reading and writing.
2120The \var{mode} argument is optional; \code{'r'} will be assumed if
2121it's omitted.
2122
2123On Windows, (XXX does the Mac need this too?) \code{'b'} appended to the
2124mode opens the file in binary mode, so there are also modes like
2125\code{'rb'}, \code{'wb'}, and \code{'r+b'}. Windows makes a
2126distinction between text and binary files; the end-of-line characters
2127in text files are automatically altered slightly when data is read or
2128written. This behind-the-scenes modification to file data is fine for
2129ASCII text files, but it'll corrupt binary data like that in JPEGs or
2130.EXE files. Be very careful to use binary mode when reading and
2131writing such files.
2132
2133\subsection{Methods of file objects}
2134
2135The rest of the examples in this section will assume that a file
2136object called \code{f} has already been created.
2137
2138To read a file's contents, call \code{f.read(\var{size})}, which reads
2139some quantity of data and returns it as a string. \var{size} is an
2140optional numeric argument. When \var{size} is omitted or negative,
2141the entire contents of the file will be read and returned; it's your
2142problem if the file is twice as large as your machine's memory.
2143Otherwise, at most \var{size} bytes are read and returned. If the end
2144of the file has been reached, \code{f.read()} will return an empty
2145string (\code {""}).
2146\bcode\begin{verbatim}
2147>>> f.read()
2148'This is the entire file.\012'
2149>>> f.read()
2150''
2151\end{verbatim}\ecode
2152%
2153\code{f.readline()} reads a single line from the file; a newline
Fred Drakeeee08cd1997-12-04 15:43:15 +00002154character (\code{\\n}) is left at the end of the string, and is only
Guido van Rossum02455691997-07-17 16:21:52 +00002155omitted on the last line of the file if the file doesn't end in a
2156newline. This makes the return value unambiguous; if
2157\code{f.readline()} returns an empty string, the end of the file has
Fred Drakeeee08cd1997-12-04 15:43:15 +00002158been reached, while a blank line is represented by \code{'\\n'}, a
Guido van Rossum02455691997-07-17 16:21:52 +00002159string containing only a single newline.
2160
2161\bcode\begin{verbatim}
2162>>> f.readline()
2163'This is the first line of the file.\012'
2164>>> f.readline()
2165'Second line of the file\012'
2166>>> f.readline()
2167''
2168\end{verbatim}\ecode
2169%
Fred Drakeeee08cd1997-12-04 15:43:15 +00002170\code{f.readlines()} uses \code{f.readline()} repeatedly, and returns
Guido van Rossum02455691997-07-17 16:21:52 +00002171a list containing all the lines of data in the file.
2172
2173\bcode\begin{verbatim}
2174>>> f.readlines()
2175['This is the first line of the file.\012', 'Second line of the file\012']
2176\end{verbatim}\ecode
2177%
2178\code{f.write(\var{string})} writes the contents of \var{string} to
2179the file, returning \code{None}.
2180
2181\bcode\begin{verbatim}
2182>>> f.write('This is a test\n')
2183\end{verbatim}\ecode
2184%
2185\code{f.tell()} returns an integer giving the file object's current
2186position in the file, measured in bytes from the beginning of the
2187file. To change the file object's position, use
2188\code{f.seek(\var{offset}, \var{from_what})}. The position is
2189computed from adding \var{offset} to a reference point; the reference
2190point is selected by the \var{from_what} argument. A \var{from_what}
2191value of 0 measures from the beginning of the file, 1 uses the current
2192file position, and 2 uses the end of the file as the reference point.
2193\var{from_what}
2194can be omitted and defaults to 0, using the beginning of the file as the reference point.
2195
2196\bcode\begin{verbatim}
2197>>> f=open('/tmp/workfile', 'r+')
2198>>> f.write('0123456789abcdef')
2199>>> f.seek(5) # Go to the 5th byte in the file
2200>>> f.read(1)
2201'5'
2202>>> f.seek(-3, 2) # Go to the 3rd byte before the end
2203>>> f.read(1)
2204'd'
2205\end{verbatim}\ecode
2206%
2207When you're done with a file, call \code{f.close()} to close it and
2208free up any system resources taken up by the open file. After calling
2209\code{f.close()}, attempts to use the file object will automatically fail.
2210
2211\bcode\begin{verbatim}
2212>>> f.close()
2213>>> f.read()
2214Traceback (innermost last):
2215 File "<stdin>", line 1, in ?
2216ValueError: I/O operation on closed file
2217\end{verbatim}\ecode
2218%
2219File objects have some additional methods, such as \code{isatty()} and
2220\code{truncate()} which are less frequently used; consult the Library
2221Reference for a complete guide to file objects.
2222
2223\subsection{The pickle module}
2224
2225Strings can easily be written to and read from a file. Numbers take a
2226bit more effort, since the \code{read()} method only returns strings,
2227which will have to be passed to a function like \code{string.atoi()},
2228which takes a string like \code{'123'} and returns its numeric value
2229123. However, when you want to save more complex data types like
2230lists, dictionaries, or class instances, things get a lot more
2231complicated.
2232
2233Rather than have users be constantly writing and debugging code to
2234save complicated data types, Python provides a standard module called
Fred Drake9e63faa1997-10-15 14:37:24 +00002235\code{pickle}. This is an amazing module that can take almost
Guido van Rossum02455691997-07-17 16:21:52 +00002236any Python object (even some forms of Python code!), and convert it to
2237a string representation; this process is called \dfn{pickling}.
2238Reconstructing the object from the string representation is called
2239\dfn{unpickling}. Between pickling and unpickling, the string
2240representing the object may have been stored in a file or data, or
2241sent over a network connection to some distant machine.
2242
2243If you have an object \code{x}, and a file object \code{f} that's been
2244opened for writing, the simplest way to pickle the object takes only
2245one line of code:
2246
2247\bcode\begin{verbatim}
2248pickle.dump(x, f)
2249\end{verbatim}\ecode
2250%
2251To unpickle the object again, if \code{f} is a file object which has been
2252opened for reading:
2253
2254\bcode\begin{verbatim}
2255x = pickle.load(f)
2256\end{verbatim}\ecode
2257%
2258(There are other variants of this, used when pickling many objects or
2259when you don't want to write the pickled data to a file; consult the
2260complete documentation for \code{pickle} in the Library Reference.)
2261
2262\code{pickle} is the standard way to make Python objects which can be
2263stored and reused by other programs or by a future invocation of the
2264same program; the technical term for this is a \dfn{persistent}
2265object. Because \code{pickle} is so widely used, many authors who
2266write Python extensions take care to ensure that new data types such
2267as matrices, XXX more examples needed XXX, can be properly pickled and
2268unpickled.
2269
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002270
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002271
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002272\chapter{Errors and Exceptions}
2273
2274Until now error messages haven't been more than mentioned, but if you
2275have tried out the examples you have probably seen some. There are
Fred Drakeeee08cd1997-12-04 15:43:15 +00002276(at least) two distinguishable kinds of errors: \emph{syntax errors}
2277and \emph{exceptions}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002278
2279\section{Syntax Errors}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002280
2281Syntax errors, also known as parsing errors, are perhaps the most common
Guido van Rossum4410c751991-06-04 20:22:18 +00002282kind of complaint you get while you are still learning Python:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002283
Guido van Rossum5ce78f11991-01-25 13:27:18 +00002284\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002285>>> while 1 print 'Hello world'
Guido van Rossum6938f061994-08-01 12:22:53 +00002286 File "<stdin>", line 1
2287 while 1 print 'Hello world'
2288 ^
2289SyntaxError: invalid syntax
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002290>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00002291\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002292%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002293The parser repeats the offending line and displays a little `arrow'
2294pointing at the earliest point in the line where the error was detected.
2295The error is caused by (or at least detected at) the token
Fred Drakeeee08cd1997-12-04 15:43:15 +00002296\emph{preceding}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002297the arrow: in the example, the error is detected at the keyword
Fred Drakeeee08cd1997-12-04 15:43:15 +00002298\code{print}, since a colon (\code{:}) is missing before it.
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002299File name and line number are printed so you know where to look in case
2300the input came from a script.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002301
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002302\section{Exceptions}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002303
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002304Even if a statement or expression is syntactically correct, it may
2305cause an error when an attempt is made to execute it.
Fred Drakeeee08cd1997-12-04 15:43:15 +00002306Errors detected during execution are called \emph{exceptions} and are
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002307not unconditionally fatal: you will soon learn how to handle them in
2308Python programs. Most exceptions are not handled by programs,
2309however, and result in error messages as shown here:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002310
Guido van Rossum5ce78f11991-01-25 13:27:18 +00002311\bcode\small\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002312>>> 10 * (1/0)
Guido van Rossum3cbc16d1993-12-17 12:13:53 +00002313Traceback (innermost last):
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002314 File "<stdin>", line 1
Guido van Rossumb2c65561993-05-12 08:53:36 +00002315ZeroDivisionError: integer division or modulo
Guido van Rossume5f8b601995-01-04 19:12:49 +00002316>>> 4 + spam*3
Guido van Rossum6938f061994-08-01 12:22:53 +00002317Traceback (innermost last):
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002318 File "<stdin>", line 1
Guido van Rossume5f8b601995-01-04 19:12:49 +00002319NameError: spam
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002320>>> '2' + 2
Guido van Rossum6938f061994-08-01 12:22:53 +00002321Traceback (innermost last):
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002322 File "<stdin>", line 1
Guido van Rossumb2c65561993-05-12 08:53:36 +00002323TypeError: illegal argument type for built-in operation
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002324>>>
Fred Drakefd255e41996-10-29 15:50:05 +00002325\end{verbatim}\normalsize\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002326%
Guido van Rossumb2c65561993-05-12 08:53:36 +00002327The last line of the error message indicates what happened.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002328Exceptions come in different types, and the type is printed as part of
2329the message: the types in the example are
Fred Drakeeee08cd1997-12-04 15:43:15 +00002330\code{ZeroDivisionError},
2331\code{NameError}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002332and
Fred Drakeeee08cd1997-12-04 15:43:15 +00002333\code{TypeError}.
Guido van Rossumb2c65561993-05-12 08:53:36 +00002334The string printed as the exception type is the name of the built-in
2335name for the exception that occurred. This is true for all built-in
2336exceptions, but need not be true for user-defined exceptions (although
2337it is a useful convention).
2338Standard exception names are built-in identifiers (not reserved
2339keywords).
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002340
Guido van Rossumb2c65561993-05-12 08:53:36 +00002341The rest of the line is a detail whose interpretation depends on the
2342exception type; its meaning is dependent on the exception type.
2343
2344The preceding part of the error message shows the context where the
2345exception happened, in the form of a stack backtrace.
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002346In general it contains a stack backtrace listing source lines; however,
2347it will not display lines read from standard input.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002348
Guido van Rossum6a05f951996-10-22 19:27:46 +00002349The Python Library Reference Manual lists the built-in exceptions and
Guido van Rossumb2c65561993-05-12 08:53:36 +00002350their meanings.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002351
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002352\section{Handling Exceptions}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002353
2354It is possible to write programs that handle selected exceptions.
2355Look at the following example, which prints a table of inverses of
2356some floating point numbers:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002357
Guido van Rossum5ce78f11991-01-25 13:27:18 +00002358\bcode\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002359>>> numbers = [0.3333, 2.5, 0, 10]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002360>>> for x in numbers:
2361... print x,
2362... try:
2363... print 1.0 / x
Guido van Rossumb2c65561993-05-12 08:53:36 +00002364... except ZeroDivisionError:
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002365... print '*** has no inverse ***'
Guido van Rossum02455691997-07-17 16:21:52 +00002366...
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000023670.3333 3.00030003
23682.5 0.4
23690 *** has no inverse ***
237010 0.1
2371>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00002372\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002373%
Fred Drakeeee08cd1997-12-04 15:43:15 +00002374The \code{try} statement works as follows.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002375\begin{itemize}
2376\item
2377First, the
Fred Drakeeee08cd1997-12-04 15:43:15 +00002378\emph{try\ clause}
2379(the statement(s) between the \code{try} and \code{except} keywords) is
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002380executed.
2381\item
2382If no exception occurs, the
Fred Drakeeee08cd1997-12-04 15:43:15 +00002383\emph{except\ clause}
2384is skipped and execution of the \code{try} statement is finished.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002385\item
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002386If an exception occurs during execution of the try clause,
2387the rest of the clause is skipped. Then if
Fred Drakeeee08cd1997-12-04 15:43:15 +00002388its type matches the exception named after the \code{except} keyword,
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002389the rest of the try clause is skipped, the except clause is executed,
Fred Drakeeee08cd1997-12-04 15:43:15 +00002390and then execution continues after the \code{try} statement.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002391\item
2392If an exception occurs which does not match the exception named in the
2393except clause, it is passed on to outer try statements; if no handler is
2394found, it is an
Fred Drakeeee08cd1997-12-04 15:43:15 +00002395\emph{unhandled exception}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002396and execution stops with a message as shown above.
2397\end{itemize}
Fred Drakeeee08cd1997-12-04 15:43:15 +00002398A \code{try} statement may have more than one except clause, to specify
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002399handlers for different exceptions.
2400At most one handler will be executed.
2401Handlers only handle exceptions that occur in the corresponding try
Fred Drakeeee08cd1997-12-04 15:43:15 +00002402clause, not in other handlers of the same \code{try} statement.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002403An except clause may name multiple exceptions as a parenthesized list,
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002404e.g.:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002405
Guido van Rossum5ce78f11991-01-25 13:27:18 +00002406\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002407... except (RuntimeError, TypeError, NameError):
2408... pass
Guido van Rossum5ce78f11991-01-25 13:27:18 +00002409\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002410%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002411The last except clause may omit the exception name(s), to serve as a
2412wildcard.
Guido van Rossumb2c65561993-05-12 08:53:36 +00002413Use this with extreme caution, since it is easy to mask a real
2414programming error in this way!
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002415
Guido van Rossum02455691997-07-17 16:21:52 +00002416The \verb\try...except\ statement has an optional \verb\else\ clause,
2417which must follow all \verb\except\ clauses. It is useful to place
2418code that must be executed if the \verb\try\ clause does not raise an
2419exception. For example:
2420
2421\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00002422 for arg in sys.argv:
2423 try:
2424 f = open(arg, 'r')
2425 except IOError:
2426 print 'cannot open', arg
2427 else:
2428 print arg, 'has', len(f.readlines()), 'lines'
2429 f.close()
Guido van Rossum02455691997-07-17 16:21:52 +00002430\end{verbatim}
2431
2432
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002433When an exception occurs, it may have an associated value, also known as
2434the exceptions's
Fred Drakeeee08cd1997-12-04 15:43:15 +00002435\emph{argument}.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002436The presence and type of the argument depend on the exception type.
2437For exception types which have an argument, the except clause may
2438specify a variable after the exception name (or list) to receive the
2439argument's value, as follows:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002440
Guido van Rossum5ce78f11991-01-25 13:27:18 +00002441\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002442>>> try:
Guido van Rossume5f8b601995-01-04 19:12:49 +00002443... spam()
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002444... except NameError, x:
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002445... print 'name', x, 'undefined'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002446...
Guido van Rossume5f8b601995-01-04 19:12:49 +00002447name spam undefined
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002448>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00002449\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002450%
Guido van Rossumb2c65561993-05-12 08:53:36 +00002451If an exception has an argument, it is printed as the last part
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002452(`detail') of the message for unhandled exceptions.
2453
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002454Exception handlers don't just handle exceptions if they occur
2455immediately in the try clause, but also if they occur inside functions
2456that are called (even indirectly) in the try clause.
2457For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002458
Guido van Rossum5ce78f11991-01-25 13:27:18 +00002459\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002460>>> def this_fails():
2461... x = 1/0
2462...
2463>>> try:
2464... this_fails()
Guido van Rossumb2c65561993-05-12 08:53:36 +00002465... except ZeroDivisionError, detail:
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002466... print 'Handling run-time error:', detail
2467...
Guido van Rossumb2c65561993-05-12 08:53:36 +00002468Handling run-time error: integer division or modulo
Guido van Rossum02455691997-07-17 16:21:52 +00002469>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00002470\end{verbatim}\ecode
Guido van Rossum02455691997-07-17 16:21:52 +00002471%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002472
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002473\section{Raising Exceptions}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002474
Fred Drakeeee08cd1997-12-04 15:43:15 +00002475The \code{raise} statement allows the programmer to force a specified
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002476exception to occur.
2477For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002478
Guido van Rossum5ce78f11991-01-25 13:27:18 +00002479\bcode\begin{verbatim}
Guido van Rossumb2c65561993-05-12 08:53:36 +00002480>>> raise NameError, 'HiThere'
Guido van Rossum6938f061994-08-01 12:22:53 +00002481Traceback (innermost last):
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002482 File "<stdin>", line 1
Guido van Rossumb2c65561993-05-12 08:53:36 +00002483NameError: HiThere
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002484>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00002485\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002486%
Fred Drakeeee08cd1997-12-04 15:43:15 +00002487The first argument to \code{raise} names the exception to be raised.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002488The optional second argument specifies the exception's argument.
2489
Guido van Rossum02455691997-07-17 16:21:52 +00002490%
2491
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002492\section{User-defined Exceptions}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002493
2494Programs may name their own exceptions by assigning a string to a
2495variable.
2496For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002497
Guido van Rossum5ce78f11991-01-25 13:27:18 +00002498\bcode\begin{verbatim}
Guido van Rossumb2c65561993-05-12 08:53:36 +00002499>>> my_exc = 'my_exc'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002500>>> try:
2501... raise my_exc, 2*2
2502... except my_exc, val:
Guido van Rossum67fa1601991-04-23 14:14:57 +00002503... print 'My exception occurred, value:', val
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002504...
Guido van Rossum6938f061994-08-01 12:22:53 +00002505My exception occurred, value: 4
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002506>>> raise my_exc, 1
Guido van Rossum6938f061994-08-01 12:22:53 +00002507Traceback (innermost last):
2508 File "<stdin>", line 1
Guido van Rossumb2c65561993-05-12 08:53:36 +00002509my_exc: 1
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002510>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00002511\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002512%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002513Many standard modules use this to report errors that may occur in
2514functions they define.
2515
Guido van Rossum02455691997-07-17 16:21:52 +00002516%
2517
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002518\section{Defining Clean-up Actions}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002519
Fred Drakeeee08cd1997-12-04 15:43:15 +00002520The \code{try} statement has another optional clause which is intended to
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002521define clean-up actions that must be executed under all circumstances.
2522For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002523
Guido van Rossum5ce78f11991-01-25 13:27:18 +00002524\bcode\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002525>>> try:
2526... raise KeyboardInterrupt
2527... finally:
2528... print 'Goodbye, world!'
2529...
2530Goodbye, world!
Guido van Rossum6938f061994-08-01 12:22:53 +00002531Traceback (innermost last):
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002532 File "<stdin>", line 2
Guido van Rossumb2c65561993-05-12 08:53:36 +00002533KeyboardInterrupt
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002534>>>
Guido van Rossum5ce78f11991-01-25 13:27:18 +00002535\end{verbatim}\ecode
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002536%
Fred Drakeeee08cd1997-12-04 15:43:15 +00002537A \code{finally} clause is executed whether or not an exception has
2538occurred in the \code{try} clause. When an exception has occurred, it
2539is re-raised after the \code{finally} clause is executed. The
2540\code{finally} clause is also executed ``on the way out'' when the
2541\code{try} statement is left via a \code{break} or \code{return}
Guido van Rossumda8c3fd1992-08-09 13:55:25 +00002542statement.
2543
Fred Drakeeee08cd1997-12-04 15:43:15 +00002544A \code{try} statement must either have one or more \code{except}
2545clauses or one \code{finally} clause, but not both.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002546
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002547\chapter{Classes}
2548
2549Python's class mechanism adds classes to the language with a minimum
2550of new syntax and semantics. It is a mixture of the class mechanisms
Guido van Rossum16d6e711994-08-08 12:30:22 +00002551found in \Cpp{} and Modula-3. As is true for modules, classes in Python
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002552do not put an absolute barrier between definition and user, but rather
2553rely on the politeness of the user not to ``break into the
2554definition.'' The most important features of classes are retained
2555with full power, however: the class inheritance mechanism allows
2556multiple base classes, a derived class can override any methods of its
2557base class(es), a method can call the method of a base class with the
2558same name. Objects can contain an arbitrary amount of private data.
2559
Guido van Rossum16d6e711994-08-08 12:30:22 +00002560In \Cpp{} terminology, all class members (including the data members) are
Fred Drakeeee08cd1997-12-04 15:43:15 +00002561\emph{public}, and all member functions are \emph{virtual}. There are
Guido van Rossum6938f061994-08-01 12:22:53 +00002562no special constructors or destructors. As in Modula-3, there are no
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002563shorthands for referencing the object's members from its methods: the
2564method function is declared with an explicit first argument
2565representing the object, which is provided implicitly by the call. As
2566in Smalltalk, classes themselves are objects, albeit in the wider
2567sense of the word: in Python, all data types are objects. This
Guido van Rossum16d6e711994-08-08 12:30:22 +00002568provides semantics for importing and renaming. But, just like in \Cpp{}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002569or Modula-3, built-in types cannot be used as base classes for
Guido van Rossum16d6e711994-08-08 12:30:22 +00002570extension by the user. Also, like in \Cpp{} but unlike in Modula-3, most
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002571built-in operators with special syntax (arithmetic operators,
Guido van Rossum6938f061994-08-01 12:22:53 +00002572subscripting etc.) can be redefined for class members.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002573
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002574\section{A word about terminology}
2575
2576Lacking universally accepted terminology to talk about classes, I'll
Guido van Rossum16d6e711994-08-08 12:30:22 +00002577make occasional use of Smalltalk and \Cpp{} terms. (I'd use Modula-3
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002578terms, since its object-oriented semantics are closer to those of
Guido van Rossum16d6e711994-08-08 12:30:22 +00002579Python than \Cpp{}, but I expect that few readers have heard of it...)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002580
2581I also have to warn you that there's a terminological pitfall for
2582object-oriented readers: the word ``object'' in Python does not
Guido van Rossum16d6e711994-08-08 12:30:22 +00002583necessarily mean a class instance. Like \Cpp{} and Modula-3, and unlike
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002584Smalltalk, not all types in Python are classes: the basic built-in
2585types like integers and lists aren't, and even somewhat more exotic
Fred Drakeeee08cd1997-12-04 15:43:15 +00002586types like files aren't. However, \emph{all} Python types share a little
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002587bit of common semantics that is best described by using the word
2588object.
2589
2590Objects have individuality, and multiple names (in multiple scopes)
2591can be bound to the same object. This is known as aliasing in other
2592languages. This is usually not appreciated on a first glance at
2593Python, and can be safely ignored when dealing with immutable basic
2594types (numbers, strings, tuples). However, aliasing has an
Guido van Rossum6938f061994-08-01 12:22:53 +00002595(intended!) effect on the semantics of Python code involving mutable
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002596objects such as lists, dictionaries, and most types representing
2597entities outside the program (files, windows, etc.). This is usually
2598used to the benefit of the program, since aliases behave like pointers
2599in some respects. For example, passing an object is cheap since only
2600a pointer is passed by the implementation; and if a function modifies
2601an object passed as an argument, the caller will see the change --- this
2602obviates the need for two different argument passing mechanisms as in
2603Pascal.
2604
2605
2606\section{Python scopes and name spaces}
2607
2608Before introducing classes, I first have to tell you something about
2609Python's scope rules. Class definitions play some neat tricks with
2610name spaces, and you need to know how scopes and name spaces work to
2611fully understand what's going on. Incidentally, knowledge about this
2612subject is useful for any advanced Python programmer.
2613
2614Let's begin with some definitions.
2615
Fred Drakeeee08cd1997-12-04 15:43:15 +00002616A \emph{name space} is a mapping from names to objects. Most name
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002617spaces are currently implemented as Python dictionaries, but that's
2618normally not noticeable in any way (except for performance), and it
2619may change in the future. Examples of name spaces are: the set of
2620built-in names (functions such as \verb\abs()\, and built-in exception
2621names); the global names in a module; and the local names in a
2622function invocation. In a sense the set of attributes of an object
Guido van Rossum16cd7f91994-10-06 10:29:26 +00002623also form a name space. The important thing to know about name
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002624spaces is that there is absolutely no relation between names in
2625different name spaces; for instance, two different modules may both
2626define a function ``maximize'' without confusion --- users of the
2627modules must prefix it with the module name.
2628
Fred Drakeeee08cd1997-12-04 15:43:15 +00002629By the way, I use the word \emph{attribute} for any name following a
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002630dot --- for example, in the expression \verb\z.real\, \verb\real\ is
2631an attribute of the object \verb\z\. Strictly speaking, references to
2632names in modules are attribute references: in the expression
2633\verb\modname.funcname\, \verb\modname\ is a module object and
2634\verb\funcname\ is an attribute of it. In this case there happens to
2635be a straightforward mapping between the module's attributes and the
2636global names defined in the module: they share the same name space!%
2637\footnote{
Guido van Rossum6938f061994-08-01 12:22:53 +00002638 Except for one thing. Module objects have a secret read-only
Fred Drakeeee08cd1997-12-04 15:43:15 +00002639 attribute called \code{__dict__} which returns the dictionary
Guido van Rossum6938f061994-08-01 12:22:53 +00002640 used to implement the module's name space; the name
Fred Drakeeee08cd1997-12-04 15:43:15 +00002641 \code{__dict__} is an attribute but not a global name.
Guido van Rossum6938f061994-08-01 12:22:53 +00002642 Obviously, using this violates the abstraction of name space
2643 implementation, and should be restricted to things like
2644 post-mortem debuggers...
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002645}
2646
2647Attributes may be read-only or writable. In the latter case,
2648assignment to attributes is possible. Module attributes are writable:
2649you can write \verb\modname.the_answer = 42\. Writable attributes may
2650also be deleted with the del statement, e.g.
2651\verb\del modname.the_answer\.
2652
2653Name spaces are created at different moments and have different
2654lifetimes. The name space containing the built-in names is created
2655when the Python interpreter starts up, and is never deleted. The
2656global name space for a module is created when the module definition
2657is read in; normally, module name spaces also last until the
2658interpreter quits. The statements executed by the top-level
2659invocation of the interpreter, either read from a script file or
2660interactively, are considered part of a module called \verb\__main__\,
2661so they have their own global name space. (The built-in names
Guido van Rossum4bd023f1993-10-27 13:49:20 +00002662actually also live in a module; this is called \verb\__builtin__\.)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002663
2664The local name space for a function is created when the function is
2665called, and deleted when the function returns or raises an exception
2666that is not handled within the function. (Actually, forgetting would
2667be a better way to describe what actually happens.) Of course,
2668recursive invocations each have their own local name space.
2669
Fred Drakeeee08cd1997-12-04 15:43:15 +00002670A \emph{scope} is a textual region of a Python program where a name space
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002671is directly accessible. ``Directly accessible'' here means that an
2672unqualified reference to a name attempts to find the name in the name
2673space.
2674
2675Although scopes are determined statically, they are used dynamically.
2676At any time during execution, exactly three nested scopes are in use
2677(i.e., exactly three name spaces are directly accessible): the
2678innermost scope, which is searched first, contains the local names,
2679the middle scope, searched next, contains the current module's global
2680names, and the outermost scope (searched last) is the name space
2681containing built-in names.
2682
2683Usually, the local scope references the local names of the (textually)
Guido van Rossum96628a91995-04-10 11:34:00 +00002684current function. Outside of functions, the local scope references
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002685the same name space as the global scope: the module's name space.
2686Class definitions place yet another name space in the local scope.
2687
2688It is important to realize that scopes are determined textually: the
2689global scope of a function defined in a module is that module's name
2690space, no matter from where or by what alias the function is called.
2691On the other hand, the actual search for names is done dynamically, at
Guido van Rossum96628a91995-04-10 11:34:00 +00002692run time --- however, the language definition is evolving towards
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002693static name resolution, at ``compile'' time, so don't rely on dynamic
2694name resolution! (In fact, local variables are already determined
2695statically.)
2696
2697A special quirk of Python is that assignments always go into the
2698innermost scope. Assignments do not copy data --- they just
2699bind names to objects. The same is true for deletions: the statement
2700\verb\del x\ removes the binding of x from the name space referenced by the
2701local scope. In fact, all operations that introduce new names use the
2702local scope: in particular, import statements and function definitions
2703bind the module or function name in the local scope. (The
2704\verb\global\ statement can be used to indicate that particular
2705variables live in the global scope.)
2706
2707
2708\section{A first look at classes}
2709
2710Classes introduce a little bit of new syntax, three new object types,
2711and some new semantics.
2712
2713
2714\subsection{Class definition syntax}
2715
2716The simplest form of class definition looks like this:
2717
2718\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00002719 class ClassName:
2720 <statement-1>
2721 .
2722 .
2723 .
2724 <statement-N>
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002725\end{verbatim}
2726
2727Class definitions, like function definitions (\verb\def\ statements)
2728must be executed before they have any effect. (You could conceivably
2729place a class definition in a branch of an \verb\if\ statement, or
2730inside a function.)
2731
2732In practice, the statements inside a class definition will usually be
2733function definitions, but other statements are allowed, and sometimes
2734useful --- we'll come back to this later. The function definitions
2735inside a class normally have a peculiar form of argument list,
2736dictated by the calling conventions for methods --- again, this is
2737explained later.
2738
2739When a class definition is entered, a new name space is created, and
2740used as the local scope --- thus, all assignments to local variables
2741go into this new name space. In particular, function definitions bind
2742the name of the new function here.
2743
Fred Drakeeee08cd1997-12-04 15:43:15 +00002744When a class definition is left normally (via the end), a \emph{class
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002745object} is created. This is basically a wrapper around the contents
2746of the name space created by the class definition; we'll learn more
2747about class objects in the next section. The original local scope
2748(the one in effect just before the class definitions was entered) is
2749reinstated, and the class object is bound here to class name given in
2750the class definition header (ClassName in the example).
2751
2752
2753\subsection{Class objects}
2754
2755Class objects support two kinds of operations: attribute references
2756and instantiation.
2757
Fred Drakeeee08cd1997-12-04 15:43:15 +00002758\emph{Attribute references} use the standard syntax used for all
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002759attribute references in Python: \verb\obj.name\. Valid attribute
2760names are all the names that were in the class's name space when the
2761class object was created. So, if the class definition looked like
2762this:
2763
2764\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00002765 class MyClass:
2766 "A simple example class"
2767 i = 12345
2768 def f(x):
2769 return 'hello world'
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002770\end{verbatim}
2771
2772then \verb\MyClass.i\ and \verb\MyClass.f\ are valid attribute
2773references, returning an integer and a function object, respectively.
Guido van Rossum02455691997-07-17 16:21:52 +00002774Class attributes can also be assigned to, so you can change the value
2775of \verb\MyClass.i\ by assignment. \verb\__doc__\ is also a valid
2776attribute that's read-only, returning the docstring belonging to
2777the class: \verb\"A simple example class"\).
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002778
Fred Drakeeee08cd1997-12-04 15:43:15 +00002779Class \emph{instantiation} uses function notation. Just pretend that
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002780the class object is a parameterless function that returns a new
2781instance of the class. For example, (assuming the above class):
2782
2783\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00002784 x = MyClass()
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002785\end{verbatim}
2786
Fred Drakeeee08cd1997-12-04 15:43:15 +00002787creates a new \emph{instance} of the class and assigns this object to
2788the local variable \code{x}.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002789
2790
2791\subsection{Instance objects}
2792
2793Now what can we do with instance objects? The only operations
2794understood by instance objects are attribute references. There are
2795two kinds of valid attribute names.
2796
Fred Drakeeee08cd1997-12-04 15:43:15 +00002797The first I'll call \emph{data attributes}. These correspond to
Guido van Rossum16d6e711994-08-08 12:30:22 +00002798``instance variables'' in Smalltalk, and to ``data members'' in \Cpp{}.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002799Data attributes need not be declared; like local variables, they
2800spring into existence when they are first assigned to. For example,
2801if \verb\x\ in the instance of \verb\MyClass\ created above, the
2802following piece of code will print the value 16, without leaving a
2803trace:
2804
2805\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00002806 x.counter = 1
2807 while x.counter < 10:
2808 x.counter = x.counter * 2
2809 print x.counter
2810 del x.counter
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002811\end{verbatim}
2812
2813The second kind of attribute references understood by instance objects
Fred Drakeeee08cd1997-12-04 15:43:15 +00002814are \emph{methods}. A method is a function that ``belongs to'' an
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002815object. (In Python, the term method is not unique to class instances:
2816other object types can have methods as well, e.g., list objects have
2817methods called append, insert, remove, sort, and so on. However,
2818below, we'll use the term method exclusively to mean methods of class
2819instance objects, unless explicitly stated otherwise.)
2820
2821Valid method names of an instance object depend on its class. By
2822definition, all attributes of a class that are (user-defined) function
2823objects define corresponding methods of its instances. So in our
Fred Drakeeee08cd1997-12-04 15:43:15 +00002824example, \code{x.f} is a valid method reference, since
2825\code{MyClass.f} is a function, but \code{x.i} is not, since
2826\code{MyClass.i} is not. But \code{x.f} is not the
2827same thing as \verb\MyClass.f\ --- it is a \emph{method object}, not a
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002828function object.
2829
2830
2831\subsection{Method objects}
2832
2833Usually, a method is called immediately, e.g.:
2834
2835\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00002836 x.f()
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002837\end{verbatim}
2838
2839In our example, this will return the string \verb\'hello world'\.
2840However, it is not necessary to call a method right away: \verb\x.f\
2841is a method object, and can be stored away and called at a later
2842moment, for example:
2843
2844\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00002845 xf = x.f
2846 while 1:
2847 print xf()
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002848\end{verbatim}
2849
2850will continue to print \verb\hello world\ until the end of time.
2851
2852What exactly happens when a method is called? You may have noticed
2853that \verb\x.f()\ was called without an argument above, even though
2854the function definition for \verb\f\ specified an argument. What
2855happened to the argument? Surely Python raises an exception when a
2856function that requires an argument is called without any --- even if
2857the argument isn't actually used...
2858
2859Actually, you may have guessed the answer: the special thing about
2860methods is that the object is passed as the first argument of the
2861function. In our example, the call \verb\x.f()\ is exactly equivalent
2862to \verb\MyClass.f(x)\. In general, calling a method with a list of
Fred Drakeeee08cd1997-12-04 15:43:15 +00002863\var{n} arguments is equivalent to calling the corresponding function
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002864with an argument list that is created by inserting the method's object
2865before the first argument.
2866
2867If you still don't understand how methods work, a look at the
2868implementation can perhaps clarify matters. When an instance
2869attribute is referenced that isn't a data attribute, its class is
2870searched. If the name denotes a valid class attribute that is a
2871function object, a method object is created by packing (pointers to)
2872the instance object and the function object just found together in an
2873abstract object: this is the method object. When the method object is
2874called with an argument list, it is unpacked again, a new argument
2875list is constructed from the instance object and the original argument
2876list, and the function object is called with this new argument list.
2877
2878
2879\section{Random remarks}
2880
2881
2882[These should perhaps be placed more carefully...]
2883
2884
2885Data attributes override method attributes with the same name; to
2886avoid accidental name conflicts, which may cause hard-to-find bugs in
2887large programs, it is wise to use some kind of convention that
2888minimizes the chance of conflicts, e.g., capitalize method names,
2889prefix data attribute names with a small unique string (perhaps just
Guido van Rossum6938f061994-08-01 12:22:53 +00002890an underscore), or use verbs for methods and nouns for data attributes.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002891
2892
2893Data attributes may be referenced by methods as well as by ordinary
2894users (``clients'') of an object. In other words, classes are not
2895usable to implement pure abstract data types. In fact, nothing in
2896Python makes it possible to enforce data hiding --- it is all based
2897upon convention. (On the other hand, the Python implementation,
2898written in C, can completely hide implementation details and control
2899access to an object if necessary; this can be used by extensions to
2900Python written in C.)
2901
2902
2903Clients should use data attributes with care --- clients may mess up
2904invariants maintained by the methods by stamping on their data
2905attributes. Note that clients may add data attributes of their own to
2906an instance object without affecting the validity of the methods, as
2907long as name conflicts are avoided --- again, a naming convention can
2908save a lot of headaches here.
2909
2910
2911There is no shorthand for referencing data attributes (or other
2912methods!) from within methods. I find that this actually increases
2913the readability of methods: there is no chance of confusing local
2914variables and instance variables when glancing through a method.
2915
2916
2917Conventionally, the first argument of methods is often called
2918\verb\self\. This is nothing more than a convention: the name
2919\verb\self\ has absolutely no special meaning to Python. (Note,
2920however, that by not following the convention your code may be less
2921readable by other Python programmers, and it is also conceivable that
Fred Drakeeee08cd1997-12-04 15:43:15 +00002922a \emph{class browser} program be written which relies upon such a
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002923convention.)
2924
2925
2926Any function object that is a class attribute defines a method for
2927instances of that class. It is not necessary that the function
2928definition is textually enclosed in the class definition: assigning a
2929function object to a local variable in the class is also ok. For
2930example:
2931
2932\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00002933 # Function defined outside the class
2934 def f1(self, x, y):
2935 return min(x, x+y)
2936
2937 class C:
2938 f = f1
2939 def g(self):
2940 return 'hello world'
2941 h = g
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002942\end{verbatim}
2943
2944Now \verb\f\, \verb\g\ and \verb\h\ are all attributes of class
2945\verb\C\ that refer to function objects, and consequently they are all
2946methods of instances of \verb\C\ --- \verb\h\ being exactly equivalent
2947to \verb\g\. Note that this practice usually only serves to confuse
2948the reader of a program.
2949
2950
2951Methods may call other methods by using method attributes of the
2952\verb\self\ argument, e.g.:
2953
2954\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00002955 class Bag:
2956 def empty(self):
2957 self.data = []
2958 def add(self, x):
2959 self.data.append(x)
2960 def addtwice(self, x):
2961 self.add(x)
2962 self.add(x)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002963\end{verbatim}
2964
2965
2966The instantiation operation (``calling'' a class object) creates an
2967empty object. Many classes like to create objects in a known initial
Guido van Rossumca3f6c81994-10-06 14:08:53 +00002968state. Therefore a class may define a special method named
Fred Drakeeee08cd1997-12-04 15:43:15 +00002969\code{__init__()}, like this:
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002970
Guido van Rossum6938f061994-08-01 12:22:53 +00002971\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00002972 def __init__(self):
2973 self.empty()
Guido van Rossum6938f061994-08-01 12:22:53 +00002974\end{verbatim}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002975
Fred Drakeeee08cd1997-12-04 15:43:15 +00002976When a class defines an \code{__init__()} method, class instantiation
2977automatically invokes \code{__init__()} for the newly-created class
2978instance. So in the \code{Bag} example, a new and initialized instance
Guido van Rossum6938f061994-08-01 12:22:53 +00002979can be obtained by:
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002980
Guido van Rossum6938f061994-08-01 12:22:53 +00002981\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00002982 x = Bag()
Guido van Rossum6938f061994-08-01 12:22:53 +00002983\end{verbatim}
2984
2985Of course, the \verb\__init__\ method may have arguments for greater
2986flexibility. In that case, arguments given to the class instantiation
2987operator are passed on to \verb\__init__\. For example,
2988
2989\bcode\begin{verbatim}
2990>>> class Complex:
2991... def __init__(self, realpart, imagpart):
2992... self.r = realpart
2993... self.i = imagpart
2994...
2995>>> x = Complex(3.0,-4.5)
2996>>> x.r, x.i
2997(3.0, -4.5)
2998>>>
2999\end{verbatim}\ecode
3000%
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003001Methods may reference global names in the same way as ordinary
3002functions. The global scope associated with a method is the module
3003containing the class definition. (The class itself is never used as a
3004global scope!) While one rarely encounters a good reason for using
3005global data in a method, there are many legitimate uses of the global
3006scope: for one thing, functions and modules imported into the global
3007scope can be used by methods, as well as functions and classes defined
3008in it. Usually, the class containing the method is itself defined in
3009this global scope, and in the next section we'll find some good
3010reasons why a method would want to reference its own class!
3011
3012
3013\section{Inheritance}
3014
3015Of course, a language feature would not be worthy of the name ``class''
3016without supporting inheritance. The syntax for a derived class
3017definition looks as follows:
3018
3019\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00003020 class DerivedClassName(BaseClassName):
3021 <statement-1>
3022 .
3023 .
3024 .
3025 <statement-N>
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003026\end{verbatim}
3027
3028The name \verb\BaseClassName\ must be defined in a scope containing
3029the derived class definition. Instead of a base class name, an
3030expression is also allowed. This is useful when the base class is
3031defined in another module, e.g.,
3032
3033\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00003034 class DerivedClassName(modname.BaseClassName):
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003035\end{verbatim}
3036
3037Execution of a derived class definition proceeds the same as for a
3038base class. When the class object is constructed, the base class is
3039remembered. This is used for resolving attribute references: if a
3040requested attribute is not found in the class, it is searched in the
3041base class. This rule is applied recursively if the base class itself
3042is derived from some other class.
3043
3044There's nothing special about instantiation of derived classes:
3045\verb\DerivedClassName()\ creates a new instance of the class. Method
3046references are resolved as follows: the corresponding class attribute
3047is searched, descending down the chain of base classes if necessary,
3048and the method reference is valid if this yields a function object.
3049
3050Derived classes may override methods of their base classes. Because
3051methods have no special privileges when calling other methods of the
3052same object, a method of a base class that calls another method
3053defined in the same base class, may in fact end up calling a method of
Guido van Rossum16d6e711994-08-08 12:30:22 +00003054a derived class that overrides it. (For \Cpp{} programmers: all methods
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003055in Python are ``virtual functions''.)
3056
3057An overriding method in a derived class may in fact want to extend
3058rather than simply replace the base class method of the same name.
3059There is a simple way to call the base class method directly: just
3060call \verb\BaseClassName.methodname(self, arguments)\. This is
3061occasionally useful to clients as well. (Note that this only works if
3062the base class is defined or imported directly in the global scope.)
3063
3064
3065\subsection{Multiple inheritance}
3066
Guido van Rossum6938f061994-08-01 12:22:53 +00003067Python supports a limited form of multiple inheritance as well. A
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003068class definition with multiple base classes looks as follows:
3069
3070\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00003071 class DerivedClassName(Base1, Base2, Base3):
3072 <statement-1>
3073 .
3074 .
3075 .
3076 <statement-N>
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003077\end{verbatim}
3078
3079The only rule necessary to explain the semantics is the resolution
3080rule used for class attribute references. This is depth-first,
3081left-to-right. Thus, if an attribute is not found in
3082\verb\DerivedClassName\, it is searched in \verb\Base1\, then
3083(recursively) in the base classes of \verb\Base1\, and only if it is
3084not found there, it is searched in \verb\Base2\, and so on.
3085
Guido van Rossum95cd2ef1992-12-08 14:37:55 +00003086(To some people breadth first---searching \verb\Base2\ and
3087\verb\Base3\ before the base classes of \verb\Base1\---looks more
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003088natural. However, this would require you to know whether a particular
3089attribute of \verb\Base1\ is actually defined in \verb\Base1\ or in
3090one of its base classes before you can figure out the consequences of
3091a name conflict with an attribute of \verb\Base2\. The depth-first
3092rule makes no differences between direct and inherited attributes of
3093\verb\Base1\.)
3094
3095It is clear that indiscriminate use of multiple inheritance is a
3096maintenance nightmare, given the reliance in Python on conventions to
3097avoid accidental name conflicts. A well-known problem with multiple
3098inheritance is a class derived from two classes that happen to have a
3099common base class. While it is easy enough to figure out what happens
3100in this case (the instance will have a single copy of ``instance
3101variables'' or data attributes used by the common base class), it is
3102not clear that these semantics are in any way useful.
3103
3104
Guido van Rossum02455691997-07-17 16:21:52 +00003105\section{Private variables through name mangling}
3106
3107There is now limited support for class-private
3108identifiers. Any identifier of the form \code{__spam} (at least two
3109leading underscores, at most one trailing underscore) is now textually
3110replaced with \code{_classname__spam}, where \code{classname} is the
3111current class name with leading underscore(s) stripped. This mangling
3112is done without regard of the syntactic position of the identifier, so
3113it can be used to define class-private instance and class variables,
3114methods, as well as globals, and even to store instance variables
Fred Drakeeee08cd1997-12-04 15:43:15 +00003115private to this class on instances of \emph{other} classes. Truncation
Guido van Rossum02455691997-07-17 16:21:52 +00003116may occur when the mangled name would be longer than 255 characters.
3117Outside classes, or when the class name consists of only underscores,
3118no mangling occurs.
3119
3120Name mangling is intended to give classes an easy way to define
3121``private'' instance variables and methods, without having to worry
3122about instance variables defined by derived classes, or mucking with
3123instance variables by code outside the class. Note that the mangling
3124rules are designed mostly to avoid accidents; it still is possible for
3125a determined soul to access or modify a variable that is considered
3126private. This can even be useful, e.g. for the debugger, and that's
3127one reason why this loophole is not closed. (Buglet: derivation of a
3128class with the same name as the base class makes use of private
3129variables of the base class possible.)
3130
3131Notice that code passed to \code{exec}, \code{eval()} or
3132\code{evalfile()} does not consider the classname of the invoking
3133class to be the current class; this is similar to the effect of the
3134\code{global} statement, the effect of which is likewise restricted to
3135code that is byte-compiled together. The same restriction applies to
3136\code{getattr()}, \code{setattr()} and \code{delattr()}, as well as
3137when referencing \code{__dict__} directly.
3138
3139Here's an example of a class that implements its own
3140\code{__getattr__} and \code{__setattr__} methods and stores all
3141attributes in a private variable, in a way that works in Python 1.4 as
3142well as in previous versions:
3143
3144\begin{verbatim}
3145class VirtualAttributes:
3146 __vdict = None
3147 __vdict_name = locals().keys()[0]
3148
3149 def __init__(self):
3150 self.__dict__[self.__vdict_name] = {}
3151
3152 def __getattr__(self, name):
3153 return self.__vdict[name]
3154
3155 def __setattr__(self, name, value):
3156 self.__vdict[name] = value
3157\end{verbatim}
3158
3159%{\em Warning: this is an experimental feature.} To avoid all
3160%potential problems, refrain from using identifiers starting with
3161%double underscore except for predefined uses like \code{__init__}. To
3162%use private names while maintaining future compatibility: refrain from
3163%using the same private name in classes related via subclassing; avoid
3164%explicit (manual) mangling/unmangling; and assume that at some point
3165%in the future, leading double underscore will revert to being just a
3166%naming convention. Discussion on extensive compile-time declarations
3167%are currently underway, and it is impossible to predict what solution
3168%will eventually be chosen for private names. Double leading
3169%underscore is still a candidate, of course --- just not the only one.
3170%It is placed in the distribution in the belief that it is useful, and
3171%so that widespread experience with its use can be gained. It will not
3172%be removed without providing a better solution and a migration path.
3173
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003174\section{Odds and ends}
3175
3176Sometimes it is useful to have a data type similar to the Pascal
3177``record'' or C ``struct'', bundling together a couple of named data
3178items. An empty class definition will do nicely, e.g.:
3179
3180\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00003181 class Employee:
3182 pass
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003183
Fred Drakeeee08cd1997-12-04 15:43:15 +00003184 john = Employee() # Create an empty employee record
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003185
Fred Drakeeee08cd1997-12-04 15:43:15 +00003186 # Fill the fields of the record
3187 john.name = 'John Doe'
3188 john.dept = 'computer lab'
3189 john.salary = 1000
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003190\end{verbatim}
3191
3192
3193A piece of Python code that expects a particular abstract data type
3194can often be passed a class that emulates the methods of that data
3195type instead. For instance, if you have a function that formats some
3196data from a file object, you can define a class with methods
3197\verb\read()\ and \verb\readline()\ that gets the data from a string
3198buffer instead, and pass it as an argument. (Unfortunately, this
3199technique has its limitations: a class can't define operations that
3200are accessed by special syntax such as sequence subscripting or
3201arithmetic operators, and assigning such a ``pseudo-file'' to
3202\verb\sys.stdin\ will not cause the interpreter to read further input
3203from it.)
3204
3205
3206Instance method objects have attributes, too: \verb\m.im_self\ is the
3207object of which the method is an instance, and \verb\m.im_func\ is the
3208function object corresponding to the method.
3209
Guido van Rossum02455691997-07-17 16:21:52 +00003210\subsection{Exceptions Can Be Classes}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003211
3212User-defined exceptions are no longer limited to being string objects
3213--- they can be identified by classes as well. Using this mechanism it
3214is possible to create extensible hierarchies of exceptions.
3215
3216There are two new valid (semantic) forms for the raise statement:
3217
3218\begin{verbatim}
3219raise Class, instance
3220
3221raise instance
3222\end{verbatim}
3223
3224In the first form, \code{instance} must be an instance of \code{Class}
3225or of a class derived from it. The second form is a shorthand for
3226
3227\begin{verbatim}
3228raise instance.__class__, instance
3229\end{verbatim}
3230
3231An except clause may list classes as well as string objects. A class
3232in an except clause is compatible with an exception if it is the same
3233class or a base class thereof (but not the other way around --- an
3234except clause listing a derived class is not compatible with a base
3235class). For example, the following code will print B, C, D in that
3236order:
3237
3238\begin{verbatim}
3239class B:
3240 pass
3241class C(B):
3242 pass
3243class D(C):
3244 pass
3245
3246for c in [B, C, D]:
3247 try:
3248 raise c()
3249 except D:
3250 print "D"
3251 except C:
3252 print "C"
3253 except B:
3254 print "B"
3255\end{verbatim}
3256
3257Note that if the except clauses were reversed (with ``\code{except B}''
3258first), it would have printed B, B, B --- the first matching except
3259clause is triggered.
3260
3261When an error message is printed for an unhandled exception which is a
3262class, the class name is printed, then a colon and a space, and
3263finally the instance converted to a string using the built-in function
3264\code{str()}.
3265
3266In this release, the built-in exceptions are still strings.
3267
Guido van Rossum02455691997-07-17 16:21:52 +00003268\chapter{What Now?}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003269
Guido van Rossum02455691997-07-17 16:21:52 +00003270Hopefully reading this tutorial has reinforced your interest in using
3271Python. Now what should you do?
Guido van Rossum194e57c1995-02-15 15:51:38 +00003272
Guido van Rossum02455691997-07-17 16:21:52 +00003273You should read, or at least page through, the Library Reference,
3274which gives complete (though terse) reference material about types,
3275functions, and modules that can save you a lot of time when writing
3276Python programs. The standard Python distribution includes a
3277\emph{lot} of code in both C and Python; there are modules to read
3278Unix mailboxes, retrieve documents via HTTP, generate random numbers,
3279parse command-line options, write CGI programs, compress data, and a
3280lot more; skimming through the Library Reference will give you an idea
3281of what's available.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003282
Guido van Rossum02455691997-07-17 16:21:52 +00003283The major Python Web site is \code{http://www.python.org}; it contains
3284code, documentation, and pointers to Python-related pages around the
3285Web. \code{www.python.org} is mirrored in various places around the
3286world, such as Europe, Japan, and Australia; a mirror may be faster
3287than the main site, depending on your geographical location. A more
3288informal site is \code{http://starship.skyport.net}, which contains a
3289bunch of Python-related personal home pages; many people have
3290downloadable software here.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003291
Guido van Rossum02455691997-07-17 16:21:52 +00003292For Python-related questions and problem reports, you can post to the
3293newsgroup \code{comp.lang.python}, or send them to the mailing list at
3294\code{python-list@cwi.nl}. The newsgroup and mailing list are
3295gatewayed, so messages posted to one will automatically be forwarded
3296to the other. There are around 20--30 postings a day, asking (and
3297answering) questions, suggesting new features, and announcing new
3298modules. But before posting, be sure to check the list of Frequently
3299Asked Questions (also called the FAQ), at
3300\code{http://www.python.org/doc/FAQ.html}, or look for it in the
3301\code{Misc/} directory of the Python source distribution. The FAQ
3302answers many of the questions that come up again and again, and may
3303already contain the solution for your problem.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003304
Guido van Rossum02455691997-07-17 16:21:52 +00003305You can support the Python community by joining the Python Software
3306Activity, which runs the python.org web, ftp and email servers, and
3307organizes Python workshops. See \code{http://www.python.org/psa/} for
3308information on how to join.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003309
Guido van Rossum194e57c1995-02-15 15:51:38 +00003310
Guido van Rossum02455691997-07-17 16:21:52 +00003311\chapter{Recent Additions as of Release 1.1}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003312
Guido van Rossum02455691997-07-17 16:21:52 +00003313XXX Should the stuff in this chapter be deleted, or can a home be found or it elsewhere in the Tutorial?
Guido van Rossum194e57c1995-02-15 15:51:38 +00003314
Guido van Rossum02455691997-07-17 16:21:52 +00003315\section{Lambda Forms}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003316
Guido van Rossum02455691997-07-17 16:21:52 +00003317XXX Where to put this? Or just leave it out?
Guido van Rossum194e57c1995-02-15 15:51:38 +00003318
Guido van Rossum02455691997-07-17 16:21:52 +00003319By popular demand, a few features commonly found in functional
3320programming languages and Lisp have been added to Python. With the
3321\verb\lambda\ keyword, small anonymous functions can be created.
3322Here's a function that returns the sum of its two arguments:
3323\verb\lambda a, b: a+b\. Lambda forms can be used wherever function
3324objects are required. They are syntactically restricted to a single
3325expression. Semantically, they are just syntactic sugar for a normal
3326function definition. Like nested function definitions, lambda forms
3327cannot reference variables from the containing scope, but this can be
3328overcome through the judicious use of default argument values, e.g.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003329
Guido van Rossum02455691997-07-17 16:21:52 +00003330\begin{verbatim}
Fred Drakeeee08cd1997-12-04 15:43:15 +00003331 def make_incrementor(n):
3332 return lambda x, incr=n: x+incr
Guido van Rossum02455691997-07-17 16:21:52 +00003333\end{verbatim}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003334
3335\section{Documentation Strings}
3336
Guido van Rossum02455691997-07-17 16:21:52 +00003337XXX Where to put this? Or just leave it out?
Guido van Rossum194e57c1995-02-15 15:51:38 +00003338
3339There are emerging conventions about the content and formatting of
3340documentation strings.
3341
3342The first line should always be a short, concise summary of the
3343object's purpose. For brevity, it should not explicitly state the
3344object's name or type, since these are available by other means
3345(except if the name happens to be a verb describing a function's
3346operation). This line should begin with a capital letter and end with
3347a period.
3348
3349If there are more lines in the documentation string, the second line
3350should be blank, visually separating the summary from the rest of the
3351description. The following lines should be one of more of paragraphs
3352describing the objects calling conventions, its side effects, etc.
3353
3354Some people like to copy the Emacs convention of using UPPER CASE for
3355function parameters --- this often saves a few words or lines.
3356
3357The Python parser does not strip indentation from multi-line string
3358literals in Python, so tools that process documentation have to strip
3359indentation. This is done using the following convention. The first
Fred Drakeeee08cd1997-12-04 15:43:15 +00003360non-blank line \emph{after} the first line of the string determines the
Guido van Rossum194e57c1995-02-15 15:51:38 +00003361amount of indentation for the entire documentation string. (We can't
3362use the first line since it is generally adjacent to the string's
3363opening quotes so its indentation is not apparent in the string
3364literal.) Whitespace ``equivalent'' to this indentation is then
3365stripped from the start of all lines of the string. Lines that are
3366indented less should not occur, but if they occur all their leading
3367whitespace should be stripped. Equivalence of whitespace should be
3368tested after expansion of tabs (to 8 spaces, normally).
3369
Guido van Rossum194e57c1995-02-15 15:51:38 +00003370
Guido van Rossum02455691997-07-17 16:21:52 +00003371\appendix\chapter{Interactive Input Editing and History Substitution}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003372
Guido van Rossum02455691997-07-17 16:21:52 +00003373Some versions of the Python interpreter support editing of the current
3374input line and history substitution, similar to facilities found in
3375the Korn shell and the GNU Bash shell. This is implemented using the
Fred Drakeeee08cd1997-12-04 15:43:15 +00003376\emph{GNU Readline} library, which supports Emacs-style and vi-style
Guido van Rossum02455691997-07-17 16:21:52 +00003377editing. This library has its own documentation which I won't
3378duplicate here; however, the basics are easily explained.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003379
Guido van Rossum02455691997-07-17 16:21:52 +00003380\subsection{Line Editing}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003381
Guido van Rossum02455691997-07-17 16:21:52 +00003382If supported, input line editing is active whenever the interpreter
3383prints a primary or secondary prompt. The current line can be edited
3384using the conventional Emacs control characters. The most important
3385of these are: C-A (Control-A) moves the cursor to the beginning of the
3386line, C-E to the end, C-B moves it one position to the left, C-F to
3387the right. Backspace erases the character to the left of the cursor,
3388C-D the character to its right. C-K kills (erases) the rest of the
3389line to the right of the cursor, C-Y yanks back the last killed
3390string. C-underscore undoes the last change you made; it can be
3391repeated for cumulative effect.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003392
Guido van Rossum02455691997-07-17 16:21:52 +00003393\subsection{History Substitution}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003394
Guido van Rossum02455691997-07-17 16:21:52 +00003395History substitution works as follows. All non-empty input lines
3396issued are saved in a history buffer, and when a new prompt is given
3397you are positioned on a new line at the bottom of this buffer. C-P
3398moves one line up (back) in the history buffer, C-N moves one down.
3399Any line in the history buffer can be edited; an asterisk appears in
3400front of the prompt to mark a line as modified. Pressing the Return
3401key passes the current line to the interpreter. C-R starts an
3402incremental reverse search; C-S starts a forward search.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003403
Guido van Rossum02455691997-07-17 16:21:52 +00003404\subsection{Key Bindings}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003405
Guido van Rossum02455691997-07-17 16:21:52 +00003406The key bindings and some other parameters of the Readline library can
3407be customized by placing commands in an initialization file called
Fred Drakeeee08cd1997-12-04 15:43:15 +00003408\file{\$HOME/.inputrc}. Key bindings have the form
Guido van Rossum194e57c1995-02-15 15:51:38 +00003409
Guido van Rossum02455691997-07-17 16:21:52 +00003410\bcode\begin{verbatim}
3411key-name: function-name
3412\end{verbatim}\ecode
3413%
3414or
Guido van Rossum194e57c1995-02-15 15:51:38 +00003415
Guido van Rossum02455691997-07-17 16:21:52 +00003416\bcode\begin{verbatim}
3417"string": function-name
3418\end{verbatim}\ecode
3419%
3420and options can be set with
Guido van Rossum194e57c1995-02-15 15:51:38 +00003421
Guido van Rossum02455691997-07-17 16:21:52 +00003422\bcode\begin{verbatim}
3423set option-name value
3424\end{verbatim}\ecode
3425%
3426For example:
Guido van Rossum194e57c1995-02-15 15:51:38 +00003427
Guido van Rossum02455691997-07-17 16:21:52 +00003428\bcode\begin{verbatim}
3429# I prefer vi-style editing:
3430set editing-mode vi
3431# Edit using a single line:
3432set horizontal-scroll-mode On
3433# Rebind some keys:
3434Meta-h: backward-kill-word
3435"\C-u": universal-argument
3436"\C-x\C-r": re-read-init-file
3437\end{verbatim}\ecode
3438%
3439Note that the default binding for TAB in Python is to insert a TAB
3440instead of Readline's default filename completion function. If you
3441insist, you can override this by putting
Guido van Rossum194e57c1995-02-15 15:51:38 +00003442
Guido van Rossum02455691997-07-17 16:21:52 +00003443\bcode\begin{verbatim}
3444TAB: complete
3445\end{verbatim}\ecode
3446%
Fred Drakeeee08cd1997-12-04 15:43:15 +00003447in your \file{\$HOME/.inputrc}. (Of course, this makes it hard to type
Guido van Rossum02455691997-07-17 16:21:52 +00003448indented continuation lines...)
Guido van Rossum194e57c1995-02-15 15:51:38 +00003449
Guido van Rossum02455691997-07-17 16:21:52 +00003450\subsection{Commentary}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003451
Guido van Rossum02455691997-07-17 16:21:52 +00003452This facility is an enormous step forward compared to previous
3453versions of the interpreter; however, some wishes are left: It would
3454be nice if the proper indentation were suggested on continuation lines
3455(the parser knows if an indent token is required next). The
3456completion mechanism might use the interpreter's symbol table. A
3457command to check (or even suggest) matching parentheses, quotes etc.
3458would also be useful.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003459
Guido van Rossum02455691997-07-17 16:21:52 +00003460XXX Lele Gaifax's readline module, which adds name completion...
Guido van Rossum97662c81996-08-23 15:35:47 +00003461
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003462\end{document}
Guido van Rossum02455691997-07-17 16:21:52 +00003463