blob: 2d758aea7c285a507ce0d6c45a48cb1208f260fb [file] [log] [blame]
Fred Drake6659c301998-03-03 22:02:19 +00001\documentclass{manual}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002
Guido van Rossum02455691997-07-17 16:21:52 +00003% Things to do:
4% Add a section on file I/O
5% Write a chapter entitled ``Some Useful Modules''
6% --regex, math+cmath
7% Should really move the Python startup file info to an appendix
Guido van Rossum02455691997-07-17 16:21:52 +00008
Guido van Rossumdccc2981997-12-30 04:40:25 +00009\title{Python Tutorial}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000010
Guido van Rossum16cd7f91994-10-06 10:29:26 +000011\input{boilerplate}
Guido van Rossum83eb9621993-11-23 16:28:45 +000012
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000013\begin{document}
14
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000015\maketitle
16
Fred Drake9f86b661998-07-28 21:55:19 +000017\ifhtml
18\chapter*{Front Matter\label{front}}
19\fi
20
Guido van Rossum16cd7f91994-10-06 10:29:26 +000021\input{copyright}
22
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000023\begin{abstract}
24
25\noindent
Guido van Rossumdccc2981997-12-30 04:40:25 +000026Python is an easy to learn, powerful programming language. It has
27efficient high-level data structures and a simple but effective
28approach to object-oriented programming. Python's elegant syntax and
29dynamic typing, together with its interpreted nature, make it an ideal
30language for scripting and rapid application development in many areas
31on most platforms.
32
33The Python interpreter and the extensive standard library are freely
34available in source or binary form for all major platforms from the
Fred Drakeca6567f1998-01-22 20:44:18 +000035Python web site, \url{http://www.python.org}, and can be freely
Guido van Rossumdccc2981997-12-30 04:40:25 +000036distributed. The same site also contains distributions of and
37pointers to many free third party Python modules, programs and tools,
38and additional documentation.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000039
Guido van Rossum4410c751991-06-04 20:22:18 +000040The Python interpreter is easily extended with new functions and data
Fred Drake3f205921998-01-13 18:56:38 +000041types implemented in \C{} or \Cpp{} (or other languages callable from \C{}).
Guido van Rossumdccc2981997-12-30 04:40:25 +000042Python is also suitable as an extension language for customizable
43applications.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000044
Guido van Rossum6fc178f1991-08-16 09:13:42 +000045This tutorial introduces the reader informally to the basic concepts
46and features of the Python language and system. It helps to have a
Guido van Rossumdccc2981997-12-30 04:40:25 +000047Python interpreter handy for hands-on experience, but all examples are
48self-contained, so the tutorial can be read off-line as well.
Guido van Rossum2292b8e1991-01-23 16:31:24 +000049
Guido van Rossumdccc2981997-12-30 04:40:25 +000050For a description of standard objects and modules, see the
51\emph{Python Library Reference} document. The \emph{Python Reference
52Manual} gives a more formal definition of the language. To write
Fred Drake3f205921998-01-13 18:56:38 +000053extensions in \C{} or \Cpp{}, read the \emph{Extending and Embedding} and
54\emph{Python/\C{} API} manuals. There are also several books covering
Guido van Rossumdccc2981997-12-30 04:40:25 +000055Python in depth.
56
57This tutorial does not attempt to be comprehensive and cover every
58single feature, or even every commonly used feature. Instead, it
59introduces many of Python's most noteworthy features, and will give
60you a good idea of the language's flavor and style. After reading it,
61you will be able to read and write Python modules and programs, and
62you will be ready to learn more about the various Python library
63modules described in the \emph{Python Library Reference}.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000064
65\end{abstract}
66
Fred Drake4d4f9e71998-01-13 22:25:02 +000067\tableofcontents
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000068
Guido van Rossum5e0759d1992-08-07 16:06:24 +000069
Fred Drakeb7833d31998-09-11 16:21:55 +000070\chapter{Whetting Your Appetite \label{intro}}
Guido van Rossum3a26dd81996-10-24 22:12:48 +000071
Guido van Rossum6fc178f1991-08-16 09:13:42 +000072If you ever wrote a large shell script, you probably know this
73feeling: you'd love to add yet another feature, but it's already so
74slow, and so big, and so complicated; or the feature involves a system
Fred Drake3f205921998-01-13 18:56:38 +000075call or other function that is only accessible from \C{} \ldots Usually
Guido van Rossum6fc178f1991-08-16 09:13:42 +000076the problem at hand isn't serious enough to warrant rewriting the
Fred Drake3f205921998-01-13 18:56:38 +000077script in \C{}; perhaps the problem requires variable-length strings or
Guido van Rossum02455691997-07-17 16:21:52 +000078other data types (like sorted lists of file names) that are easy in
Fred Drake3f205921998-01-13 18:56:38 +000079the shell but lots of work to implement in \C{}, or perhaps you're not
80sufficiently familiar with \C{}.
Guido van Rossum02455691997-07-17 16:21:52 +000081
Fred Drake3f205921998-01-13 18:56:38 +000082Another situation: perhaps you have to work with several \C{} libraries,
83and the usual \C{} write/compile/test/re-compile cycle is too slow. You
Guido van Rossum02455691997-07-17 16:21:52 +000084need to develop software more quickly. Possibly perhaps you've
85written a program that could use an extension language, and you don't
86want to design a language, write and debug an interpreter for it, then
87tie it into your application.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000088
Guido van Rossum6fc178f1991-08-16 09:13:42 +000089In such cases, Python may be just the language for you. Python is
90simple to use, but it is a real programming language, offering much
91more structure and support for large programs than the shell has. On
Fred Drake3f205921998-01-13 18:56:38 +000092the other hand, it also offers much more error checking than \C{}, and,
Fred Drakeeee08cd1997-12-04 15:43:15 +000093being a \emph{very-high-level language}, it has high-level data types
Guido van Rossum6fc178f1991-08-16 09:13:42 +000094built in, such as flexible arrays and dictionaries that would cost you
Fred Drake3f205921998-01-13 18:56:38 +000095days to implement efficiently in \C{}. Because of its more general data
Fred Drakeeee08cd1997-12-04 15:43:15 +000096types Python is applicable to a much larger problem domain than
97\emph{Awk} or even \emph{Perl}, yet many things are at least as easy
98in Python as in those languages.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000099
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000100Python allows you to split up your program in modules that can be
101reused in other Python programs. It comes with a large collection of
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000102standard modules that you can use as the basis of your programs --- or
103as examples to start learning to program in Python. There are also
104built-in modules that provide things like file I/O, system calls,
Guido van Rossum02455691997-07-17 16:21:52 +0000105sockets, and even interfaces to GUI toolkits like Tk.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000106
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000107Python is an interpreted language, which can save you considerable time
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000108during program development because no compilation and linking is
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000109necessary. The interpreter can be used interactively, which makes it
110easy to experiment with features of the language, to write throw-away
111programs, or to test functions during bottom-up program development.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000112It is also a handy desk calculator.
113
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000114Python allows writing very compact and readable programs. Programs
Fred Drake3f205921998-01-13 18:56:38 +0000115written in Python are typically much shorter than equivalent \C{}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000116programs, for several reasons:
117\begin{itemize}
118\item
119the high-level data types allow you to express complex operations in a
120single statement;
121\item
122statement grouping is done by indentation instead of begin/end
123brackets;
124\item
125no variable or argument declarations are necessary.
126\end{itemize}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000127
Fred Drake3f205921998-01-13 18:56:38 +0000128Python is \emph{extensible}: if you know how to program in \C{} it is easy
Guido van Rossum02455691997-07-17 16:21:52 +0000129to add a new built-in function or module to the interpreter, either to
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000130perform critical operations at maximum speed, or to link Python
131programs to libraries that may only be available in binary form (such
132as a vendor-specific graphics library). Once you are really hooked,
Fred Drake3f205921998-01-13 18:56:38 +0000133you can link the Python interpreter into an application written in \C{}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000134and use it as an extension or command language for that application.
135
Guido van Rossum02455691997-07-17 16:21:52 +0000136By the way, the language is named after the BBC show ``Monty Python's
137Flying Circus'' and has nothing to do with nasty reptiles. Making
138references to Monty Python skits in documentation is not only allowed,
Guido van Rossumdccc2981997-12-30 04:40:25 +0000139it is encouraged!
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000140
Fred Drakeb7833d31998-09-11 16:21:55 +0000141\section{Where From Here \label{where}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000142
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000143Now that you are all excited about Python, you'll want to examine it
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000144in some more detail. Since the best way to learn a language is
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000145using it, you are invited here to do so.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000146
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000147In the next chapter, the mechanics of using the interpreter are
148explained. This is rather mundane information, but essential for
149trying out the examples shown later.
150
Guido van Rossum4410c751991-06-04 20:22:18 +0000151The rest of the tutorial introduces various features of the Python
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000152language and system though examples, beginning with simple
153expressions, statements and data types, through functions and modules,
Guido van Rossum6938f061994-08-01 12:22:53 +0000154and finally touching upon advanced concepts like exceptions
155and user-defined classes.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000156
Fred Drakeb7833d31998-09-11 16:21:55 +0000157\chapter{Using the Python Interpreter \label{using}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000158
Fred Drakeb7833d31998-09-11 16:21:55 +0000159\section{Invoking the Interpreter \label{invoking}}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000160
Fred Drakeeee08cd1997-12-04 15:43:15 +0000161The Python interpreter is usually installed as \file{/usr/local/bin/python}
162on those machines where it is available; putting \file{/usr/local/bin} in
Fred Drake6dc2aae1996-12-13 21:56:03 +0000163your \UNIX{} shell's search path makes it possible to start it by
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000164typing the command
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000165
Fred Drake8842e861998-02-13 07:16:30 +0000166\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000167python
Fred Drake8842e861998-02-13 07:16:30 +0000168\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000169
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000170to the shell. Since the choice of the directory where the interpreter
171lives is an installation option, other places are possible; check with
Fred Drakeeee08cd1997-12-04 15:43:15 +0000172your local Python guru or system administrator. (E.g.,
173\file{/usr/local/python} is a popular alternative location.)
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000174
Guido van Rossuma8a1b9b1998-06-22 14:28:39 +0000175Typing an EOF character (Control-D on \UNIX{}, Control-Z on DOS
Guido van Rossum02455691997-07-17 16:21:52 +0000176or Windows) at the primary prompt causes the interpreter to exit with
177a zero exit status. If that doesn't work, you can exit the
Fred Drake8842e861998-02-13 07:16:30 +0000178interpreter by typing the following commands: \samp{import sys;
Guido van Rossum02455691997-07-17 16:21:52 +0000179sys.exit()}.
180
181The interpreter's line-editing features usually aren't very
Fred Drake3f205921998-01-13 18:56:38 +0000182sophisticated. On \UNIX{}, whoever installed the interpreter may have
Guido van Rossum02455691997-07-17 16:21:52 +0000183enabled support for the GNU readline library, which adds more
184elaborate interactive editing and history features. Perhaps the
185quickest check to see whether command line editing is supported is
186typing Control-P to the first Python prompt you get. If it beeps, you
187have command line editing; see Appendix A for an introduction to the
Fred Drakeeee08cd1997-12-04 15:43:15 +0000188keys. If nothing appears to happen, or if \code{\^P} is echoed,
Guido van Rossum02455691997-07-17 16:21:52 +0000189command line editing isn't available; you'll only be able to use
190backspace to remove characters from the current line.
191
Fred Drake6dc2aae1996-12-13 21:56:03 +0000192The interpreter operates somewhat like the \UNIX{} shell: when called
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000193with standard input connected to a tty device, it reads and executes
194commands interactively; when called with a file name argument or with
Fred Drakeeee08cd1997-12-04 15:43:15 +0000195a file as standard input, it reads and executes a \emph{script} from
Guido van Rossum02455691997-07-17 16:21:52 +0000196that file.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000197
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000198A third way of starting the interpreter is
Fred Drakeeee08cd1997-12-04 15:43:15 +0000199\samp{python -c command [arg] ...}, which
200executes the statement(s) in \code{command}, analogous to the shell's
201\code{-c} option. Since Python statements often contain spaces or other
202characters that are special to the shell, it is best to quote
203\code{command} in its entirety with double quotes.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000204
Fred Drakeeee08cd1997-12-04 15:43:15 +0000205Note that there is a difference between \samp{python file} and
206\samp{python <file}. In the latter case, input requests from the
207program, such as calls to \code{input()} and \code{raw_input()}, are
208satisfied from \emph{file}. Since this file has already been read
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000209until the end by the parser before the program starts executing, the
210program will encounter EOF immediately. In the former case (which is
211usually what you want) they are satisfied from whatever file or device
212is connected to standard input of the Python interpreter.
213
Guido van Rossumb2c65561993-05-12 08:53:36 +0000214When a script file is used, it is sometimes useful to be able to run
215the script and enter interactive mode afterwards. This can be done by
Fred Drakeeee08cd1997-12-04 15:43:15 +0000216passing \code{-i} before the script. (This does not work if the script
Guido van Rossumb2c65561993-05-12 08:53:36 +0000217is read from standard input, for the same reason as explained in the
218previous paragraph.)
219
Fred Drakeb7833d31998-09-11 16:21:55 +0000220\subsection{Argument Passing \label{argPassing}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000221
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000222When known to the interpreter, the script name and additional
Fred Drakeeee08cd1997-12-04 15:43:15 +0000223arguments thereafter are passed to the script in the variable
224\code{sys.argv}, which is a list of strings. Its length is at least
225one; when no script and no arguments are given, \code{sys.argv[0]} is
226an empty string. When the script name is given as \code{'-'} (meaning
227standard input), \code{sys.argv[0]} is set to \code{'-'}. When \code{-c
228command} is used, \code{sys.argv[0]} is set to \code{'-c'}. Options
229found after \code{-c command} are not consumed by the Python
230interpreter's option processing but left in \code{sys.argv} for the
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000231command to handle.
232
Fred Drakeb7833d31998-09-11 16:21:55 +0000233\subsection{Interactive Mode \label{interactive}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000234
Guido van Rossumdd010801991-06-07 14:31:11 +0000235When commands are read from a tty, the interpreter is said to be in
Fred Drakeeee08cd1997-12-04 15:43:15 +0000236\emph{interactive mode}. In this mode it prompts for the next command
237with the \emph{primary prompt}, usually three greater-than signs
Fred Drake8842e861998-02-13 07:16:30 +0000238(\samp{>>> }); for continuation lines it prompts with the
Fred Drakeeee08cd1997-12-04 15:43:15 +0000239\emph{secondary prompt},
Fred Drake8842e861998-02-13 07:16:30 +0000240by default three dots (\samp{... }).
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000241
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000242The interpreter prints a welcome message stating its version number
243and a copyright notice before printing the first prompt, e.g.:
244
Fred Drake8842e861998-02-13 07:16:30 +0000245\begin{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000246python
Fred Drakeeee08cd1997-12-04 15:43:15 +0000247Python 1.5b1 (#1, Dec 3 1997, 00:02:06) [GCC 2.7.2.2] on sunos5
248Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000249>>>
Fred Drake8842e861998-02-13 07:16:30 +0000250\end{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000251
Fred Drakeb7833d31998-09-11 16:21:55 +0000252\section{The Interpreter and Its Environment \label{interp}}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000253
Fred Drakeb7833d31998-09-11 16:21:55 +0000254\subsection{Error Handling \label{error}}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000255
256When an error occurs, the interpreter prints an error
257message and a stack trace. In interactive mode, it then returns to
258the primary prompt; when input came from a file, it exits with a
259nonzero exit status after printing
Fred Drakeeee08cd1997-12-04 15:43:15 +0000260the stack trace. (Exceptions handled by an \code{except} clause in a
261\code{try} statement are not errors in this context.) Some errors are
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000262unconditionally fatal and cause an exit with a nonzero exit; this
263applies to internal inconsistencies and some cases of running out of
264memory. All error messages are written to the standard error stream;
265normal output from the executed commands is written to standard
266output.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000267
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000268Typing the interrupt character (usually Control-C or DEL) to the
269primary or secondary prompt cancels the input and returns to the
270primary prompt.%
271\footnote{
Guido van Rossum6938f061994-08-01 12:22:53 +0000272 A problem with the GNU Readline package may prevent this.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000273}
Fred Drakeeee08cd1997-12-04 15:43:15 +0000274Typing an interrupt while a command is executing raises the
275\code{KeyboardInterrupt} exception, which may be handled by a
276\code{try} statement.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000277
Fred Drakeb7833d31998-09-11 16:21:55 +0000278\subsection{Executable Python Scripts \label{scripts}}
Guido van Rossum4410c751991-06-04 20:22:18 +0000279
Fred Drake6dc2aae1996-12-13 21:56:03 +0000280On BSD'ish \UNIX{} systems, Python scripts can be made directly
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000281executable, like shell scripts, by putting the line
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000282
Fred Drake8842e861998-02-13 07:16:30 +0000283\begin{verbatim}
Fred Drake9e63faa1997-10-15 14:37:24 +0000284#! /usr/bin/env python
Fred Drake8842e861998-02-13 07:16:30 +0000285\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000286
Fred Drake391564f1998-04-01 23:11:56 +0000287(assuming that the interpreter is on the user's \envvar{PATH}) at the
288beginning of the script and giving the file an executable mode. The
289\samp{\#!} must be the first two characters of the file.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000290
Fred Drakeb7833d31998-09-11 16:21:55 +0000291\subsection{The Interactive Startup File \label{startup}}
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000292
Fred Drake8842e861998-02-13 07:16:30 +0000293% XXX This should probably be dumped in an appendix, since most people
294% don't use Python interactively in non-trivial ways.
Guido van Rossum02455691997-07-17 16:21:52 +0000295
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000296When you use Python interactively, it is frequently handy to have some
297standard commands executed every time the interpreter is started. You
Fred Drakeeee08cd1997-12-04 15:43:15 +0000298can do this by setting an environment variable named
Fred Drake391564f1998-04-01 23:11:56 +0000299\envvar{PYTHONSTARTUP} to the name of a file containing your start-up
Fred Drakeeee08cd1997-12-04 15:43:15 +0000300commands. This is similar to the \file{.profile} feature of the \UNIX{}
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000301shells.
302
303This file is only read in interactive sessions, not when Python reads
Fred Drakeeee08cd1997-12-04 15:43:15 +0000304commands from a script, and not when \file{/dev/tty} is given as the
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000305explicit source of commands (which otherwise behaves like an
306interactive session). It is executed in the same name space where
307interactive commands are executed, so that objects that it defines or
308imports can be used without qualification in the interactive session.
Fred Drakeeee08cd1997-12-04 15:43:15 +0000309You can also change the prompts \code{sys.ps1} and \code{sys.ps2} in
Guido van Rossum7b3c8a11992-09-08 09:20:13 +0000310this file.
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000311
312If you want to read an additional start-up file from the current
Fred Drake72389881998-04-13 01:31:10 +0000313directory, you can program this in the global start-up file,
314e.g.\ \samp{execfile('.pythonrc')}\indexii{.pythonrc.py}{file}. If
315you want to use the startup file in a script, you must do this
316explicitly in the script:
Fred Drake8842e861998-02-13 07:16:30 +0000317
318\begin{verbatim}
319import os
Fred Drake72389881998-04-13 01:31:10 +0000320if os.path.isfile(os.environ['PYTHONSTARTUP']):
321 execfile(os.environ['PYTHONSTARTUP'])
Fred Drake8842e861998-02-13 07:16:30 +0000322\end{verbatim}
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000323
Fred Drake72389881998-04-13 01:31:10 +0000324
Fred Drakeb7833d31998-09-11 16:21:55 +0000325\chapter{An Informal Introduction to Python \label{informal}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000326
327In the following examples, input and output are distinguished by the
Fred Drake8842e861998-02-13 07:16:30 +0000328presence or absence of prompts (\samp{>>> } and \samp{... }): to repeat
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000329the example, you must type everything after the prompt, when the
330prompt appears; lines that do not begin with a prompt are output from
331the interpreter.%
Guido van Rossum02455691997-07-17 16:21:52 +0000332%\footnote{
333% I'd prefer to use different fonts to distinguish input
334% from output, but the amount of LaTeX hacking that would require
335% is currently beyond my ability.
336%}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000337Note that a secondary prompt on a line by itself in an example means
338you must type a blank line; this is used to end a multi-line command.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000339
Fred Drakeb7833d31998-09-11 16:21:55 +0000340\section{Using Python as a Calculator \label{calculator}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000341
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000342Let's try some simple Python commands. Start the interpreter and wait
Fred Drake8842e861998-02-13 07:16:30 +0000343for the primary prompt, \samp{>>> }. (It shouldn't take long.)
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000344
Fred Drakeb7833d31998-09-11 16:21:55 +0000345\subsection{Numbers \label{numbers}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000346
347The interpreter acts as a simple calculator: you can type an
348expression at it and it will write the value. Expression syntax is
Fred Drakeeee08cd1997-12-04 15:43:15 +0000349straightforward: the operators \code{+}, \code{-}, \code{*} and \code{/}
Fred Drake3f205921998-01-13 18:56:38 +0000350work just like in most other languages (e.g., Pascal or \C{}); parentheses
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000351can be used for grouping. For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000352
Fred Drake8842e861998-02-13 07:16:30 +0000353\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000354>>> 2+2
3554
Guido van Rossum6938f061994-08-01 12:22:53 +0000356>>> # This is a comment
357... 2+2
3584
359>>> 2+2 # and a comment on the same line as code
3604
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000361>>> (50-5*6)/4
3625
Guido van Rossum6938f061994-08-01 12:22:53 +0000363>>> # Integer division returns the floor:
364... 7/3
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003652
Guido van Rossum6938f061994-08-01 12:22:53 +0000366>>> 7/-3
367-3
Fred Drake8842e861998-02-13 07:16:30 +0000368\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000369
Fred Drake391564f1998-04-01 23:11:56 +0000370Like in \C{}, the equal sign (\character{=}) is used to assign a value to a
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000371variable. The value of an assignment is not written:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000372
Fred Drake8842e861998-02-13 07:16:30 +0000373\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000374>>> width = 20
375>>> height = 5*9
376>>> width * height
377900
Fred Drake8842e861998-02-13 07:16:30 +0000378\end{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000379%
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000380A value can be assigned to several variables simultaneously:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000381
Fred Drake8842e861998-02-13 07:16:30 +0000382\begin{verbatim}
Guido van Rossum6938f061994-08-01 12:22:53 +0000383>>> x = y = z = 0 # Zero x, y and z
384>>> x
3850
386>>> y
3870
388>>> z
3890
Fred Drake8842e861998-02-13 07:16:30 +0000390\end{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000391%
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000392There is full support for floating point; operators with mixed type
393operands convert the integer operand to floating point:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000394
Fred Drake8842e861998-02-13 07:16:30 +0000395\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000396>>> 4 * 2.5 / 3.3
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003973.0303030303
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000398>>> 7.0 / 2
3993.5
Fred Drake8842e861998-02-13 07:16:30 +0000400\end{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +0000401%
402Complex numbers are also supported; imaginary numbers are written with
Fred Drake8842e861998-02-13 07:16:30 +0000403a suffix of \samp{j} or \samp{J}. Complex numbers with a nonzero
404real component are written as \samp{(\var{real}+\var{imag}j)}, or can
405be created with the \samp{complex(\var{real}, \var{imag})} function.
Guido van Rossum02455691997-07-17 16:21:52 +0000406
Fred Drake8842e861998-02-13 07:16:30 +0000407\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +0000408>>> 1j * 1J
409(-1+0j)
410>>> 1j * complex(0,1)
411(-1+0j)
412>>> 3+1j*3
413(3+3j)
414>>> (3+1j)*3
415(9+3j)
416>>> (1+2j)/(1+1j)
417(1.5+0.5j)
Fred Drake8842e861998-02-13 07:16:30 +0000418\end{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +0000419%
420Complex numbers are always represented as two floating point numbers,
421the real and imaginary part. To extract these parts from a complex
Fred Drake8842e861998-02-13 07:16:30 +0000422number \var{z}, use \code{\var{z}.real} and \code{\var{z}.imag}.
Guido van Rossum02455691997-07-17 16:21:52 +0000423
Fred Drake8842e861998-02-13 07:16:30 +0000424\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +0000425>>> a=1.5+0.5j
426>>> a.real
4271.5
428>>> a.imag
4290.5
Fred Drake8842e861998-02-13 07:16:30 +0000430\end{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +0000431%
432The conversion functions to floating point and integer
Fred Drake8842e861998-02-13 07:16:30 +0000433(\function{float()}, \function{int()} and \function{long()}) don't
434work for complex numbers --- there is no one correct way to convert a
435complex number to a real number. Use \code{abs(\var{z})} to get its
436magnitude (as a float) or \code{z.real} to get its real part.
Guido van Rossum02455691997-07-17 16:21:52 +0000437
Fred Drake8842e861998-02-13 07:16:30 +0000438\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +0000439>>> a=1.5+0.5j
440>>> float(a)
441Traceback (innermost last):
442 File "<stdin>", line 1, in ?
443TypeError: can't convert complex to float; use e.g. abs(z)
444>>> a.real
4451.5
446>>> abs(a)
4471.58113883008
Fred Drake8842e861998-02-13 07:16:30 +0000448\end{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +0000449%
450In interactive mode, the last printed expression is assigned to the
451variable \code{_}. This means that when you are using Python as a
452desk calculator, it is somewhat easier to continue calculations, for
453example:
454
455\begin{verbatim}
456>>> tax = 17.5 / 100
457>>> price = 3.50
458>>> price * tax
4590.6125
460>>> price + _
4614.1125
462>>> round(_, 2)
4634.11
464\end{verbatim}
465
466This variable should be treated as read-only by the user. Don't
467explicitly assign a value to it --- you would create an independent
468local variable with the same name masking the built-in variable with
469its magic behavior.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000470
Fred Drakeb7833d31998-09-11 16:21:55 +0000471\subsection{Strings \label{strings}}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000472
Guido van Rossum02455691997-07-17 16:21:52 +0000473Besides numbers, Python can also manipulate strings, which can be
474expressed in several ways. They can be enclosed in single quotes or
475double quotes:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000476
Fred Drake8842e861998-02-13 07:16:30 +0000477\begin{verbatim}
Guido van Rossume5f8b601995-01-04 19:12:49 +0000478>>> 'spam eggs'
479'spam eggs'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000480>>> 'doesn\'t'
Guido van Rossum6938f061994-08-01 12:22:53 +0000481"doesn't"
482>>> "doesn't"
483"doesn't"
484>>> '"Yes," he said.'
485'"Yes," he said.'
486>>> "\"Yes,\" he said."
487'"Yes," he said.'
488>>> '"Isn\'t," she said.'
489'"Isn\'t," she said.'
Fred Drake8842e861998-02-13 07:16:30 +0000490\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000491
Fred Drake8842e861998-02-13 07:16:30 +0000492String literals can span multiple lines in several ways. Newlines can
493be escaped with backslashes, e.g.:
Guido van Rossum02455691997-07-17 16:21:52 +0000494
495\begin{verbatim}
496hello = "This is a rather long string containing\n\
497several lines of text just as you would do in C.\n\
498 Note that whitespace at the beginning of the line is\
499 significant.\n"
500print hello
501\end{verbatim}
502
503which would print the following:
Fred Drake8842e861998-02-13 07:16:30 +0000504
Guido van Rossum02455691997-07-17 16:21:52 +0000505\begin{verbatim}
506This is a rather long string containing
507several lines of text just as you would do in C.
508 Note that whitespace at the beginning of the line is significant.
509\end{verbatim}
510
511Or, strings can be surrounded in a pair of matching triple-quotes:
512\code{"""} or \code {'''}. End of lines do not need to be escaped
513when using triple-quotes, but they will be included in the string.
514
515\begin{verbatim}
516print """
517Usage: thingy [OPTIONS]
518 -h Display this usage message
519 -H hostname Hostname to connect to
520"""
521\end{verbatim}
522
523produces the following output:
524
Fred Drake8842e861998-02-13 07:16:30 +0000525\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +0000526Usage: thingy [OPTIONS]
527 -h Display this usage message
528 -H hostname Hostname to connect to
Fred Drake8842e861998-02-13 07:16:30 +0000529\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000530
Guido van Rossum02455691997-07-17 16:21:52 +0000531The interpreter prints the result of string operations in the same way
532as they are typed for input: inside quotes, and with quotes and other
533funny characters escaped by backslashes, to show the precise
534value. The string is enclosed in double quotes if the string contains
535a single quote and no double quotes, else it's enclosed in single
Fred Drake8842e861998-02-13 07:16:30 +0000536quotes. (The \keyword{print} statement, described later, can be used
537to write strings without quotes or escapes.)
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000538
Fred Drakeeee08cd1997-12-04 15:43:15 +0000539Strings can be concatenated (glued together) with the \code{+}
540operator, and repeated with \code{*}:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000541
Fred Drake8842e861998-02-13 07:16:30 +0000542\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000543>>> word = 'Help' + 'A'
544>>> word
545'HelpA'
546>>> '<' + word*5 + '>'
547'<HelpAHelpAHelpAHelpAHelpA>'
Fred Drake8842e861998-02-13 07:16:30 +0000548\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000549
Guido van Rossum02455691997-07-17 16:21:52 +0000550Two string literals next to each other are automatically concatenated;
Fred Drake8842e861998-02-13 07:16:30 +0000551the first line above could also have been written \samp{word = 'Help'
Guido van Rossum02455691997-07-17 16:21:52 +0000552'A'}; this only works with two literals, not with arbitrary string expressions.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000553
Fred Drake3f205921998-01-13 18:56:38 +0000554Strings can be subscripted (indexed); like in \C{}, the first character
Guido van Rossum02455691997-07-17 16:21:52 +0000555of a string has subscript (index) 0. There is no separate character
556type; a character is simply a string of size one. Like in Icon,
Fred Drake8842e861998-02-13 07:16:30 +0000557substrings can be specified with the \emph{slice notation}: two indices
Guido van Rossum02455691997-07-17 16:21:52 +0000558separated by a colon.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000559
Fred Drake8842e861998-02-13 07:16:30 +0000560\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000561>>> word[4]
562'A'
563>>> word[0:2]
564'He'
565>>> word[2:4]
566'lp'
Fred Drake8842e861998-02-13 07:16:30 +0000567\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000568
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000569Slice 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
Fred Drake8842e861998-02-13 07:16:30 +0000573\begin{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000574>>> 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'
Fred Drake8842e861998-02-13 07:16:30 +0000578\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000579
Fred Drakeeee08cd1997-12-04 15:43:15 +0000580Here's a useful invariant of slice operations: \code{s[:i] + s[i:]}
581equals \code{s}.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000582
Fred Drake8842e861998-02-13 07:16:30 +0000583\begin{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000584>>> word[:2] + word[2:]
585'HelpA'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000586>>> word[:3] + word[3:]
587'HelpA'
Fred Drake8842e861998-02-13 07:16:30 +0000588\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000589
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000590Degenerate slice indices are handled gracefully: an index that is too
591large is replaced by the string size, an upper bound smaller than the
592lower bound returns an empty string.
593
Fred Drake8842e861998-02-13 07:16:30 +0000594\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000595>>> word[1:100]
596'elpA'
597>>> word[10:]
598''
599>>> word[2:1]
600''
Fred Drake8842e861998-02-13 07:16:30 +0000601\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000602
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000603Indices may be negative numbers, to start counting from the right.
604For example:
605
Fred Drake8842e861998-02-13 07:16:30 +0000606\begin{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000607>>> word[-1] # The last character
608'A'
609>>> word[-2] # The last-but-one character
610'p'
611>>> word[-2:] # The last two characters
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000612'pA'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000613>>> word[:-2] # All but the last two characters
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000614'Hel'
Fred Drake8842e861998-02-13 07:16:30 +0000615\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000616
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000617But note that -0 is really the same as 0, so it does not count from
618the right!
619
Fred Drake8842e861998-02-13 07:16:30 +0000620\begin{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000621>>> word[-0] # (since -0 equals 0)
622'H'
Fred Drake8842e861998-02-13 07:16:30 +0000623\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000624
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000625Out-of-range negative slice indices are truncated, but don't try this
626for single-element (non-slice) indices:
627
Fred Drake8842e861998-02-13 07:16:30 +0000628\begin{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000629>>> word[-100:]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000630'HelpA'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000631>>> word[-10] # error
Guido van Rossum6938f061994-08-01 12:22:53 +0000632Traceback (innermost last):
633 File "<stdin>", line 1
634IndexError: string index out of range
Fred Drake8842e861998-02-13 07:16:30 +0000635\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000636
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000637The best way to remember how slices work is to think of the indices as
Fred Drakeeee08cd1997-12-04 15:43:15 +0000638pointing \emph{between} characters, with the left edge of the first
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000639character numbered 0. Then the right edge of the last character of a
Fred Drakeeee08cd1997-12-04 15:43:15 +0000640string of \var{n} characters has index \var{n}, for example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000641
Fred Drake8842e861998-02-13 07:16:30 +0000642\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000643 +---+---+---+---+---+
644 | H | e | l | p | A |
645 +---+---+---+---+---+
646 0 1 2 3 4 5
647-5 -4 -3 -2 -1
Fred Drake8842e861998-02-13 07:16:30 +0000648\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000649
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000650The first row of numbers gives the position of the indices 0...5 in
651the string; the second row gives the corresponding negative indices.
Fred Drakeeee08cd1997-12-04 15:43:15 +0000652The slice from \var{i} to \var{j} consists of all characters between
653the edges labeled \var{i} and \var{j}, respectively.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000654
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000655For nonnegative indices, the length of a slice is the difference of
656the indices, if both are within bounds, e.g., the length of
Fred Drakeeee08cd1997-12-04 15:43:15 +0000657\code{word[1:3]} is 2.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000658
Fred Drake8842e861998-02-13 07:16:30 +0000659The built-in function \function{len()} returns the length of a string:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000660
Fred Drake8842e861998-02-13 07:16:30 +0000661\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000662>>> s = 'supercalifragilisticexpialidocious'
663>>> len(s)
66434
Fred Drake8842e861998-02-13 07:16:30 +0000665\end{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000666
Fred Drakeb7833d31998-09-11 16:21:55 +0000667\subsection{Lists \label{lists}}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000668
Fred Drakeeee08cd1997-12-04 15:43:15 +0000669Python knows a number of \emph{compound} data types, used to group
670together other values. The most versatile is the \emph{list}, which
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000671can be written as a list of comma-separated values (items) between
672square brackets. List items need not all have the same type.
673
Fred Drake8842e861998-02-13 07:16:30 +0000674\begin{verbatim}
Guido van Rossume5f8b601995-01-04 19:12:49 +0000675>>> a = ['spam', 'eggs', 100, 1234]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000676>>> a
Guido van Rossume5f8b601995-01-04 19:12:49 +0000677['spam', 'eggs', 100, 1234]
Fred Drake8842e861998-02-13 07:16:30 +0000678\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000679
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000680Like string indices, list indices start at 0, and lists can be sliced,
681concatenated and so on:
682
Fred Drake8842e861998-02-13 07:16:30 +0000683\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000684>>> a[0]
Guido van Rossume5f8b601995-01-04 19:12:49 +0000685'spam'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000686>>> a[3]
6871234
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000688>>> a[-2]
689100
690>>> a[1:-1]
Guido van Rossume5f8b601995-01-04 19:12:49 +0000691['eggs', 100]
692>>> a[:2] + ['bacon', 2*2]
693['spam', 'eggs', 'bacon', 4]
Guido van Rossum4410c751991-06-04 20:22:18 +0000694>>> 3*a[:3] + ['Boe!']
Guido van Rossume5f8b601995-01-04 19:12:49 +0000695['spam', 'eggs', 100, 'spam', 'eggs', 100, 'spam', 'eggs', 100, 'Boe!']
Fred Drake8842e861998-02-13 07:16:30 +0000696\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000697
Fred Drakeeee08cd1997-12-04 15:43:15 +0000698Unlike strings, which are \emph{immutable}, it is possible to change
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000699individual elements of a list:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000700
Fred Drake8842e861998-02-13 07:16:30 +0000701\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000702>>> a
Guido van Rossume5f8b601995-01-04 19:12:49 +0000703['spam', 'eggs', 100, 1234]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000704>>> a[2] = a[2] + 23
705>>> a
Guido van Rossume5f8b601995-01-04 19:12:49 +0000706['spam', 'eggs', 123, 1234]
Fred Drake8842e861998-02-13 07:16:30 +0000707\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000708
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000709Assignment to slices is also possible, and this can even change the size
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000710of the list:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000711
Fred Drake8842e861998-02-13 07:16:30 +0000712\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000713>>> # Replace some items:
Guido van Rossum6938f061994-08-01 12:22:53 +0000714... a[0:2] = [1, 12]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000715>>> a
716[1, 12, 123, 1234]
717>>> # Remove some:
Guido van Rossum6938f061994-08-01 12:22:53 +0000718... a[0:2] = []
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000719>>> a
720[123, 1234]
721>>> # Insert some:
Guido van Rossum6938f061994-08-01 12:22:53 +0000722... a[1:1] = ['bletch', 'xyzzy']
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000723>>> a
724[123, 'bletch', 'xyzzy', 1234]
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000725>>> a[:0] = a # Insert (a copy of) itself at the beginning
726>>> a
727[123, 'bletch', 'xyzzy', 1234, 123, 'bletch', 'xyzzy', 1234]
Fred Drake8842e861998-02-13 07:16:30 +0000728\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000729
Fred Drake8842e861998-02-13 07:16:30 +0000730The built-in function \function{len()} also applies to lists:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000731
Fred Drake8842e861998-02-13 07:16:30 +0000732\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000733>>> len(a)
Guido van Rossuma8d754e1992-01-07 16:44:35 +00007348
Fred Drake8842e861998-02-13 07:16:30 +0000735\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000736
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000737It is possible to nest lists (create lists containing other lists),
738for example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000739
Fred Drake8842e861998-02-13 07:16:30 +0000740\begin{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000741>>> q = [2, 3]
742>>> p = [1, q, 4]
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000743>>> len(p)
7443
745>>> p[1]
746[2, 3]
747>>> p[1][0]
7482
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000749>>> p[1].append('xtra') # See section 5.1
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000750>>> p
751[1, [2, 3, 'xtra'], 4]
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000752>>> q
753[2, 3, 'xtra']
Fred Drake8842e861998-02-13 07:16:30 +0000754\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000755
Fred Drakeeee08cd1997-12-04 15:43:15 +0000756Note that in the last example, \code{p[1]} and \code{q} really refer to
757the same object! We'll come back to \emph{object semantics} later.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000758
Fred Drakeb7833d31998-09-11 16:21:55 +0000759\section{First Steps Towards Programming \label{firstSteps}}
Guido van Rossum2292b8e1991-01-23 16:31:24 +0000760
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000761Of course, we can use Python for more complicated tasks than adding
762two and two together. For instance, we can write an initial
Fred Drakeeee08cd1997-12-04 15:43:15 +0000763subsequence of the \emph{Fibonacci} series as follows:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000764
Fred Drake8842e861998-02-13 07:16:30 +0000765\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000766>>> # Fibonacci series:
Guido van Rossum6938f061994-08-01 12:22:53 +0000767... # the sum of two elements defines the next
768... a, b = 0, 1
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000769>>> while b < 10:
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000770... print b
771... a, b = b, a+b
772...
7731
7741
7752
7763
7775
7788
Fred Drake8842e861998-02-13 07:16:30 +0000779\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000780
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000781This example introduces several new features.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000782
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000783\begin{itemize}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000784
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000785\item
Fred Drakeeee08cd1997-12-04 15:43:15 +0000786The first line contains a \emph{multiple assignment}: the variables
787\code{a} and \code{b} simultaneously get the new values 0 and 1. On the
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000788last line this is used again, demonstrating that the expressions on
789the right-hand side are all evaluated first before any of the
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000790assignments take place.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000791
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000792\item
Fred Drake8842e861998-02-13 07:16:30 +0000793The \keyword{while} loop executes as long as the condition (here:
794\code{b < 10}) remains true. In Python, like in \C{}, any non-zero
795integer value is true; zero is false. The condition may also be a
796string or list value, in fact any sequence; anything with a non-zero
797length is true, empty sequences are false. The test used in the
798example is a simple comparison. The standard comparison operators are
799written the same as in \C{}: \code{<}, \code{>}, \code{==}, \code{<=},
800\code{>=} and \code{!=}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000801
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000802\item
Fred Drakeeee08cd1997-12-04 15:43:15 +0000803The \emph{body} of the loop is \emph{indented}: indentation is Python's
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000804way of grouping statements. Python does not (yet!) provide an
805intelligent input line editing facility, so you have to type a tab or
806space(s) for each indented line. In practice you will prepare more
807complicated input for Python with a text editor; most text editors have
808an auto-indent facility. When a compound statement is entered
809interactively, it must be followed by a blank line to indicate
810completion (since the parser cannot guess when you have typed the last
811line).
812
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000813\item
Fred Drake8842e861998-02-13 07:16:30 +0000814The \keyword{print} statement writes the value of the expression(s) it is
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000815given. It differs from just writing the expression you want to write
816(as we did earlier in the calculator examples) in the way it handles
Guido van Rossum16cd7f91994-10-06 10:29:26 +0000817multiple expressions and strings. Strings are printed without quotes,
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000818and a space is inserted between items, so you can format things nicely,
819like this:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000820
Fred Drake8842e861998-02-13 07:16:30 +0000821\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000822>>> i = 256*256
823>>> print 'The value of i is', i
824The value of i is 65536
Fred Drake8842e861998-02-13 07:16:30 +0000825\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000826
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000827A trailing comma avoids the newline after the output:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000828
Fred Drake8842e861998-02-13 07:16:30 +0000829\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000830>>> a, b = 0, 1
831>>> while b < 1000:
832... print b,
833... a, b = b, a+b
834...
8351 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
Fred Drake8842e861998-02-13 07:16:30 +0000836\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000837
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000838Note that the interpreter inserts a newline before it prints the next
839prompt if the last line was not completed.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000840
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000841\end{itemize}
842
Guido van Rossum5e0759d1992-08-07 16:06:24 +0000843
Fred Drakeb7833d31998-09-11 16:21:55 +0000844\chapter{More Control Flow Tools \label{moreControl}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000845
Fred Drake8842e861998-02-13 07:16:30 +0000846Besides the \keyword{while} statement just introduced, Python knows
847the usual control flow statements known from other languages, with
848some twists.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000849
Fred Drakeb7833d31998-09-11 16:21:55 +0000850\section{\keyword{if} Statements \label{if}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000851
Fred Drake8842e861998-02-13 07:16:30 +0000852Perhaps the most well-known statement type is the \keyword{if}
853statement. For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000854
Fred Drake8842e861998-02-13 07:16:30 +0000855\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000856>>> if x < 0:
857... x = 0
858... print 'Negative changed to zero'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000859... elif x == 0:
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000860... print 'Zero'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000861... elif x == 1:
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000862... print 'Single'
863... else:
864... print 'More'
865...
Fred Drake8842e861998-02-13 07:16:30 +0000866\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000867
Fred Drake8842e861998-02-13 07:16:30 +0000868There can be zero or more \keyword{elif} parts, and the \keyword{else}
869part is optional. The keyword `\keyword{elif}' is short for `else
870if', and is useful to avoid excessive indentation. An
871\keyword{if} \ldots\ \keyword{elif} \ldots\ \keyword{elif}
872\ldots\ sequence is a substitute for the \emph{switch} or
873% ^^^^
874% Weird spacings happen here if the wrapping of the source text
875% gets changed in the wrong way.
876\emph{case} statements found in other languages.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000877
Fred Drakeb7833d31998-09-11 16:21:55 +0000878
879\section{\keyword{for} Statements \label{for}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000880
Fred Drake8842e861998-02-13 07:16:30 +0000881The \keyword{for} statement in Python differs a bit from what you may be
Fred Drake3f205921998-01-13 18:56:38 +0000882used to in \C{} or Pascal. Rather than always iterating over an
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000883arithmetic progression of numbers (like in Pascal), or leaving the user
Fred Drake3f205921998-01-13 18:56:38 +0000884completely free in the iteration test and step (as \C{}), Python's
Fred Drake8842e861998-02-13 07:16:30 +0000885\keyword{for} statement iterates over the items of any sequence (e.g., a
Fred Drakeeee08cd1997-12-04 15:43:15 +0000886list or a string), in the order that they appear in the sequence. For
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000887example (no pun intended):
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000888
Fred Drake8842e861998-02-13 07:16:30 +0000889\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000890>>> # Measure some strings:
Guido van Rossum6938f061994-08-01 12:22:53 +0000891... a = ['cat', 'window', 'defenestrate']
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000892>>> for x in a:
893... print x, len(x)
894...
895cat 3
896window 6
897defenestrate 12
Fred Drake8842e861998-02-13 07:16:30 +0000898\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000899
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000900It is not safe to modify the sequence being iterated over in the loop
901(this can only happen for mutable sequence types, i.e., lists). If
902you need to modify the list you are iterating over, e.g., duplicate
903selected items, you must iterate over a copy. The slice notation
904makes this particularly convenient:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000905
Fred Drake8842e861998-02-13 07:16:30 +0000906\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000907>>> for x in a[:]: # make a slice copy of the entire list
908... if len(x) > 6: a.insert(0, x)
909...
910>>> a
911['defenestrate', 'cat', 'window', 'defenestrate']
Fred Drake8842e861998-02-13 07:16:30 +0000912\end{verbatim}
Guido van Rossum2292b8e1991-01-23 16:31:24 +0000913
Fred Drakeb7833d31998-09-11 16:21:55 +0000914
915\section{The \function{range()} Function \label{range}}
Guido van Rossum2292b8e1991-01-23 16:31:24 +0000916
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000917If you do need to iterate over a sequence of numbers, the built-in
Fred Drake8842e861998-02-13 07:16:30 +0000918function \function{range()} comes in handy. It generates lists
919containing arithmetic progressions, e.g.:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000920
Fred Drake8842e861998-02-13 07:16:30 +0000921\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000922>>> range(10)
923[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Fred Drake8842e861998-02-13 07:16:30 +0000924\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000925
Fred Drake8842e861998-02-13 07:16:30 +0000926The given end point is never part of the generated list;
927\code{range(10)} generates a list of 10 values, exactly the legal
928indices for items of a sequence of length 10. It is possible to let
929the range start at another number, or to specify a different increment
930(even negative):
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000931
Fred Drake8842e861998-02-13 07:16:30 +0000932\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000933>>> range(5, 10)
934[5, 6, 7, 8, 9]
935>>> range(0, 10, 3)
936[0, 3, 6, 9]
937>>> range(-10, -100, -30)
938[-10, -40, -70]
Fred Drake8842e861998-02-13 07:16:30 +0000939\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000940
Fred Drake8842e861998-02-13 07:16:30 +0000941To iterate over the indices of a sequence, combine \function{range()}
942and \function{len()} as follows:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000943
Fred Drake8842e861998-02-13 07:16:30 +0000944\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000945>>> a = ['Mary', 'had', 'a', 'little', 'lamb']
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000946>>> for i in range(len(a)):
947... print i, a[i]
948...
9490 Mary
9501 had
9512 a
9523 little
Guido van Rossum6fc178f1991-08-16 09:13:42 +00009534 lamb
Fred Drake8842e861998-02-13 07:16:30 +0000954\end{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000955
Fred Drake391564f1998-04-01 23:11:56 +0000956\section{\keyword{break} and \keyword{continue} Statements, and
Fred Drakeb7833d31998-09-11 16:21:55 +0000957 \keyword{else} Clauses on Loops
958 \label{break}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000959
Fred Drake8842e861998-02-13 07:16:30 +0000960The \keyword{break} statement, like in \C{}, breaks out of the smallest
961enclosing \keyword{for} or \keyword{while} loop.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000962
Fred Drake8842e861998-02-13 07:16:30 +0000963The \keyword{continue} statement, also borrowed from \C{}, continues
964with the next iteration of the loop.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000965
Fred Drake8842e861998-02-13 07:16:30 +0000966Loop statements may have an \code{else} clause; it is executed when
967the loop terminates through exhaustion of the list (with
968\keyword{for}) or when the condition becomes false (with
969\keyword{while}), but not when the loop is terminated by a
970\keyword{break} statement. This is exemplified by the following loop,
971which searches for prime numbers:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000972
Fred Drake8842e861998-02-13 07:16:30 +0000973\begin{verbatim}
Guido van Rossum2292b8e1991-01-23 16:31:24 +0000974>>> for n in range(2, 10):
975... for x in range(2, n):
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000976... if n % x == 0:
Guido van Rossum2292b8e1991-01-23 16:31:24 +0000977... print n, 'equals', x, '*', n/x
978... break
979... else:
980... print n, 'is a prime number'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000981...
Guido van Rossum2292b8e1991-01-23 16:31:24 +00009822 is a prime number
9833 is a prime number
9844 equals 2 * 2
9855 is a prime number
9866 equals 2 * 3
9877 is a prime number
9888 equals 2 * 4
9899 equals 3 * 3
Fred Drake8842e861998-02-13 07:16:30 +0000990\end{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000991
Fred Drakeb7833d31998-09-11 16:21:55 +0000992\section{\keyword{pass} Statements \label{pass}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000993
Fred Drake8842e861998-02-13 07:16:30 +0000994The \keyword{pass} statement does nothing.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000995It can be used when a statement is required syntactically but the
996program requires no action.
997For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000998
Fred Drake8842e861998-02-13 07:16:30 +0000999\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001000>>> while 1:
1001... pass # Busy-wait for keyboard interrupt
1002...
Fred Drake8842e861998-02-13 07:16:30 +00001003\end{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001004
Fred Drakeb7833d31998-09-11 16:21:55 +00001005\section{Defining Functions \label{functions}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001006
1007We can create a function that writes the Fibonacci series to an
1008arbitrary boundary:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001009
Fred Drake8842e861998-02-13 07:16:30 +00001010\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001011>>> def fib(n): # write Fibonacci series up to n
Guido van Rossum02455691997-07-17 16:21:52 +00001012... "Print a Fibonacci series up to n"
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001013... a, b = 0, 1
Guido van Rossum16cd7f91994-10-06 10:29:26 +00001014... while b < n:
Fred Drakeeee08cd1997-12-04 15:43:15 +00001015... print b,
1016... a, b = b, a+b
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001017...
1018>>> # Now call the function we just defined:
Guido van Rossum6938f061994-08-01 12:22:53 +00001019... fib(2000)
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000010201 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597
Fred Drake8842e861998-02-13 07:16:30 +00001021\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001022
Fred Drake8842e861998-02-13 07:16:30 +00001023The keyword \keyword{def} introduces a function \emph{definition}. It
1024must be followed by the function name and the parenthesized list of
1025formal parameters. The statements that form the body of the function
1026start at the next line, indented by a tab stop. The first statement
1027of the function body can optionally be a string literal; this string
1028literal is the function's documentation string, or \dfn{docstring}.
1029There are tools which use docstrings to automatically produce printed
Guido van Rossum02455691997-07-17 16:21:52 +00001030documentation, or to let the user interactively browse through code;
1031it's good practice to include docstrings in code that you write, so
1032try to make a habit of it.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001033
Fred Drakeeee08cd1997-12-04 15:43:15 +00001034The \emph{execution} of a function introduces a new symbol table used
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001035for the local variables of the function. More precisely, all variable
1036assignments in a function store the value in the local symbol table;
Guido van Rossum02455691997-07-17 16:21:52 +00001037whereas variable references first look in the local symbol table, then
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001038in the global symbol table, and then in the table of built-in names.
Fred Drake8842e861998-02-13 07:16:30 +00001039Thus, global variables cannot be directly assigned a value within a
1040function (unless named in a \keyword{global} statement), although
Guido van Rossum6938f061994-08-01 12:22:53 +00001041they may be referenced.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001042
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001043The actual parameters (arguments) to a function call are introduced in
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001044the local symbol table of the called function when it is called; thus,
Fred Drakeeee08cd1997-12-04 15:43:15 +00001045arguments are passed using \emph{call by value}.%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001046\footnote{
Fred Drakeeee08cd1997-12-04 15:43:15 +00001047 Actually, \emph{call by object reference} would be a better
Guido van Rossum6938f061994-08-01 12:22:53 +00001048 description, since if a mutable object is passed, the caller
1049 will see any changes the callee makes to it (e.g., items
1050 inserted into a list).
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001051}
1052When a function calls another function, a new local symbol table is
1053created for that call.
1054
Fred Drake8842e861998-02-13 07:16:30 +00001055A function definition introduces the function name in the current
1056symbol table. The value of the function name
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001057has a type that is recognized by the interpreter as a user-defined
1058function. This value can be assigned to another name which can then
1059also be used as a function. This serves as a general renaming
1060mechanism:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001061
Fred Drake8842e861998-02-13 07:16:30 +00001062\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001063>>> fib
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001064<function object at 10042ed0>
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001065>>> f = fib
1066>>> f(100)
10671 1 2 3 5 8 13 21 34 55 89
Fred Drake8842e861998-02-13 07:16:30 +00001068\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001069
Fred Drakeeee08cd1997-12-04 15:43:15 +00001070You might object that \code{fib} is not a function but a procedure. In
Fred Drake3f205921998-01-13 18:56:38 +00001071Python, like in \C{}, procedures are just functions that don't return a
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001072value. In fact, technically speaking, procedures do return a value,
Fred Drakeeee08cd1997-12-04 15:43:15 +00001073albeit a rather boring one. This value is called \code{None} (it's a
1074built-in name). Writing the value \code{None} is normally suppressed by
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001075the interpreter if it would be the only value written. You can see it
1076if you really want to:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001077
Fred Drake8842e861998-02-13 07:16:30 +00001078\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001079>>> print fib(0)
1080None
Fred Drake8842e861998-02-13 07:16:30 +00001081\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001082
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001083It is simple to write a function that returns a list of the numbers of
1084the Fibonacci series, instead of printing it:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001085
Fred Drake8842e861998-02-13 07:16:30 +00001086\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001087>>> def fib2(n): # return Fibonacci series up to n
Guido van Rossum02455691997-07-17 16:21:52 +00001088... "Return a list containing the Fibonacci series up to n"
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001089... result = []
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001090... a, b = 0, 1
Guido van Rossum16cd7f91994-10-06 10:29:26 +00001091... while b < n:
Fred Drakeeee08cd1997-12-04 15:43:15 +00001092... result.append(b) # see below
1093... a, b = b, a+b
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001094... return result
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001095...
1096>>> f100 = fib2(100) # call it
1097>>> f100 # write the result
1098[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
Fred Drake8842e861998-02-13 07:16:30 +00001099\end{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001100%
Guido van Rossum4410c751991-06-04 20:22:18 +00001101This example, as usual, demonstrates some new Python features:
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001102
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001103\begin{itemize}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001104
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001105\item
Fred Drake8842e861998-02-13 07:16:30 +00001106The \keyword{return} statement returns with a value from a function.
1107\keyword{return} without an expression argument is used to return from
Fred Drakeeee08cd1997-12-04 15:43:15 +00001108the middle of a procedure (falling off the end also returns from a
1109procedure), in which case the \code{None} value is returned.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001110
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001111\item
Fred Drakeeee08cd1997-12-04 15:43:15 +00001112The statement \code{result.append(b)} calls a \emph{method} of the list
1113object \code{result}. A method is a function that `belongs' to an
1114object and is named \code{obj.methodname}, where \code{obj} is some
1115object (this may be an expression), and \code{methodname} is the name
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001116of a method that is defined by the object's type. Different types
1117define different methods. Methods of different types may have the
1118same name without causing ambiguity. (It is possible to define your
Fred Drakeeee08cd1997-12-04 15:43:15 +00001119own object types and methods, using \emph{classes}, as discussed later
Guido van Rossum6938f061994-08-01 12:22:53 +00001120in this tutorial.)
Fred Drake8842e861998-02-13 07:16:30 +00001121The method \method{append()} shown in the example, is defined for
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001122list objects; it adds a new element at the end of the list. In this
Fred Drake8842e861998-02-13 07:16:30 +00001123example it is equivalent to \samp{result = result + [b]}, but more
1124efficient.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001125
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001126\end{itemize}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001127
Fred Drakeb7833d31998-09-11 16:21:55 +00001128\section{More on Defining Functions \label{defining}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00001129
Guido van Rossum02455691997-07-17 16:21:52 +00001130It is also possible to define functions with a variable number of
1131arguments. There are three forms, which can be combined.
1132
Fred Drakeb7833d31998-09-11 16:21:55 +00001133\subsection{Default Argument Values \label{defaultArgs}}
Guido van Rossum02455691997-07-17 16:21:52 +00001134
1135The most useful form is to specify a default value for one or more
1136arguments. This creates a function that can be called with fewer
1137arguments than it is defined, e.g.
1138
1139\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00001140def ask_ok(prompt, retries=4, complaint='Yes or no, please!'):
1141 while 1:
1142 ok = raw_input(prompt)
1143 if ok in ('y', 'ye', 'yes'): return 1
1144 if ok in ('n', 'no', 'nop', 'nope'): return 0
1145 retries = retries - 1
1146 if retries < 0: raise IOError, 'refusenik user'
1147 print complaint
Guido van Rossum02455691997-07-17 16:21:52 +00001148\end{verbatim}
1149
1150This function can be called either like this:
Fred Drakeeee08cd1997-12-04 15:43:15 +00001151\code{ask_ok('Do you really want to quit?')} or like this:
1152\code{ask_ok('OK to overwrite the file?', 2)}.
Guido van Rossum02455691997-07-17 16:21:52 +00001153
1154The default values are evaluated at the point of function definition
Fred Drakeeee08cd1997-12-04 15:43:15 +00001155in the \emph{defining} scope, so that e.g.
Guido van Rossum02455691997-07-17 16:21:52 +00001156
1157\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00001158i = 5
1159def f(arg = i): print arg
1160i = 6
1161f()
Guido van Rossum02455691997-07-17 16:21:52 +00001162\end{verbatim}
1163
Fred Drakeeee08cd1997-12-04 15:43:15 +00001164will print \code{5}.
Guido van Rossum02455691997-07-17 16:21:52 +00001165
Guido van Rossumaee5e261998-08-07 17:45:09 +00001166\strong{Important warning:} The default value is evaluated only once.
1167This makes a difference when the default is a mutable object such as a
1168list or dictionary. For example, the following function accumulates
1169the arguments passed to it on subsequent calls:
1170
1171\begin{verbatim}
1172def f(a, l = []):
1173 l.append(a)
Guido van Rossumc62cf361998-10-24 13:15:28 +00001174 return l
Guido van Rossumaee5e261998-08-07 17:45:09 +00001175print f(1)
1176print f(2)
1177print f(3)
1178\end{verbatim}
1179
1180This will print
1181
1182\begin{verbatim}
1183[1]
1184[1, 2]
1185[1, 2, 3]
1186\end{verbatim}
1187
1188If you don't want the default to be shared between subsequent calls,
1189you can write the function like this instead:
1190
1191\begin{verbatim}
1192def f(a, l = None):
1193 if l is None:
1194 l = []
1195 l.append(a)
Guido van Rossumc62cf361998-10-24 13:15:28 +00001196 return l
Guido van Rossumaee5e261998-08-07 17:45:09 +00001197\end{verbatim}
1198
Fred Drakeb7833d31998-09-11 16:21:55 +00001199\subsection{Keyword Arguments \label{keywordArgs}}
Guido van Rossum02455691997-07-17 16:21:52 +00001200
1201Functions can also be called using
Fred Drake8842e861998-02-13 07:16:30 +00001202keyword arguments of the form \samp{\var{keyword} = \var{value}}. For
Guido van Rossum02455691997-07-17 16:21:52 +00001203instance, the following function:
1204
1205\begin{verbatim}
1206def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
1207 print "-- This parrot wouldn't", action,
1208 print "if you put", voltage, "Volts through it."
1209 print "-- Lovely plumage, the", type
1210 print "-- It's", state, "!"
1211\end{verbatim}
1212
1213could be called in any of the following ways:
1214
1215\begin{verbatim}
1216parrot(1000)
1217parrot(action = 'VOOOOOM', voltage = 1000000)
1218parrot('a thousand', state = 'pushing up the daisies')
1219parrot('a million', 'bereft of life', 'jump')
1220\end{verbatim}
1221
1222but the following calls would all be invalid:
1223
1224\begin{verbatim}
1225parrot() # required argument missing
1226parrot(voltage=5.0, 'dead') # non-keyword argument following keyword
1227parrot(110, voltage=220) # duplicate value for argument
1228parrot(actor='John Cleese') # unknown keyword
1229\end{verbatim}
1230
1231In general, an argument list must have any positional arguments
1232followed by any keyword arguments, where the keywords must be chosen
1233from the formal parameter names. It's not important whether a formal
1234parameter has a default value or not. No argument must receive a
1235value more than once --- formal parameter names corresponding to
1236positional arguments cannot be used as keywords in the same calls.
1237
1238When a final formal parameter of the form \code{**\var{name}} is
1239present, it receives a dictionary containing all keyword arguments
1240whose keyword doesn't correspond to a formal parameter. This may be
1241combined with a formal parameter of the form \code{*\var{name}}
1242(described in the next subsection) which receives a tuple containing
1243the positional arguments beyond the formal parameter list.
1244(\code{*\var{name}} must occur before \code{**\var{name}}.) For
1245example, if we define a function like this:
1246
1247\begin{verbatim}
1248def cheeseshop(kind, *arguments, **keywords):
1249 print "-- Do you have any", kind, '?'
1250 print "-- I'm sorry, we're all out of", kind
1251 for arg in arguments: print arg
1252 print '-'*40
1253 for kw in keywords.keys(): print kw, ':', keywords[kw]
1254\end{verbatim}
1255
1256It could be called like this:
1257
1258\begin{verbatim}
1259cheeseshop('Limburger', "It's very runny, sir.",
1260 "It's really very, VERY runny, sir.",
1261 client='John Cleese',
1262 shopkeeper='Michael Palin',
1263 sketch='Cheese Shop Sketch')
1264\end{verbatim}
1265
1266and of course it would print:
1267
1268\begin{verbatim}
1269-- Do you have any Limburger ?
1270-- I'm sorry, we're all out of Limburger
1271It's very runny, sir.
1272It's really very, VERY runny, sir.
1273----------------------------------------
1274client : John Cleese
1275shopkeeper : Michael Palin
1276sketch : Cheese Shop Sketch
1277\end{verbatim}
1278
Fred Drakeb7833d31998-09-11 16:21:55 +00001279\subsection{Arbitrary Argument Lists \label{arbitraryArgs}}
Guido van Rossum02455691997-07-17 16:21:52 +00001280
1281Finally, the least frequently used option is to specify that a
1282function can be called with an arbitrary number of arguments. These
1283arguments will be wrapped up in a tuple. Before the variable number
1284of arguments, zero or more normal arguments may occur.
1285
1286\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00001287def fprintf(file, format, *args):
1288 file.write(format % args)
Guido van Rossum02455691997-07-17 16:21:52 +00001289\end{verbatim}
1290
Fred Drakea594baf1998-04-03 05:16:31 +00001291
Fred Drakeb7833d31998-09-11 16:21:55 +00001292\subsection{Lambda Forms \label{lambda}}
Fred Drakea594baf1998-04-03 05:16:31 +00001293
1294By popular demand, a few features commonly found in functional
1295programming languages and Lisp have been added to Python. With the
1296\keyword{lambda} keyword, small anonymous functions can be created.
1297Here's a function that returns the sum of its two arguments:
1298\samp{lambda a, b: a+b}. Lambda forms can be used wherever function
1299objects are required. They are syntactically restricted to a single
1300expression. Semantically, they are just syntactic sugar for a normal
1301function definition. Like nested function definitions, lambda forms
1302cannot reference variables from the containing scope, but this can be
1303overcome through the judicious use of default argument values, e.g.
1304
1305\begin{verbatim}
1306def make_incrementor(n):
1307 return lambda x, incr=n: x+incr
1308\end{verbatim}
1309
Fred Drakeb7833d31998-09-11 16:21:55 +00001310\subsection{Documentation Strings \label{docstrings}}
Fred Drakea594baf1998-04-03 05:16:31 +00001311
1312There are emerging conventions about the content and formatting of
1313documentation strings.
1314
1315The first line should always be a short, concise summary of the
1316object's purpose. For brevity, it should not explicitly state the
1317object's name or type, since these are available by other means
1318(except if the name happens to be a verb describing a function's
1319operation). This line should begin with a capital letter and end with
1320a period.
1321
1322If there are more lines in the documentation string, the second line
1323should be blank, visually separating the summary from the rest of the
1324description. The following lines should be one of more of paragraphs
1325describing the objects calling conventions, its side effects, etc.
1326
1327The Python parser does not strip indentation from multi-line string
1328literals in Python, so tools that process documentation have to strip
1329indentation. This is done using the following convention. The first
1330non-blank line \emph{after} the first line of the string determines the
1331amount of indentation for the entire documentation string. (We can't
1332use the first line since it is generally adjacent to the string's
1333opening quotes so its indentation is not apparent in the string
1334literal.) Whitespace ``equivalent'' to this indentation is then
1335stripped from the start of all lines of the string. Lines that are
1336indented less should not occur, but if they occur all their leading
1337whitespace should be stripped. Equivalence of whitespace should be
1338tested after expansion of tabs (to 8 spaces, normally).
1339
1340
1341
Fred Drakeb7833d31998-09-11 16:21:55 +00001342\chapter{Data Structures \label{structures}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001343
1344This chapter describes some things you've learned about already in
1345more detail, and adds some new things as well.
1346
Fred Drakeb7833d31998-09-11 16:21:55 +00001347\section{More on Lists \label{moreLists}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001348
1349The list data type has some more methods. Here are all of the methods
Fred Drakeed688541998-02-11 22:29:17 +00001350of list objects:
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001351
Guido van Rossum7d9f8d71991-01-22 11:45:00 +00001352\begin{description}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001353
Fred Drakeeee08cd1997-12-04 15:43:15 +00001354\item[\code{insert(i, x)}]
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001355Insert an item at a given position. The first argument is the index of
Fred Drakeeee08cd1997-12-04 15:43:15 +00001356the element before which to insert, so \code{a.insert(0, x)} inserts at
1357the front of the list, and \code{a.insert(len(a), x)} is equivalent to
1358\code{a.append(x)}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001359
Fred Drakeeee08cd1997-12-04 15:43:15 +00001360\item[\code{append(x)}]
1361Equivalent to \code{a.insert(len(a), x)}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001362
Fred Drakeeee08cd1997-12-04 15:43:15 +00001363\item[\code{index(x)}]
1364Return the index in the list of the first item whose value is \code{x}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001365It is an error if there is no such item.
1366
Fred Drakeeee08cd1997-12-04 15:43:15 +00001367\item[\code{remove(x)}]
1368Remove the first item from the list whose value is \code{x}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001369It is an error if there is no such item.
1370
Fred Drakeeee08cd1997-12-04 15:43:15 +00001371\item[\code{sort()}]
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001372Sort the items of the list, in place.
1373
Fred Drakeeee08cd1997-12-04 15:43:15 +00001374\item[\code{reverse()}]
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001375Reverse the elements of the list, in place.
1376
Fred Drakeeee08cd1997-12-04 15:43:15 +00001377\item[\code{count(x)}]
1378Return the number of times \code{x} appears in the list.
Guido van Rossum6938f061994-08-01 12:22:53 +00001379
Guido van Rossum7d9f8d71991-01-22 11:45:00 +00001380\end{description}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001381
1382An example that uses all list methods:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001383
Fred Drake8842e861998-02-13 07:16:30 +00001384\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001385>>> a = [66.6, 333, 333, 1, 1234.5]
Guido van Rossum6938f061994-08-01 12:22:53 +00001386>>> print a.count(333), a.count(66.6), a.count('x')
13872 1 0
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001388>>> a.insert(2, -1)
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001389>>> a.append(333)
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001390>>> a
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001391[66.6, 333, -1, 333, 1, 1234.5, 333]
1392>>> a.index(333)
13931
1394>>> a.remove(333)
1395>>> a
1396[66.6, -1, 333, 1, 1234.5, 333]
1397>>> a.reverse()
1398>>> a
1399[333, 1234.5, 1, 333, -1, 66.6]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001400>>> a.sort()
1401>>> a
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001402[-1, 1, 66.6, 333, 333, 1234.5]
Fred Drake8842e861998-02-13 07:16:30 +00001403\end{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001404
Fred Drakeb7833d31998-09-11 16:21:55 +00001405\subsection{Functional Programming Tools \label{functional}}
Guido van Rossum02455691997-07-17 16:21:52 +00001406
1407There are three built-in functions that are very useful when used with
Fred Drake8842e861998-02-13 07:16:30 +00001408lists: \function{filter()}, \function{map()}, and \function{reduce()}.
Guido van Rossum02455691997-07-17 16:21:52 +00001409
Fred Drake8842e861998-02-13 07:16:30 +00001410\samp{filter(\var{function}, \var{sequence})} returns a sequence (of
1411the same type, if possible) consisting of those items from the
1412sequence for which \code{\var{function}(\var{item})} is true. For
1413example, to compute some primes:
Guido van Rossum02455691997-07-17 16:21:52 +00001414
1415\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00001416>>> def f(x): return x%2 != 0 and x%3 != 0
1417...
1418>>> filter(f, range(2, 25))
1419[5, 7, 11, 13, 17, 19, 23]
Guido van Rossum02455691997-07-17 16:21:52 +00001420\end{verbatim}
1421
Fred Drake8842e861998-02-13 07:16:30 +00001422\samp{map(\var{function}, \var{sequence})} calls
1423\code{\var{function}(\var{item})} for each of the sequence's items and
1424returns a list of the return values. For example, to compute some
1425cubes:
Guido van Rossum02455691997-07-17 16:21:52 +00001426
1427\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00001428>>> def cube(x): return x*x*x
1429...
1430>>> map(cube, range(1, 11))
1431[1, 8, 27, 64, 125, 216, 343, 512, 729, 1000]
Guido van Rossum02455691997-07-17 16:21:52 +00001432\end{verbatim}
1433
1434More than one sequence may be passed; the function must then have as
1435many arguments as there are sequences and is called with the
Fred Drake8842e861998-02-13 07:16:30 +00001436corresponding item from each sequence (or \code{None} if some sequence
1437is shorter than another). If \code{None} is passed for the function,
Guido van Rossum02455691997-07-17 16:21:52 +00001438a function returning its argument(s) is substituted.
1439
1440Combining these two special cases, we see that
Fred Drake8842e861998-02-13 07:16:30 +00001441\samp{map(None, \var{list1}, \var{list2})} is a convenient way of
1442turning a pair of lists into a list of pairs. For example:
Guido van Rossum02455691997-07-17 16:21:52 +00001443
1444\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00001445>>> seq = range(8)
1446>>> def square(x): return x*x
1447...
1448>>> map(None, seq, map(square, seq))
1449[(0, 0), (1, 1), (2, 4), (3, 9), (4, 16), (5, 25), (6, 36), (7, 49)]
Guido van Rossum02455691997-07-17 16:21:52 +00001450\end{verbatim}
1451
Fred Drake8842e861998-02-13 07:16:30 +00001452\samp{reduce(\var{func}, \var{sequence})} returns a single value
1453constructed by calling the binary function \var{func} on the first two
1454items of the sequence, then on the result and the next item, and so
1455on. For example, to compute the sum of the numbers 1 through 10:
Guido van Rossum02455691997-07-17 16:21:52 +00001456
1457\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00001458>>> def add(x,y): return x+y
1459...
1460>>> reduce(add, range(1, 11))
146155
Guido van Rossum02455691997-07-17 16:21:52 +00001462\end{verbatim}
1463
1464If there's only one item in the sequence, its value is returned; if
1465the sequence is empty, an exception is raised.
1466
1467A third argument can be passed to indicate the starting value. In this
1468case the starting value is returned for an empty sequence, and the
1469function is first applied to the starting value and the first sequence
1470item, then to the result and the next item, and so on. For example,
1471
1472\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00001473>>> def sum(seq):
1474... def add(x,y): return x+y
1475... return reduce(add, seq, 0)
1476...
1477>>> sum(range(1, 11))
147855
1479>>> sum([])
14800
Guido van Rossum02455691997-07-17 16:21:52 +00001481\end{verbatim}
1482
Fred Drakeb7833d31998-09-11 16:21:55 +00001483\section{The \keyword{del} statement \label{del}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001484
1485There is a way to remove an item from a list given its index instead
Fred Drakeeee08cd1997-12-04 15:43:15 +00001486of its value: the \code{del} statement. This can also be used to
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001487remove slices from a list (which we did earlier by assignment of an
1488empty list to the slice). For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001489
Fred Drake8842e861998-02-13 07:16:30 +00001490\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001491>>> a
1492[-1, 1, 66.6, 333, 333, 1234.5]
1493>>> del a[0]
1494>>> a
1495[1, 66.6, 333, 333, 1234.5]
1496>>> del a[2:4]
1497>>> a
1498[1, 66.6, 1234.5]
Fred Drake8842e861998-02-13 07:16:30 +00001499\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001500
1501\keyword{del} can also be used to delete entire variables:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001502
Fred Drake8842e861998-02-13 07:16:30 +00001503\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001504>>> del a
Fred Drake8842e861998-02-13 07:16:30 +00001505\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001506
Fred Drakeeee08cd1997-12-04 15:43:15 +00001507Referencing the name \code{a} hereafter is an error (at least until
Fred Drake6c2176e1998-02-26 21:47:54 +00001508another value is assigned to it). We'll find other uses for
1509\keyword{del} later.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001510
Fred Drakeb7833d31998-09-11 16:21:55 +00001511\section{Tuples and Sequences \label{tuples}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001512
1513We saw that lists and strings have many common properties, e.g.,
Fred Drakeeee08cd1997-12-04 15:43:15 +00001514indexing and slicing operations. They are two examples of
1515\emph{sequence} data types. Since Python is an evolving language,
1516other sequence data types may be added. There is also another
1517standard sequence data type: the \emph{tuple}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001518
1519A tuple consists of a number of values separated by commas, for
1520instance:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001521
Fred Drake8842e861998-02-13 07:16:30 +00001522\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001523>>> t = 12345, 54321, 'hello!'
1524>>> t[0]
152512345
1526>>> t
1527(12345, 54321, 'hello!')
1528>>> # Tuples may be nested:
Guido van Rossum6938f061994-08-01 12:22:53 +00001529... u = t, (1, 2, 3, 4, 5)
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001530>>> u
1531((12345, 54321, 'hello!'), (1, 2, 3, 4, 5))
Fred Drake8842e861998-02-13 07:16:30 +00001532\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001533
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001534As you see, on output tuples are alway enclosed in parentheses, so
1535that nested tuples are interpreted correctly; they may be input with
1536or without surrounding parentheses, although often parentheses are
1537necessary anyway (if the tuple is part of a larger expression).
1538
1539Tuples have many uses, e.g., (x, y) coordinate pairs, employee records
1540from a database, etc. Tuples, like strings, are immutable: it is not
1541possible to assign to the individual items of a tuple (you can
1542simulate much of the same effect with slicing and concatenation,
1543though).
1544
1545A special problem is the construction of tuples containing 0 or 1
Guido van Rossum6938f061994-08-01 12:22:53 +00001546items: the syntax has some extra quirks to accommodate these. Empty
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001547tuples are constructed by an empty pair of parentheses; a tuple with
1548one item is constructed by following a value with a comma
1549(it is not sufficient to enclose a single value in parentheses).
1550Ugly, but effective. For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001551
Fred Drake8842e861998-02-13 07:16:30 +00001552\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001553>>> empty = ()
1554>>> singleton = 'hello', # <-- note trailing comma
1555>>> len(empty)
15560
1557>>> len(singleton)
15581
1559>>> singleton
1560('hello',)
Fred Drake8842e861998-02-13 07:16:30 +00001561\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001562
Fred Drakeeee08cd1997-12-04 15:43:15 +00001563The statement \code{t = 12345, 54321, 'hello!'} is an example of
1564\emph{tuple packing}: the values \code{12345}, \code{54321} and
1565\code{'hello!'} are packed together in a tuple. The reverse operation
1566is also possible, e.g.:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001567
Fred Drake8842e861998-02-13 07:16:30 +00001568\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001569>>> x, y, z = t
Fred Drake8842e861998-02-13 07:16:30 +00001570\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001571
Fred Drakeeee08cd1997-12-04 15:43:15 +00001572This is called, appropriately enough, \emph{tuple unpacking}. Tuple
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001573unpacking requires that the list of variables on the left has the same
1574number of elements as the length of the tuple. Note that multiple
1575assignment is really just a combination of tuple packing and tuple
1576unpacking!
1577
Guido van Rossumaee5e261998-08-07 17:45:09 +00001578% XXX This is no longer necessary!
Fred Drakeeee08cd1997-12-04 15:43:15 +00001579Occasionally, the corresponding operation on lists is useful: \emph{list
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001580unpacking}. This is supported by enclosing the list of variables in
1581square brackets:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001582
Fred Drake8842e861998-02-13 07:16:30 +00001583\begin{verbatim}
Guido van Rossume5f8b601995-01-04 19:12:49 +00001584>>> a = ['spam', 'eggs', 100, 1234]
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001585>>> [a1, a2, a3, a4] = a
Fred Drake8842e861998-02-13 07:16:30 +00001586\end{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001587
Guido van Rossumaee5e261998-08-07 17:45:09 +00001588% XXX Add a bit on the difference between tuples and lists.
1589% XXX Also explain that a tuple can *contain* a mutable object!
1590
Fred Drakeb7833d31998-09-11 16:21:55 +00001591\section{Dictionaries \label{dictionaries}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001592
Fred Drakeeee08cd1997-12-04 15:43:15 +00001593Another useful data type built into Python is the \emph{dictionary}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001594Dictionaries are sometimes found in other languages as ``associative
1595memories'' or ``associative arrays''. Unlike sequences, which are
Fred Drakeeee08cd1997-12-04 15:43:15 +00001596indexed by a range of numbers, dictionaries are indexed by \emph{keys},
Guido van Rossum02455691997-07-17 16:21:52 +00001597which can be any non-mutable type; strings and numbers can always be
1598keys. Tuples can be used as keys if they contain only strings,
1599numbers, or tuples. You can't use lists as keys, since lists can be
1600modified in place using their \code{append()} method.
1601
Guido van Rossum6938f061994-08-01 12:22:53 +00001602It is best to think of a dictionary as an unordered set of
Fred Drakeeee08cd1997-12-04 15:43:15 +00001603\emph{key:value} pairs, with the requirement that the keys are unique
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001604(within one dictionary).
Fred Drakeeee08cd1997-12-04 15:43:15 +00001605A pair of braces creates an empty dictionary: \code{\{\}}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001606Placing a comma-separated list of key:value pairs within the
1607braces adds initial key:value pairs to the dictionary; this is also the
1608way dictionaries are written on output.
1609
1610The main operations on a dictionary are storing a value with some key
1611and extracting the value given the key. It is also possible to delete
1612a key:value pair
Fred Drakeeee08cd1997-12-04 15:43:15 +00001613with \code{del}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001614If you store using a key that is already in use, the old value
1615associated with that key is forgotten. It is an error to extract a
Guido van Rossum6938f061994-08-01 12:22:53 +00001616value using a non-existent key.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001617
Fred Drakeeee08cd1997-12-04 15:43:15 +00001618The \code{keys()} method of a dictionary object returns a list of all the
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001619keys used in the dictionary, in random order (if you want it sorted,
Fred Drakeeee08cd1997-12-04 15:43:15 +00001620just apply the \code{sort()} method to the list of keys). To check
1621whether a single key is in the dictionary, use the \code{has_key()}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001622method of the dictionary.
1623
1624Here is a small example using a dictionary:
1625
Fred Drake8842e861998-02-13 07:16:30 +00001626\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001627>>> tel = {'jack': 4098, 'sape': 4139}
1628>>> tel['guido'] = 4127
1629>>> tel
Guido van Rossum8f96f771991-11-12 15:45:03 +00001630{'sape': 4139, 'guido': 4127, 'jack': 4098}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001631>>> tel['jack']
16324098
1633>>> del tel['sape']
1634>>> tel['irv'] = 4127
1635>>> tel
Guido van Rossum8f96f771991-11-12 15:45:03 +00001636{'guido': 4127, 'irv': 4127, 'jack': 4098}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001637>>> tel.keys()
1638['guido', 'irv', 'jack']
1639>>> tel.has_key('guido')
16401
Fred Drake8842e861998-02-13 07:16:30 +00001641\end{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001642
Fred Drakeb7833d31998-09-11 16:21:55 +00001643\section{More on Conditions \label{conditions}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001644
Fred Drakeeee08cd1997-12-04 15:43:15 +00001645The conditions used in \code{while} and \code{if} statements above can
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001646contain other operators besides comparisons.
1647
Fred Drakeeee08cd1997-12-04 15:43:15 +00001648The comparison operators \code{in} and \code{not in} check whether a value
1649occurs (does not occur) in a sequence. The operators \code{is} and
1650\code{is not} compare whether two objects are really the same object; this
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001651only matters for mutable objects like lists. All comparison operators
1652have the same priority, which is lower than that of all numerical
1653operators.
1654
Fred Drakeeee08cd1997-12-04 15:43:15 +00001655Comparisons can be chained: e.g., \code{a < b == c} tests whether \code{a}
1656is less than \code{b} and moreover \code{b} equals \code{c}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001657
Fred Drakeeee08cd1997-12-04 15:43:15 +00001658Comparisons may be combined by the Boolean operators \code{and} and
1659\code{or}, and the outcome of a comparison (or of any other Boolean
1660expression) may be negated with \code{not}. These all have lower
1661priorities than comparison operators again; between them, \code{not} has
1662the highest priority, and \code{or} the lowest, so that
1663\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 +00001664course, parentheses can be used to express the desired composition.
1665
Fred Drakeeee08cd1997-12-04 15:43:15 +00001666The Boolean operators \code{and} and \code{or} are so-called
1667\emph{shortcut} operators: their arguments are evaluated from left to
1668right, and evaluation stops as soon as the outcome is determined.
1669E.g., if \code{A} and \code{C} are true but \code{B} is false, \code{A
1670and B and C} does not evaluate the expression C. In general, the
1671return value of a shortcut operator, when used as a general value and
1672not as a Boolean, is the last evaluated argument.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001673
1674It is possible to assign the result of a comparison or other Boolean
Guido van Rossum6938f061994-08-01 12:22:53 +00001675expression to a variable. For example,
1676
Fred Drake8842e861998-02-13 07:16:30 +00001677\begin{verbatim}
Guido van Rossum6938f061994-08-01 12:22:53 +00001678>>> string1, string2, string3 = '', 'Trondheim', 'Hammer Dance'
1679>>> non_null = string1 or string2 or string3
1680>>> non_null
1681'Trondheim'
Fred Drake8842e861998-02-13 07:16:30 +00001682\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001683
Fred Drake3f205921998-01-13 18:56:38 +00001684Note that in Python, unlike \C{}, assignment cannot occur inside expressions.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001685
Fred Drakeb7833d31998-09-11 16:21:55 +00001686\section{Comparing Sequences and Other Types \label{comparing}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001687
1688Sequence objects may be compared to other objects with the same
Fred Drakeeee08cd1997-12-04 15:43:15 +00001689sequence type. The comparison uses \emph{lexicographical} ordering:
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001690first the first two items are compared, and if they differ this
1691determines the outcome of the comparison; if they are equal, the next
1692two items are compared, and so on, until either sequence is exhausted.
1693If two items to be compared are themselves sequences of the same type,
Guido van Rossum6938f061994-08-01 12:22:53 +00001694the lexicographical comparison is carried out recursively. If all
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001695items of two sequences compare equal, the sequences are considered
1696equal. If one sequence is an initial subsequence of the other, the
1697shorted sequence is the smaller one. Lexicographical ordering for
Guido van Rossum47b4c0f1995-03-15 11:25:32 +00001698strings uses the \ASCII{} ordering for individual characters. Some
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001699examples of comparisons between sequences with the same types:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001700
Fred Drake8842e861998-02-13 07:16:30 +00001701\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001702(1, 2, 3) < (1, 2, 4)
1703[1, 2, 3] < [1, 2, 4]
1704'ABC' < 'C' < 'Pascal' < 'Python'
1705(1, 2, 3, 4) < (1, 2, 4)
1706(1, 2) < (1, 2, -1)
1707(1, 2, 3) = (1.0, 2.0, 3.0)
1708(1, 2, ('aa', 'ab')) < (1, 2, ('abc', 'a'), 4)
Fred Drake8842e861998-02-13 07:16:30 +00001709\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001710
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001711Note that comparing objects of different types is legal. The outcome
1712is deterministic but arbitrary: the types are ordered by their name.
1713Thus, a list is always smaller than a string, a string is always
1714smaller than a tuple, etc. Mixed numeric types are compared according
1715to their numeric value, so 0 equals 0.0, etc.%
1716\footnote{
Guido van Rossum6938f061994-08-01 12:22:53 +00001717 The rules for comparing objects of different types should
1718 not be relied upon; they may change in a future version of
1719 the language.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001720}
1721
Guido van Rossum5e0759d1992-08-07 16:06:24 +00001722
Fred Drakeb7833d31998-09-11 16:21:55 +00001723\chapter{Modules \label{modules}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001724
Guido van Rossum4410c751991-06-04 20:22:18 +00001725If you quit from the Python interpreter and enter it again, the
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001726definitions you have made (functions and variables) are lost.
1727Therefore, if you want to write a somewhat longer program, you are
1728better off using a text editor to prepare the input for the interpreter
Guido van Rossum16d6e711994-08-08 12:30:22 +00001729and running it with that file as input instead. This is known as creating a
Fred Drakeeee08cd1997-12-04 15:43:15 +00001730\emph{script}. As your program gets longer, you may want to split it
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001731into several files for easier maintenance. You may also want to use a
1732handy function that you've written in several programs without copying
1733its definition into each program.
1734
Guido van Rossum4410c751991-06-04 20:22:18 +00001735To support this, Python has a way to put definitions in a file and use
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001736them in a script or in an interactive instance of the interpreter.
Fred Drakeeee08cd1997-12-04 15:43:15 +00001737Such a file is called a \emph{module}; definitions from a module can be
1738\emph{imported} into other modules or into the \emph{main} module (the
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001739collection of variables that you have access to in a script
1740executed at the top level
1741and in calculator mode).
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001742
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001743A module is a file containing Python definitions and statements. The
Fred Drakeeee08cd1997-12-04 15:43:15 +00001744file name is the module name with the suffix \file{.py} appended. Within
Guido van Rossum6938f061994-08-01 12:22:53 +00001745a module, the module's name (as a string) is available as the value of
Fred Drakeeee08cd1997-12-04 15:43:15 +00001746the global variable \code{__name__}. For instance, use your favorite text
1747editor to create a file called \file{fibo.py} in the current directory
Guido van Rossum6938f061994-08-01 12:22:53 +00001748with the following contents:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001749
Fred Drake8842e861998-02-13 07:16:30 +00001750\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001751# Fibonacci numbers module
1752
1753def fib(n): # write Fibonacci series up to n
1754 a, b = 0, 1
Guido van Rossum16cd7f91994-10-06 10:29:26 +00001755 while b < n:
Fred Drakeeee08cd1997-12-04 15:43:15 +00001756 print b,
1757 a, b = b, a+b
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001758
1759def fib2(n): # return Fibonacci series up to n
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001760 result = []
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001761 a, b = 0, 1
Guido van Rossum16cd7f91994-10-06 10:29:26 +00001762 while b < n:
Fred Drakeeee08cd1997-12-04 15:43:15 +00001763 result.append(b)
1764 a, b = b, a+b
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001765 return result
Fred Drake8842e861998-02-13 07:16:30 +00001766\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001767
Guido van Rossum4410c751991-06-04 20:22:18 +00001768Now enter the Python interpreter and import this module with the
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001769following command:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001770
Fred Drake8842e861998-02-13 07:16:30 +00001771\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001772>>> import fibo
Fred Drake8842e861998-02-13 07:16:30 +00001773\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001774
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001775This does not enter the names of the functions defined in
Fred Drakeeee08cd1997-12-04 15:43:15 +00001776\code{fibo}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001777directly in the current symbol table; it only enters the module name
Fred Drakeeee08cd1997-12-04 15:43:15 +00001778\code{fibo}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001779there.
1780Using the module name you can access the functions:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001781
Fred Drake8842e861998-02-13 07:16:30 +00001782\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001783>>> fibo.fib(1000)
17841 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
1785>>> fibo.fib2(100)
1786[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
Guido van Rossum6938f061994-08-01 12:22:53 +00001787>>> fibo.__name__
1788'fibo'
Fred Drake8842e861998-02-13 07:16:30 +00001789\end{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001790%
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001791If you intend to use a function often you can assign it to a local name:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001792
Fred Drake8842e861998-02-13 07:16:30 +00001793\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001794>>> fib = fibo.fib
1795>>> fib(500)
17961 1 2 3 5 8 13 21 34 55 89 144 233 377
Fred Drake8842e861998-02-13 07:16:30 +00001797\end{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001798
Guido van Rossum02455691997-07-17 16:21:52 +00001799
Fred Drakeb7833d31998-09-11 16:21:55 +00001800\section{More on Modules \label{moreModules}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001801
1802A module can contain executable statements as well as function
1803definitions.
1804These statements are intended to initialize the module.
1805They are executed only the
Fred Drakeeee08cd1997-12-04 15:43:15 +00001806\emph{first}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001807time the module is imported somewhere.%
1808\footnote{
Guido van Rossum6938f061994-08-01 12:22:53 +00001809 In fact function definitions are also `statements' that are
1810 `executed'; the execution enters the function name in the
1811 module's global symbol table.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001812}
1813
1814Each module has its own private symbol table, which is used as the
1815global symbol table by all functions defined in the module.
1816Thus, the author of a module can use global variables in the module
1817without worrying about accidental clashes with a user's global
1818variables.
1819On the other hand, if you know what you are doing you can touch a
1820module's global variables with the same notation used to refer to its
1821functions,
Fred Drakeeee08cd1997-12-04 15:43:15 +00001822\code{modname.itemname}.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001823
1824Modules can import other modules.
1825It is customary but not required to place all
Fred Drakeeee08cd1997-12-04 15:43:15 +00001826\code{import}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001827statements at the beginning of a module (or script, for that matter).
1828The imported module names are placed in the importing module's global
1829symbol table.
1830
1831There is a variant of the
Fred Drakeeee08cd1997-12-04 15:43:15 +00001832\code{import}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001833statement that imports names from a module directly into the importing
1834module's symbol table.
1835For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001836
Fred Drake8842e861998-02-13 07:16:30 +00001837\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001838>>> from fibo import fib, fib2
1839>>> fib(500)
18401 1 2 3 5 8 13 21 34 55 89 144 233 377
Fred Drake8842e861998-02-13 07:16:30 +00001841\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001842
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001843This does not introduce the module name from which the imports are taken
Fred Drakeeee08cd1997-12-04 15:43:15 +00001844in the local symbol table (so in the example, \code{fibo} is not
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001845defined).
1846
1847There is even a variant to import all names that a module defines:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001848
Fred Drake8842e861998-02-13 07:16:30 +00001849\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001850>>> from fibo import *
1851>>> fib(500)
18521 1 2 3 5 8 13 21 34 55 89 144 233 377
Fred Drake8842e861998-02-13 07:16:30 +00001853\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001854
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001855This imports all names except those beginning with an underscore
Fred Drakeeee08cd1997-12-04 15:43:15 +00001856(\code{_}).
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001857
Fred Drakeb7833d31998-09-11 16:21:55 +00001858\subsection{The Module Search Path \label{searchPath}}
Guido van Rossum02455691997-07-17 16:21:52 +00001859
Guido van Rossumaee5e261998-08-07 17:45:09 +00001860% XXX Need to document that a lone .pyc/.pyo is acceptable too!
1861
Fred Drake391564f1998-04-01 23:11:56 +00001862\indexiii{module}{search}{path}
Fred Drake8842e861998-02-13 07:16:30 +00001863When a module named \module{spam} is imported, the interpreter searches
Fred Drakeeee08cd1997-12-04 15:43:15 +00001864for a file named \file{spam.py} in the current directory,
Guido van Rossum02455691997-07-17 16:21:52 +00001865and then in the list of directories specified by
Fred Drake391564f1998-04-01 23:11:56 +00001866the environment variable \envvar{PYTHONPATH}. This has the same syntax as
1867the shell variable \envvar{PATH}, i.e., a list of
1868directory names. When \envvar{PYTHONPATH} is not set, or when the file
Guido van Rossum02455691997-07-17 16:21:52 +00001869is not found there, the search continues in an installation-dependent
Fred Drake391564f1998-04-01 23:11:56 +00001870default path; on \UNIX{}, this is usually \file{.:/usr/local/lib/python}.
Guido van Rossum02455691997-07-17 16:21:52 +00001871
1872Actually, modules are searched in the list of directories given by the
Fred Drakeeee08cd1997-12-04 15:43:15 +00001873variable \code{sys.path} which is initialized from the directory
1874containing the input script (or the current directory),
Fred Drake391564f1998-04-01 23:11:56 +00001875\envvar{PYTHONPATH} and the installation-dependent default. This allows
Guido van Rossum02455691997-07-17 16:21:52 +00001876Python programs that know what they're doing to modify or replace the
1877module search path. See the section on Standard Modules later.
1878
1879\subsection{``Compiled'' Python files}
1880
1881As an important speed-up of the start-up time for short programs that
Fred Drakeeee08cd1997-12-04 15:43:15 +00001882use a lot of standard modules, if a file called \file{spam.pyc} exists
1883in the directory where \file{spam.py} is found, this is assumed to
Guido van Rossum13c8ef61998-05-29 19:12:23 +00001884contain an already-``byte-compiled'' version of the module \module{spam}.
Fred Drake8842e861998-02-13 07:16:30 +00001885The modification time of the version of \file{spam.py} used to create
Fred Drakeeee08cd1997-12-04 15:43:15 +00001886\file{spam.pyc} is recorded in \file{spam.pyc}, and the file is
1887ignored if these don't match.
Guido van Rossum02455691997-07-17 16:21:52 +00001888
Fred Drakeeee08cd1997-12-04 15:43:15 +00001889Normally, you don't need to do anything to create the \file{spam.pyc} file.
1890Whenever \file{spam.py} is successfully compiled, an attempt is made to
1891write the compiled version to \file{spam.pyc}. It is not an error if
Guido van Rossum02455691997-07-17 16:21:52 +00001892this attempt fails; if for any reason the file is not written
Fred Drakeeee08cd1997-12-04 15:43:15 +00001893completely, the resulting \file{spam.pyc} file will be recognized as
1894invalid and thus ignored later. The contents of the \file{spam.pyc}
Guido van Rossum02455691997-07-17 16:21:52 +00001895file is platform independent, so a Python module directory can be
Guido van Rossum13c8ef61998-05-29 19:12:23 +00001896shared by machines of different architectures.
Guido van Rossum02455691997-07-17 16:21:52 +00001897
Guido van Rossum13c8ef61998-05-29 19:12:23 +00001898Some tips for experts:
1899
1900\begin{itemize}
1901
1902\item
1903When the Python interpreter is invoked with the \code{-O} flag,
1904optimized code is generated and stored in \file{.pyo} files.
1905The optimizer currently doesn't help much; it only removes
1906\keyword{assert} statements and \code{SET_LINENO} instructions.
1907When \code{-O} is used, \emph{all} bytecode is optimized; \code{.pyc}
1908files are ignored and \code{.py} files are compiled to optimized
1909bytecode.
1910
1911\item
1912A program doesn't run any faster when it is read from a
1913\file{.pyc} or \file{.pyo} file than when it is read from a \file{.py}
1914file; the only thing that's faster about \file{.pyc} or \file{.pyo}
1915files is the speed with which they are loaded.
1916
1917\item
Guido van Rossum002f7aa1998-06-28 19:16:38 +00001918When a script is run by giving its name on the command line, the
1919bytecode for the script is never written to a \file{.pyc} or
1920\file{.pyo} file. Thus, the startup time of a script may be reduced
1921by moving most of its code to a module and having a small bootstrap
1922script that imports that module.
1923
1924\item
Guido van Rossum13c8ef61998-05-29 19:12:23 +00001925It is possible to have a file called \file{spam.pyc} (or
1926\file{spam.pyo} when \code{-O} is used) without a module
1927\file{spam.py} in the same module. This can be used to distribute
1928a library of Python code in a form that is moderately hard to reverse
1929engineer.
1930
1931\item
1932The module \module{compileall}\refstmodindex{compileall} can create
1933\file{.pyc} files (or \file{.pyo} files when \code{-O} is used) for
1934all modules in a directory.
1935
1936\end{itemize}
1937
Guido van Rossum02455691997-07-17 16:21:52 +00001938
Fred Drakeb7833d31998-09-11 16:21:55 +00001939\section{Standard Modules \label{standardModules}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001940
Guido van Rossum4410c751991-06-04 20:22:18 +00001941Python comes with a library of standard modules, described in a separate
Fred Drake8842e861998-02-13 07:16:30 +00001942document, the \emph{Python Library Reference} (``Library Reference''
1943hereafter). Some modules are built into the interpreter; these
1944provide access to operations that are not part of the core of the
1945language but are nevertheless built in, either for efficiency or to
1946provide access to operating system primitives such as system calls.
1947The set of such modules is a configuration option; e.g., the
1948\module{amoeba} module is only provided on systems that somehow
1949support Amoeba primitives. One particular module deserves some
Fred Drake391564f1998-04-01 23:11:56 +00001950attention: \module{sys}\refstmodindex{sys}, which is built into every
1951Python interpreter. The variables \code{sys.ps1} and \code{sys.ps2}
1952define the strings used as primary and secondary prompts:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001953
Fred Drake8842e861998-02-13 07:16:30 +00001954\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001955>>> import sys
1956>>> sys.ps1
1957'>>> '
1958>>> sys.ps2
1959'... '
1960>>> sys.ps1 = 'C> '
1961C> print 'Yuck!'
1962Yuck!
1963C>
Fred Drake8842e861998-02-13 07:16:30 +00001964\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001965
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001966These two variables are only defined if the interpreter is in
1967interactive mode.
1968
1969The variable
Fred Drakeeee08cd1997-12-04 15:43:15 +00001970\code{sys.path}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001971is a list of strings that determine the interpreter's search path for
1972modules.
1973It is initialized to a default path taken from the environment variable
Fred Drake391564f1998-04-01 23:11:56 +00001974\envvar{PYTHONPATH}, or from a built-in default if \envvar{PYTHONPATH}
1975is not set. You can modify it using standard list operations, e.g.:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001976
Fred Drake8842e861998-02-13 07:16:30 +00001977\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001978>>> import sys
1979>>> sys.path.append('/ufs/guido/lib/python')
Fred Drake8842e861998-02-13 07:16:30 +00001980\end{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001981
Fred Drakeb7833d31998-09-11 16:21:55 +00001982\section{The \function{dir()} Function \label{dir}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001983
Fred Drake8842e861998-02-13 07:16:30 +00001984The built-in function \function{dir()} is used to find out which names
1985a module defines. It returns a sorted list of strings:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001986
Fred Drake8842e861998-02-13 07:16:30 +00001987\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001988>>> import fibo, sys
1989>>> dir(fibo)
Guido van Rossum6938f061994-08-01 12:22:53 +00001990['__name__', 'fib', 'fib2']
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001991>>> dir(sys)
Guido van Rossum6938f061994-08-01 12:22:53 +00001992['__name__', 'argv', 'builtin_module_names', 'copyright', 'exit',
1993'maxint', 'modules', 'path', 'ps1', 'ps2', 'setprofile', 'settrace',
1994'stderr', 'stdin', 'stdout', 'version']
Fred Drake8842e861998-02-13 07:16:30 +00001995\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001996
Fred Drake8842e861998-02-13 07:16:30 +00001997Without arguments, \function{dir()} lists the names you have defined
1998currently:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001999
Fred Drake8842e861998-02-13 07:16:30 +00002000\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002001>>> a = [1, 2, 3, 4, 5]
2002>>> import fibo, sys
2003>>> fib = fibo.fib
2004>>> dir()
Guido van Rossum6938f061994-08-01 12:22:53 +00002005['__name__', 'a', 'fib', 'fibo', 'sys']
Fred Drake8842e861998-02-13 07:16:30 +00002006\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002007
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002008Note that it lists all types of names: variables, modules, functions, etc.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002009
Fred Drake8842e861998-02-13 07:16:30 +00002010\function{dir()} does not list the names of built-in functions and
2011variables. If you want a list of those, they are defined in the
Fred Drake391564f1998-04-01 23:11:56 +00002012standard module \module{__builtin__}\refbimodindex{__builtin__}:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002013
Fred Drake8842e861998-02-13 07:16:30 +00002014\begin{verbatim}
Guido van Rossum4bd023f1993-10-27 13:49:20 +00002015>>> import __builtin__
2016>>> dir(__builtin__)
Guido van Rossum6938f061994-08-01 12:22:53 +00002017['AccessError', 'AttributeError', 'ConflictError', 'EOFError', 'IOError',
2018'ImportError', 'IndexError', 'KeyError', 'KeyboardInterrupt',
2019'MemoryError', 'NameError', 'None', 'OverflowError', 'RuntimeError',
2020'SyntaxError', 'SystemError', 'SystemExit', 'TypeError', 'ValueError',
2021'ZeroDivisionError', '__name__', 'abs', 'apply', 'chr', 'cmp', 'coerce',
2022'compile', 'dir', 'divmod', 'eval', 'execfile', 'filter', 'float',
2023'getattr', 'hasattr', 'hash', 'hex', 'id', 'input', 'int', 'len', 'long',
2024'map', 'max', 'min', 'oct', 'open', 'ord', 'pow', 'range', 'raw_input',
2025'reduce', 'reload', 'repr', 'round', 'setattr', 'str', 'type', 'xrange']
Fred Drake8842e861998-02-13 07:16:30 +00002026\end{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002027
Fred Drakeb7833d31998-09-11 16:21:55 +00002028\section{Packages \label{packages}}
Andrew M. Kuchling108943c1998-07-01 13:58:55 +00002029
2030Packages are a way of structuring Python's module namespace
Fred Drakeb7833d31998-09-11 16:21:55 +00002031by using ``dotted module names''. For example, the module name
2032\module{A.B} designates a submodule named \samp{B} in a package named
2033\samp{A}. Just like the use of modules saves the authors of different
2034modules from having to worry about each other's global variable names,
2035the use of dotted module names saves the authors of multi-module
2036packages like NumPy or PIL from having to worry about each other's
2037module names.
Andrew M. Kuchling108943c1998-07-01 13:58:55 +00002038
2039Suppose you want to design a collection of modules (a ``package'') for
2040the uniform handling of sound files and sound data. There are many
2041different sound file formats (usually recognized by their extension,
2042e.g. \file{.wav}, \file{.aiff}, \file{.au}), so you may need to create
2043and maintain a growing collection of modules for the conversion
2044between the various file formats. There are also many different
2045operations you might want to perform on sound data (e.g. mixing,
2046adding echo, applying an equalizer function, creating an artificial
2047stereo effect), so in addition you will be writing a never-ending
2048stream of modules to perform these operations. Here's a possible
2049structure for your package (expressed in terms of a hierarchical
2050filesystem):
2051
2052\begin{verbatim}
2053Sound/ Top-level package
2054 __init__.py Initialize the sound package
2055 Formats/ Subpackage for file format conversions
2056 __init__.py
2057 wavread.py
2058 wavwrite.py
2059 aiffread.py
2060 aiffwrite.py
2061 auread.py
2062 auwrite.py
2063 ...
2064 Effects/ Subpackage for sound effects
2065 __init__.py
2066 echo.py
2067 surround.py
2068 reverse.py
2069 ...
2070 Filters/ Subpackage for filters
2071 __init__.py
2072 equalizer.py
2073 vocoder.py
2074 karaoke.py
2075 ...
2076\end{verbatim}
2077The \file{__init__.py} files are required to make Python treat the
2078directories as containing packages; this is done to prevent
2079directories with a common name, such as \samp{string}, from
2080unintentionally hiding valid modules that occur later on the module
2081search path. In the simplest case, \file{__init__.py} can just be an
2082empty file, but it can also execute initialization code for the
2083package or set the \code{__all__} variable, described later.
2084
2085Users of the package can import individual modules from the
2086package, for example:
2087
2088\begin{verbatim}
2089import Sound.Effects.echo
2090\end{verbatim}
2091This loads the submodule \module{Sound.Effects.echo}. It must be referenced
2092with its full name, e.g.
2093
2094\begin{verbatim}
2095Sound.Effects.echo.echofilter(input, output, delay=0.7, atten=4)
2096\end{verbatim}
2097An alternative way of importing the submodule is:
2098
2099\begin{verbatim}
2100from Sound.Effects import echo
2101\end{verbatim}
2102This also loads the submodule \module{echo}, and makes it available without
2103its package prefix, so it can be used as follows:
2104
2105\begin{verbatim}
2106echo.echofilter(input, output, delay=0.7, atten=4)
2107\end{verbatim}
2108
2109Yet another variation is to import the desired function or variable directly:
2110
2111\begin{verbatim}
2112from Sound.Effects.echo import echofilter
2113\end{verbatim}
2114
2115Again, this loads the submodule \module{echo}, but this makes its function
2116echofilter directly available:
2117
2118\begin{verbatim}
2119echofilter(input, output, delay=0.7, atten=4)
2120\end{verbatim}
2121
2122Note that when using \code{from \var{package} import \var{item}}, the
2123item can be either a submodule (or subpackage) of the package, or some
2124other name defined in the package, like a function, class or
2125variable. The \code{import} statement first tests whether the item is
2126defined in the package; if not, it assumes it is a module and attempts
2127to load it. If it fails to find it, \exception{ImportError} is raised.
2128
2129Contrarily, when using syntax like \code{import
2130\var{item.subitem.subsubitem}}, each item except for the last must be
2131a package; the last item can be a module or a package but can't be a
2132class or function or variable defined in the previous item.
2133
Fred Drakeb7833d31998-09-11 16:21:55 +00002134\subsection{Importing * From a Package \label{pkg-import-star}}
Andrew M. Kuchling108943c1998-07-01 13:58:55 +00002135%The \code{__all__} Attribute
2136
2137Now what happens when the user writes \code{from Sound.Effects import
2138*}? Ideally, one would hope that this somehow goes out to the
2139filesystem, finds which submodules are present in the package, and
2140imports them all. Unfortunately, this operation does not work very
2141well on Mac and Windows platforms, where the filesystem does not
2142always have accurate information about the case of a filename! On
2143these platforms, there is no guaranteed way to know whether a file
2144\file{ECHO.PY} should be imported as a module \module{echo},
2145\module{Echo} or \module{ECHO}. (For example, Windows 95 has the
2146annoying practice of showing all file names with a capitalized first
2147letter.) The DOS 8+3 filename restriction adds another interesting
2148problem for long module names.
2149
2150The only solution is for the package author to provide an explicit
2151index of the package. The import statement uses the following
2152convention: if a package's \file{__init__.py} code defines a list named
2153\code{__all__}, it is taken to be the list of module names that should be imported
2154when \code{from \var{package} import *} is
2155encountered. It is up to the package author to keep this list
2156up-to-date when a new version of the package is released. Package
2157authors may also decide not to support it, if they don't see a use for
2158importing * from their package. For example, the file
2159\code{Sounds/Effects/__init__.py} could contain the following code:
2160
2161\begin{verbatim}
2162__all__ = ["echo", "surround", "reverse"]
2163\end{verbatim}
2164
2165This would mean that \code{from Sound.Effects import *} would
2166import the three named submodules of the \module{Sound} package.
2167
2168If \code{__all__} is not defined, the statement \code{from Sound.Effects
2169import *} does \emph{not} import all submodules from the package
2170\module{Sound.Effects} into the current namespace; it only ensures that the
2171package \module{Sound.Effects} has been imported (possibly running its
2172initialization code, \file{__init__.py}) and then imports whatever names are
2173defined in the package. This includes any names defined (and
2174submodules explicitly loaded) by \file{__init__.py}. It also includes any
2175submodules of the package that were explicitly loaded by previous
2176import statements, e.g.
2177
2178\begin{verbatim}
2179import Sound.Effects.echo
2180import Sound.Effects.surround
2181from Sound.Effects import *
2182\end{verbatim}
2183
2184
2185In this example, the echo and surround modules are imported in the
2186current namespace because they are defined in the \module{Sound.Effects}
2187package when the \code{from...import} statement is executed. (This also
2188works when \code{__all__} is defined.)
2189
2190Note that in general the practicing of importing * from a module or
2191package is frowned upon, since it often causes poorly readable code.
2192However, it is okay to use it to save typing in interactive sessions,
2193and certain modules are designed to export only names that follow
2194certain patterns.
2195
2196Remember, there is nothing wrong with using \code{from Package
2197import specific_submodule}! In fact, this is the
2198recommended notation unless the importing module needs to use
2199submodules with the same name from different packages.
2200
2201
2202\subsection{Intra-package References}
2203
2204The submodules often need to refer to each other. For example, the
2205\module{surround} module might use the \module{echo} module. In fact, such references
2206are so common that the \code{import} statement first looks in the
2207containing package before looking in the standard module search path.
2208Thus, the surround module can simply use \code{import echo} or
2209\code{from echo import echofilter}. If the imported module is not
2210found in the current package (the package of which the current module
2211is a submodule), the \code{import} statement looks for a top-level module
2212with the given name.
2213
2214When packages are structured into subpackages (as with the \module{Sound}
2215package in the example), there's no shortcut to refer to submodules of
2216sibling packages - the full name of the subpackage must be used. For
2217example, if the module \module{Sound.Filters.vocoder} needs to use the \module{echo}
2218module in the \module{Sound.Effects} package, it can use \code{from
2219Sound.Effects import echo}.
2220
2221%(One could design a notation to refer to parent packages, similar to
2222%the use of ".." to refer to the parent directory in Unix and Windows
2223%filesystems. In fact, the \module{ni} module, which was the
2224%ancestor of this package system, supported this using \code{__} for
2225%the package containing the current module,
2226%\code{__.__} for the parent package, and so on. This feature was dropped
2227%because of its awkwardness; since most packages will have a relative
2228%shallow substructure, this is no big loss.)
2229
2230
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002231
Fred Drakeb7833d31998-09-11 16:21:55 +00002232\chapter{Input and Output \label{io}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002233
Guido van Rossum02455691997-07-17 16:21:52 +00002234There are several ways to present the output of a program; data can be
2235printed in a human-readable form, or written to a file for future use.
2236This chapter will discuss some of the possibilities.
2237
Fred Drakeb7833d31998-09-11 16:21:55 +00002238
2239\section{Fancier Output Formatting \label{formatting}}
2240
Fred Drakeeee08cd1997-12-04 15:43:15 +00002241So far we've encountered two ways of writing values: \emph{expression
Fred Drake8842e861998-02-13 07:16:30 +00002242statements} and the \keyword{print} statement. (A third way is using
2243the \method{write()} method of file objects; the standard output file
2244can be referenced as \code{sys.stdout}. See the Library Reference for
2245more information on this.)
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002246
2247Often you'll want more control over the formatting of your output than
Guido van Rossum02455691997-07-17 16:21:52 +00002248simply printing space-separated values. There are two ways to format
2249your output; the first way is to do all the string handling yourself;
2250using string slicing and concatenation operations you can create any
Fred Drake391564f1998-04-01 23:11:56 +00002251lay-out you can imagine. The standard module
2252\module{string}\refstmodindex{string} contains some useful operations
2253for padding strings to a given column width;
Guido van Rossum02455691997-07-17 16:21:52 +00002254these will be discussed shortly. The second way is to use the
2255\code{\%} operator with a string as the left argument. \code{\%}
Fred Drake8842e861998-02-13 07:16:30 +00002256interprets the left argument as a \C{} \cfunction{sprintf()}-style
2257format string to be applied to the right argument, and returns the
2258string resulting from this formatting operation.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002259
2260One question remains, of course: how do you convert values to strings?
Guido van Rossum02455691997-07-17 16:21:52 +00002261Luckily, Python has a way to convert any value to a string: pass it to
Fred Drake8842e861998-02-13 07:16:30 +00002262the \function{repr()} function, or just write the value between
2263reverse quotes (\code{``}). Some examples:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002264
Fred Drake8842e861998-02-13 07:16:30 +00002265\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002266>>> x = 10 * 3.14
2267>>> y = 200*200
2268>>> s = 'The value of x is ' + `x` + ', and y is ' + `y` + '...'
2269>>> print s
2270The value of x is 31.4, and y is 40000...
2271>>> # Reverse quotes work on other types besides numbers:
Guido van Rossum6938f061994-08-01 12:22:53 +00002272... p = [x, y]
Guido van Rossum02455691997-07-17 16:21:52 +00002273>>> ps = repr(p)
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002274>>> ps
2275'[31.4, 40000]'
2276>>> # Converting a string adds string quotes and backslashes:
Guido van Rossum6938f061994-08-01 12:22:53 +00002277... hello = 'hello, world\n'
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002278>>> hellos = `hello`
2279>>> print hellos
2280'hello, world\012'
2281>>> # The argument of reverse quotes may be a tuple:
Guido van Rossume5f8b601995-01-04 19:12:49 +00002282... `x, y, ('spam', 'eggs')`
2283"(31.4, 40000, ('spam', 'eggs'))"
Fred Drake8842e861998-02-13 07:16:30 +00002284\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002285
Guido van Rossum6938f061994-08-01 12:22:53 +00002286Here are two ways to write a table of squares and cubes:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002287
Fred Drake8842e861998-02-13 07:16:30 +00002288\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002289>>> import string
2290>>> for x in range(1, 11):
2291... print string.rjust(`x`, 2), string.rjust(`x*x`, 3),
2292... # Note trailing comma on previous line
2293... print string.rjust(`x*x*x`, 4)
2294...
2295 1 1 1
2296 2 4 8
2297 3 9 27
2298 4 16 64
2299 5 25 125
2300 6 36 216
2301 7 49 343
2302 8 64 512
2303 9 81 729
230410 100 1000
Guido van Rossum6938f061994-08-01 12:22:53 +00002305>>> for x in range(1,11):
2306... print '%2d %3d %4d' % (x, x*x, x*x*x)
2307...
2308 1 1 1
2309 2 4 8
2310 3 9 27
2311 4 16 64
2312 5 25 125
2313 6 36 216
2314 7 49 343
2315 8 64 512
2316 9 81 729
231710 100 1000
Fred Drake8842e861998-02-13 07:16:30 +00002318\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002319
Fred Drake8842e861998-02-13 07:16:30 +00002320(Note that one space between each column was added by the way
2321\keyword{print} works: it always adds spaces between its arguments.)
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002322
Fred Drake8842e861998-02-13 07:16:30 +00002323This example demonstrates the function \function{string.rjust()},
2324which right-justifies a string in a field of a given width by padding
2325it with spaces on the left. There are similar functions
2326\function{string.ljust()} and \function{string.center()}. These
2327functions do not write anything, they just return a new string. If
2328the input string is too long, they don't truncate it, but return it
2329unchanged; this will mess up your column lay-out but that's usually
2330better than the alternative, which would be lying about a value. (If
2331you really want truncation you can always add a slice operation, as in
2332\samp{string.ljust(x,~n)[0:n]}.)
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002333
Fred Drake8842e861998-02-13 07:16:30 +00002334There is another function, \function{string.zfill()}, which pads a
2335numeric string on the left with zeros. It understands about plus and
2336minus signs:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002337
Fred Drake8842e861998-02-13 07:16:30 +00002338\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002339>>> string.zfill('12', 5)
2340'00012'
2341>>> string.zfill('-3.14', 7)
2342'-003.14'
2343>>> string.zfill('3.14159265359', 5)
2344'3.14159265359'
Fred Drake8842e861998-02-13 07:16:30 +00002345\end{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00002346%
2347Using the \code{\%} operator looks like this:
2348
2349\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00002350>>> import math
2351>>> print 'The value of PI is approximately %5.3f.' % math.pi
2352The value of PI is approximately 3.142.
Guido van Rossum02455691997-07-17 16:21:52 +00002353\end{verbatim}
2354
2355If there is more than one format in the string you pass a tuple as
2356right operand, e.g.
2357
2358\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00002359>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
2360>>> for name, phone in table.items():
2361... print '%-10s ==> %10d' % (name, phone)
2362...
2363Jack ==> 4098
2364Dcab ==> 8637678
2365Sjoerd ==> 4127
Guido van Rossum02455691997-07-17 16:21:52 +00002366\end{verbatim}
2367
Fred Drake3f205921998-01-13 18:56:38 +00002368Most formats work exactly as in \C{} and require that you pass the proper
Guido van Rossum02455691997-07-17 16:21:52 +00002369type; however, if you don't you get an exception, not a core dump.
Fred Drakedb70d061998-11-17 21:59:04 +00002370The \code{\%s} format is more relaxed: if the corresponding argument is
Fred Drake8842e861998-02-13 07:16:30 +00002371not a string object, it is converted to string using the
2372\function{str()} built-in function. Using \code{*} to pass the width
2373or precision in as a separate (integer) argument is supported. The
Fred Drakedb70d061998-11-17 21:59:04 +00002374\C{} formats \code{\%n} and \code{\%p} are not supported.
Guido van Rossum02455691997-07-17 16:21:52 +00002375
2376If you have a really long format string that you don't want to split
2377up, it would be nice if you could reference the variables to be
2378formatted by name instead of by position. This can be done by using
Fred Drakedb70d061998-11-17 21:59:04 +00002379an extension of \C{} formats using the form \code{\%(name)format}, e.g.
Guido van Rossum02455691997-07-17 16:21:52 +00002380
2381\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00002382>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
2383>>> print 'Jack: %(Jack)d; Sjoerd: %(Sjoerd)d; Dcab: %(Dcab)d' % table
2384Jack: 4098; Sjoerd: 4127; Dcab: 8637678
Guido van Rossum02455691997-07-17 16:21:52 +00002385\end{verbatim}
2386
2387This is particularly useful in combination with the new built-in
Fred Drake8842e861998-02-13 07:16:30 +00002388\function{vars()} function, which returns a dictionary containing all
Guido van Rossum02455691997-07-17 16:21:52 +00002389local variables.
2390
Fred Drakeb7833d31998-09-11 16:21:55 +00002391\section{Reading and Writing Files \label{files}}
Fred Drake6c2176e1998-02-26 21:47:54 +00002392
Guido van Rossum02455691997-07-17 16:21:52 +00002393% Opening files
Fred Drake391564f1998-04-01 23:11:56 +00002394\function{open()}\bifuncindex{open} returns a file
2395object\obindex{file}, and is most commonly used with two arguments:
2396\samp{open(\var{filename}, \var{mode})}.
Guido van Rossum02455691997-07-17 16:21:52 +00002397
Fred Drake8842e861998-02-13 07:16:30 +00002398\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00002399>>> f=open('/tmp/workfile', 'w')
2400>>> print f
2401<open file '/tmp/workfile', mode 'w' at 80a0960>
Fred Drake8842e861998-02-13 07:16:30 +00002402\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002403
Guido van Rossum02455691997-07-17 16:21:52 +00002404The first argument is a string containing the filename. The second
2405argument is another string containing a few characters describing the
2406way in which the file will be used. \var{mode} can be \code{'r'} when
2407the file will only be read, \code{'w'} for only writing (an existing
2408file with the same name will be erased), and \code{'a'} opens the file
2409for appending; any data written to the file is automatically added to
2410the end. \code{'r+'} opens the file for both reading and writing.
2411The \var{mode} argument is optional; \code{'r'} will be assumed if
2412it's omitted.
2413
Fred Drake391564f1998-04-01 23:11:56 +00002414On Windows and the Macintosh, \code{'b'} appended to the
Guido van Rossum02455691997-07-17 16:21:52 +00002415mode opens the file in binary mode, so there are also modes like
2416\code{'rb'}, \code{'wb'}, and \code{'r+b'}. Windows makes a
2417distinction between text and binary files; the end-of-line characters
2418in text files are automatically altered slightly when data is read or
2419written. This behind-the-scenes modification to file data is fine for
Fred Drake8842e861998-02-13 07:16:30 +00002420\ASCII{} text files, but it'll corrupt binary data like that in JPEGs or
2421\file{.EXE} files. Be very careful to use binary mode when reading and
Fred Drake391564f1998-04-01 23:11:56 +00002422writing such files. (Note that the precise semantics of text mode on
2423the Macintosh depends on the underlying \C{} library being used.)
Guido van Rossum02455691997-07-17 16:21:52 +00002424
Fred Drakeb7833d31998-09-11 16:21:55 +00002425\subsection{Methods of File Objects \label{fileMethods}}
Guido van Rossum02455691997-07-17 16:21:52 +00002426
2427The rest of the examples in this section will assume that a file
2428object called \code{f} has already been created.
2429
2430To read a file's contents, call \code{f.read(\var{size})}, which reads
2431some quantity of data and returns it as a string. \var{size} is an
2432optional numeric argument. When \var{size} is omitted or negative,
2433the entire contents of the file will be read and returned; it's your
2434problem if the file is twice as large as your machine's memory.
2435Otherwise, at most \var{size} bytes are read and returned. If the end
2436of the file has been reached, \code{f.read()} will return an empty
2437string (\code {""}).
Fred Drake8842e861998-02-13 07:16:30 +00002438\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00002439>>> f.read()
2440'This is the entire file.\012'
2441>>> f.read()
2442''
Fred Drake8842e861998-02-13 07:16:30 +00002443\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002444
Guido van Rossum02455691997-07-17 16:21:52 +00002445\code{f.readline()} reads a single line from the file; a newline
Fred Drake8842e861998-02-13 07:16:30 +00002446character (\code{\e n}) is left at the end of the string, and is only
Guido van Rossum02455691997-07-17 16:21:52 +00002447omitted on the last line of the file if the file doesn't end in a
2448newline. This makes the return value unambiguous; if
2449\code{f.readline()} returns an empty string, the end of the file has
Fred Drake8842e861998-02-13 07:16:30 +00002450been reached, while a blank line is represented by \code{'\e n'}, a
Guido van Rossum02455691997-07-17 16:21:52 +00002451string containing only a single newline.
2452
Fred Drake8842e861998-02-13 07:16:30 +00002453\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00002454>>> f.readline()
2455'This is the first line of the file.\012'
2456>>> f.readline()
2457'Second line of the file\012'
2458>>> f.readline()
2459''
Fred Drake8842e861998-02-13 07:16:30 +00002460\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002461
Fred Drakeeee08cd1997-12-04 15:43:15 +00002462\code{f.readlines()} uses \code{f.readline()} repeatedly, and returns
Guido van Rossum02455691997-07-17 16:21:52 +00002463a list containing all the lines of data in the file.
2464
Fred Drake8842e861998-02-13 07:16:30 +00002465\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00002466>>> f.readlines()
2467['This is the first line of the file.\012', 'Second line of the file\012']
Fred Drake8842e861998-02-13 07:16:30 +00002468\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002469
Guido van Rossum02455691997-07-17 16:21:52 +00002470\code{f.write(\var{string})} writes the contents of \var{string} to
2471the file, returning \code{None}.
2472
Fred Drake8842e861998-02-13 07:16:30 +00002473\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00002474>>> f.write('This is a test\n')
Fred Drake8842e861998-02-13 07:16:30 +00002475\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002476
Guido van Rossum02455691997-07-17 16:21:52 +00002477\code{f.tell()} returns an integer giving the file object's current
2478position in the file, measured in bytes from the beginning of the
2479file. To change the file object's position, use
Fred Drake8842e861998-02-13 07:16:30 +00002480\samp{f.seek(\var{offset}, \var{from_what})}. The position is
Guido van Rossum02455691997-07-17 16:21:52 +00002481computed from adding \var{offset} to a reference point; the reference
2482point is selected by the \var{from_what} argument. A \var{from_what}
2483value of 0 measures from the beginning of the file, 1 uses the current
2484file position, and 2 uses the end of the file as the reference point.
Fred Drake8842e861998-02-13 07:16:30 +00002485\var{from_what} can be omitted and defaults to 0, using the beginning
2486of the file as the reference point.
Guido van Rossum02455691997-07-17 16:21:52 +00002487
Fred Drake8842e861998-02-13 07:16:30 +00002488\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00002489>>> f=open('/tmp/workfile', 'r+')
2490>>> f.write('0123456789abcdef')
2491>>> f.seek(5) # Go to the 5th byte in the file
2492>>> f.read(1)
2493'5'
2494>>> f.seek(-3, 2) # Go to the 3rd byte before the end
2495>>> f.read(1)
2496'd'
Fred Drake8842e861998-02-13 07:16:30 +00002497\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002498
Guido van Rossum02455691997-07-17 16:21:52 +00002499When you're done with a file, call \code{f.close()} to close it and
2500free up any system resources taken up by the open file. After calling
2501\code{f.close()}, attempts to use the file object will automatically fail.
2502
Fred Drake8842e861998-02-13 07:16:30 +00002503\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00002504>>> f.close()
2505>>> f.read()
2506Traceback (innermost last):
2507 File "<stdin>", line 1, in ?
2508ValueError: I/O operation on closed file
Fred Drake8842e861998-02-13 07:16:30 +00002509\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002510
Fred Drake8842e861998-02-13 07:16:30 +00002511File objects have some additional methods, such as \method{isatty()}
2512and \method{truncate()} which are less frequently used; consult the
2513Library Reference for a complete guide to file objects.
Guido van Rossum02455691997-07-17 16:21:52 +00002514
Fred Drakeb7833d31998-09-11 16:21:55 +00002515\subsection{The \module{pickle} Module \label{pickle}}
Fred Drake391564f1998-04-01 23:11:56 +00002516\refstmodindex{pickle}
Guido van Rossum02455691997-07-17 16:21:52 +00002517
2518Strings can easily be written to and read from a file. Numbers take a
Fred Drake8842e861998-02-13 07:16:30 +00002519bit more effort, since the \method{read()} method only returns
2520strings, which will have to be passed to a function like
2521\function{string.atoi()}, which takes a string like \code{'123'} and
2522returns its numeric value 123. However, when you want to save more
2523complex data types like lists, dictionaries, or class instances,
2524things get a lot more complicated.
Guido van Rossum02455691997-07-17 16:21:52 +00002525
2526Rather than have users be constantly writing and debugging code to
2527save complicated data types, Python provides a standard module called
Fred Drake8842e861998-02-13 07:16:30 +00002528\module{pickle}. This is an amazing module that can take almost
Guido van Rossum02455691997-07-17 16:21:52 +00002529any Python object (even some forms of Python code!), and convert it to
2530a string representation; this process is called \dfn{pickling}.
2531Reconstructing the object from the string representation is called
2532\dfn{unpickling}. Between pickling and unpickling, the string
2533representing the object may have been stored in a file or data, or
2534sent over a network connection to some distant machine.
2535
2536If you have an object \code{x}, and a file object \code{f} that's been
2537opened for writing, the simplest way to pickle the object takes only
2538one line of code:
2539
Fred Drake8842e861998-02-13 07:16:30 +00002540\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00002541pickle.dump(x, f)
Fred Drake8842e861998-02-13 07:16:30 +00002542\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002543
Fred Drake8842e861998-02-13 07:16:30 +00002544To unpickle the object again, if \code{f} is a file object which has
2545been opened for reading:
Guido van Rossum02455691997-07-17 16:21:52 +00002546
Fred Drake8842e861998-02-13 07:16:30 +00002547\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00002548x = pickle.load(f)
Fred Drake8842e861998-02-13 07:16:30 +00002549\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002550
Guido van Rossum02455691997-07-17 16:21:52 +00002551(There are other variants of this, used when pickling many objects or
2552when you don't want to write the pickled data to a file; consult the
Fred Drake8842e861998-02-13 07:16:30 +00002553complete documentation for \module{pickle} in the Library Reference.)
Guido van Rossum02455691997-07-17 16:21:52 +00002554
Fred Drake8842e861998-02-13 07:16:30 +00002555\module{pickle} is the standard way to make Python objects which can be
Guido van Rossum02455691997-07-17 16:21:52 +00002556stored and reused by other programs or by a future invocation of the
2557same program; the technical term for this is a \dfn{persistent}
Fred Drake8842e861998-02-13 07:16:30 +00002558object. Because \module{pickle} is so widely used, many authors who
Guido van Rossum02455691997-07-17 16:21:52 +00002559write Python extensions take care to ensure that new data types such
Fred Drake72389881998-04-13 01:31:10 +00002560as matrices can be properly pickled and unpickled.
Guido van Rossum02455691997-07-17 16:21:52 +00002561
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002562
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002563
Fred Drakeb7833d31998-09-11 16:21:55 +00002564\chapter{Errors and Exceptions \label{errors}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002565
2566Until now error messages haven't been more than mentioned, but if you
2567have tried out the examples you have probably seen some. There are
Fred Drakeeee08cd1997-12-04 15:43:15 +00002568(at least) two distinguishable kinds of errors: \emph{syntax errors}
2569and \emph{exceptions}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002570
Fred Drakeb7833d31998-09-11 16:21:55 +00002571\section{Syntax Errors \label{syntaxErrors}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002572
2573Syntax errors, also known as parsing errors, are perhaps the most common
Guido van Rossum4410c751991-06-04 20:22:18 +00002574kind of complaint you get while you are still learning Python:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002575
Fred Drake8842e861998-02-13 07:16:30 +00002576\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002577>>> while 1 print 'Hello world'
Guido van Rossum6938f061994-08-01 12:22:53 +00002578 File "<stdin>", line 1
2579 while 1 print 'Hello world'
2580 ^
2581SyntaxError: invalid syntax
Fred Drake8842e861998-02-13 07:16:30 +00002582\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002583
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002584The parser repeats the offending line and displays a little `arrow'
2585pointing at the earliest point in the line where the error was detected.
2586The error is caused by (or at least detected at) the token
Fred Drakeeee08cd1997-12-04 15:43:15 +00002587\emph{preceding}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002588the arrow: in the example, the error is detected at the keyword
Fred Drake391564f1998-04-01 23:11:56 +00002589\keyword{print}, since a colon (\character{:}) is missing before it.
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002590File name and line number are printed so you know where to look in case
2591the input came from a script.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002592
Fred Drakeb7833d31998-09-11 16:21:55 +00002593\section{Exceptions \label{exceptions}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002594
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002595Even if a statement or expression is syntactically correct, it may
2596cause an error when an attempt is made to execute it.
Fred Drakeeee08cd1997-12-04 15:43:15 +00002597Errors detected during execution are called \emph{exceptions} and are
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002598not unconditionally fatal: you will soon learn how to handle them in
2599Python programs. Most exceptions are not handled by programs,
2600however, and result in error messages as shown here:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002601
Fred Drake8842e861998-02-13 07:16:30 +00002602\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002603>>> 10 * (1/0)
Guido van Rossum3cbc16d1993-12-17 12:13:53 +00002604Traceback (innermost last):
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002605 File "<stdin>", line 1
Guido van Rossumb2c65561993-05-12 08:53:36 +00002606ZeroDivisionError: integer division or modulo
Guido van Rossume5f8b601995-01-04 19:12:49 +00002607>>> 4 + spam*3
Guido van Rossum6938f061994-08-01 12:22:53 +00002608Traceback (innermost last):
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002609 File "<stdin>", line 1
Guido van Rossume5f8b601995-01-04 19:12:49 +00002610NameError: spam
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002611>>> '2' + 2
Guido van Rossum6938f061994-08-01 12:22:53 +00002612Traceback (innermost last):
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002613 File "<stdin>", line 1
Guido van Rossumb2c65561993-05-12 08:53:36 +00002614TypeError: illegal argument type for built-in operation
Fred Drake8842e861998-02-13 07:16:30 +00002615\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002616
Guido van Rossumb2c65561993-05-12 08:53:36 +00002617The last line of the error message indicates what happened.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002618Exceptions come in different types, and the type is printed as part of
2619the message: the types in the example are
Fred Drake8842e861998-02-13 07:16:30 +00002620\exception{ZeroDivisionError},
2621\exception{NameError}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002622and
Fred Drake8842e861998-02-13 07:16:30 +00002623\exception{TypeError}.
Guido van Rossumb2c65561993-05-12 08:53:36 +00002624The string printed as the exception type is the name of the built-in
2625name for the exception that occurred. This is true for all built-in
2626exceptions, but need not be true for user-defined exceptions (although
2627it is a useful convention).
2628Standard exception names are built-in identifiers (not reserved
2629keywords).
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002630
Guido van Rossumb2c65561993-05-12 08:53:36 +00002631The rest of the line is a detail whose interpretation depends on the
2632exception type; its meaning is dependent on the exception type.
2633
2634The preceding part of the error message shows the context where the
2635exception happened, in the form of a stack backtrace.
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002636In general it contains a stack backtrace listing source lines; however,
2637it will not display lines read from standard input.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002638
Fred Drake8842e861998-02-13 07:16:30 +00002639The Library Reference lists the built-in exceptions and their
2640meanings.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002641
Fred Drakeb7833d31998-09-11 16:21:55 +00002642\section{Handling Exceptions \label{handling}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002643
2644It is possible to write programs that handle selected exceptions.
2645Look at the following example, which prints a table of inverses of
2646some floating point numbers:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002647
Fred Drake8842e861998-02-13 07:16:30 +00002648\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002649>>> numbers = [0.3333, 2.5, 0, 10]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002650>>> for x in numbers:
2651... print x,
2652... try:
2653... print 1.0 / x
Guido van Rossumb2c65561993-05-12 08:53:36 +00002654... except ZeroDivisionError:
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002655... print '*** has no inverse ***'
Guido van Rossum02455691997-07-17 16:21:52 +00002656...
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000026570.3333 3.00030003
26582.5 0.4
26590 *** has no inverse ***
266010 0.1
Fred Drake8842e861998-02-13 07:16:30 +00002661\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002662
Fred Drake8842e861998-02-13 07:16:30 +00002663The \keyword{try} statement works as follows.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002664\begin{itemize}
2665\item
Fred Drake8842e861998-02-13 07:16:30 +00002666First, the \emph{try clause}
2667(the statement(s) between the \keyword{try} and \keyword{except}
2668keywords) is executed.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002669\item
2670If no exception occurs, the
Fred Drakeeee08cd1997-12-04 15:43:15 +00002671\emph{except\ clause}
Fred Drake8842e861998-02-13 07:16:30 +00002672is skipped and execution of the \keyword{try} statement is finished.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002673\item
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002674If an exception occurs during execution of the try clause,
Fred Drake8842e861998-02-13 07:16:30 +00002675the rest of the clause is skipped. Then if its type matches the
2676exception named after the \keyword{except} keyword, the rest of the
2677try clause is skipped, the except clause is executed, and then
2678execution continues after the \keyword{try} statement.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002679\item
2680If an exception occurs which does not match the exception named in the
Fred Drake8842e861998-02-13 07:16:30 +00002681except clause, it is passed on to outer \keyword{try} statements; if
2682no handler is found, it is an \emph{unhandled exception}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002683and execution stops with a message as shown above.
2684\end{itemize}
Fred Drake8842e861998-02-13 07:16:30 +00002685A \keyword{try} statement may have more than one except clause, to
2686specify handlers for different exceptions.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002687At most one handler will be executed.
2688Handlers only handle exceptions that occur in the corresponding try
Fred Drake8842e861998-02-13 07:16:30 +00002689clause, not in other handlers of the same \keyword{try} statement.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002690An except clause may name multiple exceptions as a parenthesized list,
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002691e.g.:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002692
Fred Drake8842e861998-02-13 07:16:30 +00002693\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002694... except (RuntimeError, TypeError, NameError):
2695... pass
Fred Drake8842e861998-02-13 07:16:30 +00002696\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002697
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002698The last except clause may omit the exception name(s), to serve as a
2699wildcard.
Guido van Rossumb2c65561993-05-12 08:53:36 +00002700Use this with extreme caution, since it is easy to mask a real
2701programming error in this way!
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002702
Fred Drake8842e861998-02-13 07:16:30 +00002703The \keyword{try} \ldots\ \keyword{except} statement has an optional
2704\emph{else clause}, which must follow all except clauses. It is
2705useful to place code that must be executed if the try clause does not
2706raise an exception. For example:
Guido van Rossum02455691997-07-17 16:21:52 +00002707
2708\begin{verbatim}
Guido van Rossuma4289a71998-07-07 20:18:06 +00002709for arg in sys.argv[1:]:
Fred Drake8842e861998-02-13 07:16:30 +00002710 try:
2711 f = open(arg, 'r')
2712 except IOError:
2713 print 'cannot open', arg
2714 else:
2715 print arg, 'has', len(f.readlines()), 'lines'
2716 f.close()
Guido van Rossum02455691997-07-17 16:21:52 +00002717\end{verbatim}
2718
2719
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002720When an exception occurs, it may have an associated value, also known as
Fred Drake8842e861998-02-13 07:16:30 +00002721the exceptions's \emph{argument}.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002722The presence and type of the argument depend on the exception type.
2723For exception types which have an argument, the except clause may
2724specify a variable after the exception name (or list) to receive the
2725argument's value, as follows:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002726
Fred Drake8842e861998-02-13 07:16:30 +00002727\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002728>>> try:
Guido van Rossume5f8b601995-01-04 19:12:49 +00002729... spam()
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002730... except NameError, x:
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002731... print 'name', x, 'undefined'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002732...
Guido van Rossume5f8b601995-01-04 19:12:49 +00002733name spam undefined
Fred Drake8842e861998-02-13 07:16:30 +00002734\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002735
Guido van Rossumb2c65561993-05-12 08:53:36 +00002736If an exception has an argument, it is printed as the last part
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002737(`detail') of the message for unhandled exceptions.
2738
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002739Exception handlers don't just handle exceptions if they occur
2740immediately in the try clause, but also if they occur inside functions
2741that are called (even indirectly) in the try clause.
2742For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002743
Fred Drake8842e861998-02-13 07:16:30 +00002744\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002745>>> def this_fails():
2746... x = 1/0
2747...
2748>>> try:
2749... this_fails()
Guido van Rossumb2c65561993-05-12 08:53:36 +00002750... except ZeroDivisionError, detail:
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002751... print 'Handling run-time error:', detail
2752...
Guido van Rossumb2c65561993-05-12 08:53:36 +00002753Handling run-time error: integer division or modulo
Fred Drake8842e861998-02-13 07:16:30 +00002754\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002755
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002756
Fred Drakeb7833d31998-09-11 16:21:55 +00002757\section{Raising Exceptions \label{raising}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002758
Fred Drake8842e861998-02-13 07:16:30 +00002759The \keyword{raise} statement allows the programmer to force a
2760specified exception to occur.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002761For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002762
Fred Drake8842e861998-02-13 07:16:30 +00002763\begin{verbatim}
Guido van Rossumb2c65561993-05-12 08:53:36 +00002764>>> raise NameError, 'HiThere'
Guido van Rossum6938f061994-08-01 12:22:53 +00002765Traceback (innermost last):
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002766 File "<stdin>", line 1
Guido van Rossumb2c65561993-05-12 08:53:36 +00002767NameError: HiThere
Fred Drake8842e861998-02-13 07:16:30 +00002768\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002769
Fred Drake8842e861998-02-13 07:16:30 +00002770The first argument to \keyword{raise} names the exception to be
2771raised. The optional second argument specifies the exception's
2772argument.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002773
Guido van Rossum02455691997-07-17 16:21:52 +00002774
Fred Drakeb7833d31998-09-11 16:21:55 +00002775\section{User-defined Exceptions \label{userExceptions}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002776
2777Programs may name their own exceptions by assigning a string to a
2778variable.
2779For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002780
Fred Drake8842e861998-02-13 07:16:30 +00002781\begin{verbatim}
Guido van Rossumb2c65561993-05-12 08:53:36 +00002782>>> my_exc = 'my_exc'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002783>>> try:
2784... raise my_exc, 2*2
2785... except my_exc, val:
Guido van Rossum67fa1601991-04-23 14:14:57 +00002786... print 'My exception occurred, value:', val
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002787...
Guido van Rossum6938f061994-08-01 12:22:53 +00002788My exception occurred, value: 4
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002789>>> raise my_exc, 1
Guido van Rossum6938f061994-08-01 12:22:53 +00002790Traceback (innermost last):
2791 File "<stdin>", line 1
Guido van Rossumb2c65561993-05-12 08:53:36 +00002792my_exc: 1
Fred Drake8842e861998-02-13 07:16:30 +00002793\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002794
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002795Many standard modules use this to report errors that may occur in
2796functions they define.
2797
Guido van Rossum02455691997-07-17 16:21:52 +00002798
Fred Drakeb7833d31998-09-11 16:21:55 +00002799\section{Defining Clean-up Actions \label{cleanup}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002800
Fred Drake8842e861998-02-13 07:16:30 +00002801The \keyword{try} statement has another optional clause which is
2802intended to define clean-up actions that must be executed under all
2803circumstances. For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002804
Fred Drake8842e861998-02-13 07:16:30 +00002805\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002806>>> try:
2807... raise KeyboardInterrupt
2808... finally:
2809... print 'Goodbye, world!'
2810...
2811Goodbye, world!
Guido van Rossum6938f061994-08-01 12:22:53 +00002812Traceback (innermost last):
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002813 File "<stdin>", line 2
Guido van Rossumb2c65561993-05-12 08:53:36 +00002814KeyboardInterrupt
Fred Drake8842e861998-02-13 07:16:30 +00002815\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002816
Fred Drake8842e861998-02-13 07:16:30 +00002817A \emph{finally clause} is executed whether or not an exception has
2818occurred in the try clause. When an exception has occurred, it is
2819re-raised after the finally clause is executed. The finally clause is
2820also executed ``on the way out'' when the \keyword{try} statement is
2821left via a \keyword{break} or \keyword{return} statement.
Guido van Rossumda8c3fd1992-08-09 13:55:25 +00002822
Fred Drake8842e861998-02-13 07:16:30 +00002823A \keyword{try} statement must either have one or more except clauses
2824or one finally clause, but not both.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002825
Fred Drakeb7833d31998-09-11 16:21:55 +00002826\chapter{Classes \label{classes}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002827
2828Python's class mechanism adds classes to the language with a minimum
2829of new syntax and semantics. It is a mixture of the class mechanisms
Guido van Rossum16d6e711994-08-08 12:30:22 +00002830found in \Cpp{} and Modula-3. As is true for modules, classes in Python
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002831do not put an absolute barrier between definition and user, but rather
2832rely on the politeness of the user not to ``break into the
2833definition.'' The most important features of classes are retained
2834with full power, however: the class inheritance mechanism allows
2835multiple base classes, a derived class can override any methods of its
Fred Drake391564f1998-04-01 23:11:56 +00002836base class or classes, a method can call the method of a base class with the
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002837same name. Objects can contain an arbitrary amount of private data.
2838
Guido van Rossum16d6e711994-08-08 12:30:22 +00002839In \Cpp{} terminology, all class members (including the data members) are
Fred Drakeeee08cd1997-12-04 15:43:15 +00002840\emph{public}, and all member functions are \emph{virtual}. There are
Guido van Rossum6938f061994-08-01 12:22:53 +00002841no special constructors or destructors. As in Modula-3, there are no
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002842shorthands for referencing the object's members from its methods: the
2843method function is declared with an explicit first argument
2844representing the object, which is provided implicitly by the call. As
2845in Smalltalk, classes themselves are objects, albeit in the wider
2846sense of the word: in Python, all data types are objects. This
Guido van Rossum16d6e711994-08-08 12:30:22 +00002847provides semantics for importing and renaming. But, just like in \Cpp{}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002848or Modula-3, built-in types cannot be used as base classes for
Guido van Rossum16d6e711994-08-08 12:30:22 +00002849extension by the user. Also, like in \Cpp{} but unlike in Modula-3, most
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002850built-in operators with special syntax (arithmetic operators,
Fred Drake391564f1998-04-01 23:11:56 +00002851subscripting etc.) can be redefined for class instances.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002852
Fred Drakeb7833d31998-09-11 16:21:55 +00002853\section{A Word About Terminology \label{terminology}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002854
Fred Drake391564f1998-04-01 23:11:56 +00002855Lacking universally accepted terminology to talk about classes, I will
2856make occasional use of Smalltalk and \Cpp{} terms. (I would use Modula-3
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002857terms, since its object-oriented semantics are closer to those of
Fred Drake8842e861998-02-13 07:16:30 +00002858Python than \Cpp{}, but I expect that few readers have heard of it.)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002859
2860I also have to warn you that there's a terminological pitfall for
2861object-oriented readers: the word ``object'' in Python does not
Fred Drake8842e861998-02-13 07:16:30 +00002862necessarily mean a class instance. Like \Cpp{} and Modula-3, and
2863unlike Smalltalk, not all types in Python are classes: the basic
Fred Drake391564f1998-04-01 23:11:56 +00002864built-in types like integers and lists are not, and even somewhat more
Fred Drake8842e861998-02-13 07:16:30 +00002865exotic types like files aren't. However, \emph{all} Python types
2866share a little bit of common semantics that is best described by using
2867the word object.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002868
2869Objects have individuality, and multiple names (in multiple scopes)
2870can be bound to the same object. This is known as aliasing in other
2871languages. This is usually not appreciated on a first glance at
2872Python, and can be safely ignored when dealing with immutable basic
2873types (numbers, strings, tuples). However, aliasing has an
Guido van Rossum6938f061994-08-01 12:22:53 +00002874(intended!) effect on the semantics of Python code involving mutable
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002875objects such as lists, dictionaries, and most types representing
2876entities outside the program (files, windows, etc.). This is usually
2877used to the benefit of the program, since aliases behave like pointers
2878in some respects. For example, passing an object is cheap since only
2879a pointer is passed by the implementation; and if a function modifies
2880an object passed as an argument, the caller will see the change --- this
2881obviates the need for two different argument passing mechanisms as in
2882Pascal.
2883
2884
Fred Drakeb7833d31998-09-11 16:21:55 +00002885\section{Python Scopes and Name Spaces \label{scopes}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002886
2887Before introducing classes, I first have to tell you something about
2888Python's scope rules. Class definitions play some neat tricks with
2889name spaces, and you need to know how scopes and name spaces work to
2890fully understand what's going on. Incidentally, knowledge about this
2891subject is useful for any advanced Python programmer.
2892
2893Let's begin with some definitions.
2894
Fred Drakeeee08cd1997-12-04 15:43:15 +00002895A \emph{name space} is a mapping from names to objects. Most name
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002896spaces are currently implemented as Python dictionaries, but that's
2897normally not noticeable in any way (except for performance), and it
2898may change in the future. Examples of name spaces are: the set of
Fred Drake8842e861998-02-13 07:16:30 +00002899built-in names (functions such as \function{abs()}, and built-in exception
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002900names); the global names in a module; and the local names in a
2901function invocation. In a sense the set of attributes of an object
Guido van Rossum16cd7f91994-10-06 10:29:26 +00002902also form a name space. The important thing to know about name
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002903spaces is that there is absolutely no relation between names in
2904different name spaces; for instance, two different modules may both
2905define a function ``maximize'' without confusion --- users of the
2906modules must prefix it with the module name.
2907
Fred Drakeeee08cd1997-12-04 15:43:15 +00002908By the way, I use the word \emph{attribute} for any name following a
Fred Drake8842e861998-02-13 07:16:30 +00002909dot --- for example, in the expression \code{z.real}, \code{real} is
2910an attribute of the object \code{z}. Strictly speaking, references to
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002911names in modules are attribute references: in the expression
Fred Drake8842e861998-02-13 07:16:30 +00002912\code{modname.funcname}, \code{modname} is a module object and
2913\code{funcname} is an attribute of it. In this case there happens to
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002914be a straightforward mapping between the module's attributes and the
2915global names defined in the module: they share the same name space!%
2916\footnote{
Guido van Rossum6938f061994-08-01 12:22:53 +00002917 Except for one thing. Module objects have a secret read-only
Fred Drakeeee08cd1997-12-04 15:43:15 +00002918 attribute called \code{__dict__} which returns the dictionary
Guido van Rossum6938f061994-08-01 12:22:53 +00002919 used to implement the module's name space; the name
Fred Drakeeee08cd1997-12-04 15:43:15 +00002920 \code{__dict__} is an attribute but not a global name.
Guido van Rossum6938f061994-08-01 12:22:53 +00002921 Obviously, using this violates the abstraction of name space
2922 implementation, and should be restricted to things like
Fred Drake8842e861998-02-13 07:16:30 +00002923 post-mortem debuggers.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002924}
2925
2926Attributes may be read-only or writable. In the latter case,
2927assignment to attributes is possible. Module attributes are writable:
Fred Drake8842e861998-02-13 07:16:30 +00002928you can write \samp{modname.the_answer = 42}. Writable attributes may
Fred Drake391564f1998-04-01 23:11:56 +00002929also be deleted with the \keyword{del} statement, e.g.
Fred Drake8842e861998-02-13 07:16:30 +00002930\samp{del modname.the_answer}.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002931
2932Name spaces are created at different moments and have different
2933lifetimes. The name space containing the built-in names is created
2934when the Python interpreter starts up, and is never deleted. The
2935global name space for a module is created when the module definition
2936is read in; normally, module name spaces also last until the
2937interpreter quits. The statements executed by the top-level
2938invocation of the interpreter, either read from a script file or
Fred Drake8842e861998-02-13 07:16:30 +00002939interactively, are considered part of a module called
2940\module{__main__}, so they have their own global name space. (The
2941built-in names actually also live in a module; this is called
2942\module{__builtin__}.)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002943
2944The local name space for a function is created when the function is
2945called, and deleted when the function returns or raises an exception
2946that is not handled within the function. (Actually, forgetting would
2947be a better way to describe what actually happens.) Of course,
2948recursive invocations each have their own local name space.
2949
Fred Drakeeee08cd1997-12-04 15:43:15 +00002950A \emph{scope} is a textual region of a Python program where a name space
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002951is directly accessible. ``Directly accessible'' here means that an
2952unqualified reference to a name attempts to find the name in the name
2953space.
2954
2955Although scopes are determined statically, they are used dynamically.
2956At any time during execution, exactly three nested scopes are in use
2957(i.e., exactly three name spaces are directly accessible): the
2958innermost scope, which is searched first, contains the local names,
2959the middle scope, searched next, contains the current module's global
2960names, and the outermost scope (searched last) is the name space
2961containing built-in names.
2962
2963Usually, the local scope references the local names of the (textually)
Guido van Rossum96628a91995-04-10 11:34:00 +00002964current function. Outside of functions, the local scope references
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002965the same name space as the global scope: the module's name space.
2966Class definitions place yet another name space in the local scope.
2967
2968It is important to realize that scopes are determined textually: the
2969global scope of a function defined in a module is that module's name
2970space, no matter from where or by what alias the function is called.
2971On the other hand, the actual search for names is done dynamically, at
Guido van Rossum96628a91995-04-10 11:34:00 +00002972run time --- however, the language definition is evolving towards
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002973static name resolution, at ``compile'' time, so don't rely on dynamic
2974name resolution! (In fact, local variables are already determined
2975statically.)
2976
2977A special quirk of Python is that assignments always go into the
2978innermost scope. Assignments do not copy data --- they just
2979bind names to objects. The same is true for deletions: the statement
Fred Drake391564f1998-04-01 23:11:56 +00002980\samp{del x} removes the binding of \code{x} from the name space
2981referenced by the local scope. In fact, all operations that introduce
2982new names use the local scope: in particular, import statements and
2983function definitions bind the module or function name in the local
2984scope. (The \keyword{global} statement can be used to indicate that
2985particular variables live in the global scope.)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002986
2987
Fred Drakeb7833d31998-09-11 16:21:55 +00002988\section{A First Look at Classes \label{firstClasses}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002989
2990Classes introduce a little bit of new syntax, three new object types,
2991and some new semantics.
2992
2993
Fred Drakeb7833d31998-09-11 16:21:55 +00002994\subsection{Class Definition Syntax \label{classDefinition}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002995
2996The simplest form of class definition looks like this:
2997
2998\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00002999class ClassName:
3000 <statement-1>
3001 .
3002 .
3003 .
3004 <statement-N>
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003005\end{verbatim}
3006
Fred Drake8842e861998-02-13 07:16:30 +00003007Class definitions, like function definitions (\keyword{def}
3008statements) must be executed before they have any effect. (You could
3009conceivably place a class definition in a branch of an \keyword{if}
3010statement, or inside a function.)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003011
3012In practice, the statements inside a class definition will usually be
3013function definitions, but other statements are allowed, and sometimes
3014useful --- we'll come back to this later. The function definitions
3015inside a class normally have a peculiar form of argument list,
3016dictated by the calling conventions for methods --- again, this is
3017explained later.
3018
3019When a class definition is entered, a new name space is created, and
3020used as the local scope --- thus, all assignments to local variables
3021go into this new name space. In particular, function definitions bind
3022the name of the new function here.
3023
Fred Drakeeee08cd1997-12-04 15:43:15 +00003024When a class definition is left normally (via the end), a \emph{class
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003025object} is created. This is basically a wrapper around the contents
3026of the name space created by the class definition; we'll learn more
3027about class objects in the next section. The original local scope
3028(the one in effect just before the class definitions was entered) is
Fred Drakea594baf1998-04-03 05:16:31 +00003029reinstated, and the class object is bound here to the class name given
3030in the class definition header (\class{ClassName} in the example).
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003031
3032
Fred Drakeb7833d31998-09-11 16:21:55 +00003033\subsection{Class Objects \label{classObjects}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003034
3035Class objects support two kinds of operations: attribute references
3036and instantiation.
3037
Fred Drakeeee08cd1997-12-04 15:43:15 +00003038\emph{Attribute references} use the standard syntax used for all
Fred Drake8842e861998-02-13 07:16:30 +00003039attribute references in Python: \code{obj.name}. Valid attribute
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003040names are all the names that were in the class's name space when the
3041class object was created. So, if the class definition looked like
3042this:
3043
3044\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003045class MyClass:
3046 "A simple example class"
3047 i = 12345
3048 def f(x):
3049 return 'hello world'
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003050\end{verbatim}
3051
Fred Drake8842e861998-02-13 07:16:30 +00003052then \code{MyClass.i} and \code{MyClass.f} are valid attribute
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003053references, returning an integer and a function object, respectively.
Guido van Rossum02455691997-07-17 16:21:52 +00003054Class attributes can also be assigned to, so you can change the value
Fred Drake8842e861998-02-13 07:16:30 +00003055of \code{MyClass.i} by assignment. \code{__doc__} is also a valid
Guido van Rossum02455691997-07-17 16:21:52 +00003056attribute that's read-only, returning the docstring belonging to
Fred Drake8842e861998-02-13 07:16:30 +00003057the class: \code{"A simple example class"}).
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003058
Fred Drakeeee08cd1997-12-04 15:43:15 +00003059Class \emph{instantiation} uses function notation. Just pretend that
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003060the class object is a parameterless function that returns a new
3061instance of the class. For example, (assuming the above class):
3062
3063\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003064x = MyClass()
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003065\end{verbatim}
3066
Fred Drakeeee08cd1997-12-04 15:43:15 +00003067creates a new \emph{instance} of the class and assigns this object to
3068the local variable \code{x}.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003069
3070
Fred Drakeb7833d31998-09-11 16:21:55 +00003071\subsection{Instance Objects \label{instanceObjects}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003072
3073Now what can we do with instance objects? The only operations
3074understood by instance objects are attribute references. There are
3075two kinds of valid attribute names.
3076
Fred Drakeeee08cd1997-12-04 15:43:15 +00003077The first I'll call \emph{data attributes}. These correspond to
Fred Drake8842e861998-02-13 07:16:30 +00003078``instance variables'' in Smalltalk, and to ``data members'' in
3079\Cpp{}. Data attributes need not be declared; like local variables,
3080they spring into existence when they are first assigned to. For
3081example, if \code{x} is the instance of \class{MyClass} created above,
3082the following piece of code will print the value \code{16}, without
3083leaving a trace:
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003084
3085\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003086x.counter = 1
3087while x.counter < 10:
3088 x.counter = x.counter * 2
3089print x.counter
3090del x.counter
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003091\end{verbatim}
3092
3093The second kind of attribute references understood by instance objects
Fred Drakeeee08cd1997-12-04 15:43:15 +00003094are \emph{methods}. A method is a function that ``belongs to'' an
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003095object. (In Python, the term method is not unique to class instances:
3096other object types can have methods as well, e.g., list objects have
3097methods called append, insert, remove, sort, and so on. However,
3098below, we'll use the term method exclusively to mean methods of class
3099instance objects, unless explicitly stated otherwise.)
3100
3101Valid method names of an instance object depend on its class. By
Fred Drake8842e861998-02-13 07:16:30 +00003102definition, all attributes of a class that are (user-defined) function
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003103objects define corresponding methods of its instances. So in our
Fred Drakeeee08cd1997-12-04 15:43:15 +00003104example, \code{x.f} is a valid method reference, since
3105\code{MyClass.f} is a function, but \code{x.i} is not, since
Fred Drake8842e861998-02-13 07:16:30 +00003106\code{MyClass.i} is not. But \code{x.f} is not the same thing as
3107\code{MyClass.f} --- it is a \emph{method object}, not a function
Fred Drakea594baf1998-04-03 05:16:31 +00003108object.%
3109\obindex{method}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003110
3111
Fred Drakeb7833d31998-09-11 16:21:55 +00003112\subsection{Method Objects \label{methodObjects}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003113
3114Usually, a method is called immediately, e.g.:
3115
3116\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003117x.f()
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003118\end{verbatim}
3119
Fred Drake8842e861998-02-13 07:16:30 +00003120In our example, this will return the string \code{'hello world'}.
3121However, it is not necessary to call a method right away: \code{x.f}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003122is a method object, and can be stored away and called at a later
3123moment, for example:
3124
3125\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003126xf = x.f
3127while 1:
3128 print xf()
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003129\end{verbatim}
3130
Fred Drake8842e861998-02-13 07:16:30 +00003131will continue to print \samp{hello world} until the end of time.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003132
3133What exactly happens when a method is called? You may have noticed
Fred Drake8842e861998-02-13 07:16:30 +00003134that \code{x.f()} was called without an argument above, even though
3135the function definition for \method{f} specified an argument. What
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003136happened to the argument? Surely Python raises an exception when a
3137function that requires an argument is called without any --- even if
3138the argument isn't actually used...
3139
3140Actually, you may have guessed the answer: the special thing about
3141methods is that the object is passed as the first argument of the
Fred Drake8842e861998-02-13 07:16:30 +00003142function. In our example, the call \code{x.f()} is exactly equivalent
3143to \code{MyClass.f(x)}. In general, calling a method with a list of
Fred Drakeeee08cd1997-12-04 15:43:15 +00003144\var{n} arguments is equivalent to calling the corresponding function
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003145with an argument list that is created by inserting the method's object
3146before the first argument.
3147
3148If you still don't understand how methods work, a look at the
3149implementation can perhaps clarify matters. When an instance
3150attribute is referenced that isn't a data attribute, its class is
3151searched. If the name denotes a valid class attribute that is a
3152function object, a method object is created by packing (pointers to)
3153the instance object and the function object just found together in an
3154abstract object: this is the method object. When the method object is
3155called with an argument list, it is unpacked again, a new argument
3156list is constructed from the instance object and the original argument
3157list, and the function object is called with this new argument list.
3158
3159
Fred Drakeb7833d31998-09-11 16:21:55 +00003160\section{Random Remarks \label{remarks}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003161
3162[These should perhaps be placed more carefully...]
3163
3164
3165Data attributes override method attributes with the same name; to
3166avoid accidental name conflicts, which may cause hard-to-find bugs in
3167large programs, it is wise to use some kind of convention that
3168minimizes the chance of conflicts, e.g., capitalize method names,
3169prefix data attribute names with a small unique string (perhaps just
Guido van Rossum6938f061994-08-01 12:22:53 +00003170an underscore), or use verbs for methods and nouns for data attributes.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003171
3172
3173Data attributes may be referenced by methods as well as by ordinary
3174users (``clients'') of an object. In other words, classes are not
3175usable to implement pure abstract data types. In fact, nothing in
3176Python makes it possible to enforce data hiding --- it is all based
3177upon convention. (On the other hand, the Python implementation,
Fred Drake3f205921998-01-13 18:56:38 +00003178written in \C{}, can completely hide implementation details and control
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003179access to an object if necessary; this can be used by extensions to
Fred Drake3f205921998-01-13 18:56:38 +00003180Python written in \C{}.)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003181
3182
3183Clients should use data attributes with care --- clients may mess up
3184invariants maintained by the methods by stamping on their data
3185attributes. Note that clients may add data attributes of their own to
3186an instance object without affecting the validity of the methods, as
3187long as name conflicts are avoided --- again, a naming convention can
3188save a lot of headaches here.
3189
3190
3191There is no shorthand for referencing data attributes (or other
3192methods!) from within methods. I find that this actually increases
3193the readability of methods: there is no chance of confusing local
3194variables and instance variables when glancing through a method.
3195
3196
3197Conventionally, the first argument of methods is often called
Fred Drake8842e861998-02-13 07:16:30 +00003198\code{self}. This is nothing more than a convention: the name
3199\code{self} has absolutely no special meaning to Python. (Note,
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003200however, that by not following the convention your code may be less
3201readable by other Python programmers, and it is also conceivable that
Fred Drakeeee08cd1997-12-04 15:43:15 +00003202a \emph{class browser} program be written which relies upon such a
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003203convention.)
3204
3205
3206Any function object that is a class attribute defines a method for
3207instances of that class. It is not necessary that the function
3208definition is textually enclosed in the class definition: assigning a
3209function object to a local variable in the class is also ok. For
3210example:
3211
3212\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003213# Function defined outside the class
3214def f1(self, x, y):
3215 return min(x, x+y)
3216
3217class C:
3218 f = f1
3219 def g(self):
3220 return 'hello world'
3221 h = g
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003222\end{verbatim}
3223
Fred Drake8842e861998-02-13 07:16:30 +00003224Now \code{f}, \code{g} and \code{h} are all attributes of class
3225\class{C} that refer to function objects, and consequently they are all
3226methods of instances of \class{C} --- \code{h} being exactly equivalent
3227to \code{g}. Note that this practice usually only serves to confuse
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003228the reader of a program.
3229
3230
3231Methods may call other methods by using method attributes of the
Fred Drake8842e861998-02-13 07:16:30 +00003232\code{self} argument, e.g.:
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003233
3234\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003235class Bag:
3236 def empty(self):
3237 self.data = []
3238 def add(self, x):
3239 self.data.append(x)
3240 def addtwice(self, x):
3241 self.add(x)
3242 self.add(x)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003243\end{verbatim}
3244
3245
3246The instantiation operation (``calling'' a class object) creates an
3247empty object. Many classes like to create objects in a known initial
Guido van Rossumca3f6c81994-10-06 14:08:53 +00003248state. Therefore a class may define a special method named
Fred Drake8842e861998-02-13 07:16:30 +00003249\method{__init__()}, like this:
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003250
Guido van Rossum6938f061994-08-01 12:22:53 +00003251\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003252 def __init__(self):
3253 self.empty()
Guido van Rossum6938f061994-08-01 12:22:53 +00003254\end{verbatim}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003255
Fred Drake8842e861998-02-13 07:16:30 +00003256When a class defines an \method{__init__()} method, class
3257instantiation automatically invokes \method{__init__()} for the
3258newly-created class instance. So in the \class{Bag} example, a new
3259and initialized instance can be obtained by:
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003260
Guido van Rossum6938f061994-08-01 12:22:53 +00003261\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003262x = Bag()
Guido van Rossum6938f061994-08-01 12:22:53 +00003263\end{verbatim}
3264
Fred Drake8842e861998-02-13 07:16:30 +00003265Of course, the \method{__init__()} method may have arguments for
3266greater flexibility. In that case, arguments given to the class
3267instantiation operator are passed on to \method{__init__()}. For
3268example,
Guido van Rossum6938f061994-08-01 12:22:53 +00003269
Fred Drake8842e861998-02-13 07:16:30 +00003270\begin{verbatim}
Guido van Rossum6938f061994-08-01 12:22:53 +00003271>>> class Complex:
3272... def __init__(self, realpart, imagpart):
3273... self.r = realpart
3274... self.i = imagpart
3275...
3276>>> x = Complex(3.0,-4.5)
3277>>> x.r, x.i
3278(3.0, -4.5)
Fred Drake8842e861998-02-13 07:16:30 +00003279\end{verbatim}
3280
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003281Methods may reference global names in the same way as ordinary
3282functions. The global scope associated with a method is the module
3283containing the class definition. (The class itself is never used as a
3284global scope!) While one rarely encounters a good reason for using
3285global data in a method, there are many legitimate uses of the global
3286scope: for one thing, functions and modules imported into the global
3287scope can be used by methods, as well as functions and classes defined
3288in it. Usually, the class containing the method is itself defined in
3289this global scope, and in the next section we'll find some good
3290reasons why a method would want to reference its own class!
3291
3292
Fred Drakeb7833d31998-09-11 16:21:55 +00003293\section{Inheritance \label{inheritance}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003294
3295Of course, a language feature would not be worthy of the name ``class''
3296without supporting inheritance. The syntax for a derived class
3297definition looks as follows:
3298
3299\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003300class DerivedClassName(BaseClassName):
3301 <statement-1>
3302 .
3303 .
3304 .
3305 <statement-N>
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003306\end{verbatim}
3307
Fred Drake8842e861998-02-13 07:16:30 +00003308The name \class{BaseClassName} must be defined in a scope containing
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003309the derived class definition. Instead of a base class name, an
3310expression is also allowed. This is useful when the base class is
3311defined in another module, e.g.,
3312
3313\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003314class DerivedClassName(modname.BaseClassName):
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003315\end{verbatim}
3316
3317Execution of a derived class definition proceeds the same as for a
3318base class. When the class object is constructed, the base class is
3319remembered. This is used for resolving attribute references: if a
3320requested attribute is not found in the class, it is searched in the
3321base class. This rule is applied recursively if the base class itself
3322is derived from some other class.
3323
3324There's nothing special about instantiation of derived classes:
Fred Drake8842e861998-02-13 07:16:30 +00003325\code{DerivedClassName()} creates a new instance of the class. Method
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003326references are resolved as follows: the corresponding class attribute
3327is searched, descending down the chain of base classes if necessary,
3328and the method reference is valid if this yields a function object.
3329
3330Derived classes may override methods of their base classes. Because
3331methods have no special privileges when calling other methods of the
3332same object, a method of a base class that calls another method
3333defined in the same base class, may in fact end up calling a method of
Guido van Rossum16d6e711994-08-08 12:30:22 +00003334a derived class that overrides it. (For \Cpp{} programmers: all methods
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003335in Python are ``virtual functions''.)
3336
3337An overriding method in a derived class may in fact want to extend
3338rather than simply replace the base class method of the same name.
3339There is a simple way to call the base class method directly: just
Fred Drake8842e861998-02-13 07:16:30 +00003340call \samp{BaseClassName.methodname(self, arguments)}. This is
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003341occasionally useful to clients as well. (Note that this only works if
3342the base class is defined or imported directly in the global scope.)
3343
3344
Fred Drakeb7833d31998-09-11 16:21:55 +00003345\subsection{Multiple Inheritance \label{multiple}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003346
Guido van Rossum6938f061994-08-01 12:22:53 +00003347Python supports a limited form of multiple inheritance as well. A
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003348class definition with multiple base classes looks as follows:
3349
3350\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003351class DerivedClassName(Base1, Base2, Base3):
3352 <statement-1>
3353 .
3354 .
3355 .
3356 <statement-N>
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003357\end{verbatim}
3358
3359The only rule necessary to explain the semantics is the resolution
3360rule used for class attribute references. This is depth-first,
3361left-to-right. Thus, if an attribute is not found in
Fred Drake8842e861998-02-13 07:16:30 +00003362\class{DerivedClassName}, it is searched in \class{Base1}, then
3363(recursively) in the base classes of \class{Base1}, and only if it is
3364not found there, it is searched in \class{Base2}, and so on.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003365
Fred Drake8842e861998-02-13 07:16:30 +00003366(To some people breadth first --- searching \class{Base2} and
3367\class{Base3} before the base classes of \class{Base1} --- looks more
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003368natural. However, this would require you to know whether a particular
Fred Drake8842e861998-02-13 07:16:30 +00003369attribute of \class{Base1} is actually defined in \class{Base1} or in
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003370one of its base classes before you can figure out the consequences of
Fred Drake8842e861998-02-13 07:16:30 +00003371a name conflict with an attribute of \class{Base2}. The depth-first
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003372rule makes no differences between direct and inherited attributes of
Fred Drake8842e861998-02-13 07:16:30 +00003373\class{Base1}.)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003374
3375It is clear that indiscriminate use of multiple inheritance is a
3376maintenance nightmare, given the reliance in Python on conventions to
3377avoid accidental name conflicts. A well-known problem with multiple
3378inheritance is a class derived from two classes that happen to have a
3379common base class. While it is easy enough to figure out what happens
3380in this case (the instance will have a single copy of ``instance
3381variables'' or data attributes used by the common base class), it is
3382not clear that these semantics are in any way useful.
3383
3384
Fred Drakeb7833d31998-09-11 16:21:55 +00003385\section{Private Variables \label{private}}
Guido van Rossum02455691997-07-17 16:21:52 +00003386
Fred Drakea594baf1998-04-03 05:16:31 +00003387There is limited support for class-private
Guido van Rossum02455691997-07-17 16:21:52 +00003388identifiers. Any identifier of the form \code{__spam} (at least two
3389leading underscores, at most one trailing underscore) is now textually
3390replaced with \code{_classname__spam}, where \code{classname} is the
3391current class name with leading underscore(s) stripped. This mangling
3392is done without regard of the syntactic position of the identifier, so
3393it can be used to define class-private instance and class variables,
3394methods, as well as globals, and even to store instance variables
Fred Drakeeee08cd1997-12-04 15:43:15 +00003395private to this class on instances of \emph{other} classes. Truncation
Guido van Rossum02455691997-07-17 16:21:52 +00003396may occur when the mangled name would be longer than 255 characters.
3397Outside classes, or when the class name consists of only underscores,
3398no mangling occurs.
3399
3400Name mangling is intended to give classes an easy way to define
3401``private'' instance variables and methods, without having to worry
3402about instance variables defined by derived classes, or mucking with
3403instance variables by code outside the class. Note that the mangling
3404rules are designed mostly to avoid accidents; it still is possible for
3405a determined soul to access or modify a variable that is considered
3406private. This can even be useful, e.g. for the debugger, and that's
3407one reason why this loophole is not closed. (Buglet: derivation of a
3408class with the same name as the base class makes use of private
3409variables of the base class possible.)
3410
3411Notice that code passed to \code{exec}, \code{eval()} or
3412\code{evalfile()} does not consider the classname of the invoking
3413class to be the current class; this is similar to the effect of the
3414\code{global} statement, the effect of which is likewise restricted to
3415code that is byte-compiled together. The same restriction applies to
3416\code{getattr()}, \code{setattr()} and \code{delattr()}, as well as
3417when referencing \code{__dict__} directly.
3418
3419Here's an example of a class that implements its own
3420\code{__getattr__} and \code{__setattr__} methods and stores all
3421attributes in a private variable, in a way that works in Python 1.4 as
3422well as in previous versions:
3423
3424\begin{verbatim}
3425class VirtualAttributes:
3426 __vdict = None
3427 __vdict_name = locals().keys()[0]
3428
3429 def __init__(self):
3430 self.__dict__[self.__vdict_name] = {}
3431
3432 def __getattr__(self, name):
3433 return self.__vdict[name]
3434
3435 def __setattr__(self, name, value):
3436 self.__vdict[name] = value
3437\end{verbatim}
3438
Fred Drakeaf8a0151998-01-14 14:51:31 +00003439%\emph{Warning: this is an experimental feature.} To avoid all
Guido van Rossum02455691997-07-17 16:21:52 +00003440%potential problems, refrain from using identifiers starting with
3441%double underscore except for predefined uses like \code{__init__}. To
3442%use private names while maintaining future compatibility: refrain from
3443%using the same private name in classes related via subclassing; avoid
3444%explicit (manual) mangling/unmangling; and assume that at some point
3445%in the future, leading double underscore will revert to being just a
3446%naming convention. Discussion on extensive compile-time declarations
3447%are currently underway, and it is impossible to predict what solution
3448%will eventually be chosen for private names. Double leading
3449%underscore is still a candidate, of course --- just not the only one.
3450%It is placed in the distribution in the belief that it is useful, and
3451%so that widespread experience with its use can be gained. It will not
3452%be removed without providing a better solution and a migration path.
3453
Fred Drakeb7833d31998-09-11 16:21:55 +00003454\section{Odds and Ends \label{odds}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003455
3456Sometimes it is useful to have a data type similar to the Pascal
Fred Drake3f205921998-01-13 18:56:38 +00003457``record'' or \C{} ``struct'', bundling together a couple of named data
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003458items. An empty class definition will do nicely, e.g.:
3459
3460\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003461class Employee:
3462 pass
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003463
Fred Drake8842e861998-02-13 07:16:30 +00003464john = Employee() # Create an empty employee record
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003465
Fred Drake8842e861998-02-13 07:16:30 +00003466# Fill the fields of the record
3467john.name = 'John Doe'
3468john.dept = 'computer lab'
3469john.salary = 1000
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003470\end{verbatim}
3471
3472
3473A piece of Python code that expects a particular abstract data type
3474can often be passed a class that emulates the methods of that data
3475type instead. For instance, if you have a function that formats some
3476data from a file object, you can define a class with methods
Fred Drake8842e861998-02-13 07:16:30 +00003477\method{read()} and \method{readline()} that gets the data from a string
Fred Drake391564f1998-04-01 23:11:56 +00003478buffer instead, and pass it as an argument.% (Unfortunately, this
3479%technique has its limitations: a class can't define operations that
3480%are accessed by special syntax such as sequence subscripting or
3481%arithmetic operators, and assigning such a ``pseudo-file'' to
3482%\code{sys.stdin} will not cause the interpreter to read further input
3483%from it.)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003484
3485
Fred Drake8842e861998-02-13 07:16:30 +00003486Instance method objects have attributes, too: \code{m.im_self} is the
3487object of which the method is an instance, and \code{m.im_func} is the
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003488function object corresponding to the method.
3489
Fred Drakeb7833d31998-09-11 16:21:55 +00003490\subsection{Exceptions Can Be Classes \label{exceptionClasses}}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003491
3492User-defined exceptions are no longer limited to being string objects
3493--- they can be identified by classes as well. Using this mechanism it
3494is possible to create extensible hierarchies of exceptions.
3495
3496There are two new valid (semantic) forms for the raise statement:
3497
3498\begin{verbatim}
3499raise Class, instance
3500
3501raise instance
3502\end{verbatim}
3503
Fred Drake8842e861998-02-13 07:16:30 +00003504In the first form, \code{instance} must be an instance of \class{Class}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003505or of a class derived from it. The second form is a shorthand for
3506
3507\begin{verbatim}
3508raise instance.__class__, instance
3509\end{verbatim}
3510
3511An except clause may list classes as well as string objects. A class
3512in an except clause is compatible with an exception if it is the same
3513class or a base class thereof (but not the other way around --- an
3514except clause listing a derived class is not compatible with a base
3515class). For example, the following code will print B, C, D in that
3516order:
3517
3518\begin{verbatim}
3519class B:
3520 pass
3521class C(B):
3522 pass
3523class D(C):
3524 pass
3525
3526for c in [B, C, D]:
3527 try:
3528 raise c()
3529 except D:
3530 print "D"
3531 except C:
3532 print "C"
3533 except B:
3534 print "B"
3535\end{verbatim}
3536
Fred Drake8842e861998-02-13 07:16:30 +00003537Note that if the except clauses were reversed (with \samp{except B}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003538first), it would have printed B, B, B --- the first matching except
3539clause is triggered.
3540
3541When an error message is printed for an unhandled exception which is a
3542class, the class name is printed, then a colon and a space, and
3543finally the instance converted to a string using the built-in function
Fred Drake8842e861998-02-13 07:16:30 +00003544\function{str()}.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003545
Guido van Rossum194e57c1995-02-15 15:51:38 +00003546
Fred Drakeb7833d31998-09-11 16:21:55 +00003547\chapter{What Now? \label{whatNow}}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003548
Guido van Rossum02455691997-07-17 16:21:52 +00003549Hopefully reading this tutorial has reinforced your interest in using
3550Python. Now what should you do?
Guido van Rossum194e57c1995-02-15 15:51:38 +00003551
Guido van Rossum02455691997-07-17 16:21:52 +00003552You should read, or at least page through, the Library Reference,
3553which gives complete (though terse) reference material about types,
3554functions, and modules that can save you a lot of time when writing
3555Python programs. The standard Python distribution includes a
Fred Drake3f205921998-01-13 18:56:38 +00003556\emph{lot} of code in both \C{} and Python; there are modules to read
Fred Drake8842e861998-02-13 07:16:30 +00003557\UNIX{} mailboxes, retrieve documents via HTTP, generate random
3558numbers, parse command-line options, write CGI programs, compress
3559data, and a lot more; skimming through the Library Reference will give
3560you an idea of what's available.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003561
Fred Drakeca6567f1998-01-22 20:44:18 +00003562The major Python Web site is \url{http://www.python.org}; it contains
Guido van Rossum02455691997-07-17 16:21:52 +00003563code, documentation, and pointers to Python-related pages around the
Fred Drake391564f1998-04-01 23:11:56 +00003564Web. This web site is mirrored in various places around the
Guido van Rossum02455691997-07-17 16:21:52 +00003565world, such as Europe, Japan, and Australia; a mirror may be faster
3566than the main site, depending on your geographical location. A more
Fred Drakeca6567f1998-01-22 20:44:18 +00003567informal site is \url{http://starship.skyport.net}, which contains a
Guido van Rossum02455691997-07-17 16:21:52 +00003568bunch of Python-related personal home pages; many people have
3569downloadable software here.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003570
Guido van Rossum02455691997-07-17 16:21:52 +00003571For Python-related questions and problem reports, you can post to the
Fred Drake391564f1998-04-01 23:11:56 +00003572newsgroup \newsgroup{comp.lang.python}, or send them to the mailing
3573list at \email{python-list@cwi.nl}. The newsgroup and mailing list
3574are gatewayed, so messages posted to one will automatically be
3575forwarded to the other. There are around 35--45 postings a day,
3576% Postings figure based on average of last six months activity as
3577% reported by www.findmail.com; Oct. '97 - Mar. '98: 7480 msgs / 182
3578% days = 41.1 msgs / day.
3579asking (and answering) questions, suggesting new features, and
3580announcing new modules. Before posting, be sure to check the list of
3581Frequently Asked Questions (also called the FAQ), at
Fred Drakeca6567f1998-01-22 20:44:18 +00003582\url{http://www.python.org/doc/FAQ.html}, or look for it in the
3583\file{Misc/} directory of the Python source distribution. The FAQ
Guido van Rossum02455691997-07-17 16:21:52 +00003584answers many of the questions that come up again and again, and may
3585already contain the solution for your problem.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003586
Guido van Rossum02455691997-07-17 16:21:52 +00003587You can support the Python community by joining the Python Software
3588Activity, which runs the python.org web, ftp and email servers, and
Fred Drakeca6567f1998-01-22 20:44:18 +00003589organizes Python workshops. See \url{http://www.python.org/psa/} for
Guido van Rossum02455691997-07-17 16:21:52 +00003590information on how to join.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003591
Guido van Rossum194e57c1995-02-15 15:51:38 +00003592
Fred Drakea594baf1998-04-03 05:16:31 +00003593\appendix
Guido van Rossum194e57c1995-02-15 15:51:38 +00003594
Fred Drakeb7833d31998-09-11 16:21:55 +00003595\chapter{Interactive Input Editing and History Substitution
3596 \label{interacting}}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003597
Guido van Rossum02455691997-07-17 16:21:52 +00003598Some versions of the Python interpreter support editing of the current
3599input line and history substitution, similar to facilities found in
3600the Korn shell and the GNU Bash shell. This is implemented using the
Fred Drakeeee08cd1997-12-04 15:43:15 +00003601\emph{GNU Readline} library, which supports Emacs-style and vi-style
Guido van Rossum02455691997-07-17 16:21:52 +00003602editing. This library has its own documentation which I won't
3603duplicate here; however, the basics are easily explained.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003604
Fred Drakeb7833d31998-09-11 16:21:55 +00003605\section{Line Editing \label{lineEditing}}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003606
Guido van Rossum02455691997-07-17 16:21:52 +00003607If supported, input line editing is active whenever the interpreter
3608prints a primary or secondary prompt. The current line can be edited
3609using the conventional Emacs control characters. The most important
3610of these are: C-A (Control-A) moves the cursor to the beginning of the
3611line, C-E to the end, C-B moves it one position to the left, C-F to
3612the right. Backspace erases the character to the left of the cursor,
3613C-D the character to its right. C-K kills (erases) the rest of the
3614line to the right of the cursor, C-Y yanks back the last killed
3615string. C-underscore undoes the last change you made; it can be
3616repeated for cumulative effect.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003617
Fred Drakeb7833d31998-09-11 16:21:55 +00003618\section{History Substitution \label{history}}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003619
Guido van Rossum02455691997-07-17 16:21:52 +00003620History substitution works as follows. All non-empty input lines
3621issued are saved in a history buffer, and when a new prompt is given
3622you are positioned on a new line at the bottom of this buffer. C-P
3623moves one line up (back) in the history buffer, C-N moves one down.
3624Any line in the history buffer can be edited; an asterisk appears in
3625front of the prompt to mark a line as modified. Pressing the Return
3626key passes the current line to the interpreter. C-R starts an
3627incremental reverse search; C-S starts a forward search.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003628
Fred Drakeb7833d31998-09-11 16:21:55 +00003629\section{Key Bindings \label{keyBindings}}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003630
Guido van Rossum02455691997-07-17 16:21:52 +00003631The key bindings and some other parameters of the Readline library can
3632be customized by placing commands in an initialization file called
Fred Drakeeee08cd1997-12-04 15:43:15 +00003633\file{\$HOME/.inputrc}. Key bindings have the form
Guido van Rossum194e57c1995-02-15 15:51:38 +00003634
Fred Drake8842e861998-02-13 07:16:30 +00003635\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00003636key-name: function-name
Fred Drake8842e861998-02-13 07:16:30 +00003637\end{verbatim}
3638
Guido van Rossum02455691997-07-17 16:21:52 +00003639or
Guido van Rossum194e57c1995-02-15 15:51:38 +00003640
Fred Drake8842e861998-02-13 07:16:30 +00003641\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00003642"string": function-name
Fred Drake8842e861998-02-13 07:16:30 +00003643\end{verbatim}
3644
Guido van Rossum02455691997-07-17 16:21:52 +00003645and options can be set with
Guido van Rossum194e57c1995-02-15 15:51:38 +00003646
Fred Drake8842e861998-02-13 07:16:30 +00003647\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00003648set option-name value
Fred Drake8842e861998-02-13 07:16:30 +00003649\end{verbatim}
3650
Guido van Rossum02455691997-07-17 16:21:52 +00003651For example:
Guido van Rossum194e57c1995-02-15 15:51:38 +00003652
Fred Drake8842e861998-02-13 07:16:30 +00003653\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00003654# I prefer vi-style editing:
3655set editing-mode vi
3656# Edit using a single line:
3657set horizontal-scroll-mode On
3658# Rebind some keys:
3659Meta-h: backward-kill-word
3660"\C-u": universal-argument
3661"\C-x\C-r": re-read-init-file
Fred Drake8842e861998-02-13 07:16:30 +00003662\end{verbatim}
3663
Guido van Rossum02455691997-07-17 16:21:52 +00003664Note that the default binding for TAB in Python is to insert a TAB
3665instead of Readline's default filename completion function. If you
3666insist, you can override this by putting
Guido van Rossum194e57c1995-02-15 15:51:38 +00003667
Fred Drake8842e861998-02-13 07:16:30 +00003668\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00003669TAB: complete
Fred Drake8842e861998-02-13 07:16:30 +00003670\end{verbatim}
3671
Fred Drakeeee08cd1997-12-04 15:43:15 +00003672in your \file{\$HOME/.inputrc}. (Of course, this makes it hard to type
Guido van Rossum02455691997-07-17 16:21:52 +00003673indented continuation lines...)
Guido van Rossum194e57c1995-02-15 15:51:38 +00003674
Fred Drake72389881998-04-13 01:31:10 +00003675Automatic completion of variable and module names is optionally
3676available. To enable it in the interpreter's interactive mode, add
3677the following to your \file{\$HOME/.pythonrc} file:% $ <- bow to font-lock
3678\indexii{.pythonrc.py}{file}%
3679\refstmodindex{rlcompleter}%
3680\refbimodindex{readline}
3681
3682\begin{verbatim}
3683import rlcompleter, readline
3684readline.parse_and_bind('tab: complete')
3685\end{verbatim}
3686
3687This binds the TAB key to the completion function, so hitting the TAB
3688key twice suggests completions; it looks at Python statement names,
3689the current local variables, and the available module names. For
3690dotted expressions such as \code{string.a}, it will evaluate the the
3691expression up to the final \character{.} and then suggest completions
3692from the attributes of the resulting object. Note that this may
3693execute application-defined code if an object with a
3694\method{__getattr__()} method is part of the expression.
3695
3696
Fred Drakeb7833d31998-09-11 16:21:55 +00003697\section{Commentary \label{commentary}}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003698
Guido van Rossum02455691997-07-17 16:21:52 +00003699This facility is an enormous step forward compared to previous
3700versions of the interpreter; however, some wishes are left: It would
3701be nice if the proper indentation were suggested on continuation lines
3702(the parser knows if an indent token is required next). The
3703completion mechanism might use the interpreter's symbol table. A
3704command to check (or even suggest) matching parentheses, quotes etc.
3705would also be useful.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003706
Fred Drake8842e861998-02-13 07:16:30 +00003707% XXX Lele Gaifax's readline module, which adds name completion...
Guido van Rossum97662c81996-08-23 15:35:47 +00003708
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003709\end{document}
Guido van Rossum02455691997-07-17 16:21:52 +00003710