blob: 14261aa9ce2a7298e389f5a7d4c7d29537946ef8 [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''
Fred Drake20082d92000-04-03 04:26:58 +00006% --re, math+cmath
Guido van Rossum02455691997-07-17 16:21:52 +00007% 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 Drakeee84d591999-03-10 17:25:30 +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
Fred Drake37f15741999-11-10 16:21:37 +000051\citetitle[../lib/lib.html]{Python Library Reference} document. The
52\citetitle[../ref/ref.html]{Python Reference Manual} gives a more
53formal definition of the language. To write extensions in C or
54\Cpp{}, read \citetitle[../ext/ext.html]{Extending and Embedding the
55Python Interpreter} and \citetitle[../api/api.html]{Python/C API
56Reference}. There are also several books covering Python in depth.
Guido van Rossumdccc2981997-12-30 04:40:25 +000057
58This tutorial does not attempt to be comprehensive and cover every
59single feature, or even every commonly used feature. Instead, it
60introduces many of Python's most noteworthy features, and will give
61you a good idea of the language's flavor and style. After reading it,
62you will be able to read and write Python modules and programs, and
63you will be ready to learn more about the various Python library
Fred Drake37f15741999-11-10 16:21:37 +000064modules described in the \citetitle[../lib/lib.html]{Python Library
65Reference}.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000066
67\end{abstract}
68
Fred Drake4d4f9e71998-01-13 22:25:02 +000069\tableofcontents
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000070
Guido van Rossum5e0759d1992-08-07 16:06:24 +000071
Fred Drakeb7833d31998-09-11 16:21:55 +000072\chapter{Whetting Your Appetite \label{intro}}
Guido van Rossum3a26dd81996-10-24 22:12:48 +000073
Guido van Rossum6fc178f1991-08-16 09:13:42 +000074If you ever wrote a large shell script, you probably know this
75feeling: you'd love to add yet another feature, but it's already so
76slow, and so big, and so complicated; or the feature involves a system
Fred Drakeee84d591999-03-10 17:25:30 +000077call or other function that is only accessible from C \ldots Usually
Guido van Rossum6fc178f1991-08-16 09:13:42 +000078the problem at hand isn't serious enough to warrant rewriting the
Fred Drakeee84d591999-03-10 17:25:30 +000079script in C; perhaps the problem requires variable-length strings or
Guido van Rossum02455691997-07-17 16:21:52 +000080other data types (like sorted lists of file names) that are easy in
Fred Drakeee84d591999-03-10 17:25:30 +000081the shell but lots of work to implement in C, or perhaps you're not
82sufficiently familiar with C.
Guido van Rossum02455691997-07-17 16:21:52 +000083
Fred Drakeee84d591999-03-10 17:25:30 +000084Another situation: perhaps you have to work with several C libraries,
85and the usual C write/compile/test/re-compile cycle is too slow. You
Guido van Rossum02455691997-07-17 16:21:52 +000086need to develop software more quickly. Possibly perhaps you've
87written a program that could use an extension language, and you don't
88want to design a language, write and debug an interpreter for it, then
89tie it into your application.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000090
Guido van Rossum6fc178f1991-08-16 09:13:42 +000091In such cases, Python may be just the language for you. Python is
92simple to use, but it is a real programming language, offering much
93more structure and support for large programs than the shell has. On
Fred Drakeee84d591999-03-10 17:25:30 +000094the other hand, it also offers much more error checking than C, and,
Fred Drakeeee08cd1997-12-04 15:43:15 +000095being a \emph{very-high-level language}, it has high-level data types
Guido van Rossum6fc178f1991-08-16 09:13:42 +000096built in, such as flexible arrays and dictionaries that would cost you
Fred Drakeee84d591999-03-10 17:25:30 +000097days to implement efficiently in C. Because of its more general data
Fred Drakeeee08cd1997-12-04 15:43:15 +000098types Python is applicable to a much larger problem domain than
99\emph{Awk} or even \emph{Perl}, yet many things are at least as easy
100in Python as in those languages.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000101
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000102Python allows you to split up your program in modules that can be
103reused in other Python programs. It comes with a large collection of
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000104standard modules that you can use as the basis of your programs --- or
105as examples to start learning to program in Python. There are also
106built-in modules that provide things like file I/O, system calls,
Guido van Rossum02455691997-07-17 16:21:52 +0000107sockets, and even interfaces to GUI toolkits like Tk.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000108
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000109Python is an interpreted language, which can save you considerable time
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000110during program development because no compilation and linking is
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000111necessary. The interpreter can be used interactively, which makes it
112easy to experiment with features of the language, to write throw-away
113programs, or to test functions during bottom-up program development.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000114It is also a handy desk calculator.
115
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000116Python allows writing very compact and readable programs. Programs
Fred Drake20082d92000-04-03 04:26:58 +0000117written in Python are typically much shorter than equivalent C or
118\Cpp{} programs, for several reasons:
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000119\begin{itemize}
120\item
121the high-level data types allow you to express complex operations in a
122single statement;
123\item
124statement grouping is done by indentation instead of begin/end
125brackets;
126\item
127no variable or argument declarations are necessary.
128\end{itemize}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000129
Fred Drakeee84d591999-03-10 17:25:30 +0000130Python is \emph{extensible}: if you know how to program in C it is easy
Guido van Rossum02455691997-07-17 16:21:52 +0000131to add a new built-in function or module to the interpreter, either to
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000132perform critical operations at maximum speed, or to link Python
133programs to libraries that may only be available in binary form (such
134as a vendor-specific graphics library). Once you are really hooked,
Fred Drakeee84d591999-03-10 17:25:30 +0000135you can link the Python interpreter into an application written in C
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000136and use it as an extension or command language for that application.
137
Guido van Rossum02455691997-07-17 16:21:52 +0000138By the way, the language is named after the BBC show ``Monty Python's
139Flying Circus'' and has nothing to do with nasty reptiles. Making
140references to Monty Python skits in documentation is not only allowed,
Guido van Rossumdccc2981997-12-30 04:40:25 +0000141it is encouraged!
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000142
Fred Drakeb7833d31998-09-11 16:21:55 +0000143\section{Where From Here \label{where}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000144
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000145Now that you are all excited about Python, you'll want to examine it
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000146in some more detail. Since the best way to learn a language is
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000147using it, you are invited here to do so.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000148
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000149In the next chapter, the mechanics of using the interpreter are
150explained. This is rather mundane information, but essential for
151trying out the examples shown later.
152
Guido van Rossum4410c751991-06-04 20:22:18 +0000153The rest of the tutorial introduces various features of the Python
Fred Drakef64f8a01999-06-10 15:30:21 +0000154language and system through examples, beginning with simple
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000155expressions, statements and data types, through functions and modules,
Guido van Rossum6938f061994-08-01 12:22:53 +0000156and finally touching upon advanced concepts like exceptions
157and user-defined classes.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000158
Fred Drakeb7833d31998-09-11 16:21:55 +0000159\chapter{Using the Python Interpreter \label{using}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000160
Fred Drakeb7833d31998-09-11 16:21:55 +0000161\section{Invoking the Interpreter \label{invoking}}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000162
Fred Drake20082d92000-04-03 04:26:58 +0000163The Python interpreter is usually installed as
164\file{/usr/local/bin/python} on those machines where it is available;
165putting \file{/usr/local/bin} in your \UNIX{} shell's search path
166makes it possible to start it by typing the command
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000167
Fred Drake8842e861998-02-13 07:16:30 +0000168\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000169python
Fred Drake8842e861998-02-13 07:16:30 +0000170\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000171
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000172to the shell. Since the choice of the directory where the interpreter
173lives is an installation option, other places are possible; check with
Fred Drakeeee08cd1997-12-04 15:43:15 +0000174your local Python guru or system administrator. (E.g.,
175\file{/usr/local/python} is a popular alternative location.)
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000176
Fred Drake5443c492000-07-08 05:18:54 +0000177Typing an \EOF{} character (\kbd{Control-D} on \UNIX,
178\kbd{Control-Z} on DOS or Windows) at the primary prompt causes the
179interpreter to exit with a zero exit status. If that doesn't work,
180you can exit the interpreter by typing the following commands:
181\samp{import sys; sys.exit()}.
Guido van Rossum02455691997-07-17 16:21:52 +0000182
183The interpreter's line-editing features usually aren't very
Fred Drake3f205921998-01-13 18:56:38 +0000184sophisticated. On \UNIX{}, whoever installed the interpreter may have
Guido van Rossum02455691997-07-17 16:21:52 +0000185enabled support for the GNU readline library, which adds more
186elaborate interactive editing and history features. Perhaps the
187quickest check to see whether command line editing is supported is
188typing Control-P to the first Python prompt you get. If it beeps, you
Fred Drake5443c492000-07-08 05:18:54 +0000189have command line editing; see Appendix \ref{interacting} for an
190introduction to the keys. If nothing appears to happen, or if
191\code{\^P} is echoed, command line editing isn't available; you'll
192only be able to use backspace to remove characters from the current
193line.
Guido van Rossum02455691997-07-17 16:21:52 +0000194
Fred Drake6dc2aae1996-12-13 21:56:03 +0000195The interpreter operates somewhat like the \UNIX{} shell: when called
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000196with standard input connected to a tty device, it reads and executes
197commands interactively; when called with a file name argument or with
Fred Drakeeee08cd1997-12-04 15:43:15 +0000198a file as standard input, it reads and executes a \emph{script} from
Guido van Rossum02455691997-07-17 16:21:52 +0000199that file.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000200
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000201A third way of starting the interpreter is
Fred Drake37f15741999-11-10 16:21:37 +0000202\samp{\program{python} \programopt{-c} \var{command} [arg] ...}, which
203executes the statement(s) in \var{command}, analogous to the shell's
204\programopt{-c} option. Since Python statements often contain spaces
205or other characters that are special to the shell, it is best to quote
206\var{command} in its entirety with double quotes.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000207
Fred Drakeeee08cd1997-12-04 15:43:15 +0000208Note that there is a difference between \samp{python file} and
209\samp{python <file}. In the latter case, input requests from the
210program, such as calls to \code{input()} and \code{raw_input()}, are
211satisfied from \emph{file}. Since this file has already been read
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000212until the end by the parser before the program starts executing, the
213program will encounter EOF immediately. In the former case (which is
214usually what you want) they are satisfied from whatever file or device
215is connected to standard input of the Python interpreter.
216
Guido van Rossumb2c65561993-05-12 08:53:36 +0000217When a script file is used, it is sometimes useful to be able to run
218the script and enter interactive mode afterwards. This can be done by
Fred Drake37f15741999-11-10 16:21:37 +0000219passing \programopt{-i} before the script. (This does not work if the
220script is read from standard input, for the same reason as explained
221in the previous paragraph.)
Guido van Rossumb2c65561993-05-12 08:53:36 +0000222
Fred Drakeb7833d31998-09-11 16:21:55 +0000223\subsection{Argument Passing \label{argPassing}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000224
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000225When known to the interpreter, the script name and additional
Fred Drakeeee08cd1997-12-04 15:43:15 +0000226arguments thereafter are passed to the script in the variable
227\code{sys.argv}, which is a list of strings. Its length is at least
228one; when no script and no arguments are given, \code{sys.argv[0]} is
229an empty string. When the script name is given as \code{'-'} (meaning
Fred Drake37f15741999-11-10 16:21:37 +0000230standard input), \code{sys.argv[0]} is set to \code{'-'}. When
231\programopt{-c} \var{command} is used, \code{sys.argv[0]} is set to
232\code{'-c'}. Options found after \programopt{-c} \var{command} are
233not consumed by the Python interpreter's option processing but left in
234\code{sys.argv} for the command to handle.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000235
Fred Drakeb7833d31998-09-11 16:21:55 +0000236\subsection{Interactive Mode \label{interactive}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000237
Guido van Rossumdd010801991-06-07 14:31:11 +0000238When commands are read from a tty, the interpreter is said to be in
Fred Drakeeee08cd1997-12-04 15:43:15 +0000239\emph{interactive mode}. In this mode it prompts for the next command
240with the \emph{primary prompt}, usually three greater-than signs
Fred Drake31b761e2000-09-29 15:17:36 +0000241(\samp{>\code{>}>~}); for continuation lines it prompts with the
Fred Drake20082d92000-04-03 04:26:58 +0000242\emph{secondary prompt}, by default three dots (\samp{...~}).
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000243The interpreter prints a welcome message stating its version number
244and a copyright notice before printing the first prompt, e.g.:
245
Fred Drake8842e861998-02-13 07:16:30 +0000246\begin{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000247python
Fred Drakeee84d591999-03-10 17:25:30 +0000248Python 1.5.2b2 (#1, Feb 28 1999, 00:02:06) [GCC 2.8.1] on sunos5
Fred Drakeeee08cd1997-12-04 15:43:15 +0000249Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000250>>>
Fred Drake8842e861998-02-13 07:16:30 +0000251\end{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000252
Fred Drake20082d92000-04-03 04:26:58 +0000253Continuation lines are needed when entering a multi-line construct.
254As an example, take a look at this \keyword{if} statement:
255
256\begin{verbatim}
257>>> the_world_is_flat = 1
258>>> if the_world_is_flat:
259... print "Be careful not to fall off!"
260...
261Be careful not to fall off!
262\end{verbatim}
263
264
Fred Drakeb7833d31998-09-11 16:21:55 +0000265\section{The Interpreter and Its Environment \label{interp}}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000266
Fred Drakeb7833d31998-09-11 16:21:55 +0000267\subsection{Error Handling \label{error}}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000268
269When an error occurs, the interpreter prints an error
270message and a stack trace. In interactive mode, it then returns to
271the primary prompt; when input came from a file, it exits with a
272nonzero exit status after printing
Fred Drakeeee08cd1997-12-04 15:43:15 +0000273the stack trace. (Exceptions handled by an \code{except} clause in a
274\code{try} statement are not errors in this context.) Some errors are
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000275unconditionally fatal and cause an exit with a nonzero exit; this
276applies to internal inconsistencies and some cases of running out of
277memory. All error messages are written to the standard error stream;
278normal output from the executed commands is written to standard
279output.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000280
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000281Typing the interrupt character (usually Control-C or DEL) to the
282primary or secondary prompt cancels the input and returns to the
Fred Drake93aa0f21999-04-05 21:39:17 +0000283primary prompt.\footnote{
Guido van Rossum6938f061994-08-01 12:22:53 +0000284 A problem with the GNU Readline package may prevent this.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000285}
Fred Drakeeee08cd1997-12-04 15:43:15 +0000286Typing an interrupt while a command is executing raises the
287\code{KeyboardInterrupt} exception, which may be handled by a
288\code{try} statement.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000289
Fred Drakeb7833d31998-09-11 16:21:55 +0000290\subsection{Executable Python Scripts \label{scripts}}
Guido van Rossum4410c751991-06-04 20:22:18 +0000291
Fred Drake6dc2aae1996-12-13 21:56:03 +0000292On BSD'ish \UNIX{} systems, Python scripts can be made directly
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000293executable, like shell scripts, by putting the line
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000294
Fred Drake8842e861998-02-13 07:16:30 +0000295\begin{verbatim}
Fred Drake9e63faa1997-10-15 14:37:24 +0000296#! /usr/bin/env python
Fred Drake8842e861998-02-13 07:16:30 +0000297\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000298
Fred Drake391564f1998-04-01 23:11:56 +0000299(assuming that the interpreter is on the user's \envvar{PATH}) at the
300beginning of the script and giving the file an executable mode. The
Fred Drakebdadf0f1999-04-29 13:20:25 +0000301\samp{\#!} must be the first two characters of the file. Note that
302the hash, or pound, character, \character{\#}, is used to start a
303comment in Python.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000304
Fred Drakeb7833d31998-09-11 16:21:55 +0000305\subsection{The Interactive Startup File \label{startup}}
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000306
Fred Drake8842e861998-02-13 07:16:30 +0000307% XXX This should probably be dumped in an appendix, since most people
308% don't use Python interactively in non-trivial ways.
Guido van Rossum02455691997-07-17 16:21:52 +0000309
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000310When you use Python interactively, it is frequently handy to have some
311standard commands executed every time the interpreter is started. You
Fred Drakeeee08cd1997-12-04 15:43:15 +0000312can do this by setting an environment variable named
Fred Drake391564f1998-04-01 23:11:56 +0000313\envvar{PYTHONSTARTUP} to the name of a file containing your start-up
Fred Drake20082d92000-04-03 04:26:58 +0000314commands. This is similar to the \file{.profile} feature of the
315\UNIX{} shells.
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000316
317This file is only read in interactive sessions, not when Python reads
Fred Drakeeee08cd1997-12-04 15:43:15 +0000318commands from a script, and not when \file{/dev/tty} is given as the
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000319explicit source of commands (which otherwise behaves like an
Fred Drake13494372000-09-12 16:23:48 +0000320interactive session). It is executed in the same namespace where
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000321interactive commands are executed, so that objects that it defines or
322imports can be used without qualification in the interactive session.
Fred Drakeeee08cd1997-12-04 15:43:15 +0000323You can also change the prompts \code{sys.ps1} and \code{sys.ps2} in
Guido van Rossum7b3c8a11992-09-08 09:20:13 +0000324this file.
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000325
326If you want to read an additional start-up file from the current
Fred Drake72389881998-04-13 01:31:10 +0000327directory, you can program this in the global start-up file,
Fred Drake5443c492000-07-08 05:18:54 +0000328e.g.\ \samp{if os.path.isfile('.pythonrc.py'):
329execfile('.pythonrc.py')}. If you want to use the startup file in a
330script, you must do this explicitly in the script:
Fred Drake8842e861998-02-13 07:16:30 +0000331
332\begin{verbatim}
333import os
Fred Drake5443c492000-07-08 05:18:54 +0000334filename = os.environ.get('PYTHONSTARTUP')
335if filename and os.path.isfile(filename):
336 execfile(filename)
Fred Drake8842e861998-02-13 07:16:30 +0000337\end{verbatim}
Guido van Rossum9a4e3fc1992-09-03 21:27:55 +0000338
Fred Drake72389881998-04-13 01:31:10 +0000339
Fred Drakeb7833d31998-09-11 16:21:55 +0000340\chapter{An Informal Introduction to Python \label{informal}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000341
342In the following examples, input and output are distinguished by the
Fred Drake31b761e2000-09-29 15:17:36 +0000343presence or absence of prompts (\samp{>\code{>}>~} and \samp{...~}): to repeat
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000344the example, you must type everything after the prompt, when the
345prompt appears; lines that do not begin with a prompt are output from
Fred Drakebdadf0f1999-04-29 13:20:25 +0000346the interpreter. %
Guido van Rossum02455691997-07-17 16:21:52 +0000347%\footnote{
348% I'd prefer to use different fonts to distinguish input
349% from output, but the amount of LaTeX hacking that would require
350% is currently beyond my ability.
351%}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000352Note that a secondary prompt on a line by itself in an example means
353you must type a blank line; this is used to end a multi-line command.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000354
Fred Drakebdadf0f1999-04-29 13:20:25 +0000355Many of the examples in this manual, even those entered at the
356interactive prompt, include comments. Comments in Python start with
357the hash character, \character{\#}, and extend to the end of the
358physical line. A comment may appear at the start of a line or
359following whitespace or code, but not within a string literal. A hash
360character within a string literal is just a hash character.
361
362Some examples:
363
364\begin{verbatim}
365# this is the first comment
366SPAM = 1 # and this is the second comment
367 # ... and now a third!
368STRING = "# This is not a comment."
369\end{verbatim}
370
371
Fred Drakeb7833d31998-09-11 16:21:55 +0000372\section{Using Python as a Calculator \label{calculator}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000373
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000374Let's try some simple Python commands. Start the interpreter and wait
Fred Drake31b761e2000-09-29 15:17:36 +0000375for the primary prompt, \samp{>\code{>}>~}. (It shouldn't take long.)
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000376
Fred Drakeb7833d31998-09-11 16:21:55 +0000377\subsection{Numbers \label{numbers}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000378
379The interpreter acts as a simple calculator: you can type an
380expression at it and it will write the value. Expression syntax is
Fred Drake20082d92000-04-03 04:26:58 +0000381straightforward: the operators \code{+}, \code{-}, \code{*} and
382\code{/} work just like in most other languages (for example, Pascal
383or C); parentheses can be used for grouping. For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000384
Fred Drake8842e861998-02-13 07:16:30 +0000385\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000386>>> 2+2
3874
Guido van Rossum6938f061994-08-01 12:22:53 +0000388>>> # This is a comment
389... 2+2
3904
391>>> 2+2 # and a comment on the same line as code
3924
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000393>>> (50-5*6)/4
3945
Guido van Rossum6938f061994-08-01 12:22:53 +0000395>>> # Integer division returns the floor:
396... 7/3
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003972
Guido van Rossum6938f061994-08-01 12:22:53 +0000398>>> 7/-3
399-3
Fred Drake8842e861998-02-13 07:16:30 +0000400\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000401
Fred Drakeee84d591999-03-10 17:25:30 +0000402Like in C, the equal sign (\character{=}) is used to assign a value to a
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000403variable. The value of an assignment is not written:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000404
Fred Drake8842e861998-02-13 07:16:30 +0000405\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000406>>> width = 20
407>>> height = 5*9
408>>> width * height
409900
Fred Drake8842e861998-02-13 07:16:30 +0000410\end{verbatim}
Fred Drake20082d92000-04-03 04:26:58 +0000411
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000412A value can be assigned to several variables simultaneously:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000413
Fred Drake8842e861998-02-13 07:16:30 +0000414\begin{verbatim}
Guido van Rossum6938f061994-08-01 12:22:53 +0000415>>> x = y = z = 0 # Zero x, y and z
416>>> x
4170
418>>> y
4190
420>>> z
4210
Fred Drake8842e861998-02-13 07:16:30 +0000422\end{verbatim}
Fred Drake31b761e2000-09-29 15:17:36 +0000423
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000424There is full support for floating point; operators with mixed type
425operands convert the integer operand to floating point:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000426
Fred Drake8842e861998-02-13 07:16:30 +0000427\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000428>>> 4 * 2.5 / 3.3
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00004293.0303030303
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000430>>> 7.0 / 2
4313.5
Fred Drake8842e861998-02-13 07:16:30 +0000432\end{verbatim}
Fred Drake31b761e2000-09-29 15:17:36 +0000433
Guido van Rossum02455691997-07-17 16:21:52 +0000434Complex numbers are also supported; imaginary numbers are written with
Fred Drake8842e861998-02-13 07:16:30 +0000435a suffix of \samp{j} or \samp{J}. Complex numbers with a nonzero
436real component are written as \samp{(\var{real}+\var{imag}j)}, or can
437be created with the \samp{complex(\var{real}, \var{imag})} function.
Guido van Rossum02455691997-07-17 16:21:52 +0000438
Fred Drake8842e861998-02-13 07:16:30 +0000439\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +0000440>>> 1j * 1J
441(-1+0j)
442>>> 1j * complex(0,1)
443(-1+0j)
444>>> 3+1j*3
445(3+3j)
446>>> (3+1j)*3
447(9+3j)
448>>> (1+2j)/(1+1j)
449(1.5+0.5j)
Fred Drake8842e861998-02-13 07:16:30 +0000450\end{verbatim}
Fred Drake31b761e2000-09-29 15:17:36 +0000451
Guido van Rossum02455691997-07-17 16:21:52 +0000452Complex numbers are always represented as two floating point numbers,
453the real and imaginary part. To extract these parts from a complex
Fred Drake8842e861998-02-13 07:16:30 +0000454number \var{z}, use \code{\var{z}.real} and \code{\var{z}.imag}.
Guido van Rossum02455691997-07-17 16:21:52 +0000455
Fred Drake8842e861998-02-13 07:16:30 +0000456\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +0000457>>> a=1.5+0.5j
458>>> a.real
4591.5
460>>> a.imag
4610.5
Fred Drake8842e861998-02-13 07:16:30 +0000462\end{verbatim}
Fred Drake31b761e2000-09-29 15:17:36 +0000463
Guido van Rossum02455691997-07-17 16:21:52 +0000464The conversion functions to floating point and integer
Fred Drake8842e861998-02-13 07:16:30 +0000465(\function{float()}, \function{int()} and \function{long()}) don't
466work for complex numbers --- there is no one correct way to convert a
467complex number to a real number. Use \code{abs(\var{z})} to get its
468magnitude (as a float) or \code{z.real} to get its real part.
Guido van Rossum02455691997-07-17 16:21:52 +0000469
Fred Drake8842e861998-02-13 07:16:30 +0000470\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +0000471>>> a=1.5+0.5j
472>>> float(a)
473Traceback (innermost last):
474 File "<stdin>", line 1, in ?
475TypeError: can't convert complex to float; use e.g. abs(z)
476>>> a.real
4771.5
478>>> abs(a)
4791.58113883008
Fred Drake8842e861998-02-13 07:16:30 +0000480\end{verbatim}
Fred Drake31b761e2000-09-29 15:17:36 +0000481
Guido van Rossum02455691997-07-17 16:21:52 +0000482In interactive mode, the last printed expression is assigned to the
483variable \code{_}. This means that when you are using Python as a
484desk calculator, it is somewhat easier to continue calculations, for
485example:
486
487\begin{verbatim}
488>>> tax = 17.5 / 100
489>>> price = 3.50
490>>> price * tax
Fred Drake343ad7a2000-09-22 04:12:27 +00004910.61249999999999993
Guido van Rossum02455691997-07-17 16:21:52 +0000492>>> price + _
Fred Drake343ad7a2000-09-22 04:12:27 +00004934.1124999999999998
Guido van Rossum02455691997-07-17 16:21:52 +0000494>>> round(_, 2)
Fred Drake343ad7a2000-09-22 04:12:27 +00004954.1100000000000003
Guido van Rossum02455691997-07-17 16:21:52 +0000496\end{verbatim}
497
498This variable should be treated as read-only by the user. Don't
499explicitly assign a value to it --- you would create an independent
500local variable with the same name masking the built-in variable with
501its magic behavior.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000502
Fred Drakeb7833d31998-09-11 16:21:55 +0000503\subsection{Strings \label{strings}}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000504
Guido van Rossum02455691997-07-17 16:21:52 +0000505Besides numbers, Python can also manipulate strings, which can be
506expressed in several ways. They can be enclosed in single quotes or
507double quotes:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000508
Fred Drake8842e861998-02-13 07:16:30 +0000509\begin{verbatim}
Guido van Rossume5f8b601995-01-04 19:12:49 +0000510>>> 'spam eggs'
511'spam eggs'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000512>>> 'doesn\'t'
Guido van Rossum6938f061994-08-01 12:22:53 +0000513"doesn't"
514>>> "doesn't"
515"doesn't"
516>>> '"Yes," he said.'
517'"Yes," he said.'
518>>> "\"Yes,\" he said."
519'"Yes," he said.'
520>>> '"Isn\'t," she said.'
521'"Isn\'t," she said.'
Fred Drake8842e861998-02-13 07:16:30 +0000522\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000523
Fred Drake8842e861998-02-13 07:16:30 +0000524String literals can span multiple lines in several ways. Newlines can
525be escaped with backslashes, e.g.:
Guido van Rossum02455691997-07-17 16:21:52 +0000526
527\begin{verbatim}
528hello = "This is a rather long string containing\n\
529several lines of text just as you would do in C.\n\
530 Note that whitespace at the beginning of the line is\
531 significant.\n"
532print hello
533\end{verbatim}
534
535which would print the following:
Fred Drake8842e861998-02-13 07:16:30 +0000536
Guido van Rossum02455691997-07-17 16:21:52 +0000537\begin{verbatim}
538This is a rather long string containing
539several lines of text just as you would do in C.
540 Note that whitespace at the beginning of the line is significant.
541\end{verbatim}
542
543Or, strings can be surrounded in a pair of matching triple-quotes:
544\code{"""} or \code {'''}. End of lines do not need to be escaped
545when using triple-quotes, but they will be included in the string.
546
547\begin{verbatim}
548print """
549Usage: thingy [OPTIONS]
550 -h Display this usage message
551 -H hostname Hostname to connect to
552"""
553\end{verbatim}
554
555produces the following output:
556
Fred Drake8842e861998-02-13 07:16:30 +0000557\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +0000558Usage: thingy [OPTIONS]
559 -h Display this usage message
560 -H hostname Hostname to connect to
Fred Drake8842e861998-02-13 07:16:30 +0000561\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000562
Guido van Rossum02455691997-07-17 16:21:52 +0000563The interpreter prints the result of string operations in the same way
564as they are typed for input: inside quotes, and with quotes and other
565funny characters escaped by backslashes, to show the precise
566value. The string is enclosed in double quotes if the string contains
567a single quote and no double quotes, else it's enclosed in single
Fred Drake8842e861998-02-13 07:16:30 +0000568quotes. (The \keyword{print} statement, described later, can be used
569to write strings without quotes or escapes.)
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000570
Fred Drake20082d92000-04-03 04:26:58 +0000571Strings can be concatenated (glued together) with the
572\code{+} operator, and repeated with \code{*}:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000573
Fred Drake8842e861998-02-13 07:16:30 +0000574\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000575>>> word = 'Help' + 'A'
576>>> word
577'HelpA'
578>>> '<' + word*5 + '>'
579'<HelpAHelpAHelpAHelpAHelpA>'
Fred Drake8842e861998-02-13 07:16:30 +0000580\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000581
Guido van Rossum02455691997-07-17 16:21:52 +0000582Two string literals next to each other are automatically concatenated;
Fred Drake8842e861998-02-13 07:16:30 +0000583the first line above could also have been written \samp{word = 'Help'
Guido van Rossume51aa5b1999-01-06 23:14:14 +0000584'A'}; this only works with two literals, not with arbitrary string
585expressions:
586
587\begin{verbatim}
Fred Drake0ba58151999-09-14 18:00:49 +0000588>>> import string
Guido van Rossume51aa5b1999-01-06 23:14:14 +0000589>>> 'str' 'ing' # <- This is ok
590'string'
591>>> string.strip('str') + 'ing' # <- This is ok
592'string'
593>>> string.strip('str') 'ing' # <- This is invalid
594 File "<stdin>", line 1
595 string.strip('str') 'ing'
596 ^
597SyntaxError: invalid syntax
598\end{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000599
Fred Drakeee84d591999-03-10 17:25:30 +0000600Strings can be subscripted (indexed); like in C, the first character
Guido van Rossum02455691997-07-17 16:21:52 +0000601of a string has subscript (index) 0. There is no separate character
602type; a character is simply a string of size one. Like in Icon,
Fred Drake8842e861998-02-13 07:16:30 +0000603substrings can be specified with the \emph{slice notation}: two indices
Guido van Rossum02455691997-07-17 16:21:52 +0000604separated by a colon.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000605
Fred Drake8842e861998-02-13 07:16:30 +0000606\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000607>>> word[4]
608'A'
609>>> word[0:2]
610'He'
611>>> word[2:4]
612'lp'
Fred Drake8842e861998-02-13 07:16:30 +0000613\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000614
Fred Drake20082d92000-04-03 04:26:58 +0000615Unlike a C string, Python strings cannot be changed. Assigning to an
616indexed position in the string results in an error:
617
618\begin{verbatim}
619>>> word[0] = 'x'
620Traceback (innermost last):
621 File "<stdin>", line 1, in ?
622TypeError: object doesn't support item assignment
623>>> word[:-1] = 'Splat'
624Traceback (innermost last):
625 File "<stdin>", line 1, in ?
626TypeError: object doesn't support slice assignment
627\end{verbatim}
628
629However, creating a new string with the combined content is easy and
630efficient:
631
632\begin{verbatim}
633>>> 'x' + word[1:]
634'xelpA'
635>>> 'Splat' + word[-1:]
636'SplatA'
637\end{verbatim}
638
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000639Slice indices have useful defaults; an omitted first index defaults to
640zero, an omitted second index defaults to the size of the string being
641sliced.
642
Fred Drake8842e861998-02-13 07:16:30 +0000643\begin{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000644>>> word[:2] # The first two characters
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000645'He'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000646>>> word[2:] # All but the first two characters
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000647'lpA'
Fred Drake8842e861998-02-13 07:16:30 +0000648\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000649
Fred Drake20082d92000-04-03 04:26:58 +0000650Here's a useful invariant of slice operations:
651\code{s[:i] + s[i:]} equals \code{s}.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000652
Fred Drake8842e861998-02-13 07:16:30 +0000653\begin{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000654>>> word[:2] + word[2:]
655'HelpA'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000656>>> word[:3] + word[3:]
657'HelpA'
Fred Drake8842e861998-02-13 07:16:30 +0000658\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000659
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000660Degenerate slice indices are handled gracefully: an index that is too
661large is replaced by the string size, an upper bound smaller than the
662lower bound returns an empty string.
663
Fred Drake8842e861998-02-13 07:16:30 +0000664\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000665>>> word[1:100]
666'elpA'
667>>> word[10:]
668''
669>>> word[2:1]
670''
Fred Drake8842e861998-02-13 07:16:30 +0000671\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000672
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000673Indices may be negative numbers, to start counting from the right.
674For example:
675
Fred Drake8842e861998-02-13 07:16:30 +0000676\begin{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000677>>> word[-1] # The last character
678'A'
679>>> word[-2] # The last-but-one character
680'p'
681>>> word[-2:] # The last two characters
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000682'pA'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000683>>> word[:-2] # All but the last two characters
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000684'Hel'
Fred Drake8842e861998-02-13 07:16:30 +0000685\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000686
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000687But note that -0 is really the same as 0, so it does not count from
688the right!
689
Fred Drake8842e861998-02-13 07:16:30 +0000690\begin{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000691>>> word[-0] # (since -0 equals 0)
692'H'
Fred Drake8842e861998-02-13 07:16:30 +0000693\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000694
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000695Out-of-range negative slice indices are truncated, but don't try this
696for single-element (non-slice) indices:
697
Fred Drake8842e861998-02-13 07:16:30 +0000698\begin{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000699>>> word[-100:]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000700'HelpA'
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000701>>> word[-10] # error
Guido van Rossum6938f061994-08-01 12:22:53 +0000702Traceback (innermost last):
703 File "<stdin>", line 1
704IndexError: string index out of range
Fred Drake8842e861998-02-13 07:16:30 +0000705\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000706
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000707The best way to remember how slices work is to think of the indices as
Fred Drakeeee08cd1997-12-04 15:43:15 +0000708pointing \emph{between} characters, with the left edge of the first
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000709character numbered 0. Then the right edge of the last character of a
Fred Drakeeee08cd1997-12-04 15:43:15 +0000710string of \var{n} characters has index \var{n}, for example:
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 +---+---+---+---+---+
714 | H | e | l | p | A |
715 +---+---+---+---+---+
716 0 1 2 3 4 5
717-5 -4 -3 -2 -1
Fred Drake8842e861998-02-13 07:16:30 +0000718\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000719
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000720The first row of numbers gives the position of the indices 0...5 in
721the string; the second row gives the corresponding negative indices.
Fred Drakeeee08cd1997-12-04 15:43:15 +0000722The slice from \var{i} to \var{j} consists of all characters between
723the edges labeled \var{i} and \var{j}, respectively.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000724
Fred Drake20082d92000-04-03 04:26:58 +0000725For non-negative indices, the length of a slice is the difference of
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000726the indices, if both are within bounds, e.g., the length of
Fred Drakeeee08cd1997-12-04 15:43:15 +0000727\code{word[1:3]} is 2.
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000728
Fred Drake8842e861998-02-13 07:16:30 +0000729The built-in function \function{len()} returns the length of a string:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000730
Fred Drake8842e861998-02-13 07:16:30 +0000731\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000732>>> s = 'supercalifragilisticexpialidocious'
733>>> len(s)
73434
Fred Drake8842e861998-02-13 07:16:30 +0000735\end{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000736
Fred Drake9dc30bb2000-04-06 14:17:03 +0000737
738\subsection{Unicode Strings \label{unicodeStrings}}
739\sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com}
740
Fred Drake30f76ff2000-06-30 16:06:19 +0000741Starting with Python 2.0 a new data type for storing text data is
Fred Drake9dc30bb2000-04-06 14:17:03 +0000742available to the programmer: the Unicode object. It can be used to
743store and manipulate Unicode data (see \url{http://www.unicode.org})
Thomas Woutersf9b526d2000-07-16 19:05:38 +0000744and integrates well with the existing string objects providing
Fred Drake9dc30bb2000-04-06 14:17:03 +0000745auto-conversions where necessary.
746
747Unicode has the advantage of providing one ordinal for every character
748in every script used in modern and ancient texts. Previously, there
749were only 256 possible ordinals for script characters and texts were
750typically bound to a code page which mapped the ordinals to script
751characters. This lead to very much confusion especially with respect
Fred Drake31b761e2000-09-29 15:17:36 +0000752to internationalization (usually written as \samp{i18n} ---
753\character{i} + 18 characters + \character{n}) of software. Unicode
754solves these problems by defining one code page for all scripts.
Fred Drake9dc30bb2000-04-06 14:17:03 +0000755
756Creating Unicode strings in Python is just as simple as creating
757normal strings:
758
759\begin{verbatim}
760>>> u'Hello World !'
761u'Hello World !'
762\end{verbatim}
763
764The small \character{u} in front of the quote indicates that an
765Unicode string is supposed to be created. If you want to include
766special characters in the string, you can do so by using the Python
767\emph{Unicode-Escape} encoding. The following example shows how:
768
769\begin{verbatim}
770>>> u'Hello\\u0020World !'
771u'Hello World !'
772\end{verbatim}
773
774The escape sequence \code{\\u0020} indicates to insert the Unicode
775character with the HEX ordinal 0x0020 (the space character) at the
776given position.
777
778Other characters are interpreted by using their respective ordinal
779value directly as Unicode ordinal. Due to the fact that the lower 256
780Unicode are the same as the standard Latin-1 encoding used in many
781western countries, the process of entering Unicode is greatly
782simplified.
783
784For experts, there is also a raw mode just like for normal
785strings. You have to prepend the string with a small 'r' to have
786Python use the \emph{Raw-Unicode-Escape} encoding. It will only apply
787the above \code{\\uXXXX} conversion if there is an uneven number of
788backslashes in front of the small 'u'.
789
790\begin{verbatim}
791>>> ur'Hello\u0020World !'
792u'Hello World !'
793>>> ur'Hello\\u0020World !'
794u'Hello\\\\u0020World !'
795\end{verbatim}
796
797The raw mode is most useful when you have to enter lots of backslashes
798e.g. in regular expressions.
799
800Apart from these standard encodings, Python provides a whole set of
Thomas Woutersf9b526d2000-07-16 19:05:38 +0000801other ways of creating Unicode strings on the basis of a known
Fred Drake9dc30bb2000-04-06 14:17:03 +0000802encoding.
803
804The builtin \function{unicode()}\bifuncindex{unicode} provides access
805to all registered Unicode codecs (COders and DECoders). Some of the
806more well known encodings which these codecs can convert are
807\emph{Latin-1}, \emph{ASCII}, \emph{UTF-8} and \emph{UTF-16}. The latter two
808are variable length encodings which permit to store Unicode characters
809in 8 or 16 bits. Python uses UTF-8 as default encoding. This becomes
Thomas Woutersf9b526d2000-07-16 19:05:38 +0000810noticeable when printing Unicode strings or writing them to files.
Fred Drake9dc30bb2000-04-06 14:17:03 +0000811
812\begin{verbatim}
813>>> u"äöü"
814u'\344\366\374'
815>>> str(u"äöü")
816'\303\244\303\266\303\274'
817\end{verbatim}
818
819If you have data in a specific encoding and want to produce a
820corresponding Unicode string from it, you can use the
821\function{unicode()} builtin with the encoding name as second
822argument.
823
824\begin{verbatim}
825>>> unicode('\303\244\303\266\303\274','UTF-8')
826u'\344\366\374'
827\end{verbatim}
828
829To convert the Unicode string back into a string using the original
830encoding, the objects provide an \method{encode()} method.
831
832\begin{verbatim}
833>>> u"äöü".encode('UTF-8')
834'\303\244\303\266\303\274'
835\end{verbatim}
836
837
Fred Drakeb7833d31998-09-11 16:21:55 +0000838\subsection{Lists \label{lists}}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000839
Fred Drakeeee08cd1997-12-04 15:43:15 +0000840Python knows a number of \emph{compound} data types, used to group
841together other values. The most versatile is the \emph{list}, which
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000842can be written as a list of comma-separated values (items) between
843square brackets. List items need not all have the same type.
844
Fred Drake8842e861998-02-13 07:16:30 +0000845\begin{verbatim}
Guido van Rossume5f8b601995-01-04 19:12:49 +0000846>>> a = ['spam', 'eggs', 100, 1234]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000847>>> a
Guido van Rossume5f8b601995-01-04 19:12:49 +0000848['spam', 'eggs', 100, 1234]
Fred Drake8842e861998-02-13 07:16:30 +0000849\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000850
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000851Like string indices, list indices start at 0, and lists can be sliced,
852concatenated and so on:
853
Fred Drake8842e861998-02-13 07:16:30 +0000854\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000855>>> a[0]
Guido van Rossume5f8b601995-01-04 19:12:49 +0000856'spam'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000857>>> a[3]
8581234
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000859>>> a[-2]
860100
861>>> a[1:-1]
Guido van Rossume5f8b601995-01-04 19:12:49 +0000862['eggs', 100]
863>>> a[:2] + ['bacon', 2*2]
864['spam', 'eggs', 'bacon', 4]
Guido van Rossum4410c751991-06-04 20:22:18 +0000865>>> 3*a[:3] + ['Boe!']
Guido van Rossume5f8b601995-01-04 19:12:49 +0000866['spam', 'eggs', 100, 'spam', 'eggs', 100, 'spam', 'eggs', 100, 'Boe!']
Fred Drake8842e861998-02-13 07:16:30 +0000867\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000868
Fred Drakeeee08cd1997-12-04 15:43:15 +0000869Unlike strings, which are \emph{immutable}, it is possible to change
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000870individual elements of a list:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000871
Fred Drake8842e861998-02-13 07:16:30 +0000872\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000873>>> a
Guido van Rossume5f8b601995-01-04 19:12:49 +0000874['spam', 'eggs', 100, 1234]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000875>>> a[2] = a[2] + 23
876>>> a
Guido van Rossume5f8b601995-01-04 19:12:49 +0000877['spam', 'eggs', 123, 1234]
Fred Drake8842e861998-02-13 07:16:30 +0000878\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000879
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000880Assignment to slices is also possible, and this can even change the size
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000881of the list:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000882
Fred Drake8842e861998-02-13 07:16:30 +0000883\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000884>>> # Replace some items:
Guido van Rossum6938f061994-08-01 12:22:53 +0000885... a[0:2] = [1, 12]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000886>>> a
887[1, 12, 123, 1234]
888>>> # Remove some:
Guido van Rossum6938f061994-08-01 12:22:53 +0000889... a[0:2] = []
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000890>>> a
891[123, 1234]
892>>> # Insert some:
Guido van Rossum6938f061994-08-01 12:22:53 +0000893... a[1:1] = ['bletch', 'xyzzy']
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000894>>> a
895[123, 'bletch', 'xyzzy', 1234]
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000896>>> a[:0] = a # Insert (a copy of) itself at the beginning
897>>> a
898[123, 'bletch', 'xyzzy', 1234, 123, 'bletch', 'xyzzy', 1234]
Fred Drake8842e861998-02-13 07:16:30 +0000899\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000900
Fred Drake8842e861998-02-13 07:16:30 +0000901The built-in function \function{len()} also applies to lists:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000902
Fred Drake8842e861998-02-13 07:16:30 +0000903\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000904>>> len(a)
Guido van Rossuma8d754e1992-01-07 16:44:35 +00009058
Fred Drake8842e861998-02-13 07:16:30 +0000906\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000907
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000908It is possible to nest lists (create lists containing other lists),
909for example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000910
Fred Drake8842e861998-02-13 07:16:30 +0000911\begin{verbatim}
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000912>>> q = [2, 3]
913>>> p = [1, q, 4]
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000914>>> len(p)
9153
916>>> p[1]
917[2, 3]
918>>> p[1][0]
9192
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000920>>> p[1].append('xtra') # See section 5.1
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000921>>> p
922[1, [2, 3, 'xtra'], 4]
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000923>>> q
924[2, 3, 'xtra']
Fred Drake8842e861998-02-13 07:16:30 +0000925\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000926
Fred Drakeeee08cd1997-12-04 15:43:15 +0000927Note that in the last example, \code{p[1]} and \code{q} really refer to
928the same object! We'll come back to \emph{object semantics} later.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000929
Fred Drakeb7833d31998-09-11 16:21:55 +0000930\section{First Steps Towards Programming \label{firstSteps}}
Guido van Rossum2292b8e1991-01-23 16:31:24 +0000931
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000932Of course, we can use Python for more complicated tasks than adding
933two and two together. For instance, we can write an initial
Fred Drakeeee08cd1997-12-04 15:43:15 +0000934subsequence of the \emph{Fibonacci} series as follows:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000935
Fred Drake8842e861998-02-13 07:16:30 +0000936\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000937>>> # Fibonacci series:
Guido van Rossum6938f061994-08-01 12:22:53 +0000938... # the sum of two elements defines the next
939... a, b = 0, 1
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000940>>> while b < 10:
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000941... print b
942... a, b = b, a+b
943...
9441
9451
9462
9473
9485
9498
Fred Drake8842e861998-02-13 07:16:30 +0000950\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +0000951
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000952This example introduces several new features.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000953
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000954\begin{itemize}
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000955
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000956\item
Fred Drakeeee08cd1997-12-04 15:43:15 +0000957The first line contains a \emph{multiple assignment}: the variables
958\code{a} and \code{b} simultaneously get the new values 0 and 1. On the
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000959last line this is used again, demonstrating that the expressions on
960the right-hand side are all evaluated first before any of the
Fred Drake20082d92000-04-03 04:26:58 +0000961assignments take place. The right-hand side expressions are evaluated
962from the left to the right.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000963
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000964\item
Fred Drake8842e861998-02-13 07:16:30 +0000965The \keyword{while} loop executes as long as the condition (here:
Fred Drakeee84d591999-03-10 17:25:30 +0000966\code{b < 10}) remains true. In Python, like in C, any non-zero
Fred Drake8842e861998-02-13 07:16:30 +0000967integer value is true; zero is false. The condition may also be a
968string or list value, in fact any sequence; anything with a non-zero
969length is true, empty sequences are false. The test used in the
970example is a simple comparison. The standard comparison operators are
Fred Drake20082d92000-04-03 04:26:58 +0000971written the same as in C: \code{<} (less than), \code{>} (greater than),
972\code{==} (equal to), \code{<=} (less than or equal to),
973\code{>=} (greater than or equal to) and \code{!=} (not equal to).
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000974
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000975\item
Fred Drakeeee08cd1997-12-04 15:43:15 +0000976The \emph{body} of the loop is \emph{indented}: indentation is Python's
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000977way of grouping statements. Python does not (yet!) provide an
978intelligent input line editing facility, so you have to type a tab or
979space(s) for each indented line. In practice you will prepare more
980complicated input for Python with a text editor; most text editors have
981an auto-indent facility. When a compound statement is entered
982interactively, it must be followed by a blank line to indicate
983completion (since the parser cannot guess when you have typed the last
Fred Drake20082d92000-04-03 04:26:58 +0000984line). Note that each line within a basic block must be indented by
985the same amount.
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000986
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000987\item
Fred Drake8842e861998-02-13 07:16:30 +0000988The \keyword{print} statement writes the value of the expression(s) it is
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000989given. It differs from just writing the expression you want to write
990(as we did earlier in the calculator examples) in the way it handles
Guido van Rossum16cd7f91994-10-06 10:29:26 +0000991multiple expressions and strings. Strings are printed without quotes,
Guido van Rossum6fc178f1991-08-16 09:13:42 +0000992and a space is inserted between items, so you can format things nicely,
993like this:
Guido van Rossuma8d754e1992-01-07 16:44:35 +0000994
Fred Drake8842e861998-02-13 07:16:30 +0000995\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +0000996>>> i = 256*256
997>>> print 'The value of i is', i
998The value of i is 65536
Fred Drake8842e861998-02-13 07:16:30 +0000999\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001000
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001001A trailing comma avoids the newline after the output:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001002
Fred Drake8842e861998-02-13 07:16:30 +00001003\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001004>>> a, b = 0, 1
1005>>> while b < 1000:
1006... print b,
1007... a, b = b, a+b
1008...
10091 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
Fred Drake8842e861998-02-13 07:16:30 +00001010\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001011
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001012Note that the interpreter inserts a newline before it prints the next
1013prompt if the last line was not completed.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001014
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001015\end{itemize}
1016
Guido van Rossum5e0759d1992-08-07 16:06:24 +00001017
Fred Drakeb7833d31998-09-11 16:21:55 +00001018\chapter{More Control Flow Tools \label{moreControl}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001019
Fred Drake8842e861998-02-13 07:16:30 +00001020Besides the \keyword{while} statement just introduced, Python knows
1021the usual control flow statements known from other languages, with
1022some twists.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001023
Fred Drakeb7833d31998-09-11 16:21:55 +00001024\section{\keyword{if} Statements \label{if}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001025
Fred Drake20082d92000-04-03 04:26:58 +00001026Perhaps the most well-known statement type is the
1027\keyword{if} statement. For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001028
Fred Drake8842e861998-02-13 07:16:30 +00001029\begin{verbatim}
Fred Drake20082d92000-04-03 04:26:58 +00001030>>> x = int(raw_input("Please enter a number: "))
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001031>>> if x < 0:
1032... x = 0
1033... print 'Negative changed to zero'
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001034... elif x == 0:
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001035... print 'Zero'
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001036... elif x == 1:
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001037... print 'Single'
1038... else:
1039... print 'More'
1040...
Fred Drake8842e861998-02-13 07:16:30 +00001041\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001042
Fred Drake20082d92000-04-03 04:26:58 +00001043There can be zero or more \keyword{elif} parts, and the
1044\keyword{else} part is optional. The keyword `\keyword{elif}' is
1045short for `else if', and is useful to avoid excessive indentation. An
1046\keyword{if} \ldots\ \keyword{elif} \ldots\ \keyword{elif} \ldots\ sequence
Fred Drake8842e861998-02-13 07:16:30 +00001047% Weird spacings happen here if the wrapping of the source text
1048% gets changed in the wrong way.
Fred Drake20082d92000-04-03 04:26:58 +00001049is a substitute for the \emph{switch} or
Fred Drake8842e861998-02-13 07:16:30 +00001050\emph{case} statements found in other languages.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001051
Fred Drakeb7833d31998-09-11 16:21:55 +00001052
1053\section{\keyword{for} Statements \label{for}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001054
Fred Drakef790b161998-11-30 20:37:24 +00001055The \keyword{for}\stindex{for} statement in Python differs a bit from
Fred Drakeee84d591999-03-10 17:25:30 +00001056what you may be used to in C or Pascal. Rather than always
Fred Drakef790b161998-11-30 20:37:24 +00001057iterating over an arithmetic progression of numbers (like in Pascal),
1058or giving the user the ability to define both the iteration step and
Fred Drake20082d92000-04-03 04:26:58 +00001059halting condition (as C), Python's
1060\keyword{for}\stindex{for} statement iterates over the items of any
1061sequence (e.g., a list or a string), in the order that they appear in
1062the sequence. For example (no pun intended):
Fred Drakef790b161998-11-30 20:37:24 +00001063% One suggestion was to give a real C example here, but that may only
1064% serve to confuse non-C programmers.
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001065
Fred Drake8842e861998-02-13 07:16:30 +00001066\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001067>>> # Measure some strings:
Guido van Rossum6938f061994-08-01 12:22:53 +00001068... a = ['cat', 'window', 'defenestrate']
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001069>>> for x in a:
1070... print x, len(x)
1071...
1072cat 3
1073window 6
1074defenestrate 12
Fred Drake8842e861998-02-13 07:16:30 +00001075\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001076
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001077It is not safe to modify the sequence being iterated over in the loop
1078(this can only happen for mutable sequence types, i.e., lists). If
1079you need to modify the list you are iterating over, e.g., duplicate
1080selected items, you must iterate over a copy. The slice notation
1081makes this particularly convenient:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001082
Fred Drake8842e861998-02-13 07:16:30 +00001083\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001084>>> for x in a[:]: # make a slice copy of the entire list
1085... if len(x) > 6: a.insert(0, x)
1086...
1087>>> a
1088['defenestrate', 'cat', 'window', 'defenestrate']
Fred Drake8842e861998-02-13 07:16:30 +00001089\end{verbatim}
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001090
Fred Drakeb7833d31998-09-11 16:21:55 +00001091
1092\section{The \function{range()} Function \label{range}}
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001093
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001094If you do need to iterate over a sequence of numbers, the built-in
Fred Drake8842e861998-02-13 07:16:30 +00001095function \function{range()} comes in handy. It generates lists
1096containing arithmetic progressions, e.g.:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001097
Fred Drake8842e861998-02-13 07:16:30 +00001098\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001099>>> range(10)
1100[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
Fred Drake8842e861998-02-13 07:16:30 +00001101\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001102
Fred Drake8842e861998-02-13 07:16:30 +00001103The given end point is never part of the generated list;
1104\code{range(10)} generates a list of 10 values, exactly the legal
1105indices for items of a sequence of length 10. It is possible to let
1106the range start at another number, or to specify a different increment
Fred Drake20082d92000-04-03 04:26:58 +00001107(even negative; sometimes this is called the `step'):
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001108
Fred Drake8842e861998-02-13 07:16:30 +00001109\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001110>>> range(5, 10)
1111[5, 6, 7, 8, 9]
1112>>> range(0, 10, 3)
1113[0, 3, 6, 9]
1114>>> range(-10, -100, -30)
1115[-10, -40, -70]
Fred Drake8842e861998-02-13 07:16:30 +00001116\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001117
Fred Drake20082d92000-04-03 04:26:58 +00001118To iterate over the indices of a sequence, combine
1119\function{range()} and \function{len()} as follows:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001120
Fred Drake8842e861998-02-13 07:16:30 +00001121\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001122>>> a = ['Mary', 'had', 'a', 'little', 'lamb']
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001123>>> for i in range(len(a)):
1124... print i, a[i]
1125...
11260 Mary
11271 had
11282 a
11293 little
Guido van Rossum6fc178f1991-08-16 09:13:42 +000011304 lamb
Fred Drake8842e861998-02-13 07:16:30 +00001131\end{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001132
Fred Drake20082d92000-04-03 04:26:58 +00001133
Fred Drake391564f1998-04-01 23:11:56 +00001134\section{\keyword{break} and \keyword{continue} Statements, and
Fred Drakeb7833d31998-09-11 16:21:55 +00001135 \keyword{else} Clauses on Loops
1136 \label{break}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001137
Fred Drakeee84d591999-03-10 17:25:30 +00001138The \keyword{break} statement, like in C, breaks out of the smallest
Fred Drake8842e861998-02-13 07:16:30 +00001139enclosing \keyword{for} or \keyword{while} loop.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001140
Fred Drakeee84d591999-03-10 17:25:30 +00001141The \keyword{continue} statement, also borrowed from C, continues
Fred Drake8842e861998-02-13 07:16:30 +00001142with the next iteration of the loop.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001143
Fred Drake8842e861998-02-13 07:16:30 +00001144Loop statements may have an \code{else} clause; it is executed when
1145the loop terminates through exhaustion of the list (with
1146\keyword{for}) or when the condition becomes false (with
1147\keyword{while}), but not when the loop is terminated by a
1148\keyword{break} statement. This is exemplified by the following loop,
1149which searches for prime numbers:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001150
Fred Drake8842e861998-02-13 07:16:30 +00001151\begin{verbatim}
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001152>>> for n in range(2, 10):
1153... for x in range(2, n):
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001154... if n % x == 0:
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001155... print n, 'equals', x, '*', n/x
1156... break
1157... else:
1158... print n, 'is a prime number'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001159...
Guido van Rossum2292b8e1991-01-23 16:31:24 +000011602 is a prime number
11613 is a prime number
11624 equals 2 * 2
11635 is a prime number
11646 equals 2 * 3
11657 is a prime number
11668 equals 2 * 4
11679 equals 3 * 3
Fred Drake8842e861998-02-13 07:16:30 +00001168\end{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001169
Fred Drake31b761e2000-09-29 15:17:36 +00001170
Fred Drakeb7833d31998-09-11 16:21:55 +00001171\section{\keyword{pass} Statements \label{pass}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001172
Fred Drake8842e861998-02-13 07:16:30 +00001173The \keyword{pass} statement does nothing.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001174It can be used when a statement is required syntactically but the
1175program requires no action.
1176For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001177
Fred Drake8842e861998-02-13 07:16:30 +00001178\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001179>>> while 1:
1180... pass # Busy-wait for keyboard interrupt
1181...
Fred Drake8842e861998-02-13 07:16:30 +00001182\end{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001183
Fred Drake31b761e2000-09-29 15:17:36 +00001184
Fred Drakeb7833d31998-09-11 16:21:55 +00001185\section{Defining Functions \label{functions}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001186
1187We can create a function that writes the Fibonacci series to an
1188arbitrary boundary:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001189
Fred Drake8842e861998-02-13 07:16:30 +00001190\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001191>>> def fib(n): # write Fibonacci series up to n
Guido van Rossum02455691997-07-17 16:21:52 +00001192... "Print a Fibonacci series up to n"
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001193... a, b = 0, 1
Guido van Rossum16cd7f91994-10-06 10:29:26 +00001194... while b < n:
Fred Drakeeee08cd1997-12-04 15:43:15 +00001195... print b,
1196... a, b = b, a+b
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001197...
1198>>> # Now call the function we just defined:
Guido van Rossum6938f061994-08-01 12:22:53 +00001199... fib(2000)
Guido van Rossumd9bf55d1991-01-11 16:35:08 +000012001 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597
Fred Drake8842e861998-02-13 07:16:30 +00001201\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001202
Fred Drake8842e861998-02-13 07:16:30 +00001203The keyword \keyword{def} introduces a function \emph{definition}. It
1204must be followed by the function name and the parenthesized list of
1205formal parameters. The statements that form the body of the function
Fred Drake20082d92000-04-03 04:26:58 +00001206start at the next line, and must be indented. The first statement of
1207the function body can optionally be a string literal; this string
1208literal is the function's \index{documentation strings}documentation
1209string, or \dfn{docstring}.\index{docstrings}\index{strings, documentation}
1210
1211There are tools which use docstrings to automatically produce online
1212or printed documentation, or to let the user interactively browse
1213through code; it's good practice to include docstrings in code that
1214you write, so try to make a habit of it.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001215
Fred Drakeeee08cd1997-12-04 15:43:15 +00001216The \emph{execution} of a function introduces a new symbol table used
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001217for the local variables of the function. More precisely, all variable
1218assignments in a function store the value in the local symbol table;
Guido van Rossum02455691997-07-17 16:21:52 +00001219whereas variable references first look in the local symbol table, then
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001220in the global symbol table, and then in the table of built-in names.
Fred Drake8842e861998-02-13 07:16:30 +00001221Thus, global variables cannot be directly assigned a value within a
1222function (unless named in a \keyword{global} statement), although
Guido van Rossum6938f061994-08-01 12:22:53 +00001223they may be referenced.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001224
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001225The actual parameters (arguments) to a function call are introduced in
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001226the local symbol table of the called function when it is called; thus,
Fred Drake20082d92000-04-03 04:26:58 +00001227arguments are passed using \emph{call by value} (where the
1228\emph{value} is always an object \emph{reference}, not the value of
1229the object).\footnote{
Fred Drakeeee08cd1997-12-04 15:43:15 +00001230 Actually, \emph{call by object reference} would be a better
Guido van Rossum6938f061994-08-01 12:22:53 +00001231 description, since if a mutable object is passed, the caller
1232 will see any changes the callee makes to it (e.g., items
1233 inserted into a list).
Fred Drake20082d92000-04-03 04:26:58 +00001234} When a function calls another function, a new local symbol table is
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001235created for that call.
1236
Fred Drake8842e861998-02-13 07:16:30 +00001237A function definition introduces the function name in the current
1238symbol table. The value of the function name
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001239has a type that is recognized by the interpreter as a user-defined
1240function. This value can be assigned to another name which can then
1241also be used as a function. This serves as a general renaming
1242mechanism:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001243
Fred Drake8842e861998-02-13 07:16:30 +00001244\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001245>>> fib
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001246<function object at 10042ed0>
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001247>>> f = fib
1248>>> f(100)
12491 1 2 3 5 8 13 21 34 55 89
Fred Drake8842e861998-02-13 07:16:30 +00001250\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001251
Fred Drakeeee08cd1997-12-04 15:43:15 +00001252You might object that \code{fib} is not a function but a procedure. In
Fred Drakeee84d591999-03-10 17:25:30 +00001253Python, like in C, procedures are just functions that don't return a
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001254value. In fact, technically speaking, procedures do return a value,
Fred Drakeeee08cd1997-12-04 15:43:15 +00001255albeit a rather boring one. This value is called \code{None} (it's a
1256built-in name). Writing the value \code{None} is normally suppressed by
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001257the interpreter if it would be the only value written. You can see it
1258if you really want to:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001259
Fred Drake8842e861998-02-13 07:16:30 +00001260\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001261>>> print fib(0)
1262None
Fred Drake8842e861998-02-13 07:16:30 +00001263\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001264
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001265It is simple to write a function that returns a list of the numbers of
1266the Fibonacci series, instead of printing it:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001267
Fred Drake8842e861998-02-13 07:16:30 +00001268\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001269>>> def fib2(n): # return Fibonacci series up to n
Guido van Rossum02455691997-07-17 16:21:52 +00001270... "Return a list containing the Fibonacci series up to n"
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001271... result = []
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001272... a, b = 0, 1
Guido van Rossum16cd7f91994-10-06 10:29:26 +00001273... while b < n:
Fred Drakeeee08cd1997-12-04 15:43:15 +00001274... result.append(b) # see below
1275... a, b = b, a+b
Guido van Rossum2292b8e1991-01-23 16:31:24 +00001276... return result
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001277...
1278>>> f100 = fib2(100) # call it
1279>>> f100 # write the result
1280[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
Fred Drake8842e861998-02-13 07:16:30 +00001281\end{verbatim}
Fred Drake31b761e2000-09-29 15:17:36 +00001282
Guido van Rossum4410c751991-06-04 20:22:18 +00001283This example, as usual, demonstrates some new Python features:
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001284
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001285\begin{itemize}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001286
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001287\item
Fred Drake8842e861998-02-13 07:16:30 +00001288The \keyword{return} statement returns with a value from a function.
1289\keyword{return} without an expression argument is used to return from
Fred Drakeeee08cd1997-12-04 15:43:15 +00001290the middle of a procedure (falling off the end also returns from a
1291procedure), in which case the \code{None} value is returned.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001292
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001293\item
Fred Drakeeee08cd1997-12-04 15:43:15 +00001294The statement \code{result.append(b)} calls a \emph{method} of the list
1295object \code{result}. A method is a function that `belongs' to an
1296object and is named \code{obj.methodname}, where \code{obj} is some
1297object (this may be an expression), and \code{methodname} is the name
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001298of a method that is defined by the object's type. Different types
1299define different methods. Methods of different types may have the
1300same name without causing ambiguity. (It is possible to define your
Fred Drakeeee08cd1997-12-04 15:43:15 +00001301own object types and methods, using \emph{classes}, as discussed later
Guido van Rossum6938f061994-08-01 12:22:53 +00001302in this tutorial.)
Fred Drake8842e861998-02-13 07:16:30 +00001303The method \method{append()} shown in the example, is defined for
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001304list objects; it adds a new element at the end of the list. In this
Fred Drake8842e861998-02-13 07:16:30 +00001305example it is equivalent to \samp{result = result + [b]}, but more
1306efficient.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001307
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001308\end{itemize}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001309
Fred Drakeb7833d31998-09-11 16:21:55 +00001310\section{More on Defining Functions \label{defining}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00001311
Guido van Rossum02455691997-07-17 16:21:52 +00001312It is also possible to define functions with a variable number of
1313arguments. There are three forms, which can be combined.
1314
Fred Drakeb7833d31998-09-11 16:21:55 +00001315\subsection{Default Argument Values \label{defaultArgs}}
Guido van Rossum02455691997-07-17 16:21:52 +00001316
1317The most useful form is to specify a default value for one or more
1318arguments. This creates a function that can be called with fewer
1319arguments than it is defined, e.g.
1320
1321\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00001322def ask_ok(prompt, retries=4, complaint='Yes or no, please!'):
1323 while 1:
1324 ok = raw_input(prompt)
1325 if ok in ('y', 'ye', 'yes'): return 1
1326 if ok in ('n', 'no', 'nop', 'nope'): return 0
1327 retries = retries - 1
1328 if retries < 0: raise IOError, 'refusenik user'
1329 print complaint
Guido van Rossum02455691997-07-17 16:21:52 +00001330\end{verbatim}
1331
1332This function can be called either like this:
Fred Drakeeee08cd1997-12-04 15:43:15 +00001333\code{ask_ok('Do you really want to quit?')} or like this:
1334\code{ask_ok('OK to overwrite the file?', 2)}.
Guido van Rossum02455691997-07-17 16:21:52 +00001335
1336The default values are evaluated at the point of function definition
Fred Drakeeee08cd1997-12-04 15:43:15 +00001337in the \emph{defining} scope, so that e.g.
Guido van Rossum02455691997-07-17 16:21:52 +00001338
1339\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00001340i = 5
1341def f(arg = i): print arg
1342i = 6
1343f()
Guido van Rossum02455691997-07-17 16:21:52 +00001344\end{verbatim}
1345
Fred Drakeeee08cd1997-12-04 15:43:15 +00001346will print \code{5}.
Guido van Rossum02455691997-07-17 16:21:52 +00001347
Guido van Rossumaee5e261998-08-07 17:45:09 +00001348\strong{Important warning:} The default value is evaluated only once.
1349This makes a difference when the default is a mutable object such as a
1350list or dictionary. For example, the following function accumulates
1351the arguments passed to it on subsequent calls:
1352
1353\begin{verbatim}
1354def f(a, l = []):
1355 l.append(a)
Guido van Rossumc62cf361998-10-24 13:15:28 +00001356 return l
Guido van Rossumaee5e261998-08-07 17:45:09 +00001357print f(1)
1358print f(2)
1359print f(3)
1360\end{verbatim}
1361
1362This will print
1363
1364\begin{verbatim}
1365[1]
1366[1, 2]
1367[1, 2, 3]
1368\end{verbatim}
1369
1370If you don't want the default to be shared between subsequent calls,
1371you can write the function like this instead:
1372
1373\begin{verbatim}
1374def f(a, l = None):
1375 if l is None:
1376 l = []
1377 l.append(a)
Guido van Rossumc62cf361998-10-24 13:15:28 +00001378 return l
Guido van Rossumaee5e261998-08-07 17:45:09 +00001379\end{verbatim}
1380
Fred Drakeb7833d31998-09-11 16:21:55 +00001381\subsection{Keyword Arguments \label{keywordArgs}}
Guido van Rossum02455691997-07-17 16:21:52 +00001382
1383Functions can also be called using
Fred Drake8842e861998-02-13 07:16:30 +00001384keyword arguments of the form \samp{\var{keyword} = \var{value}}. For
Guido van Rossum02455691997-07-17 16:21:52 +00001385instance, the following function:
1386
1387\begin{verbatim}
1388def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
1389 print "-- This parrot wouldn't", action,
1390 print "if you put", voltage, "Volts through it."
1391 print "-- Lovely plumage, the", type
1392 print "-- It's", state, "!"
1393\end{verbatim}
1394
1395could be called in any of the following ways:
1396
1397\begin{verbatim}
1398parrot(1000)
1399parrot(action = 'VOOOOOM', voltage = 1000000)
1400parrot('a thousand', state = 'pushing up the daisies')
1401parrot('a million', 'bereft of life', 'jump')
1402\end{verbatim}
1403
1404but the following calls would all be invalid:
1405
1406\begin{verbatim}
1407parrot() # required argument missing
1408parrot(voltage=5.0, 'dead') # non-keyword argument following keyword
1409parrot(110, voltage=220) # duplicate value for argument
1410parrot(actor='John Cleese') # unknown keyword
1411\end{verbatim}
1412
1413In general, an argument list must have any positional arguments
1414followed by any keyword arguments, where the keywords must be chosen
1415from the formal parameter names. It's not important whether a formal
Fred Drakef1ad2071999-06-30 15:32:50 +00001416parameter has a default value or not. No argument may receive a
Guido van Rossum02455691997-07-17 16:21:52 +00001417value more than once --- formal parameter names corresponding to
1418positional arguments cannot be used as keywords in the same calls.
Fred Drakef1ad2071999-06-30 15:32:50 +00001419Here's an example that fails due to this restriction:
1420
1421\begin{verbatim}
1422>>> def function(a):
1423... pass
1424...
1425>>> function(0, a=0)
1426Traceback (innermost last):
1427 File "<stdin>", line 1, in ?
1428TypeError: keyword parameter redefined
1429\end{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00001430
1431When a final formal parameter of the form \code{**\var{name}} is
1432present, it receives a dictionary containing all keyword arguments
1433whose keyword doesn't correspond to a formal parameter. This may be
Fred Drake20082d92000-04-03 04:26:58 +00001434combined with a formal parameter of the form
1435\code{*\var{name}} (described in the next subsection) which receives a
1436tuple containing the positional arguments beyond the formal parameter
1437list. (\code{*\var{name}} must occur before \code{**\var{name}}.)
1438For example, if we define a function like this:
Guido van Rossum02455691997-07-17 16:21:52 +00001439
1440\begin{verbatim}
1441def cheeseshop(kind, *arguments, **keywords):
1442 print "-- Do you have any", kind, '?'
1443 print "-- I'm sorry, we're all out of", kind
1444 for arg in arguments: print arg
1445 print '-'*40
1446 for kw in keywords.keys(): print kw, ':', keywords[kw]
1447\end{verbatim}
1448
1449It could be called like this:
1450
1451\begin{verbatim}
1452cheeseshop('Limburger', "It's very runny, sir.",
1453 "It's really very, VERY runny, sir.",
1454 client='John Cleese',
1455 shopkeeper='Michael Palin',
1456 sketch='Cheese Shop Sketch')
1457\end{verbatim}
1458
1459and of course it would print:
1460
1461\begin{verbatim}
1462-- Do you have any Limburger ?
1463-- I'm sorry, we're all out of Limburger
1464It's very runny, sir.
1465It's really very, VERY runny, sir.
1466----------------------------------------
1467client : John Cleese
1468shopkeeper : Michael Palin
1469sketch : Cheese Shop Sketch
1470\end{verbatim}
1471
Fred Drake31b761e2000-09-29 15:17:36 +00001472
Fred Drakeb7833d31998-09-11 16:21:55 +00001473\subsection{Arbitrary Argument Lists \label{arbitraryArgs}}
Guido van Rossum02455691997-07-17 16:21:52 +00001474
1475Finally, the least frequently used option is to specify that a
1476function can be called with an arbitrary number of arguments. These
1477arguments will be wrapped up in a tuple. Before the variable number
1478of arguments, zero or more normal arguments may occur.
1479
1480\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00001481def fprintf(file, format, *args):
1482 file.write(format % args)
Guido van Rossum02455691997-07-17 16:21:52 +00001483\end{verbatim}
1484
Fred Drakea594baf1998-04-03 05:16:31 +00001485
Fred Drakeb7833d31998-09-11 16:21:55 +00001486\subsection{Lambda Forms \label{lambda}}
Fred Drakea594baf1998-04-03 05:16:31 +00001487
1488By popular demand, a few features commonly found in functional
1489programming languages and Lisp have been added to Python. With the
1490\keyword{lambda} keyword, small anonymous functions can be created.
1491Here's a function that returns the sum of its two arguments:
1492\samp{lambda a, b: a+b}. Lambda forms can be used wherever function
1493objects are required. They are syntactically restricted to a single
1494expression. Semantically, they are just syntactic sugar for a normal
1495function definition. Like nested function definitions, lambda forms
1496cannot reference variables from the containing scope, but this can be
1497overcome through the judicious use of default argument values, e.g.
1498
1499\begin{verbatim}
1500def make_incrementor(n):
1501 return lambda x, incr=n: x+incr
1502\end{verbatim}
1503
Fred Drake20082d92000-04-03 04:26:58 +00001504
Fred Drakeb7833d31998-09-11 16:21:55 +00001505\subsection{Documentation Strings \label{docstrings}}
Fred Drakea594baf1998-04-03 05:16:31 +00001506
1507There are emerging conventions about the content and formatting of
1508documentation strings.
Fred Drake20082d92000-04-03 04:26:58 +00001509\index{docstrings}\index{documentation strings}
1510\index{strings, documentation}
Fred Drakea594baf1998-04-03 05:16:31 +00001511
1512The first line should always be a short, concise summary of the
1513object's purpose. For brevity, it should not explicitly state the
1514object's name or type, since these are available by other means
1515(except if the name happens to be a verb describing a function's
1516operation). This line should begin with a capital letter and end with
1517a period.
1518
1519If there are more lines in the documentation string, the second line
1520should be blank, visually separating the summary from the rest of the
Fred Drake4b1a07a1999-03-12 18:21:32 +00001521description. The following lines should be one or more paragraphs
1522describing the object's calling conventions, its side effects, etc.
Fred Drakea594baf1998-04-03 05:16:31 +00001523
1524The Python parser does not strip indentation from multi-line string
1525literals in Python, so tools that process documentation have to strip
Fred Drake20082d92000-04-03 04:26:58 +00001526indentation if desired. This is done using the following convention.
1527The first non-blank line \emph{after} the first line of the string
1528determines the amount of indentation for the entire documentation
1529string. (We can't use the first line since it is generally adjacent
1530to the string's opening quotes so its indentation is not apparent in
1531the string literal.) Whitespace ``equivalent'' to this indentation is
1532then stripped from the start of all lines of the string. Lines that
1533are indented less should not occur, but if they occur all their
1534leading whitespace should be stripped. Equivalence of whitespace
1535should be tested after expansion of tabs (to 8 spaces, normally).
1536
1537Here is an example of a multi-line docstring:
1538
1539\begin{verbatim}
1540>>> def my_function():
1541... """Do nothing, but document it.
1542...
1543... No, really, it doesn't do anything.
1544... """
1545... pass
1546...
1547>>> print my_function.__doc__
1548Do nothing, but document it.
1549
1550 No, really, it doesn't do anything.
1551
1552\end{verbatim}
Fred Drakea594baf1998-04-03 05:16:31 +00001553
1554
1555
Fred Drakeb7833d31998-09-11 16:21:55 +00001556\chapter{Data Structures \label{structures}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001557
1558This chapter describes some things you've learned about already in
1559more detail, and adds some new things as well.
1560
Fred Drake20082d92000-04-03 04:26:58 +00001561
Fred Drakeb7833d31998-09-11 16:21:55 +00001562\section{More on Lists \label{moreLists}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001563
1564The list data type has some more methods. Here are all of the methods
Fred Drakeed688541998-02-11 22:29:17 +00001565of list objects:
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001566
Guido van Rossum7d9f8d71991-01-22 11:45:00 +00001567\begin{description}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001568
Fred Drake20082d92000-04-03 04:26:58 +00001569\item[\code{append(x)}]
1570Add an item to the end of the list;
1571equivalent to \code{a[len(a):] = [x]}.
1572
1573\item[\code{extend(L)}]
1574Extend the list by appending all the items in the given list;
1575equivalent to \code{a[len(a):] = L}.
1576
Fred Drakeeee08cd1997-12-04 15:43:15 +00001577\item[\code{insert(i, x)}]
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001578Insert an item at a given position. The first argument is the index of
Fred Drakeeee08cd1997-12-04 15:43:15 +00001579the element before which to insert, so \code{a.insert(0, x)} inserts at
1580the front of the list, and \code{a.insert(len(a), x)} is equivalent to
1581\code{a.append(x)}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001582
Fred Drake20082d92000-04-03 04:26:58 +00001583\item[\code{remove(x)}]
1584Remove the first item from the list whose value is \code{x}.
1585It is an error if there is no such item.
1586
1587\item[\code{pop(\optional{i})}]
1588Remove the item at the given position in the list, and return it. If
1589no index is specified, \code{a.pop()} returns the last item in the
1590list. The item is also removed from the list.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001591
Fred Drakeeee08cd1997-12-04 15:43:15 +00001592\item[\code{index(x)}]
1593Return the index in the list of the first item whose value is \code{x}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001594It is an error if there is no such item.
1595
Fred Drake20082d92000-04-03 04:26:58 +00001596\item[\code{count(x)}]
1597Return the number of times \code{x} appears in the list.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001598
Fred Drakeeee08cd1997-12-04 15:43:15 +00001599\item[\code{sort()}]
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001600Sort the items of the list, in place.
1601
Fred Drakeeee08cd1997-12-04 15:43:15 +00001602\item[\code{reverse()}]
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001603Reverse the elements of the list, in place.
1604
Guido van Rossum7d9f8d71991-01-22 11:45:00 +00001605\end{description}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001606
Fred Drake20082d92000-04-03 04:26:58 +00001607An example that uses most of the list methods:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001608
Fred Drake8842e861998-02-13 07:16:30 +00001609\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001610>>> a = [66.6, 333, 333, 1, 1234.5]
Guido van Rossum6938f061994-08-01 12:22:53 +00001611>>> print a.count(333), a.count(66.6), a.count('x')
16122 1 0
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001613>>> a.insert(2, -1)
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001614>>> a.append(333)
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001615>>> a
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001616[66.6, 333, -1, 333, 1, 1234.5, 333]
1617>>> a.index(333)
16181
1619>>> a.remove(333)
1620>>> a
1621[66.6, -1, 333, 1, 1234.5, 333]
1622>>> a.reverse()
1623>>> a
1624[333, 1234.5, 1, 333, -1, 66.6]
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001625>>> a.sort()
1626>>> a
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001627[-1, 1, 66.6, 333, 333, 1234.5]
Fred Drake8842e861998-02-13 07:16:30 +00001628\end{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001629
Fred Drake20082d92000-04-03 04:26:58 +00001630
1631\subsection{Using Lists as Stacks \label{lists-as-stacks}}
1632\sectionauthor{Ka-Ping Yee}{ping@lfs.org}
1633
1634The list methods make it very easy to use a list as a stack, where the
1635last element added is the first element retrieved (``last-in,
1636first-out''). To add an item to the top of the stack, use
1637\method{append()}. To retrieve an item from the top of the stack, use
1638\method{pop()} without an explicit index. For example:
1639
1640\begin{verbatim}
1641>>> stack = [3, 4, 5]
1642>>> stack.append(6)
1643>>> stack.append(7)
1644>>> stack
1645[3, 4, 5, 6, 7]
1646>>> stack.pop()
16477
1648>>> stack
1649[3, 4, 5, 6]
1650>>> stack.pop()
16516
1652>>> stack.pop()
16535
1654>>> stack
1655[3, 4]
1656\end{verbatim}
1657
1658
1659\subsection{Using Lists as Queues \label{lists-as-queues}}
1660\sectionauthor{Ka-Ping Yee}{ping@lfs.org}
1661
1662You can also use a list conveniently as a queue, where the first
1663element added is the first element retrieved (``first-in,
1664first-out''). To add an item to the back of the queue, use
1665\method{append()}. To retrieve an item from the front of the queue,
1666use \method{pop()} with \code{0} as the index. For example:
1667
1668\begin{verbatim}
1669>>> queue = ["Eric", "John", "Michael"]
1670>>> queue.append("Terry") # Terry arrives
1671>>> queue.append("Graham") # Graham arrives
1672>>> queue.pop(0)
1673'Eric'
1674>>> queue.pop(0)
1675'John'
1676>>> queue
1677['Michael', 'Terry', 'Graham']
1678\end{verbatim}
1679
1680
Fred Drakeb7833d31998-09-11 16:21:55 +00001681\subsection{Functional Programming Tools \label{functional}}
Guido van Rossum02455691997-07-17 16:21:52 +00001682
1683There are three built-in functions that are very useful when used with
Fred Drake8842e861998-02-13 07:16:30 +00001684lists: \function{filter()}, \function{map()}, and \function{reduce()}.
Guido van Rossum02455691997-07-17 16:21:52 +00001685
Fred Drake8842e861998-02-13 07:16:30 +00001686\samp{filter(\var{function}, \var{sequence})} returns a sequence (of
1687the same type, if possible) consisting of those items from the
1688sequence for which \code{\var{function}(\var{item})} is true. For
1689example, to compute some primes:
Guido van Rossum02455691997-07-17 16:21:52 +00001690
1691\begin{verbatim}
Fred Drakeee84d591999-03-10 17:25:30 +00001692>>> def f(x): return x % 2 != 0 and x % 3 != 0
Fred Drake8842e861998-02-13 07:16:30 +00001693...
1694>>> filter(f, range(2, 25))
1695[5, 7, 11, 13, 17, 19, 23]
Guido van Rossum02455691997-07-17 16:21:52 +00001696\end{verbatim}
1697
Fred Drake8842e861998-02-13 07:16:30 +00001698\samp{map(\var{function}, \var{sequence})} calls
1699\code{\var{function}(\var{item})} for each of the sequence's items and
1700returns a list of the return values. For example, to compute some
1701cubes:
Guido van Rossum02455691997-07-17 16:21:52 +00001702
1703\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00001704>>> def cube(x): return x*x*x
1705...
1706>>> map(cube, range(1, 11))
1707[1, 8, 27, 64, 125, 216, 343, 512, 729, 1000]
Guido van Rossum02455691997-07-17 16:21:52 +00001708\end{verbatim}
1709
1710More than one sequence may be passed; the function must then have as
1711many arguments as there are sequences and is called with the
Fred Drake8842e861998-02-13 07:16:30 +00001712corresponding item from each sequence (or \code{None} if some sequence
1713is shorter than another). If \code{None} is passed for the function,
Guido van Rossum02455691997-07-17 16:21:52 +00001714a function returning its argument(s) is substituted.
1715
1716Combining these two special cases, we see that
Fred Drake8842e861998-02-13 07:16:30 +00001717\samp{map(None, \var{list1}, \var{list2})} is a convenient way of
1718turning a pair of lists into a list of pairs. For example:
Guido van Rossum02455691997-07-17 16:21:52 +00001719
1720\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00001721>>> seq = range(8)
1722>>> def square(x): return x*x
1723...
1724>>> map(None, seq, map(square, seq))
1725[(0, 0), (1, 1), (2, 4), (3, 9), (4, 16), (5, 25), (6, 36), (7, 49)]
Guido van Rossum02455691997-07-17 16:21:52 +00001726\end{verbatim}
1727
Fred Drake8842e861998-02-13 07:16:30 +00001728\samp{reduce(\var{func}, \var{sequence})} returns a single value
1729constructed by calling the binary function \var{func} on the first two
1730items of the sequence, then on the result and the next item, and so
1731on. For example, to compute the sum of the numbers 1 through 10:
Guido van Rossum02455691997-07-17 16:21:52 +00001732
1733\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00001734>>> def add(x,y): return x+y
1735...
1736>>> reduce(add, range(1, 11))
173755
Guido van Rossum02455691997-07-17 16:21:52 +00001738\end{verbatim}
1739
1740If there's only one item in the sequence, its value is returned; if
1741the sequence is empty, an exception is raised.
1742
1743A third argument can be passed to indicate the starting value. In this
1744case the starting value is returned for an empty sequence, and the
1745function is first applied to the starting value and the first sequence
1746item, then to the result and the next item, and so on. For example,
1747
1748\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00001749>>> def sum(seq):
1750... def add(x,y): return x+y
1751... return reduce(add, seq, 0)
1752...
1753>>> sum(range(1, 11))
175455
1755>>> sum([])
17560
Guido van Rossum02455691997-07-17 16:21:52 +00001757\end{verbatim}
1758
Fred Drake31b761e2000-09-29 15:17:36 +00001759
Skip Montanaro803d6e52000-08-12 18:09:51 +00001760\subsection{List Comprehensions}
1761
Skip Montanaro46dfa5f2000-08-22 02:43:07 +00001762List comprehensions provide a concise way to create lists without resorting
1763to use of \function{map()}, \function{filter()} and/or \keyword{lambda}.
1764The resulting list definition tends often to be clearer than lists built
1765using those constructs. Each list comprehension consists of an expression
1766following by a \keyword{for} clause, then zero or more \keyword{for} or
1767\keyword{if} clauses. The result will be a list resulting from evaluating
1768the expression in the context of the \keyword{for} and \keyword{if} clauses
1769which follow it. If the expression would evaluate to a tuple, it must be
1770parenthesized.
Skip Montanaro803d6e52000-08-12 18:09:51 +00001771
1772\begin{verbatim}
Fred Drake1aebadf2000-08-16 21:44:03 +00001773>>> freshfruit = [' banana', ' loganberry ', 'passion fruit ']
1774>>> [weapon.strip() for weapon in freshfruit]
1775['banana', 'loganberry', 'passion fruit']
Skip Montanaro803d6e52000-08-12 18:09:51 +00001776>>> vec = [2, 4, 6]
Fred Drake1aebadf2000-08-16 21:44:03 +00001777>>> [3*x for x in vec]
Skip Montanaro803d6e52000-08-12 18:09:51 +00001778[6, 12, 18]
Fred Drake1aebadf2000-08-16 21:44:03 +00001779>>> [3*x for x in vec if x > 3]
1780[12, 18]
1781>>> [3*x for x in vec if x < 2]
1782[]
Skip Montanaro46dfa5f2000-08-22 02:43:07 +00001783>>> [{x: x**2} for x in vec]
1784[{2: 4}, {4: 16}, {6: 36}]
1785>>> [[x,x**2] for x in vec]
1786[[2, 4], [4, 16], [6, 36]]
1787>>> [x, x**2 for x in vec] # error - parens required for tuples
1788 File "<stdin>", line 1
1789 [x, x**2 for x in vec]
1790 ^
1791SyntaxError: invalid syntax
1792>>> [(x, x**2) for x in vec]
1793[(2, 4), (4, 16), (6, 36)]
Skip Montanaro803d6e52000-08-12 18:09:51 +00001794>>> vec1 = [2, 4, 6]
1795>>> vec2 = [4, 3, -9]
Fred Drake1aebadf2000-08-16 21:44:03 +00001796>>> [x*y for x in vec1 for y in vec2]
Skip Montanaro803d6e52000-08-12 18:09:51 +00001797[8, 6, -18, 16, 12, -36, 24, 18, -54]
Fred Drake1aebadf2000-08-16 21:44:03 +00001798>>> [x+y for x in vec1 for y in vec2]
Skip Montanaro803d6e52000-08-12 18:09:51 +00001799[6, 5, -7, 8, 7, -5, 10, 9, -3]
1800\end{verbatim}
1801
Fred Drake31b761e2000-09-29 15:17:36 +00001802
Fred Drakeb7833d31998-09-11 16:21:55 +00001803\section{The \keyword{del} statement \label{del}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001804
1805There is a way to remove an item from a list given its index instead
Fred Drake81f7eb62000-08-12 20:08:04 +00001806of its value: the \keyword{del} statement. This can also be used to
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001807remove slices from a list (which we did earlier by assignment of an
1808empty list to the slice). For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001809
Fred Drake8842e861998-02-13 07:16:30 +00001810\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001811>>> a
1812[-1, 1, 66.6, 333, 333, 1234.5]
1813>>> del a[0]
1814>>> a
1815[1, 66.6, 333, 333, 1234.5]
1816>>> del a[2:4]
1817>>> a
1818[1, 66.6, 1234.5]
Fred Drake8842e861998-02-13 07:16:30 +00001819\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001820
1821\keyword{del} can also be used to delete entire variables:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001822
Fred Drake8842e861998-02-13 07:16:30 +00001823\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001824>>> del a
Fred Drake8842e861998-02-13 07:16:30 +00001825\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001826
Fred Drakeeee08cd1997-12-04 15:43:15 +00001827Referencing the name \code{a} hereafter is an error (at least until
Fred Drake6c2176e1998-02-26 21:47:54 +00001828another value is assigned to it). We'll find other uses for
1829\keyword{del} later.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001830
Fred Drake31b761e2000-09-29 15:17:36 +00001831
Fred Drakeb7833d31998-09-11 16:21:55 +00001832\section{Tuples and Sequences \label{tuples}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001833
1834We saw that lists and strings have many common properties, e.g.,
Fred Drakeeee08cd1997-12-04 15:43:15 +00001835indexing and slicing operations. They are two examples of
1836\emph{sequence} data types. Since Python is an evolving language,
1837other sequence data types may be added. There is also another
1838standard sequence data type: the \emph{tuple}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001839
1840A tuple consists of a number of values separated by commas, for
1841instance:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001842
Fred Drake8842e861998-02-13 07:16:30 +00001843\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001844>>> t = 12345, 54321, 'hello!'
1845>>> t[0]
184612345
1847>>> t
1848(12345, 54321, 'hello!')
1849>>> # Tuples may be nested:
Guido van Rossum6938f061994-08-01 12:22:53 +00001850... u = t, (1, 2, 3, 4, 5)
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001851>>> u
1852((12345, 54321, 'hello!'), (1, 2, 3, 4, 5))
Fred Drake8842e861998-02-13 07:16:30 +00001853\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001854
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001855As you see, on output tuples are alway enclosed in parentheses, so
1856that nested tuples are interpreted correctly; they may be input with
1857or without surrounding parentheses, although often parentheses are
1858necessary anyway (if the tuple is part of a larger expression).
1859
1860Tuples have many uses, e.g., (x, y) coordinate pairs, employee records
1861from a database, etc. Tuples, like strings, are immutable: it is not
1862possible to assign to the individual items of a tuple (you can
1863simulate much of the same effect with slicing and concatenation,
Fred Drake31b761e2000-09-29 15:17:36 +00001864though). It is also possible to create tuples which contain mutable
1865objects, such as lists.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001866
1867A special problem is the construction of tuples containing 0 or 1
Guido van Rossum6938f061994-08-01 12:22:53 +00001868items: the syntax has some extra quirks to accommodate these. Empty
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001869tuples are constructed by an empty pair of parentheses; a tuple with
1870one item is constructed by following a value with a comma
1871(it is not sufficient to enclose a single value in parentheses).
1872Ugly, but effective. For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001873
Fred Drake8842e861998-02-13 07:16:30 +00001874\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001875>>> empty = ()
1876>>> singleton = 'hello', # <-- note trailing comma
1877>>> len(empty)
18780
1879>>> len(singleton)
18801
1881>>> singleton
1882('hello',)
Fred Drake8842e861998-02-13 07:16:30 +00001883\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001884
Fred Drakeeee08cd1997-12-04 15:43:15 +00001885The statement \code{t = 12345, 54321, 'hello!'} is an example of
1886\emph{tuple packing}: the values \code{12345}, \code{54321} and
1887\code{'hello!'} are packed together in a tuple. The reverse operation
1888is also possible, e.g.:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00001889
Fred Drake8842e861998-02-13 07:16:30 +00001890\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001891>>> x, y, z = t
Fred Drake8842e861998-02-13 07:16:30 +00001892\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00001893
Fred Drake31b761e2000-09-29 15:17:36 +00001894This is called, appropriately enough, \emph{sequence unpacking}.
1895Sequence unpacking requires that the list of variables on the left
1896have the same number of elements as the length of the sequence. Note
1897that multiple assignment is really just a combination of tuple packing
1898and sequence unpacking!
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001899
Fred Drake31b761e2000-09-29 15:17:36 +00001900There is a small bit of asymmetry here: packing multiple values
1901always creates a tuple, and unpacking works for any sequence.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001902
Guido van Rossumaee5e261998-08-07 17:45:09 +00001903% XXX Add a bit on the difference between tuples and lists.
Fred Drake31b761e2000-09-29 15:17:36 +00001904
Guido van Rossumaee5e261998-08-07 17:45:09 +00001905
Fred Drakeb7833d31998-09-11 16:21:55 +00001906\section{Dictionaries \label{dictionaries}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001907
Fred Drakeeee08cd1997-12-04 15:43:15 +00001908Another useful data type built into Python is the \emph{dictionary}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001909Dictionaries are sometimes found in other languages as ``associative
1910memories'' or ``associative arrays''. Unlike sequences, which are
Fred Drakeeee08cd1997-12-04 15:43:15 +00001911indexed by a range of numbers, dictionaries are indexed by \emph{keys},
Fred Drakef1ad2071999-06-30 15:32:50 +00001912which can be any immutable type; strings and numbers can always be
Guido van Rossum02455691997-07-17 16:21:52 +00001913keys. Tuples can be used as keys if they contain only strings,
Fred Drake31b761e2000-09-29 15:17:36 +00001914numbers, or tuples; if a tuple contains any mutable object either
1915directly or indirectly, it cannot be used as a key. You can't use
1916lists as keys, since lists can be modified in place using their
1917\method{append()} and \method{extend()} methods, as well as slice and
1918indexed assignments.
Guido van Rossum02455691997-07-17 16:21:52 +00001919
Guido van Rossum6938f061994-08-01 12:22:53 +00001920It is best to think of a dictionary as an unordered set of
Fred Drake31b761e2000-09-29 15:17:36 +00001921\emph{key: value} pairs, with the requirement that the keys are unique
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001922(within one dictionary).
Fred Drakeeee08cd1997-12-04 15:43:15 +00001923A pair of braces creates an empty dictionary: \code{\{\}}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001924Placing a comma-separated list of key:value pairs within the
1925braces adds initial key:value pairs to the dictionary; this is also the
1926way dictionaries are written on output.
1927
1928The main operations on a dictionary are storing a value with some key
1929and extracting the value given the key. It is also possible to delete
1930a key:value pair
Fred Drakeeee08cd1997-12-04 15:43:15 +00001931with \code{del}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001932If you store using a key that is already in use, the old value
1933associated with that key is forgotten. It is an error to extract a
Guido van Rossum6938f061994-08-01 12:22:53 +00001934value using a non-existent key.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001935
Fred Drake20082d92000-04-03 04:26:58 +00001936The \code{keys()} method of a dictionary object returns a list of all
1937the keys used in the dictionary, in random order (if you want it
1938sorted, just apply the \code{sort()} method to the list of keys). To
1939check whether a single key is in the dictionary, use the
1940\code{has_key()} method of the dictionary.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001941
1942Here is a small example using a dictionary:
1943
Fred Drake8842e861998-02-13 07:16:30 +00001944\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001945>>> tel = {'jack': 4098, 'sape': 4139}
1946>>> tel['guido'] = 4127
1947>>> tel
Guido van Rossum8f96f771991-11-12 15:45:03 +00001948{'sape': 4139, 'guido': 4127, 'jack': 4098}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001949>>> tel['jack']
19504098
1951>>> del tel['sape']
1952>>> tel['irv'] = 4127
1953>>> tel
Guido van Rossum8f96f771991-11-12 15:45:03 +00001954{'guido': 4127, 'irv': 4127, 'jack': 4098}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001955>>> tel.keys()
1956['guido', 'irv', 'jack']
1957>>> tel.has_key('guido')
19581
Fred Drake8842e861998-02-13 07:16:30 +00001959\end{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00001960
Fred Drakeb7833d31998-09-11 16:21:55 +00001961\section{More on Conditions \label{conditions}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001962
Fred Drakeeee08cd1997-12-04 15:43:15 +00001963The conditions used in \code{while} and \code{if} statements above can
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001964contain other operators besides comparisons.
1965
Fred Drakeeee08cd1997-12-04 15:43:15 +00001966The comparison operators \code{in} and \code{not in} check whether a value
1967occurs (does not occur) in a sequence. The operators \code{is} and
1968\code{is not} compare whether two objects are really the same object; this
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001969only matters for mutable objects like lists. All comparison operators
1970have the same priority, which is lower than that of all numerical
1971operators.
1972
Fred Drakef1ad2071999-06-30 15:32:50 +00001973Comparisons can be chained: e.g., \code{a < b == c} tests whether
1974\code{a} is less than \code{b} and moreover \code{b} equals \code{c}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001975
Fred Drakeeee08cd1997-12-04 15:43:15 +00001976Comparisons may be combined by the Boolean operators \code{and} and
1977\code{or}, and the outcome of a comparison (or of any other Boolean
1978expression) may be negated with \code{not}. These all have lower
1979priorities than comparison operators again; between them, \code{not} has
1980the highest priority, and \code{or} the lowest, so that
1981\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 +00001982course, parentheses can be used to express the desired composition.
1983
Fred Drakeeee08cd1997-12-04 15:43:15 +00001984The Boolean operators \code{and} and \code{or} are so-called
1985\emph{shortcut} operators: their arguments are evaluated from left to
1986right, and evaluation stops as soon as the outcome is determined.
1987E.g., if \code{A} and \code{C} are true but \code{B} is false, \code{A
1988and B and C} does not evaluate the expression C. In general, the
1989return value of a shortcut operator, when used as a general value and
1990not as a Boolean, is the last evaluated argument.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00001991
1992It is possible to assign the result of a comparison or other Boolean
Guido van Rossum6938f061994-08-01 12:22:53 +00001993expression to a variable. For example,
1994
Fred Drake8842e861998-02-13 07:16:30 +00001995\begin{verbatim}
Guido van Rossum6938f061994-08-01 12:22:53 +00001996>>> string1, string2, string3 = '', 'Trondheim', 'Hammer Dance'
1997>>> non_null = string1 or string2 or string3
1998>>> non_null
1999'Trondheim'
Fred Drake8842e861998-02-13 07:16:30 +00002000\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002001
Fred Drakeee84d591999-03-10 17:25:30 +00002002Note that in Python, unlike C, assignment cannot occur inside expressions.
Fred Drake20082d92000-04-03 04:26:58 +00002003C programmers may grumble about this, but it avoids a common class of
2004problems encountered in C programs: typing \code{=} in an expression when
2005\code{==} was intended.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002006
Fred Drake31b761e2000-09-29 15:17:36 +00002007
Fred Drakeb7833d31998-09-11 16:21:55 +00002008\section{Comparing Sequences and Other Types \label{comparing}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002009
2010Sequence objects may be compared to other objects with the same
Fred Drakeeee08cd1997-12-04 15:43:15 +00002011sequence type. The comparison uses \emph{lexicographical} ordering:
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002012first the first two items are compared, and if they differ this
2013determines the outcome of the comparison; if they are equal, the next
2014two items are compared, and so on, until either sequence is exhausted.
2015If two items to be compared are themselves sequences of the same type,
Guido van Rossum6938f061994-08-01 12:22:53 +00002016the lexicographical comparison is carried out recursively. If all
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002017items of two sequences compare equal, the sequences are considered
2018equal. If one sequence is an initial subsequence of the other, the
2019shorted sequence is the smaller one. Lexicographical ordering for
Guido van Rossum47b4c0f1995-03-15 11:25:32 +00002020strings uses the \ASCII{} ordering for individual characters. Some
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002021examples of comparisons between sequences with the same types:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002022
Fred Drake8842e861998-02-13 07:16:30 +00002023\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002024(1, 2, 3) < (1, 2, 4)
2025[1, 2, 3] < [1, 2, 4]
2026'ABC' < 'C' < 'Pascal' < 'Python'
2027(1, 2, 3, 4) < (1, 2, 4)
2028(1, 2) < (1, 2, -1)
Fred Drake511281a1999-04-16 13:17:04 +00002029(1, 2, 3) == (1.0, 2.0, 3.0)
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002030(1, 2, ('aa', 'ab')) < (1, 2, ('abc', 'a'), 4)
Fred Drake8842e861998-02-13 07:16:30 +00002031\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002032
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002033Note that comparing objects of different types is legal. The outcome
2034is deterministic but arbitrary: the types are ordered by their name.
2035Thus, a list is always smaller than a string, a string is always
2036smaller than a tuple, etc. Mixed numeric types are compared according
Fred Drake93aa0f21999-04-05 21:39:17 +00002037to their numeric value, so 0 equals 0.0, etc.\footnote{
Guido van Rossum6938f061994-08-01 12:22:53 +00002038 The rules for comparing objects of different types should
2039 not be relied upon; they may change in a future version of
2040 the language.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002041}
2042
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002043
Fred Drakeb7833d31998-09-11 16:21:55 +00002044\chapter{Modules \label{modules}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002045
Guido van Rossum4410c751991-06-04 20:22:18 +00002046If you quit from the Python interpreter and enter it again, the
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002047definitions you have made (functions and variables) are lost.
2048Therefore, if you want to write a somewhat longer program, you are
2049better off using a text editor to prepare the input for the interpreter
Guido van Rossum16d6e711994-08-08 12:30:22 +00002050and running it with that file as input instead. This is known as creating a
Fred Drakeeee08cd1997-12-04 15:43:15 +00002051\emph{script}. As your program gets longer, you may want to split it
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002052into several files for easier maintenance. You may also want to use a
2053handy function that you've written in several programs without copying
2054its definition into each program.
2055
Guido van Rossum4410c751991-06-04 20:22:18 +00002056To support this, Python has a way to put definitions in a file and use
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002057them in a script or in an interactive instance of the interpreter.
Fred Drakeeee08cd1997-12-04 15:43:15 +00002058Such a file is called a \emph{module}; definitions from a module can be
2059\emph{imported} into other modules or into the \emph{main} module (the
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002060collection of variables that you have access to in a script
2061executed at the top level
2062and in calculator mode).
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002063
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002064A module is a file containing Python definitions and statements. The
Fred Drakeeee08cd1997-12-04 15:43:15 +00002065file name is the module name with the suffix \file{.py} appended. Within
Guido van Rossum6938f061994-08-01 12:22:53 +00002066a module, the module's name (as a string) is available as the value of
Fred Drakeeee08cd1997-12-04 15:43:15 +00002067the global variable \code{__name__}. For instance, use your favorite text
2068editor to create a file called \file{fibo.py} in the current directory
Guido van Rossum6938f061994-08-01 12:22:53 +00002069with the following contents:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002070
Fred Drake8842e861998-02-13 07:16:30 +00002071\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002072# Fibonacci numbers module
2073
2074def fib(n): # write Fibonacci series up to n
2075 a, b = 0, 1
Guido van Rossum16cd7f91994-10-06 10:29:26 +00002076 while b < n:
Fred Drakeeee08cd1997-12-04 15:43:15 +00002077 print b,
2078 a, b = b, a+b
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002079
2080def fib2(n): # return Fibonacci series up to n
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002081 result = []
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002082 a, b = 0, 1
Guido van Rossum16cd7f91994-10-06 10:29:26 +00002083 while b < n:
Fred Drakeeee08cd1997-12-04 15:43:15 +00002084 result.append(b)
2085 a, b = b, a+b
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002086 return result
Fred Drake8842e861998-02-13 07:16:30 +00002087\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002088
Guido van Rossum4410c751991-06-04 20:22:18 +00002089Now enter the Python interpreter and import this module with the
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002090following command:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002091
Fred Drake8842e861998-02-13 07:16:30 +00002092\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002093>>> import fibo
Fred Drake8842e861998-02-13 07:16:30 +00002094\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002095
Fred Drakef1ad2071999-06-30 15:32:50 +00002096This does not enter the names of the functions defined in \code{fibo}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002097directly in the current symbol table; it only enters the module name
Fred Drakef1ad2071999-06-30 15:32:50 +00002098\code{fibo} there.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002099Using the module name you can access the functions:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002100
Fred Drake8842e861998-02-13 07:16:30 +00002101\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002102>>> fibo.fib(1000)
21031 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
2104>>> fibo.fib2(100)
2105[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
Guido van Rossum6938f061994-08-01 12:22:53 +00002106>>> fibo.__name__
2107'fibo'
Fred Drake8842e861998-02-13 07:16:30 +00002108\end{verbatim}
Fred Drake31b761e2000-09-29 15:17:36 +00002109
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002110If you intend to use a function often you can assign it to a local name:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002111
Fred Drake8842e861998-02-13 07:16:30 +00002112\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002113>>> fib = fibo.fib
2114>>> fib(500)
21151 1 2 3 5 8 13 21 34 55 89 144 233 377
Fred Drake8842e861998-02-13 07:16:30 +00002116\end{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002117
Guido van Rossum02455691997-07-17 16:21:52 +00002118
Fred Drakeb7833d31998-09-11 16:21:55 +00002119\section{More on Modules \label{moreModules}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002120
2121A module can contain executable statements as well as function
Fred Drake20082d92000-04-03 04:26:58 +00002122definitions.
2123These statements are intended to initialize the module.
2124They are executed only the
2125\emph{first} time the module is imported somewhere.\footnote{
Guido van Rossum6938f061994-08-01 12:22:53 +00002126 In fact function definitions are also `statements' that are
2127 `executed'; the execution enters the function name in the
2128 module's global symbol table.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002129}
2130
2131Each module has its own private symbol table, which is used as the
2132global symbol table by all functions defined in the module.
2133Thus, the author of a module can use global variables in the module
2134without worrying about accidental clashes with a user's global
2135variables.
2136On the other hand, if you know what you are doing you can touch a
2137module's global variables with the same notation used to refer to its
2138functions,
Fred Drakeeee08cd1997-12-04 15:43:15 +00002139\code{modname.itemname}.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002140
Fred Drake20082d92000-04-03 04:26:58 +00002141Modules can import other modules. It is customary but not required to
2142place all \keyword{import} statements at the beginning of a module (or
2143script, for that matter). The imported module names are placed in the
2144importing module's global symbol table.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002145
Fred Drake20082d92000-04-03 04:26:58 +00002146There is a variant of the \keyword{import} statement that imports
2147names from a module directly into the importing module's symbol
2148table. For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002149
Fred Drake8842e861998-02-13 07:16:30 +00002150\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002151>>> from fibo import fib, fib2
2152>>> fib(500)
21531 1 2 3 5 8 13 21 34 55 89 144 233 377
Fred Drake8842e861998-02-13 07:16:30 +00002154\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002155
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002156This does not introduce the module name from which the imports are taken
Fred Drakeeee08cd1997-12-04 15:43:15 +00002157in the local symbol table (so in the example, \code{fibo} is not
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002158defined).
2159
2160There is even a variant to import all names that a module defines:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002161
Fred Drake8842e861998-02-13 07:16:30 +00002162\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002163>>> from fibo import *
2164>>> fib(500)
21651 1 2 3 5 8 13 21 34 55 89 144 233 377
Fred Drake8842e861998-02-13 07:16:30 +00002166\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002167
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002168This imports all names except those beginning with an underscore
Fred Drakeeee08cd1997-12-04 15:43:15 +00002169(\code{_}).
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002170
Guido van Rossum02455691997-07-17 16:21:52 +00002171
Fred Drake31b761e2000-09-29 15:17:36 +00002172\subsection{The Module Search Path \label{searchPath}}
Guido van Rossumaee5e261998-08-07 17:45:09 +00002173
Fred Drake391564f1998-04-01 23:11:56 +00002174\indexiii{module}{search}{path}
Fred Drake8842e861998-02-13 07:16:30 +00002175When a module named \module{spam} is imported, the interpreter searches
Fred Drakeeee08cd1997-12-04 15:43:15 +00002176for a file named \file{spam.py} in the current directory,
Guido van Rossum02455691997-07-17 16:21:52 +00002177and then in the list of directories specified by
Fred Drake391564f1998-04-01 23:11:56 +00002178the environment variable \envvar{PYTHONPATH}. This has the same syntax as
2179the shell variable \envvar{PATH}, i.e., a list of
2180directory names. When \envvar{PYTHONPATH} is not set, or when the file
Guido van Rossum02455691997-07-17 16:21:52 +00002181is not found there, the search continues in an installation-dependent
Fred Drake391564f1998-04-01 23:11:56 +00002182default path; on \UNIX{}, this is usually \file{.:/usr/local/lib/python}.
Guido van Rossum02455691997-07-17 16:21:52 +00002183
2184Actually, modules are searched in the list of directories given by the
Fred Drakeeee08cd1997-12-04 15:43:15 +00002185variable \code{sys.path} which is initialized from the directory
2186containing the input script (or the current directory),
Fred Drake391564f1998-04-01 23:11:56 +00002187\envvar{PYTHONPATH} and the installation-dependent default. This allows
Guido van Rossum02455691997-07-17 16:21:52 +00002188Python programs that know what they're doing to modify or replace the
2189module search path. See the section on Standard Modules later.
2190
2191\subsection{``Compiled'' Python files}
2192
2193As an important speed-up of the start-up time for short programs that
Fred Drakeeee08cd1997-12-04 15:43:15 +00002194use a lot of standard modules, if a file called \file{spam.pyc} exists
2195in the directory where \file{spam.py} is found, this is assumed to
Guido van Rossum13c8ef61998-05-29 19:12:23 +00002196contain an already-``byte-compiled'' version of the module \module{spam}.
Fred Drake8842e861998-02-13 07:16:30 +00002197The modification time of the version of \file{spam.py} used to create
Fred Drake20082d92000-04-03 04:26:58 +00002198\file{spam.pyc} is recorded in \file{spam.pyc}, and the
2199\file{.pyc} file is ignored if these don't match.
Guido van Rossum02455691997-07-17 16:21:52 +00002200
Fred Drake20082d92000-04-03 04:26:58 +00002201Normally, you don't need to do anything to create the
2202\file{spam.pyc} file. Whenever \file{spam.py} is successfully
2203compiled, an attempt is made to write the compiled version to
2204\file{spam.pyc}. It is not an error if this attempt fails; if for any
2205reason the file is not written completely, the resulting
2206\file{spam.pyc} file will be recognized as invalid and thus ignored
2207later. The contents of the \file{spam.pyc} file are platform
2208independent, so a Python module directory can be shared by machines of
2209different architectures.
Guido van Rossum02455691997-07-17 16:21:52 +00002210
Guido van Rossum13c8ef61998-05-29 19:12:23 +00002211Some tips for experts:
2212
2213\begin{itemize}
2214
2215\item
Fred Drake37f15741999-11-10 16:21:37 +00002216When the Python interpreter is invoked with the \programopt{-O} flag,
Guido van Rossum13c8ef61998-05-29 19:12:23 +00002217optimized code is generated and stored in \file{.pyo} files.
2218The optimizer currently doesn't help much; it only removes
2219\keyword{assert} statements and \code{SET_LINENO} instructions.
Fred Drake37f15741999-11-10 16:21:37 +00002220When \programopt{-O} is used, \emph{all} bytecode is optimized;
2221\code{.pyc} files are ignored and \code{.py} files are compiled to
2222optimized bytecode.
Guido van Rossum13c8ef61998-05-29 19:12:23 +00002223
2224\item
Fred Drake37f15741999-11-10 16:21:37 +00002225Passing two \programopt{-O} flags to the Python interpreter
2226(\programopt{-OO}) will cause the bytecode compiler to perform
2227optimizations that could in some rare cases result in malfunctioning
2228programs. Currently only \code{__doc__} strings are removed from the
2229bytecode, resulting in more compact \file{.pyo} files. Since some
2230programs may rely on having these available, you should only use this
2231option if you know what you're doing.
Guido van Rossum6b86a421999-01-28 15:07:47 +00002232
2233\item
Fred Drake20082d92000-04-03 04:26:58 +00002234A program doesn't run any faster when it is read from a \file{.pyc} or
2235\file{.pyo} file than when it is read from a \file{.py} file; the only
2236thing that's faster about \file{.pyc} or \file{.pyo} files is the
2237speed with which they are loaded.
Guido van Rossum13c8ef61998-05-29 19:12:23 +00002238
2239\item
Guido van Rossum002f7aa1998-06-28 19:16:38 +00002240When a script is run by giving its name on the command line, the
2241bytecode for the script is never written to a \file{.pyc} or
2242\file{.pyo} file. Thus, the startup time of a script may be reduced
2243by moving most of its code to a module and having a small bootstrap
Fred Drake31b761e2000-09-29 15:17:36 +00002244script that imports that module. It is also possible to name a
2245\file{.pyc} or \file{.pyo} file directly on the command line.
Guido van Rossum002f7aa1998-06-28 19:16:38 +00002246
2247\item
Guido van Rossum13c8ef61998-05-29 19:12:23 +00002248It is possible to have a file called \file{spam.pyc} (or
Fred Drake31b761e2000-09-29 15:17:36 +00002249\file{spam.pyo} when \programopt{-O} is used) without a file
2250\file{spam.py} for the same module. This can be used to distribute a
2251library of Python code in a form that is moderately hard to reverse
Guido van Rossum13c8ef61998-05-29 19:12:23 +00002252engineer.
2253
2254\item
2255The module \module{compileall}\refstmodindex{compileall} can create
Fred Drake37f15741999-11-10 16:21:37 +00002256\file{.pyc} files (or \file{.pyo} files when \programopt{-O} is used) for
Guido van Rossum13c8ef61998-05-29 19:12:23 +00002257all modules in a directory.
2258
2259\end{itemize}
2260
Guido van Rossum02455691997-07-17 16:21:52 +00002261
Fred Drakeb7833d31998-09-11 16:21:55 +00002262\section{Standard Modules \label{standardModules}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002263
Guido van Rossum4410c751991-06-04 20:22:18 +00002264Python comes with a library of standard modules, described in a separate
Fred Drake37f15741999-11-10 16:21:37 +00002265document, the \citetitle[../lib/lib.html]{Python Library Reference}
2266(``Library Reference'' hereafter). Some modules are built into the
2267interpreter; these provide access to operations that are not part of
2268the core of the language but are nevertheless built in, either for
2269efficiency or to provide access to operating system primitives such as
2270system calls. The set of such modules is a configuration option; e.g.,
2271the \module{amoeba} module is only provided on systems that somehow
Fred Drake8842e861998-02-13 07:16:30 +00002272support Amoeba primitives. One particular module deserves some
Fred Drake391564f1998-04-01 23:11:56 +00002273attention: \module{sys}\refstmodindex{sys}, which is built into every
Fred Drakeee84d591999-03-10 17:25:30 +00002274Python interpreter. The variables \code{sys.ps1} and
2275\code{sys.ps2} define the strings used as primary and secondary
2276prompts:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002277
Fred Drake8842e861998-02-13 07:16:30 +00002278\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002279>>> import sys
2280>>> sys.ps1
2281'>>> '
2282>>> sys.ps2
2283'... '
2284>>> sys.ps1 = 'C> '
2285C> print 'Yuck!'
2286Yuck!
2287C>
Fred Drake8842e861998-02-13 07:16:30 +00002288\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002289
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002290These two variables are only defined if the interpreter is in
2291interactive mode.
2292
Fred Drakeee84d591999-03-10 17:25:30 +00002293The variable \code{sys.path} is a list of strings that determine the
2294interpreter's search path for modules. It is initialized to a default
2295path taken from the environment variable \envvar{PYTHONPATH}, or from
2296a built-in default if \envvar{PYTHONPATH} is not set. You can modify
2297it using standard list operations, e.g.:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002298
Fred Drake8842e861998-02-13 07:16:30 +00002299\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002300>>> import sys
2301>>> sys.path.append('/ufs/guido/lib/python')
Fred Drake8842e861998-02-13 07:16:30 +00002302\end{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002303
Fred Drakeb7833d31998-09-11 16:21:55 +00002304\section{The \function{dir()} Function \label{dir}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002305
Fred Drake8842e861998-02-13 07:16:30 +00002306The built-in function \function{dir()} is used to find out which names
2307a module defines. It returns a sorted list of strings:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002308
Fred Drake8842e861998-02-13 07:16:30 +00002309\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002310>>> import fibo, sys
2311>>> dir(fibo)
Guido van Rossum6938f061994-08-01 12:22:53 +00002312['__name__', 'fib', 'fib2']
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002313>>> dir(sys)
Guido van Rossum6938f061994-08-01 12:22:53 +00002314['__name__', 'argv', 'builtin_module_names', 'copyright', 'exit',
2315'maxint', 'modules', 'path', 'ps1', 'ps2', 'setprofile', 'settrace',
2316'stderr', 'stdin', 'stdout', 'version']
Fred Drake8842e861998-02-13 07:16:30 +00002317\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002318
Fred Drake8842e861998-02-13 07:16:30 +00002319Without arguments, \function{dir()} lists the names you have defined
2320currently:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002321
Fred Drake8842e861998-02-13 07:16:30 +00002322\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002323>>> a = [1, 2, 3, 4, 5]
2324>>> import fibo, sys
2325>>> fib = fibo.fib
2326>>> dir()
Guido van Rossum6938f061994-08-01 12:22:53 +00002327['__name__', 'a', 'fib', 'fibo', 'sys']
Fred Drake8842e861998-02-13 07:16:30 +00002328\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002329
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002330Note that it lists all types of names: variables, modules, functions, etc.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002331
Fred Drake8842e861998-02-13 07:16:30 +00002332\function{dir()} does not list the names of built-in functions and
2333variables. If you want a list of those, they are defined in the
Fred Drake391564f1998-04-01 23:11:56 +00002334standard module \module{__builtin__}\refbimodindex{__builtin__}:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002335
Fred Drake8842e861998-02-13 07:16:30 +00002336\begin{verbatim}
Guido van Rossum4bd023f1993-10-27 13:49:20 +00002337>>> import __builtin__
2338>>> dir(__builtin__)
Guido van Rossum6938f061994-08-01 12:22:53 +00002339['AccessError', 'AttributeError', 'ConflictError', 'EOFError', 'IOError',
2340'ImportError', 'IndexError', 'KeyError', 'KeyboardInterrupt',
2341'MemoryError', 'NameError', 'None', 'OverflowError', 'RuntimeError',
2342'SyntaxError', 'SystemError', 'SystemExit', 'TypeError', 'ValueError',
2343'ZeroDivisionError', '__name__', 'abs', 'apply', 'chr', 'cmp', 'coerce',
2344'compile', 'dir', 'divmod', 'eval', 'execfile', 'filter', 'float',
2345'getattr', 'hasattr', 'hash', 'hex', 'id', 'input', 'int', 'len', 'long',
2346'map', 'max', 'min', 'oct', 'open', 'ord', 'pow', 'range', 'raw_input',
2347'reduce', 'reload', 'repr', 'round', 'setattr', 'str', 'type', 'xrange']
Fred Drake8842e861998-02-13 07:16:30 +00002348\end{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002349
Fred Drake31b761e2000-09-29 15:17:36 +00002350
Fred Drakeb7833d31998-09-11 16:21:55 +00002351\section{Packages \label{packages}}
Andrew M. Kuchling108943c1998-07-01 13:58:55 +00002352
2353Packages are a way of structuring Python's module namespace
Fred Drakeb7833d31998-09-11 16:21:55 +00002354by using ``dotted module names''. For example, the module name
2355\module{A.B} designates a submodule named \samp{B} in a package named
2356\samp{A}. Just like the use of modules saves the authors of different
2357modules from having to worry about each other's global variable names,
2358the use of dotted module names saves the authors of multi-module
Fred Drake20082d92000-04-03 04:26:58 +00002359packages like NumPy or the Python Imaging Library from having to worry
2360about each other's module names.
Andrew M. Kuchling108943c1998-07-01 13:58:55 +00002361
2362Suppose you want to design a collection of modules (a ``package'') for
2363the uniform handling of sound files and sound data. There are many
2364different sound file formats (usually recognized by their extension,
2365e.g. \file{.wav}, \file{.aiff}, \file{.au}), so you may need to create
2366and maintain a growing collection of modules for the conversion
2367between the various file formats. There are also many different
2368operations you might want to perform on sound data (e.g. mixing,
2369adding echo, applying an equalizer function, creating an artificial
2370stereo effect), so in addition you will be writing a never-ending
2371stream of modules to perform these operations. Here's a possible
2372structure for your package (expressed in terms of a hierarchical
2373filesystem):
2374
2375\begin{verbatim}
2376Sound/ Top-level package
2377 __init__.py Initialize the sound package
2378 Formats/ Subpackage for file format conversions
2379 __init__.py
2380 wavread.py
2381 wavwrite.py
2382 aiffread.py
2383 aiffwrite.py
2384 auread.py
2385 auwrite.py
2386 ...
2387 Effects/ Subpackage for sound effects
2388 __init__.py
2389 echo.py
2390 surround.py
2391 reverse.py
2392 ...
2393 Filters/ Subpackage for filters
2394 __init__.py
2395 equalizer.py
2396 vocoder.py
2397 karaoke.py
2398 ...
2399\end{verbatim}
Fred Drake31b761e2000-09-29 15:17:36 +00002400
Andrew M. Kuchling108943c1998-07-01 13:58:55 +00002401The \file{__init__.py} files are required to make Python treat the
2402directories as containing packages; this is done to prevent
2403directories with a common name, such as \samp{string}, from
2404unintentionally hiding valid modules that occur later on the module
2405search path. In the simplest case, \file{__init__.py} can just be an
2406empty file, but it can also execute initialization code for the
2407package or set the \code{__all__} variable, described later.
2408
2409Users of the package can import individual modules from the
2410package, for example:
2411
2412\begin{verbatim}
2413import Sound.Effects.echo
2414\end{verbatim}
Fred Drake31b761e2000-09-29 15:17:36 +00002415
Andrew M. Kuchling108943c1998-07-01 13:58:55 +00002416This loads the submodule \module{Sound.Effects.echo}. It must be referenced
2417with its full name, e.g.
2418
2419\begin{verbatim}
2420Sound.Effects.echo.echofilter(input, output, delay=0.7, atten=4)
2421\end{verbatim}
Fred Drake31b761e2000-09-29 15:17:36 +00002422
Andrew M. Kuchling108943c1998-07-01 13:58:55 +00002423An alternative way of importing the submodule is:
2424
2425\begin{verbatim}
2426from Sound.Effects import echo
2427\end{verbatim}
Fred Drake31b761e2000-09-29 15:17:36 +00002428
Andrew M. Kuchling108943c1998-07-01 13:58:55 +00002429This also loads the submodule \module{echo}, and makes it available without
2430its package prefix, so it can be used as follows:
2431
2432\begin{verbatim}
2433echo.echofilter(input, output, delay=0.7, atten=4)
2434\end{verbatim}
2435
2436Yet another variation is to import the desired function or variable directly:
2437
2438\begin{verbatim}
2439from Sound.Effects.echo import echofilter
2440\end{verbatim}
2441
2442Again, this loads the submodule \module{echo}, but this makes its function
Fred Drake20082d92000-04-03 04:26:58 +00002443\function{echofilter()} directly available:
Andrew M. Kuchling108943c1998-07-01 13:58:55 +00002444
2445\begin{verbatim}
2446echofilter(input, output, delay=0.7, atten=4)
2447\end{verbatim}
2448
2449Note that when using \code{from \var{package} import \var{item}}, the
Fred Drake20082d92000-04-03 04:26:58 +00002450item can be either a submodule (or subpackage) of the package, or some
Andrew M. Kuchling108943c1998-07-01 13:58:55 +00002451other name defined in the package, like a function, class or
2452variable. The \code{import} statement first tests whether the item is
2453defined in the package; if not, it assumes it is a module and attempts
Fred Drake20082d92000-04-03 04:26:58 +00002454to load it. If it fails to find it, an
2455\exception{ImportError} exception is raised.
Andrew M. Kuchling108943c1998-07-01 13:58:55 +00002456
2457Contrarily, when using syntax like \code{import
2458\var{item.subitem.subsubitem}}, each item except for the last must be
2459a package; the last item can be a module or a package but can't be a
2460class or function or variable defined in the previous item.
2461
Fred Drakeb7833d31998-09-11 16:21:55 +00002462\subsection{Importing * From a Package \label{pkg-import-star}}
Andrew M. Kuchling108943c1998-07-01 13:58:55 +00002463%The \code{__all__} Attribute
2464
2465Now what happens when the user writes \code{from Sound.Effects import
2466*}? Ideally, one would hope that this somehow goes out to the
2467filesystem, finds which submodules are present in the package, and
2468imports them all. Unfortunately, this operation does not work very
2469well on Mac and Windows platforms, where the filesystem does not
2470always have accurate information about the case of a filename! On
2471these platforms, there is no guaranteed way to know whether a file
2472\file{ECHO.PY} should be imported as a module \module{echo},
2473\module{Echo} or \module{ECHO}. (For example, Windows 95 has the
2474annoying practice of showing all file names with a capitalized first
2475letter.) The DOS 8+3 filename restriction adds another interesting
2476problem for long module names.
2477
2478The only solution is for the package author to provide an explicit
2479index of the package. The import statement uses the following
Fred Drake20082d92000-04-03 04:26:58 +00002480convention: if a package's \file{__init__.py} code defines a list
2481named \code{__all__}, it is taken to be the list of module names that
2482should be imported when \code{from \var{package} import *} is
Andrew M. Kuchling108943c1998-07-01 13:58:55 +00002483encountered. It is up to the package author to keep this list
2484up-to-date when a new version of the package is released. Package
2485authors may also decide not to support it, if they don't see a use for
2486importing * from their package. For example, the file
Fred Drake20082d92000-04-03 04:26:58 +00002487\file{Sounds/Effects/__init__.py} could contain the following code:
Andrew M. Kuchling108943c1998-07-01 13:58:55 +00002488
2489\begin{verbatim}
2490__all__ = ["echo", "surround", "reverse"]
2491\end{verbatim}
2492
2493This would mean that \code{from Sound.Effects import *} would
2494import the three named submodules of the \module{Sound} package.
2495
2496If \code{__all__} is not defined, the statement \code{from Sound.Effects
2497import *} does \emph{not} import all submodules from the package
2498\module{Sound.Effects} into the current namespace; it only ensures that the
2499package \module{Sound.Effects} has been imported (possibly running its
2500initialization code, \file{__init__.py}) and then imports whatever names are
2501defined in the package. This includes any names defined (and
2502submodules explicitly loaded) by \file{__init__.py}. It also includes any
2503submodules of the package that were explicitly loaded by previous
2504import statements, e.g.
2505
2506\begin{verbatim}
2507import Sound.Effects.echo
2508import Sound.Effects.surround
2509from Sound.Effects import *
2510\end{verbatim}
2511
Andrew M. Kuchling108943c1998-07-01 13:58:55 +00002512In this example, the echo and surround modules are imported in the
Fred Drake20082d92000-04-03 04:26:58 +00002513current namespace because they are defined in the
2514\module{Sound.Effects} package when the \code{from...import} statement
2515is executed. (This also works when \code{__all__} is defined.)
Andrew M. Kuchling108943c1998-07-01 13:58:55 +00002516
2517Note that in general the practicing of importing * from a module or
2518package is frowned upon, since it often causes poorly readable code.
2519However, it is okay to use it to save typing in interactive sessions,
2520and certain modules are designed to export only names that follow
2521certain patterns.
2522
2523Remember, there is nothing wrong with using \code{from Package
2524import specific_submodule}! In fact, this is the
2525recommended notation unless the importing module needs to use
2526submodules with the same name from different packages.
2527
2528
2529\subsection{Intra-package References}
2530
2531The submodules often need to refer to each other. For example, the
2532\module{surround} module might use the \module{echo} module. In fact, such references
2533are so common that the \code{import} statement first looks in the
2534containing package before looking in the standard module search path.
2535Thus, the surround module can simply use \code{import echo} or
2536\code{from echo import echofilter}. If the imported module is not
2537found in the current package (the package of which the current module
2538is a submodule), the \code{import} statement looks for a top-level module
2539with the given name.
2540
Fred Drake20082d92000-04-03 04:26:58 +00002541When packages are structured into subpackages (as with the
2542\module{Sound} package in the example), there's no shortcut to refer
2543to submodules of sibling packages - the full name of the subpackage
2544must be used. For example, if the module
2545\module{Sound.Filters.vocoder} needs to use the \module{echo} module
2546in the \module{Sound.Effects} package, it can use \code{from
Andrew M. Kuchling108943c1998-07-01 13:58:55 +00002547Sound.Effects import echo}.
2548
2549%(One could design a notation to refer to parent packages, similar to
2550%the use of ".." to refer to the parent directory in Unix and Windows
2551%filesystems. In fact, the \module{ni} module, which was the
2552%ancestor of this package system, supported this using \code{__} for
2553%the package containing the current module,
2554%\code{__.__} for the parent package, and so on. This feature was dropped
2555%because of its awkwardness; since most packages will have a relative
2556%shallow substructure, this is no big loss.)
2557
2558
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002559
Fred Drakeb7833d31998-09-11 16:21:55 +00002560\chapter{Input and Output \label{io}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002561
Guido van Rossum02455691997-07-17 16:21:52 +00002562There are several ways to present the output of a program; data can be
2563printed in a human-readable form, or written to a file for future use.
2564This chapter will discuss some of the possibilities.
2565
Fred Drakeb7833d31998-09-11 16:21:55 +00002566
2567\section{Fancier Output Formatting \label{formatting}}
2568
Fred Drakeeee08cd1997-12-04 15:43:15 +00002569So far we've encountered two ways of writing values: \emph{expression
Fred Drake8842e861998-02-13 07:16:30 +00002570statements} and the \keyword{print} statement. (A third way is using
2571the \method{write()} method of file objects; the standard output file
2572can be referenced as \code{sys.stdout}. See the Library Reference for
2573more information on this.)
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002574
2575Often you'll want more control over the formatting of your output than
Guido van Rossum02455691997-07-17 16:21:52 +00002576simply printing space-separated values. There are two ways to format
2577your output; the first way is to do all the string handling yourself;
2578using string slicing and concatenation operations you can create any
Fred Drake391564f1998-04-01 23:11:56 +00002579lay-out you can imagine. The standard module
2580\module{string}\refstmodindex{string} contains some useful operations
Fred Drake20082d92000-04-03 04:26:58 +00002581for padding strings to a given column width; these will be discussed
2582shortly. The second way is to use the \code{\%} operator with a
2583string as the left argument. The \code{\%} operator interprets the
2584left argument as a C much like a \cfunction{sprintf()}-style format
2585string to be applied to the right argument, and returns the string
2586resulting from this formatting operation.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002587
2588One question remains, of course: how do you convert values to strings?
Guido van Rossum02455691997-07-17 16:21:52 +00002589Luckily, Python has a way to convert any value to a string: pass it to
Fred Drake8842e861998-02-13 07:16:30 +00002590the \function{repr()} function, or just write the value between
2591reverse quotes (\code{``}). Some examples:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002592
Fred Drake8842e861998-02-13 07:16:30 +00002593\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002594>>> x = 10 * 3.14
2595>>> y = 200*200
2596>>> s = 'The value of x is ' + `x` + ', and y is ' + `y` + '...'
2597>>> print s
2598The value of x is 31.4, and y is 40000...
2599>>> # Reverse quotes work on other types besides numbers:
Guido van Rossum6938f061994-08-01 12:22:53 +00002600... p = [x, y]
Guido van Rossum02455691997-07-17 16:21:52 +00002601>>> ps = repr(p)
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002602>>> ps
2603'[31.4, 40000]'
2604>>> # Converting a string adds string quotes and backslashes:
Guido van Rossum6938f061994-08-01 12:22:53 +00002605... hello = 'hello, world\n'
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002606>>> hellos = `hello`
2607>>> print hellos
2608'hello, world\012'
2609>>> # The argument of reverse quotes may be a tuple:
Guido van Rossume5f8b601995-01-04 19:12:49 +00002610... `x, y, ('spam', 'eggs')`
2611"(31.4, 40000, ('spam', 'eggs'))"
Fred Drake8842e861998-02-13 07:16:30 +00002612\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002613
Guido van Rossum6938f061994-08-01 12:22:53 +00002614Here are two ways to write a table of squares and cubes:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002615
Fred Drake8842e861998-02-13 07:16:30 +00002616\begin{verbatim}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002617>>> import string
2618>>> for x in range(1, 11):
2619... print string.rjust(`x`, 2), string.rjust(`x*x`, 3),
2620... # Note trailing comma on previous line
2621... print string.rjust(`x*x*x`, 4)
2622...
2623 1 1 1
2624 2 4 8
2625 3 9 27
2626 4 16 64
2627 5 25 125
2628 6 36 216
2629 7 49 343
2630 8 64 512
2631 9 81 729
263210 100 1000
Guido van Rossum6938f061994-08-01 12:22:53 +00002633>>> for x in range(1,11):
2634... print '%2d %3d %4d' % (x, x*x, x*x*x)
2635...
2636 1 1 1
2637 2 4 8
2638 3 9 27
2639 4 16 64
2640 5 25 125
2641 6 36 216
2642 7 49 343
2643 8 64 512
2644 9 81 729
264510 100 1000
Fred Drake8842e861998-02-13 07:16:30 +00002646\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002647
Fred Drake8842e861998-02-13 07:16:30 +00002648(Note that one space between each column was added by the way
2649\keyword{print} works: it always adds spaces between its arguments.)
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002650
Fred Drake8842e861998-02-13 07:16:30 +00002651This example demonstrates the function \function{string.rjust()},
2652which right-justifies a string in a field of a given width by padding
2653it with spaces on the left. There are similar functions
2654\function{string.ljust()} and \function{string.center()}. These
2655functions do not write anything, they just return a new string. If
2656the input string is too long, they don't truncate it, but return it
2657unchanged; this will mess up your column lay-out but that's usually
2658better than the alternative, which would be lying about a value. (If
2659you really want truncation you can always add a slice operation, as in
2660\samp{string.ljust(x,~n)[0:n]}.)
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002661
Fred Drake8842e861998-02-13 07:16:30 +00002662There is another function, \function{string.zfill()}, which pads a
2663numeric string on the left with zeros. It understands about plus and
2664minus signs:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002665
Fred Drake8842e861998-02-13 07:16:30 +00002666\begin{verbatim}
Fred Drake0ba58151999-09-14 18:00:49 +00002667>>> import string
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002668>>> string.zfill('12', 5)
2669'00012'
2670>>> string.zfill('-3.14', 7)
2671'-003.14'
2672>>> string.zfill('3.14159265359', 5)
2673'3.14159265359'
Fred Drake8842e861998-02-13 07:16:30 +00002674\end{verbatim}
Fred Drake31b761e2000-09-29 15:17:36 +00002675
Guido van Rossum02455691997-07-17 16:21:52 +00002676Using the \code{\%} operator looks like this:
2677
2678\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00002679>>> import math
2680>>> print 'The value of PI is approximately %5.3f.' % math.pi
2681The value of PI is approximately 3.142.
Guido van Rossum02455691997-07-17 16:21:52 +00002682\end{verbatim}
2683
2684If there is more than one format in the string you pass a tuple as
2685right operand, e.g.
2686
2687\begin{verbatim}
Fred Drake20082d92000-04-03 04:26:58 +00002688>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 7678}
Fred Drake8842e861998-02-13 07:16:30 +00002689>>> for name, phone in table.items():
2690... print '%-10s ==> %10d' % (name, phone)
2691...
2692Jack ==> 4098
Fred Drake69fbf332000-04-04 19:53:06 +00002693Dcab ==> 7678
Fred Drake8842e861998-02-13 07:16:30 +00002694Sjoerd ==> 4127
Guido van Rossum02455691997-07-17 16:21:52 +00002695\end{verbatim}
2696
Fred Drakeee84d591999-03-10 17:25:30 +00002697Most formats work exactly as in C and require that you pass the proper
Guido van Rossum02455691997-07-17 16:21:52 +00002698type; however, if you don't you get an exception, not a core dump.
Fred Drakedb70d061998-11-17 21:59:04 +00002699The \code{\%s} format is more relaxed: if the corresponding argument is
Fred Drake8842e861998-02-13 07:16:30 +00002700not a string object, it is converted to string using the
2701\function{str()} built-in function. Using \code{*} to pass the width
2702or precision in as a separate (integer) argument is supported. The
Fred Drakeee84d591999-03-10 17:25:30 +00002703C formats \code{\%n} and \code{\%p} are not supported.
Guido van Rossum02455691997-07-17 16:21:52 +00002704
2705If you have a really long format string that you don't want to split
2706up, it would be nice if you could reference the variables to be
2707formatted by name instead of by position. This can be done by using
Fred Drakeee84d591999-03-10 17:25:30 +00002708an extension of C formats using the form \code{\%(name)format}, e.g.
Guido van Rossum02455691997-07-17 16:21:52 +00002709
2710\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00002711>>> table = {'Sjoerd': 4127, 'Jack': 4098, 'Dcab': 8637678}
2712>>> print 'Jack: %(Jack)d; Sjoerd: %(Sjoerd)d; Dcab: %(Dcab)d' % table
2713Jack: 4098; Sjoerd: 4127; Dcab: 8637678
Guido van Rossum02455691997-07-17 16:21:52 +00002714\end{verbatim}
2715
2716This is particularly useful in combination with the new built-in
Fred Drake8842e861998-02-13 07:16:30 +00002717\function{vars()} function, which returns a dictionary containing all
Guido van Rossum02455691997-07-17 16:21:52 +00002718local variables.
2719
Fred Drakeb7833d31998-09-11 16:21:55 +00002720\section{Reading and Writing Files \label{files}}
Fred Drake6c2176e1998-02-26 21:47:54 +00002721
Guido van Rossum02455691997-07-17 16:21:52 +00002722% Opening files
Fred Drake391564f1998-04-01 23:11:56 +00002723\function{open()}\bifuncindex{open} returns a file
2724object\obindex{file}, and is most commonly used with two arguments:
2725\samp{open(\var{filename}, \var{mode})}.
Guido van Rossum02455691997-07-17 16:21:52 +00002726
Fred Drake8842e861998-02-13 07:16:30 +00002727\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00002728>>> f=open('/tmp/workfile', 'w')
2729>>> print f
2730<open file '/tmp/workfile', mode 'w' at 80a0960>
Fred Drake8842e861998-02-13 07:16:30 +00002731\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002732
Guido van Rossum02455691997-07-17 16:21:52 +00002733The first argument is a string containing the filename. The second
2734argument is another string containing a few characters describing the
2735way in which the file will be used. \var{mode} can be \code{'r'} when
2736the file will only be read, \code{'w'} for only writing (an existing
2737file with the same name will be erased), and \code{'a'} opens the file
2738for appending; any data written to the file is automatically added to
2739the end. \code{'r+'} opens the file for both reading and writing.
2740The \var{mode} argument is optional; \code{'r'} will be assumed if
2741it's omitted.
2742
Fred Drake391564f1998-04-01 23:11:56 +00002743On Windows and the Macintosh, \code{'b'} appended to the
Guido van Rossum02455691997-07-17 16:21:52 +00002744mode opens the file in binary mode, so there are also modes like
2745\code{'rb'}, \code{'wb'}, and \code{'r+b'}. Windows makes a
2746distinction between text and binary files; the end-of-line characters
2747in text files are automatically altered slightly when data is read or
2748written. This behind-the-scenes modification to file data is fine for
Fred Drake8842e861998-02-13 07:16:30 +00002749\ASCII{} text files, but it'll corrupt binary data like that in JPEGs or
2750\file{.EXE} files. Be very careful to use binary mode when reading and
Fred Drake391564f1998-04-01 23:11:56 +00002751writing such files. (Note that the precise semantics of text mode on
Fred Drakeee84d591999-03-10 17:25:30 +00002752the Macintosh depends on the underlying C library being used.)
Guido van Rossum02455691997-07-17 16:21:52 +00002753
Fred Drakeb7833d31998-09-11 16:21:55 +00002754\subsection{Methods of File Objects \label{fileMethods}}
Guido van Rossum02455691997-07-17 16:21:52 +00002755
2756The rest of the examples in this section will assume that a file
2757object called \code{f} has already been created.
2758
2759To read a file's contents, call \code{f.read(\var{size})}, which reads
2760some quantity of data and returns it as a string. \var{size} is an
2761optional numeric argument. When \var{size} is omitted or negative,
2762the entire contents of the file will be read and returned; it's your
2763problem if the file is twice as large as your machine's memory.
2764Otherwise, at most \var{size} bytes are read and returned. If the end
2765of the file has been reached, \code{f.read()} will return an empty
2766string (\code {""}).
Fred Drake8842e861998-02-13 07:16:30 +00002767\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00002768>>> f.read()
2769'This is the entire file.\012'
2770>>> f.read()
2771''
Fred Drake8842e861998-02-13 07:16:30 +00002772\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002773
Guido van Rossum02455691997-07-17 16:21:52 +00002774\code{f.readline()} reads a single line from the file; a newline
Fred Drake8842e861998-02-13 07:16:30 +00002775character (\code{\e n}) is left at the end of the string, and is only
Guido van Rossum02455691997-07-17 16:21:52 +00002776omitted on the last line of the file if the file doesn't end in a
2777newline. This makes the return value unambiguous; if
2778\code{f.readline()} returns an empty string, the end of the file has
Fred Drake8842e861998-02-13 07:16:30 +00002779been reached, while a blank line is represented by \code{'\e n'}, a
Guido van Rossum02455691997-07-17 16:21:52 +00002780string containing only a single newline.
2781
Fred Drake8842e861998-02-13 07:16:30 +00002782\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00002783>>> f.readline()
2784'This is the first line of the file.\012'
2785>>> f.readline()
2786'Second line of the file\012'
2787>>> f.readline()
2788''
Fred Drake8842e861998-02-13 07:16:30 +00002789\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002790
Fred Drake343ad7a2000-09-22 04:12:27 +00002791\code{f.readlines()} returns a list containing all the lines of data
2792in the file. If given an optional parameter \var{sizehint}, it reads
2793that many bytes from the file and enough more to complete a line, and
2794returns the lines from that. This is often used to allow efficient
2795reading of a large file by lines, but without having to load the
2796entire file in memory. Only complete lines will be returned.
Guido van Rossum02455691997-07-17 16:21:52 +00002797
Fred Drake8842e861998-02-13 07:16:30 +00002798\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00002799>>> f.readlines()
2800['This is the first line of the file.\012', 'Second line of the file\012']
Fred Drake8842e861998-02-13 07:16:30 +00002801\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002802
Guido van Rossum02455691997-07-17 16:21:52 +00002803\code{f.write(\var{string})} writes the contents of \var{string} to
2804the file, returning \code{None}.
2805
Fred Drake8842e861998-02-13 07:16:30 +00002806\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00002807>>> f.write('This is a test\n')
Fred Drake8842e861998-02-13 07:16:30 +00002808\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002809
Guido van Rossum02455691997-07-17 16:21:52 +00002810\code{f.tell()} returns an integer giving the file object's current
2811position in the file, measured in bytes from the beginning of the
2812file. To change the file object's position, use
Fred Drake8842e861998-02-13 07:16:30 +00002813\samp{f.seek(\var{offset}, \var{from_what})}. The position is
Guido van Rossum02455691997-07-17 16:21:52 +00002814computed from adding \var{offset} to a reference point; the reference
Fred Drake20082d92000-04-03 04:26:58 +00002815point is selected by the \var{from_what} argument. A
2816\var{from_what} value of 0 measures from the beginning of the file, 1
2817uses the current file position, and 2 uses the end of the file as the
2818reference point. \var{from_what} can be omitted and defaults to 0,
2819using the beginning of the file as the reference point.
Guido van Rossum02455691997-07-17 16:21:52 +00002820
Fred Drake8842e861998-02-13 07:16:30 +00002821\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00002822>>> f=open('/tmp/workfile', 'r+')
2823>>> f.write('0123456789abcdef')
2824>>> f.seek(5) # Go to the 5th byte in the file
2825>>> f.read(1)
2826'5'
2827>>> f.seek(-3, 2) # Go to the 3rd byte before the end
2828>>> f.read(1)
2829'd'
Fred Drake8842e861998-02-13 07:16:30 +00002830\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002831
Guido van Rossum02455691997-07-17 16:21:52 +00002832When you're done with a file, call \code{f.close()} to close it and
2833free up any system resources taken up by the open file. After calling
2834\code{f.close()}, attempts to use the file object will automatically fail.
2835
Fred Drake8842e861998-02-13 07:16:30 +00002836\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00002837>>> f.close()
2838>>> f.read()
2839Traceback (innermost last):
2840 File "<stdin>", line 1, in ?
2841ValueError: I/O operation on closed file
Fred Drake8842e861998-02-13 07:16:30 +00002842\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002843
Fred Drake20082d92000-04-03 04:26:58 +00002844File objects have some additional methods, such as
2845\method{isatty()} and \method{truncate()} which are less frequently
2846used; consult the Library Reference for a complete guide to file
2847objects.
Guido van Rossum02455691997-07-17 16:21:52 +00002848
Fred Drakeb7833d31998-09-11 16:21:55 +00002849\subsection{The \module{pickle} Module \label{pickle}}
Fred Drake391564f1998-04-01 23:11:56 +00002850\refstmodindex{pickle}
Guido van Rossum02455691997-07-17 16:21:52 +00002851
2852Strings can easily be written to and read from a file. Numbers take a
Fred Drake8842e861998-02-13 07:16:30 +00002853bit more effort, since the \method{read()} method only returns
2854strings, which will have to be passed to a function like
2855\function{string.atoi()}, which takes a string like \code{'123'} and
2856returns its numeric value 123. However, when you want to save more
2857complex data types like lists, dictionaries, or class instances,
2858things get a lot more complicated.
Guido van Rossum02455691997-07-17 16:21:52 +00002859
2860Rather than have users be constantly writing and debugging code to
2861save complicated data types, Python provides a standard module called
Fred Drake8842e861998-02-13 07:16:30 +00002862\module{pickle}. This is an amazing module that can take almost
Guido van Rossum02455691997-07-17 16:21:52 +00002863any Python object (even some forms of Python code!), and convert it to
2864a string representation; this process is called \dfn{pickling}.
2865Reconstructing the object from the string representation is called
2866\dfn{unpickling}. Between pickling and unpickling, the string
2867representing the object may have been stored in a file or data, or
2868sent over a network connection to some distant machine.
2869
2870If you have an object \code{x}, and a file object \code{f} that's been
2871opened for writing, the simplest way to pickle the object takes only
2872one line of code:
2873
Fred Drake8842e861998-02-13 07:16:30 +00002874\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00002875pickle.dump(x, f)
Fred Drake8842e861998-02-13 07:16:30 +00002876\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002877
Fred Drake8842e861998-02-13 07:16:30 +00002878To unpickle the object again, if \code{f} is a file object which has
2879been opened for reading:
Guido van Rossum02455691997-07-17 16:21:52 +00002880
Fred Drake8842e861998-02-13 07:16:30 +00002881\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00002882x = pickle.load(f)
Fred Drake8842e861998-02-13 07:16:30 +00002883\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002884
Guido van Rossum02455691997-07-17 16:21:52 +00002885(There are other variants of this, used when pickling many objects or
2886when you don't want to write the pickled data to a file; consult the
Fred Drake8842e861998-02-13 07:16:30 +00002887complete documentation for \module{pickle} in the Library Reference.)
Guido van Rossum02455691997-07-17 16:21:52 +00002888
Fred Drake20082d92000-04-03 04:26:58 +00002889\module{pickle} is the standard way to make Python objects which can
2890be stored and reused by other programs or by a future invocation of
2891the same program; the technical term for this is a
2892\dfn{persistent} object. Because \module{pickle} is so widely used,
2893many authors who write Python extensions take care to ensure that new
2894data types such as matrices can be properly pickled and unpickled.
Guido van Rossum02455691997-07-17 16:21:52 +00002895
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002896
Guido van Rossum5e0759d1992-08-07 16:06:24 +00002897
Fred Drakeb7833d31998-09-11 16:21:55 +00002898\chapter{Errors and Exceptions \label{errors}}
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002899
2900Until now error messages haven't been more than mentioned, but if you
2901have tried out the examples you have probably seen some. There are
Fred Drake20082d92000-04-03 04:26:58 +00002902(at least) two distinguishable kinds of errors:
2903\emph{syntax errors} and \emph{exceptions}.
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002904
Fred Drakeb7833d31998-09-11 16:21:55 +00002905\section{Syntax Errors \label{syntaxErrors}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002906
2907Syntax errors, also known as parsing errors, are perhaps the most common
Guido van Rossum4410c751991-06-04 20:22:18 +00002908kind of complaint you get while you are still learning Python:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002909
Fred Drake8842e861998-02-13 07:16:30 +00002910\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002911>>> while 1 print 'Hello world'
Guido van Rossum6938f061994-08-01 12:22:53 +00002912 File "<stdin>", line 1
2913 while 1 print 'Hello world'
2914 ^
2915SyntaxError: invalid syntax
Fred Drake8842e861998-02-13 07:16:30 +00002916\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002917
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002918The parser repeats the offending line and displays a little `arrow'
Fred Drake20082d92000-04-03 04:26:58 +00002919pointing at the earliest point in the line where the error was
2920detected. The error is caused by (or at least detected at) the token
2921\emph{preceding} the arrow: in the example, the error is detected at
2922the keyword \keyword{print}, since a colon (\character{:}) is missing
2923before it. File name and line number are printed so you know where to
2924look in case the input came from a script.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002925
Fred Drakeb7833d31998-09-11 16:21:55 +00002926\section{Exceptions \label{exceptions}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002927
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002928Even if a statement or expression is syntactically correct, it may
2929cause an error when an attempt is made to execute it.
Fred Drakeeee08cd1997-12-04 15:43:15 +00002930Errors detected during execution are called \emph{exceptions} and are
Guido van Rossum6fc178f1991-08-16 09:13:42 +00002931not unconditionally fatal: you will soon learn how to handle them in
2932Python programs. Most exceptions are not handled by programs,
2933however, and result in error messages as shown here:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002934
Fred Drake8842e861998-02-13 07:16:30 +00002935\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002936>>> 10 * (1/0)
Guido van Rossum3cbc16d1993-12-17 12:13:53 +00002937Traceback (innermost last):
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002938 File "<stdin>", line 1
Guido van Rossumb2c65561993-05-12 08:53:36 +00002939ZeroDivisionError: integer division or modulo
Guido van Rossume5f8b601995-01-04 19:12:49 +00002940>>> 4 + spam*3
Guido van Rossum6938f061994-08-01 12:22:53 +00002941Traceback (innermost last):
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002942 File "<stdin>", line 1
Guido van Rossume5f8b601995-01-04 19:12:49 +00002943NameError: spam
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002944>>> '2' + 2
Guido van Rossum6938f061994-08-01 12:22:53 +00002945Traceback (innermost last):
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002946 File "<stdin>", line 1
Guido van Rossumb2c65561993-05-12 08:53:36 +00002947TypeError: illegal argument type for built-in operation
Fred Drake8842e861998-02-13 07:16:30 +00002948\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002949
Guido van Rossumb2c65561993-05-12 08:53:36 +00002950The last line of the error message indicates what happened.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002951Exceptions come in different types, and the type is printed as part of
2952the message: the types in the example are
Fred Drake20082d92000-04-03 04:26:58 +00002953\exception{ZeroDivisionError}, \exception{NameError} and
Fred Drake8842e861998-02-13 07:16:30 +00002954\exception{TypeError}.
Guido van Rossumb2c65561993-05-12 08:53:36 +00002955The string printed as the exception type is the name of the built-in
2956name for the exception that occurred. This is true for all built-in
2957exceptions, but need not be true for user-defined exceptions (although
2958it is a useful convention).
2959Standard exception names are built-in identifiers (not reserved
2960keywords).
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002961
Guido van Rossumb2c65561993-05-12 08:53:36 +00002962The rest of the line is a detail whose interpretation depends on the
2963exception type; its meaning is dependent on the exception type.
2964
2965The preceding part of the error message shows the context where the
2966exception happened, in the form of a stack backtrace.
Guido van Rossum2292b8e1991-01-23 16:31:24 +00002967In general it contains a stack backtrace listing source lines; however,
2968it will not display lines read from standard input.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002969
Fred Drake20082d92000-04-03 04:26:58 +00002970The \emph{Python Library Reference} lists the built-in exceptions and
2971their meanings.
2972
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002973
Fred Drakeb7833d31998-09-11 16:21:55 +00002974\section{Handling Exceptions \label{handling}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002975
2976It is possible to write programs that handle selected exceptions.
Fred Drake20082d92000-04-03 04:26:58 +00002977Look at the following example, which asks the user for input until a
2978valid integer has been entered, but allows the user to interrupt the
2979program (using \kbd{Control-C} or whatever the operating system
2980supports); note that a user-generated interruption is signalled by
2981raising the \exception{KeyboardInterrupt} exception.
Guido van Rossuma8d754e1992-01-07 16:44:35 +00002982
Fred Drake8842e861998-02-13 07:16:30 +00002983\begin{verbatim}
Fred Drake20082d92000-04-03 04:26:58 +00002984>>> while 1:
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002985... try:
Fred Drake20082d92000-04-03 04:26:58 +00002986... x = int(raw_input("Please enter a number: "))
2987... break
2988... except ValueError:
2989... print "Oops! That was no valid number. Try again..."
Guido van Rossum02455691997-07-17 16:21:52 +00002990...
Fred Drake8842e861998-02-13 07:16:30 +00002991\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00002992
Fred Drake8842e861998-02-13 07:16:30 +00002993The \keyword{try} statement works as follows.
Fred Drake20082d92000-04-03 04:26:58 +00002994
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00002995\begin{itemize}
2996\item
Fred Drake20082d92000-04-03 04:26:58 +00002997First, the \emph{try clause} (the statement(s) between the
2998\keyword{try} and \keyword{except} keywords) is executed.
2999
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003000\item
Fred Drake20082d92000-04-03 04:26:58 +00003001If no exception occurs, the \emph{except\ clause} is skipped and
3002execution of the \keyword{try} statement is finished.
3003
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003004\item
Fred Drake20082d92000-04-03 04:26:58 +00003005If an exception occurs during execution of the try clause, the rest of
3006the clause is skipped. Then if its type matches the exception named
3007after the \keyword{except} keyword, the rest of the try clause is
3008skipped, the except clause is executed, and then execution continues
3009after the \keyword{try} statement.
3010
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003011\item
3012If an exception occurs which does not match the exception named in the
Fred Drake8842e861998-02-13 07:16:30 +00003013except clause, it is passed on to outer \keyword{try} statements; if
Fred Drake20082d92000-04-03 04:26:58 +00003014no handler is found, it is an \emph{unhandled exception} and execution
3015stops with a message as shown above.
3016
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003017\end{itemize}
Fred Drake20082d92000-04-03 04:26:58 +00003018
Fred Drake8842e861998-02-13 07:16:30 +00003019A \keyword{try} statement may have more than one except clause, to
Fred Drake20082d92000-04-03 04:26:58 +00003020specify handlers for different exceptions. At most one handler will
3021be executed. Handlers only handle exceptions that occur in the
3022corresponding try clause, not in other handlers of the same
3023\keyword{try} statement. An except clause may name multiple exceptions
3024as a parenthesized list, e.g.:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00003025
Fred Drake8842e861998-02-13 07:16:30 +00003026\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003027... except (RuntimeError, TypeError, NameError):
3028... pass
Fred Drake8842e861998-02-13 07:16:30 +00003029\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00003030
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003031The last except clause may omit the exception name(s), to serve as a
Fred Drake20082d92000-04-03 04:26:58 +00003032wildcard. Use this with extreme caution, since it is easy to mask a
3033real programming error in this way! It can also be used to print an
3034error message and then re-raise the exception (allowing a caller to
3035handle the exception as well):
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003036
Fred Drake20082d92000-04-03 04:26:58 +00003037\begin{verbatim}
3038import string, sys
3039
3040try:
3041 f = open('myfile.txt')
3042 s = f.readline()
3043 i = int(string.strip(s))
3044except IOError, (errno, strerror):
3045 print "I/O error(%s): %s" % (errno, strerror)
3046except ValueError:
3047 print "Could not convert data to an integer."
3048except:
3049 print "Unexpected error:", sys.exc_info()[0]
3050 raise
3051\end{verbatim}
Fred Drake2900ff91999-08-24 22:14:57 +00003052
Fred Drake8842e861998-02-13 07:16:30 +00003053The \keyword{try} \ldots\ \keyword{except} statement has an optional
Fred Drakee99d1db2000-04-17 14:56:31 +00003054\emph{else clause}, which, when present, must follow all except
3055clauses. It is useful for code that must be executed if the try
3056clause does not raise an exception. For example:
Guido van Rossum02455691997-07-17 16:21:52 +00003057
3058\begin{verbatim}
Guido van Rossuma4289a71998-07-07 20:18:06 +00003059for arg in sys.argv[1:]:
Fred Drake8842e861998-02-13 07:16:30 +00003060 try:
3061 f = open(arg, 'r')
3062 except IOError:
3063 print 'cannot open', arg
3064 else:
3065 print arg, 'has', len(f.readlines()), 'lines'
3066 f.close()
Guido van Rossum02455691997-07-17 16:21:52 +00003067\end{verbatim}
3068
Fred Drakee99d1db2000-04-17 14:56:31 +00003069The use of the \keyword{else} clause is better than adding additional
3070code to the \keyword{try} clause because it avoids accidentally
3071catching an exception that wasn't raised by the code being protected
3072by the \keyword{try} \ldots\ \keyword{except} statement.
3073
Guido van Rossum02455691997-07-17 16:21:52 +00003074
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003075When an exception occurs, it may have an associated value, also known as
Thomas Woutersf9b526d2000-07-16 19:05:38 +00003076the exception's \emph{argument}.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003077The presence and type of the argument depend on the exception type.
3078For exception types which have an argument, the except clause may
3079specify a variable after the exception name (or list) to receive the
3080argument's value, as follows:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00003081
Fred Drake8842e861998-02-13 07:16:30 +00003082\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003083>>> try:
Guido van Rossume5f8b601995-01-04 19:12:49 +00003084... spam()
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003085... except NameError, x:
Guido van Rossum2292b8e1991-01-23 16:31:24 +00003086... print 'name', x, 'undefined'
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003087...
Guido van Rossume5f8b601995-01-04 19:12:49 +00003088name spam undefined
Fred Drake8842e861998-02-13 07:16:30 +00003089\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00003090
Guido van Rossumb2c65561993-05-12 08:53:36 +00003091If an exception has an argument, it is printed as the last part
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003092(`detail') of the message for unhandled exceptions.
3093
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003094Exception handlers don't just handle exceptions if they occur
3095immediately in the try clause, but also if they occur inside functions
3096that are called (even indirectly) in the try clause.
3097For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00003098
Fred Drake8842e861998-02-13 07:16:30 +00003099\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003100>>> def this_fails():
3101... x = 1/0
3102...
3103>>> try:
3104... this_fails()
Guido van Rossumb2c65561993-05-12 08:53:36 +00003105... except ZeroDivisionError, detail:
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003106... print 'Handling run-time error:', detail
3107...
Guido van Rossumb2c65561993-05-12 08:53:36 +00003108Handling run-time error: integer division or modulo
Fred Drake8842e861998-02-13 07:16:30 +00003109\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00003110
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003111
Fred Drakeb7833d31998-09-11 16:21:55 +00003112\section{Raising Exceptions \label{raising}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003113
Fred Drake8842e861998-02-13 07:16:30 +00003114The \keyword{raise} statement allows the programmer to force a
3115specified exception to occur.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003116For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00003117
Fred Drake8842e861998-02-13 07:16:30 +00003118\begin{verbatim}
Guido van Rossumb2c65561993-05-12 08:53:36 +00003119>>> raise NameError, 'HiThere'
Guido van Rossum6938f061994-08-01 12:22:53 +00003120Traceback (innermost last):
Guido van Rossum2292b8e1991-01-23 16:31:24 +00003121 File "<stdin>", line 1
Guido van Rossumb2c65561993-05-12 08:53:36 +00003122NameError: HiThere
Fred Drake8842e861998-02-13 07:16:30 +00003123\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00003124
Fred Drake8842e861998-02-13 07:16:30 +00003125The first argument to \keyword{raise} names the exception to be
3126raised. The optional second argument specifies the exception's
3127argument.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003128
Guido van Rossum02455691997-07-17 16:21:52 +00003129
Fred Drakeb7833d31998-09-11 16:21:55 +00003130\section{User-defined Exceptions \label{userExceptions}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003131
3132Programs may name their own exceptions by assigning a string to a
Fred Drake20082d92000-04-03 04:26:58 +00003133variable or creating a new exception class. For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00003134
Fred Drake8842e861998-02-13 07:16:30 +00003135\begin{verbatim}
Fred Drake20082d92000-04-03 04:26:58 +00003136>>> class MyError:
3137... def __init__(self, value):
3138... self.value = value
3139... def __str__(self):
3140... return `self.value`
3141...
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003142>>> try:
Fred Drake20082d92000-04-03 04:26:58 +00003143... raise MyError(2*2)
3144... except MyError, e:
3145... print 'My exception occurred, value:', e.value
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003146...
Guido van Rossum6938f061994-08-01 12:22:53 +00003147My exception occurred, value: 4
Fred Drake20082d92000-04-03 04:26:58 +00003148>>> raise MyError, 1
Guido van Rossum6938f061994-08-01 12:22:53 +00003149Traceback (innermost last):
3150 File "<stdin>", line 1
Fred Drake20082d92000-04-03 04:26:58 +00003151__main__.MyError: 1
Fred Drake8842e861998-02-13 07:16:30 +00003152\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00003153
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003154Many standard modules use this to report errors that may occur in
3155functions they define.
3156
Fred Drake20082d92000-04-03 04:26:58 +00003157More information on classes is presented in chapter \ref{classes},
3158``Classes.''
3159
Guido van Rossum02455691997-07-17 16:21:52 +00003160
Fred Drakeb7833d31998-09-11 16:21:55 +00003161\section{Defining Clean-up Actions \label{cleanup}}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003162
Fred Drake8842e861998-02-13 07:16:30 +00003163The \keyword{try} statement has another optional clause which is
3164intended to define clean-up actions that must be executed under all
3165circumstances. For example:
Guido van Rossuma8d754e1992-01-07 16:44:35 +00003166
Fred Drake8842e861998-02-13 07:16:30 +00003167\begin{verbatim}
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003168>>> try:
3169... raise KeyboardInterrupt
3170... finally:
3171... print 'Goodbye, world!'
3172...
3173Goodbye, world!
Guido van Rossum6938f061994-08-01 12:22:53 +00003174Traceback (innermost last):
Guido van Rossum2292b8e1991-01-23 16:31:24 +00003175 File "<stdin>", line 2
Guido van Rossumb2c65561993-05-12 08:53:36 +00003176KeyboardInterrupt
Fred Drake8842e861998-02-13 07:16:30 +00003177\end{verbatim}
Fred Drake6c2176e1998-02-26 21:47:54 +00003178
Fred Drake8842e861998-02-13 07:16:30 +00003179A \emph{finally clause} is executed whether or not an exception has
3180occurred in the try clause. When an exception has occurred, it is
3181re-raised after the finally clause is executed. The finally clause is
3182also executed ``on the way out'' when the \keyword{try} statement is
3183left via a \keyword{break} or \keyword{return} statement.
Guido van Rossumda8c3fd1992-08-09 13:55:25 +00003184
Fred Drake8842e861998-02-13 07:16:30 +00003185A \keyword{try} statement must either have one or more except clauses
3186or one finally clause, but not both.
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00003187
Fred Drakeb7833d31998-09-11 16:21:55 +00003188\chapter{Classes \label{classes}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003189
3190Python's class mechanism adds classes to the language with a minimum
3191of new syntax and semantics. It is a mixture of the class mechanisms
Guido van Rossum16d6e711994-08-08 12:30:22 +00003192found in \Cpp{} and Modula-3. As is true for modules, classes in Python
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003193do not put an absolute barrier between definition and user, but rather
3194rely on the politeness of the user not to ``break into the
3195definition.'' The most important features of classes are retained
3196with full power, however: the class inheritance mechanism allows
3197multiple base classes, a derived class can override any methods of its
Fred Drake391564f1998-04-01 23:11:56 +00003198base class or classes, a method can call the method of a base class with the
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003199same name. Objects can contain an arbitrary amount of private data.
3200
Guido van Rossum16d6e711994-08-08 12:30:22 +00003201In \Cpp{} terminology, all class members (including the data members) are
Fred Drakeeee08cd1997-12-04 15:43:15 +00003202\emph{public}, and all member functions are \emph{virtual}. There are
Guido van Rossum6938f061994-08-01 12:22:53 +00003203no special constructors or destructors. As in Modula-3, there are no
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003204shorthands for referencing the object's members from its methods: the
3205method function is declared with an explicit first argument
3206representing the object, which is provided implicitly by the call. As
3207in Smalltalk, classes themselves are objects, albeit in the wider
3208sense of the word: in Python, all data types are objects. This
Fred Drake20082d92000-04-03 04:26:58 +00003209provides semantics for importing and renaming. But, just like in
3210\Cpp{} or Modula-3, built-in types cannot be used as base classes for
Guido van Rossum16d6e711994-08-08 12:30:22 +00003211extension by the user. Also, like in \Cpp{} but unlike in Modula-3, most
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003212built-in operators with special syntax (arithmetic operators,
Fred Drake391564f1998-04-01 23:11:56 +00003213subscripting etc.) can be redefined for class instances.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003214
Fred Drakeb7833d31998-09-11 16:21:55 +00003215\section{A Word About Terminology \label{terminology}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003216
Fred Drake391564f1998-04-01 23:11:56 +00003217Lacking universally accepted terminology to talk about classes, I will
3218make occasional use of Smalltalk and \Cpp{} terms. (I would use Modula-3
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003219terms, since its object-oriented semantics are closer to those of
Fred Drake8842e861998-02-13 07:16:30 +00003220Python than \Cpp{}, but I expect that few readers have heard of it.)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003221
3222I also have to warn you that there's a terminological pitfall for
3223object-oriented readers: the word ``object'' in Python does not
Fred Drake8842e861998-02-13 07:16:30 +00003224necessarily mean a class instance. Like \Cpp{} and Modula-3, and
3225unlike Smalltalk, not all types in Python are classes: the basic
Fred Drake391564f1998-04-01 23:11:56 +00003226built-in types like integers and lists are not, and even somewhat more
Fred Drake8842e861998-02-13 07:16:30 +00003227exotic types like files aren't. However, \emph{all} Python types
3228share a little bit of common semantics that is best described by using
3229the word object.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003230
3231Objects have individuality, and multiple names (in multiple scopes)
3232can be bound to the same object. This is known as aliasing in other
3233languages. This is usually not appreciated on a first glance at
3234Python, and can be safely ignored when dealing with immutable basic
3235types (numbers, strings, tuples). However, aliasing has an
Guido van Rossum6938f061994-08-01 12:22:53 +00003236(intended!) effect on the semantics of Python code involving mutable
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003237objects such as lists, dictionaries, and most types representing
3238entities outside the program (files, windows, etc.). This is usually
3239used to the benefit of the program, since aliases behave like pointers
3240in some respects. For example, passing an object is cheap since only
3241a pointer is passed by the implementation; and if a function modifies
3242an object passed as an argument, the caller will see the change --- this
3243obviates the need for two different argument passing mechanisms as in
3244Pascal.
3245
3246
Fred Drakeb7833d31998-09-11 16:21:55 +00003247\section{Python Scopes and Name Spaces \label{scopes}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003248
3249Before introducing classes, I first have to tell you something about
3250Python's scope rules. Class definitions play some neat tricks with
Fred Drake13494372000-09-12 16:23:48 +00003251namespaces, and you need to know how scopes and namespaces work to
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003252fully understand what's going on. Incidentally, knowledge about this
3253subject is useful for any advanced Python programmer.
3254
3255Let's begin with some definitions.
3256
Fred Drake13494372000-09-12 16:23:48 +00003257A \emph{namespace} is a mapping from names to objects. Most
3258namespaces are currently implemented as Python dictionaries, but
3259that's normally not noticeable in any way (except for performance),
3260and it may change in the future. Examples of namespaces are: the set
3261of built-in names (functions such as \function{abs()}, and built-in
3262exception names); the global names in a module; and the local names in
3263a function invocation. In a sense the set of attributes of an object
3264also form a namespace. The important thing to know about namespaces
3265is that there is absolutely no relation between names in different
3266namespaces; for instance, two different modules may both define a
3267function ``maximize'' without confusion --- users of the modules must
3268prefix it with the module name.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003269
Fred Drakeeee08cd1997-12-04 15:43:15 +00003270By the way, I use the word \emph{attribute} for any name following a
Fred Drake8842e861998-02-13 07:16:30 +00003271dot --- for example, in the expression \code{z.real}, \code{real} is
3272an attribute of the object \code{z}. Strictly speaking, references to
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003273names in modules are attribute references: in the expression
Fred Drake8842e861998-02-13 07:16:30 +00003274\code{modname.funcname}, \code{modname} is a module object and
3275\code{funcname} is an attribute of it. In this case there happens to
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003276be a straightforward mapping between the module's attributes and the
Fred Drake13494372000-09-12 16:23:48 +00003277global names defined in the module: they share the same namespace!
3278\footnote{
Guido van Rossum6938f061994-08-01 12:22:53 +00003279 Except for one thing. Module objects have a secret read-only
Fred Drake13494372000-09-12 16:23:48 +00003280 attribute called \member{__dict__} which returns the dictionary
3281 used to implement the module's namespace; the name
3282 \member{__dict__} is an attribute but not a global name.
3283 Obviously, using this violates the abstraction of namespace
Guido van Rossum6938f061994-08-01 12:22:53 +00003284 implementation, and should be restricted to things like
Fred Drake8842e861998-02-13 07:16:30 +00003285 post-mortem debuggers.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003286}
3287
3288Attributes may be read-only or writable. In the latter case,
3289assignment to attributes is possible. Module attributes are writable:
Fred Drake8842e861998-02-13 07:16:30 +00003290you can write \samp{modname.the_answer = 42}. Writable attributes may
Fred Drake391564f1998-04-01 23:11:56 +00003291also be deleted with the \keyword{del} statement, e.g.
Fred Drake8842e861998-02-13 07:16:30 +00003292\samp{del modname.the_answer}.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003293
3294Name spaces are created at different moments and have different
Fred Drake13494372000-09-12 16:23:48 +00003295lifetimes. The namespace containing the built-in names is created
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003296when the Python interpreter starts up, and is never deleted. The
Fred Drake13494372000-09-12 16:23:48 +00003297global namespace for a module is created when the module definition
3298is read in; normally, module namespaces also last until the
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003299interpreter quits. The statements executed by the top-level
3300invocation of the interpreter, either read from a script file or
Fred Drake8842e861998-02-13 07:16:30 +00003301interactively, are considered part of a module called
Fred Drake13494372000-09-12 16:23:48 +00003302\module{__main__}, so they have their own global namespace. (The
Fred Drake8842e861998-02-13 07:16:30 +00003303built-in names actually also live in a module; this is called
3304\module{__builtin__}.)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003305
Fred Drake13494372000-09-12 16:23:48 +00003306The local namespace for a function is created when the function is
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003307called, and deleted when the function returns or raises an exception
3308that is not handled within the function. (Actually, forgetting would
3309be a better way to describe what actually happens.) Of course,
Fred Drake13494372000-09-12 16:23:48 +00003310recursive invocations each have their own local namespace.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003311
Fred Drake13494372000-09-12 16:23:48 +00003312A \emph{scope} is a textual region of a Python program where a
3313namespace is directly accessible. ``Directly accessible'' here means
3314that an unqualified reference to a name attempts to find the name in
3315the namespace.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003316
3317Although scopes are determined statically, they are used dynamically.
3318At any time during execution, exactly three nested scopes are in use
Fred Drake13494372000-09-12 16:23:48 +00003319(i.e., exactly three namespaces are directly accessible): the
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003320innermost scope, which is searched first, contains the local names,
3321the middle scope, searched next, contains the current module's global
Fred Drake13494372000-09-12 16:23:48 +00003322names, and the outermost scope (searched last) is the namespace
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003323containing built-in names.
3324
3325Usually, the local scope references the local names of the (textually)
Guido van Rossum96628a91995-04-10 11:34:00 +00003326current function. Outside of functions, the local scope references
Fred Drake13494372000-09-12 16:23:48 +00003327the same namespace as the global scope: the module's namespace.
3328Class definitions place yet another namespace in the local scope.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003329
3330It is important to realize that scopes are determined textually: the
Fred Drake13494372000-09-12 16:23:48 +00003331global scope of a function defined in a module is that module's
3332namespace, no matter from where or by what alias the function is
3333called. On the other hand, the actual search for names is done
3334dynamically, at run time --- however, the language definition is
3335evolving towards static name resolution, at ``compile'' time, so don't
3336rely on dynamic name resolution! (In fact, local variables are
3337already determined statically.)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003338
3339A special quirk of Python is that assignments always go into the
3340innermost scope. Assignments do not copy data --- they just
3341bind names to objects. The same is true for deletions: the statement
Fred Drake13494372000-09-12 16:23:48 +00003342\samp{del x} removes the binding of \code{x} from the namespace
Fred Drake391564f1998-04-01 23:11:56 +00003343referenced by the local scope. In fact, all operations that introduce
3344new names use the local scope: in particular, import statements and
3345function definitions bind the module or function name in the local
3346scope. (The \keyword{global} statement can be used to indicate that
3347particular variables live in the global scope.)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003348
3349
Fred Drakeb7833d31998-09-11 16:21:55 +00003350\section{A First Look at Classes \label{firstClasses}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003351
3352Classes introduce a little bit of new syntax, three new object types,
3353and some new semantics.
3354
3355
Fred Drakeb7833d31998-09-11 16:21:55 +00003356\subsection{Class Definition Syntax \label{classDefinition}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003357
3358The simplest form of class definition looks like this:
3359
3360\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003361class ClassName:
3362 <statement-1>
3363 .
3364 .
3365 .
3366 <statement-N>
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003367\end{verbatim}
3368
Fred Drake20082d92000-04-03 04:26:58 +00003369Class definitions, like function definitions
3370(\keyword{def} statements) must be executed before they have any
3371effect. (You could conceivably place a class definition in a branch
3372of an \keyword{if} statement, or inside a function.)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003373
3374In practice, the statements inside a class definition will usually be
3375function definitions, but other statements are allowed, and sometimes
3376useful --- we'll come back to this later. The function definitions
3377inside a class normally have a peculiar form of argument list,
3378dictated by the calling conventions for methods --- again, this is
3379explained later.
3380
Fred Drake13494372000-09-12 16:23:48 +00003381When a class definition is entered, a new namespace is created, and
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003382used as the local scope --- thus, all assignments to local variables
Fred Drake13494372000-09-12 16:23:48 +00003383go into this new namespace. In particular, function definitions bind
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003384the name of the new function here.
3385
Fred Drakeeee08cd1997-12-04 15:43:15 +00003386When a class definition is left normally (via the end), a \emph{class
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003387object} is created. This is basically a wrapper around the contents
Fred Drake13494372000-09-12 16:23:48 +00003388of the namespace created by the class definition; we'll learn more
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003389about class objects in the next section. The original local scope
3390(the one in effect just before the class definitions was entered) is
Fred Drakea594baf1998-04-03 05:16:31 +00003391reinstated, and the class object is bound here to the class name given
3392in the class definition header (\class{ClassName} in the example).
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003393
3394
Fred Drakeb7833d31998-09-11 16:21:55 +00003395\subsection{Class Objects \label{classObjects}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003396
3397Class objects support two kinds of operations: attribute references
3398and instantiation.
3399
Fred Drakeeee08cd1997-12-04 15:43:15 +00003400\emph{Attribute references} use the standard syntax used for all
Fred Drake8842e861998-02-13 07:16:30 +00003401attribute references in Python: \code{obj.name}. Valid attribute
Fred Drake13494372000-09-12 16:23:48 +00003402names are all the names that were in the class's namespace when the
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003403class object was created. So, if the class definition looked like
3404this:
3405
3406\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003407class MyClass:
3408 "A simple example class"
3409 i = 12345
3410 def f(x):
3411 return 'hello world'
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003412\end{verbatim}
3413
Fred Drake8842e861998-02-13 07:16:30 +00003414then \code{MyClass.i} and \code{MyClass.f} are valid attribute
Fred Drake20082d92000-04-03 04:26:58 +00003415references, returning an integer and a method object, respectively.
Guido van Rossum02455691997-07-17 16:21:52 +00003416Class attributes can also be assigned to, so you can change the value
Fred Drake20082d92000-04-03 04:26:58 +00003417of \code{MyClass.i} by assignment. \member{__doc__} is also a valid
3418attribute, returning the docstring belonging to the class: \code{"A
3419simple example class"}).
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003420
Fred Drakeeee08cd1997-12-04 15:43:15 +00003421Class \emph{instantiation} uses function notation. Just pretend that
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003422the class object is a parameterless function that returns a new
Fred Drake20082d92000-04-03 04:26:58 +00003423instance of the class. For example (assuming the above class):
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003424
3425\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003426x = MyClass()
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003427\end{verbatim}
3428
Fred Drakeeee08cd1997-12-04 15:43:15 +00003429creates a new \emph{instance} of the class and assigns this object to
3430the local variable \code{x}.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003431
Fred Drake20082d92000-04-03 04:26:58 +00003432The instantiation operation (``calling'' a class object) creates an
3433empty object. Many classes like to create objects in a known initial
3434state. Therefore a class may define a special method named
3435\method{__init__()}, like this:
3436
3437\begin{verbatim}
3438 def __init__(self):
3439 self.data = []
3440\end{verbatim}
3441
3442When a class defines an \method{__init__()} method, class
3443instantiation automatically invokes \method{__init__()} for the
3444newly-created class instance. So in this example, a new, initialized
3445instance can be obtained by:
3446
3447\begin{verbatim}
3448x = MyClass()
3449\end{verbatim}
3450
3451Of course, the \method{__init__()} method may have arguments for
3452greater flexibility. In that case, arguments given to the class
3453instantiation operator are passed on to \method{__init__()}. For
3454example,
3455
3456\begin{verbatim}
3457>>> class Complex:
3458... def __init__(self, realpart, imagpart):
3459... self.r = realpart
3460... self.i = imagpart
3461...
3462>>> x = Complex(3.0,-4.5)
3463>>> x.r, x.i
3464(3.0, -4.5)
3465\end{verbatim}
3466
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003467
Fred Drakeb7833d31998-09-11 16:21:55 +00003468\subsection{Instance Objects \label{instanceObjects}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003469
3470Now what can we do with instance objects? The only operations
3471understood by instance objects are attribute references. There are
3472two kinds of valid attribute names.
3473
Fred Drakeeee08cd1997-12-04 15:43:15 +00003474The first I'll call \emph{data attributes}. These correspond to
Fred Drake8842e861998-02-13 07:16:30 +00003475``instance variables'' in Smalltalk, and to ``data members'' in
3476\Cpp{}. Data attributes need not be declared; like local variables,
3477they spring into existence when they are first assigned to. For
3478example, if \code{x} is the instance of \class{MyClass} created above,
3479the following piece of code will print the value \code{16}, without
3480leaving a trace:
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003481
3482\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003483x.counter = 1
3484while x.counter < 10:
3485 x.counter = x.counter * 2
3486print x.counter
3487del x.counter
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003488\end{verbatim}
3489
3490The second kind of attribute references understood by instance objects
Fred Drakeeee08cd1997-12-04 15:43:15 +00003491are \emph{methods}. A method is a function that ``belongs to'' an
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003492object. (In Python, the term method is not unique to class instances:
3493other object types can have methods as well, e.g., list objects have
3494methods called append, insert, remove, sort, and so on. However,
3495below, we'll use the term method exclusively to mean methods of class
3496instance objects, unless explicitly stated otherwise.)
3497
3498Valid method names of an instance object depend on its class. By
Fred Drake8842e861998-02-13 07:16:30 +00003499definition, all attributes of a class that are (user-defined) function
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003500objects define corresponding methods of its instances. So in our
Fred Drakeeee08cd1997-12-04 15:43:15 +00003501example, \code{x.f} is a valid method reference, since
3502\code{MyClass.f} is a function, but \code{x.i} is not, since
Fred Drake8842e861998-02-13 07:16:30 +00003503\code{MyClass.i} is not. But \code{x.f} is not the same thing as
Fred Drake20082d92000-04-03 04:26:58 +00003504\code{MyClass.f} --- it is a \obindex{method}\emph{method object}, not
3505a function object.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003506
3507
Fred Drakeb7833d31998-09-11 16:21:55 +00003508\subsection{Method Objects \label{methodObjects}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003509
3510Usually, a method is called immediately, e.g.:
3511
3512\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003513x.f()
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003514\end{verbatim}
3515
Fred Drake8842e861998-02-13 07:16:30 +00003516In our example, this will return the string \code{'hello world'}.
Fred Drakeee84d591999-03-10 17:25:30 +00003517However, it is not necessary to call a method right away:
3518\code{x.f} is a method object, and can be stored away and called at a
3519later time. For example:
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003520
3521\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003522xf = x.f
3523while 1:
3524 print xf()
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003525\end{verbatim}
3526
Fred Drake8842e861998-02-13 07:16:30 +00003527will continue to print \samp{hello world} until the end of time.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003528
3529What exactly happens when a method is called? You may have noticed
Fred Drake8842e861998-02-13 07:16:30 +00003530that \code{x.f()} was called without an argument above, even though
3531the function definition for \method{f} specified an argument. What
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003532happened to the argument? Surely Python raises an exception when a
3533function that requires an argument is called without any --- even if
3534the argument isn't actually used...
3535
3536Actually, you may have guessed the answer: the special thing about
3537methods is that the object is passed as the first argument of the
Fred Drake8842e861998-02-13 07:16:30 +00003538function. In our example, the call \code{x.f()} is exactly equivalent
3539to \code{MyClass.f(x)}. In general, calling a method with a list of
Fred Drakeeee08cd1997-12-04 15:43:15 +00003540\var{n} arguments is equivalent to calling the corresponding function
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003541with an argument list that is created by inserting the method's object
3542before the first argument.
3543
3544If you still don't understand how methods work, a look at the
3545implementation can perhaps clarify matters. When an instance
3546attribute is referenced that isn't a data attribute, its class is
3547searched. If the name denotes a valid class attribute that is a
3548function object, a method object is created by packing (pointers to)
3549the instance object and the function object just found together in an
3550abstract object: this is the method object. When the method object is
3551called with an argument list, it is unpacked again, a new argument
3552list is constructed from the instance object and the original argument
3553list, and the function object is called with this new argument list.
3554
3555
Fred Drakeb7833d31998-09-11 16:21:55 +00003556\section{Random Remarks \label{remarks}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003557
3558[These should perhaps be placed more carefully...]
3559
3560
3561Data attributes override method attributes with the same name; to
3562avoid accidental name conflicts, which may cause hard-to-find bugs in
3563large programs, it is wise to use some kind of convention that
3564minimizes the chance of conflicts, e.g., capitalize method names,
3565prefix data attribute names with a small unique string (perhaps just
Guido van Rossum6938f061994-08-01 12:22:53 +00003566an underscore), or use verbs for methods and nouns for data attributes.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003567
3568
3569Data attributes may be referenced by methods as well as by ordinary
3570users (``clients'') of an object. In other words, classes are not
3571usable to implement pure abstract data types. In fact, nothing in
3572Python makes it possible to enforce data hiding --- it is all based
3573upon convention. (On the other hand, the Python implementation,
Fred Drakeee84d591999-03-10 17:25:30 +00003574written in C, can completely hide implementation details and control
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003575access to an object if necessary; this can be used by extensions to
Fred Drakeee84d591999-03-10 17:25:30 +00003576Python written in C.)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003577
3578
3579Clients should use data attributes with care --- clients may mess up
3580invariants maintained by the methods by stamping on their data
3581attributes. Note that clients may add data attributes of their own to
3582an instance object without affecting the validity of the methods, as
3583long as name conflicts are avoided --- again, a naming convention can
3584save a lot of headaches here.
3585
3586
3587There is no shorthand for referencing data attributes (or other
3588methods!) from within methods. I find that this actually increases
3589the readability of methods: there is no chance of confusing local
3590variables and instance variables when glancing through a method.
3591
3592
3593Conventionally, the first argument of methods is often called
Fred Drake8842e861998-02-13 07:16:30 +00003594\code{self}. This is nothing more than a convention: the name
3595\code{self} has absolutely no special meaning to Python. (Note,
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003596however, that by not following the convention your code may be less
3597readable by other Python programmers, and it is also conceivable that
Fred Drakeeee08cd1997-12-04 15:43:15 +00003598a \emph{class browser} program be written which relies upon such a
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003599convention.)
3600
3601
3602Any function object that is a class attribute defines a method for
3603instances of that class. It is not necessary that the function
3604definition is textually enclosed in the class definition: assigning a
3605function object to a local variable in the class is also ok. For
3606example:
3607
3608\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003609# Function defined outside the class
3610def f1(self, x, y):
3611 return min(x, x+y)
3612
3613class C:
3614 f = f1
3615 def g(self):
3616 return 'hello world'
3617 h = g
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003618\end{verbatim}
3619
Fred Drake8842e861998-02-13 07:16:30 +00003620Now \code{f}, \code{g} and \code{h} are all attributes of class
3621\class{C} that refer to function objects, and consequently they are all
3622methods of instances of \class{C} --- \code{h} being exactly equivalent
3623to \code{g}. Note that this practice usually only serves to confuse
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003624the reader of a program.
3625
3626
3627Methods may call other methods by using method attributes of the
Fred Drake8842e861998-02-13 07:16:30 +00003628\code{self} argument, e.g.:
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003629
3630\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003631class Bag:
Fred Drake20082d92000-04-03 04:26:58 +00003632 def __init__(self):
Fred Drake8842e861998-02-13 07:16:30 +00003633 self.data = []
3634 def add(self, x):
3635 self.data.append(x)
3636 def addtwice(self, x):
3637 self.add(x)
3638 self.add(x)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003639\end{verbatim}
3640
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003641Methods may reference global names in the same way as ordinary
3642functions. The global scope associated with a method is the module
3643containing the class definition. (The class itself is never used as a
3644global scope!) While one rarely encounters a good reason for using
3645global data in a method, there are many legitimate uses of the global
3646scope: for one thing, functions and modules imported into the global
3647scope can be used by methods, as well as functions and classes defined
3648in it. Usually, the class containing the method is itself defined in
3649this global scope, and in the next section we'll find some good
3650reasons why a method would want to reference its own class!
3651
3652
Fred Drakeb7833d31998-09-11 16:21:55 +00003653\section{Inheritance \label{inheritance}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003654
3655Of course, a language feature would not be worthy of the name ``class''
3656without supporting inheritance. The syntax for a derived class
3657definition looks as follows:
3658
3659\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003660class DerivedClassName(BaseClassName):
3661 <statement-1>
3662 .
3663 .
3664 .
3665 <statement-N>
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003666\end{verbatim}
3667
Fred Drake8842e861998-02-13 07:16:30 +00003668The name \class{BaseClassName} must be defined in a scope containing
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003669the derived class definition. Instead of a base class name, an
3670expression is also allowed. This is useful when the base class is
3671defined in another module, e.g.,
3672
3673\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003674class DerivedClassName(modname.BaseClassName):
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003675\end{verbatim}
3676
3677Execution of a derived class definition proceeds the same as for a
3678base class. When the class object is constructed, the base class is
3679remembered. This is used for resolving attribute references: if a
3680requested attribute is not found in the class, it is searched in the
3681base class. This rule is applied recursively if the base class itself
3682is derived from some other class.
3683
3684There's nothing special about instantiation of derived classes:
Fred Drake8842e861998-02-13 07:16:30 +00003685\code{DerivedClassName()} creates a new instance of the class. Method
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003686references are resolved as follows: the corresponding class attribute
3687is searched, descending down the chain of base classes if necessary,
3688and the method reference is valid if this yields a function object.
3689
3690Derived classes may override methods of their base classes. Because
3691methods have no special privileges when calling other methods of the
3692same object, a method of a base class that calls another method
3693defined in the same base class, may in fact end up calling a method of
Guido van Rossum16d6e711994-08-08 12:30:22 +00003694a derived class that overrides it. (For \Cpp{} programmers: all methods
Fred Drake20082d92000-04-03 04:26:58 +00003695in Python are effectively \keyword{virtual}.)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003696
3697An overriding method in a derived class may in fact want to extend
3698rather than simply replace the base class method of the same name.
3699There is a simple way to call the base class method directly: just
Fred Drake8842e861998-02-13 07:16:30 +00003700call \samp{BaseClassName.methodname(self, arguments)}. This is
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003701occasionally useful to clients as well. (Note that this only works if
3702the base class is defined or imported directly in the global scope.)
3703
3704
Fred Drakeb7833d31998-09-11 16:21:55 +00003705\subsection{Multiple Inheritance \label{multiple}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003706
Guido van Rossum6938f061994-08-01 12:22:53 +00003707Python supports a limited form of multiple inheritance as well. A
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003708class definition with multiple base classes looks as follows:
3709
3710\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003711class DerivedClassName(Base1, Base2, Base3):
3712 <statement-1>
3713 .
3714 .
3715 .
3716 <statement-N>
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003717\end{verbatim}
3718
3719The only rule necessary to explain the semantics is the resolution
3720rule used for class attribute references. This is depth-first,
3721left-to-right. Thus, if an attribute is not found in
Fred Drake8842e861998-02-13 07:16:30 +00003722\class{DerivedClassName}, it is searched in \class{Base1}, then
3723(recursively) in the base classes of \class{Base1}, and only if it is
3724not found there, it is searched in \class{Base2}, and so on.
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003725
Fred Drake8842e861998-02-13 07:16:30 +00003726(To some people breadth first --- searching \class{Base2} and
3727\class{Base3} before the base classes of \class{Base1} --- looks more
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003728natural. However, this would require you to know whether a particular
Fred Drake8842e861998-02-13 07:16:30 +00003729attribute of \class{Base1} is actually defined in \class{Base1} or in
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003730one of its base classes before you can figure out the consequences of
Fred Drake8842e861998-02-13 07:16:30 +00003731a name conflict with an attribute of \class{Base2}. The depth-first
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003732rule makes no differences between direct and inherited attributes of
Fred Drake8842e861998-02-13 07:16:30 +00003733\class{Base1}.)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003734
3735It is clear that indiscriminate use of multiple inheritance is a
3736maintenance nightmare, given the reliance in Python on conventions to
3737avoid accidental name conflicts. A well-known problem with multiple
3738inheritance is a class derived from two classes that happen to have a
3739common base class. While it is easy enough to figure out what happens
3740in this case (the instance will have a single copy of ``instance
3741variables'' or data attributes used by the common base class), it is
3742not clear that these semantics are in any way useful.
3743
3744
Fred Drakeb7833d31998-09-11 16:21:55 +00003745\section{Private Variables \label{private}}
Guido van Rossum02455691997-07-17 16:21:52 +00003746
Fred Drakea594baf1998-04-03 05:16:31 +00003747There is limited support for class-private
Guido van Rossum02455691997-07-17 16:21:52 +00003748identifiers. Any identifier of the form \code{__spam} (at least two
3749leading underscores, at most one trailing underscore) is now textually
3750replaced with \code{_classname__spam}, where \code{classname} is the
3751current class name with leading underscore(s) stripped. This mangling
3752is done without regard of the syntactic position of the identifier, so
3753it can be used to define class-private instance and class variables,
3754methods, as well as globals, and even to store instance variables
Fred Drakeeee08cd1997-12-04 15:43:15 +00003755private to this class on instances of \emph{other} classes. Truncation
Guido van Rossum02455691997-07-17 16:21:52 +00003756may occur when the mangled name would be longer than 255 characters.
3757Outside classes, or when the class name consists of only underscores,
3758no mangling occurs.
3759
3760Name mangling is intended to give classes an easy way to define
3761``private'' instance variables and methods, without having to worry
3762about instance variables defined by derived classes, or mucking with
3763instance variables by code outside the class. Note that the mangling
3764rules are designed mostly to avoid accidents; it still is possible for
3765a determined soul to access or modify a variable that is considered
3766private. This can even be useful, e.g. for the debugger, and that's
3767one reason why this loophole is not closed. (Buglet: derivation of a
3768class with the same name as the base class makes use of private
3769variables of the base class possible.)
3770
3771Notice that code passed to \code{exec}, \code{eval()} or
3772\code{evalfile()} does not consider the classname of the invoking
3773class to be the current class; this is similar to the effect of the
3774\code{global} statement, the effect of which is likewise restricted to
3775code that is byte-compiled together. The same restriction applies to
3776\code{getattr()}, \code{setattr()} and \code{delattr()}, as well as
3777when referencing \code{__dict__} directly.
3778
3779Here's an example of a class that implements its own
Fred Drake13494372000-09-12 16:23:48 +00003780\method{__getattr__()} and \method{__setattr__()} methods and stores
3781all attributes in a private variable, in a way that works in all
3782versions of Python, including those available before this feature was
3783added:
Guido van Rossum02455691997-07-17 16:21:52 +00003784
3785\begin{verbatim}
3786class VirtualAttributes:
3787 __vdict = None
3788 __vdict_name = locals().keys()[0]
3789
3790 def __init__(self):
3791 self.__dict__[self.__vdict_name] = {}
3792
3793 def __getattr__(self, name):
3794 return self.__vdict[name]
3795
3796 def __setattr__(self, name, value):
3797 self.__vdict[name] = value
3798\end{verbatim}
3799
Guido van Rossum02455691997-07-17 16:21:52 +00003800
Fred Drakeb7833d31998-09-11 16:21:55 +00003801\section{Odds and Ends \label{odds}}
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003802
3803Sometimes it is useful to have a data type similar to the Pascal
Fred Drakeee84d591999-03-10 17:25:30 +00003804``record'' or C ``struct'', bundling together a couple of named data
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003805items. An empty class definition will do nicely, e.g.:
3806
3807\begin{verbatim}
Fred Drake8842e861998-02-13 07:16:30 +00003808class Employee:
3809 pass
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003810
Fred Drake8842e861998-02-13 07:16:30 +00003811john = Employee() # Create an empty employee record
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003812
Fred Drake8842e861998-02-13 07:16:30 +00003813# Fill the fields of the record
3814john.name = 'John Doe'
3815john.dept = 'computer lab'
3816john.salary = 1000
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003817\end{verbatim}
3818
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003819A piece of Python code that expects a particular abstract data type
3820can often be passed a class that emulates the methods of that data
3821type instead. For instance, if you have a function that formats some
3822data from a file object, you can define a class with methods
Fred Drake8842e861998-02-13 07:16:30 +00003823\method{read()} and \method{readline()} that gets the data from a string
Fred Drake391564f1998-04-01 23:11:56 +00003824buffer instead, and pass it as an argument.% (Unfortunately, this
3825%technique has its limitations: a class can't define operations that
3826%are accessed by special syntax such as sequence subscripting or
3827%arithmetic operators, and assigning such a ``pseudo-file'' to
3828%\code{sys.stdin} will not cause the interpreter to read further input
3829%from it.)
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003830
3831
Fred Drake8842e861998-02-13 07:16:30 +00003832Instance method objects have attributes, too: \code{m.im_self} is the
3833object of which the method is an instance, and \code{m.im_func} is the
Guido van Rossum5e0759d1992-08-07 16:06:24 +00003834function object corresponding to the method.
3835
Fred Drakeb7833d31998-09-11 16:21:55 +00003836\subsection{Exceptions Can Be Classes \label{exceptionClasses}}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003837
3838User-defined exceptions are no longer limited to being string objects
3839--- they can be identified by classes as well. Using this mechanism it
3840is possible to create extensible hierarchies of exceptions.
3841
3842There are two new valid (semantic) forms for the raise statement:
3843
3844\begin{verbatim}
3845raise Class, instance
3846
3847raise instance
3848\end{verbatim}
3849
Fred Drake20082d92000-04-03 04:26:58 +00003850In the first form, \code{instance} must be an instance of
3851\class{Class} or of a class derived from it. The second form is a
3852shorthand for:
Guido van Rossum194e57c1995-02-15 15:51:38 +00003853
3854\begin{verbatim}
3855raise instance.__class__, instance
3856\end{verbatim}
3857
3858An except clause may list classes as well as string objects. A class
3859in an except clause is compatible with an exception if it is the same
3860class or a base class thereof (but not the other way around --- an
3861except clause listing a derived class is not compatible with a base
3862class). For example, the following code will print B, C, D in that
3863order:
3864
3865\begin{verbatim}
3866class B:
3867 pass
3868class C(B):
3869 pass
3870class D(C):
3871 pass
3872
3873for c in [B, C, D]:
3874 try:
3875 raise c()
3876 except D:
3877 print "D"
3878 except C:
3879 print "C"
3880 except B:
3881 print "B"
3882\end{verbatim}
3883
Fred Drakeee84d591999-03-10 17:25:30 +00003884Note that if the except clauses were reversed (with
3885\samp{except B} first), it would have printed B, B, B --- the first
3886matching except clause is triggered.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003887
3888When an error message is printed for an unhandled exception which is a
3889class, the class name is printed, then a colon and a space, and
3890finally the instance converted to a string using the built-in function
Fred Drake8842e861998-02-13 07:16:30 +00003891\function{str()}.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003892
Guido van Rossum194e57c1995-02-15 15:51:38 +00003893
Fred Drakeb7833d31998-09-11 16:21:55 +00003894\chapter{What Now? \label{whatNow}}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003895
Guido van Rossum02455691997-07-17 16:21:52 +00003896Hopefully reading this tutorial has reinforced your interest in using
3897Python. Now what should you do?
Guido van Rossum194e57c1995-02-15 15:51:38 +00003898
Guido van Rossum02455691997-07-17 16:21:52 +00003899You should read, or at least page through, the Library Reference,
3900which gives complete (though terse) reference material about types,
3901functions, and modules that can save you a lot of time when writing
3902Python programs. The standard Python distribution includes a
Fred Drakeee84d591999-03-10 17:25:30 +00003903\emph{lot} of code in both C and Python; there are modules to read
Fred Drake8842e861998-02-13 07:16:30 +00003904\UNIX{} mailboxes, retrieve documents via HTTP, generate random
3905numbers, parse command-line options, write CGI programs, compress
3906data, and a lot more; skimming through the Library Reference will give
3907you an idea of what's available.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003908
Fred Drake518e55c2000-07-27 20:55:12 +00003909The major Python Web site is \url{http://www.python.org/}; it contains
Guido van Rossum02455691997-07-17 16:21:52 +00003910code, documentation, and pointers to Python-related pages around the
Fred Drake391564f1998-04-01 23:11:56 +00003911Web. This web site is mirrored in various places around the
Guido van Rossum02455691997-07-17 16:21:52 +00003912world, such as Europe, Japan, and Australia; a mirror may be faster
3913than the main site, depending on your geographical location. A more
Fred Drakec0fcbc11999-04-29 02:30:04 +00003914informal site is \url{http://starship.python.net/}, which contains a
Guido van Rossum02455691997-07-17 16:21:52 +00003915bunch of Python-related personal home pages; many people have
Fred Drakec0fcbc11999-04-29 02:30:04 +00003916downloadable software there.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003917
Guido van Rossum02455691997-07-17 16:21:52 +00003918For Python-related questions and problem reports, you can post to the
Fred Drake391564f1998-04-01 23:11:56 +00003919newsgroup \newsgroup{comp.lang.python}, or send them to the mailing
Fred Drake518e55c2000-07-27 20:55:12 +00003920list at \email{python-list@python.org}. The newsgroup and mailing list
Fred Drake391564f1998-04-01 23:11:56 +00003921are gatewayed, so messages posted to one will automatically be
Fred Drake518e55c2000-07-27 20:55:12 +00003922forwarded to the other. There are around 120 postings a day,
Fred Drake391564f1998-04-01 23:11:56 +00003923% Postings figure based on average of last six months activity as
Fred Drake518e55c2000-07-27 20:55:12 +00003924% reported by www.egroups.com; Jan. 2000 - June 2000: 21272 msgs / 182
3925% days = 116.9 msgs / day and steadily increasing.
Fred Drake391564f1998-04-01 23:11:56 +00003926asking (and answering) questions, suggesting new features, and
3927announcing new modules. Before posting, be sure to check the list of
3928Frequently Asked Questions (also called the FAQ), at
Fred Drakeca6567f1998-01-22 20:44:18 +00003929\url{http://www.python.org/doc/FAQ.html}, or look for it in the
Fred Drake518e55c2000-07-27 20:55:12 +00003930\file{Misc/} directory of the Python source distribution. Mailing
3931list archives are available at \url{http://www.python.org/pipermail/}.
3932The FAQ answers many of the questions that come up again and again,
3933and may already contain the solution for your problem.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003934
Guido van Rossum194e57c1995-02-15 15:51:38 +00003935
Fred Drakea594baf1998-04-03 05:16:31 +00003936\appendix
Guido van Rossum194e57c1995-02-15 15:51:38 +00003937
Fred Drakeb7833d31998-09-11 16:21:55 +00003938\chapter{Interactive Input Editing and History Substitution
3939 \label{interacting}}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003940
Guido van Rossum02455691997-07-17 16:21:52 +00003941Some versions of the Python interpreter support editing of the current
3942input line and history substitution, similar to facilities found in
3943the Korn shell and the GNU Bash shell. This is implemented using the
Fred Drakeeee08cd1997-12-04 15:43:15 +00003944\emph{GNU Readline} library, which supports Emacs-style and vi-style
Guido van Rossum02455691997-07-17 16:21:52 +00003945editing. This library has its own documentation which I won't
Fred Drakecc09e8d1998-12-28 21:21:36 +00003946duplicate here; however, the basics are easily explained. The
3947interactive editing and history described here are optionally
3948available in the \UNIX{} and CygWin versions of the interpreter.
3949
3950This chapter does \emph{not} document the editing facilities of Mark
3951Hammond's PythonWin package or the Tk-based environment, IDLE,
3952distributed with Python. The command line history recall which
3953operates within DOS boxes on NT and some other DOS and Windows flavors
3954is yet another beast.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003955
Fred Drakeb7833d31998-09-11 16:21:55 +00003956\section{Line Editing \label{lineEditing}}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003957
Guido van Rossum02455691997-07-17 16:21:52 +00003958If supported, input line editing is active whenever the interpreter
3959prints a primary or secondary prompt. The current line can be edited
3960using the conventional Emacs control characters. The most important
Fred Drake5443c492000-07-08 05:18:54 +00003961of these are: \kbd{C-A} (Control-A) moves the cursor to the beginning
3962of the line, \kbd{C-E} to the end, \kbd{C-B} moves it one position to
3963the left, \kbd{C-F} to the right. Backspace erases the character to
3964the left of the cursor, \kbd{C-D} the character to its right.
3965\kbd{C-K} kills (erases) the rest of the line to the right of the
3966cursor, \kbd{C-Y} yanks back the last killed string.
3967\kbd{C-underscore} undoes the last change you made; it can be repeated
3968for cumulative effect.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003969
Fred Drakeb7833d31998-09-11 16:21:55 +00003970\section{History Substitution \label{history}}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003971
Guido van Rossum02455691997-07-17 16:21:52 +00003972History substitution works as follows. All non-empty input lines
3973issued are saved in a history buffer, and when a new prompt is given
Fred Drake5443c492000-07-08 05:18:54 +00003974you are positioned on a new line at the bottom of this buffer.
3975\kbd{C-P} moves one line up (back) in the history buffer,
3976\kbd{C-N} moves one down. Any line in the history buffer can be
3977edited; an asterisk appears in front of the prompt to mark a line as
3978modified. Pressing the \kbd{Return} key passes the current line to
3979the interpreter. \kbd{C-R} starts an incremental reverse search;
3980\kbd{C-S} starts a forward search.
Guido van Rossum194e57c1995-02-15 15:51:38 +00003981
Fred Drakeb7833d31998-09-11 16:21:55 +00003982\section{Key Bindings \label{keyBindings}}
Guido van Rossum194e57c1995-02-15 15:51:38 +00003983
Guido van Rossum02455691997-07-17 16:21:52 +00003984The key bindings and some other parameters of the Readline library can
3985be customized by placing commands in an initialization file called
Fred Drake5443c492000-07-08 05:18:54 +00003986\file{\~{}/.inputrc}. Key bindings have the form
Guido van Rossum194e57c1995-02-15 15:51:38 +00003987
Fred Drake8842e861998-02-13 07:16:30 +00003988\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00003989key-name: function-name
Fred Drake8842e861998-02-13 07:16:30 +00003990\end{verbatim}
3991
Guido van Rossum02455691997-07-17 16:21:52 +00003992or
Guido van Rossum194e57c1995-02-15 15:51:38 +00003993
Fred Drake8842e861998-02-13 07:16:30 +00003994\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00003995"string": function-name
Fred Drake8842e861998-02-13 07:16:30 +00003996\end{verbatim}
3997
Guido van Rossum02455691997-07-17 16:21:52 +00003998and options can be set with
Guido van Rossum194e57c1995-02-15 15:51:38 +00003999
Fred Drake8842e861998-02-13 07:16:30 +00004000\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00004001set option-name value
Fred Drake8842e861998-02-13 07:16:30 +00004002\end{verbatim}
4003
Guido van Rossum02455691997-07-17 16:21:52 +00004004For example:
Guido van Rossum194e57c1995-02-15 15:51:38 +00004005
Fred Drake8842e861998-02-13 07:16:30 +00004006\begin{verbatim}
Guido van Rossum02455691997-07-17 16:21:52 +00004007# I prefer vi-style editing:
4008set editing-mode vi
Fred Drake5443c492000-07-08 05:18:54 +00004009
Guido van Rossum02455691997-07-17 16:21:52 +00004010# Edit using a single line:
4011set horizontal-scroll-mode On
Fred Drake5443c492000-07-08 05:18:54 +00004012
Guido van Rossum02455691997-07-17 16:21:52 +00004013# Rebind some keys:
4014Meta-h: backward-kill-word
4015"\C-u": universal-argument
4016"\C-x\C-r": re-read-init-file
Fred Drake8842e861998-02-13 07:16:30 +00004017\end{verbatim}
4018
Fred Drake5443c492000-07-08 05:18:54 +00004019Note that the default binding for \kbd{Tab} in Python is to insert a
4020\kbd{Tab} character instead of Readline's default filename completion
4021function. If you insist, you can override this by putting
Guido van Rossum194e57c1995-02-15 15:51:38 +00004022
Fred Drake8842e861998-02-13 07:16:30 +00004023\begin{verbatim}
Fred Drake5443c492000-07-08 05:18:54 +00004024Tab: complete
Fred Drake8842e861998-02-13 07:16:30 +00004025\end{verbatim}
4026
Fred Drake5443c492000-07-08 05:18:54 +00004027in your \file{\~{}/.inputrc}. (Of course, this makes it harder to
4028type indented continuation lines.)
Guido van Rossum194e57c1995-02-15 15:51:38 +00004029
Fred Drake72389881998-04-13 01:31:10 +00004030Automatic completion of variable and module names is optionally
4031available. To enable it in the interpreter's interactive mode, add
Fred Drake5443c492000-07-08 05:18:54 +00004032the following to your startup file:\footnote{
4033 Python will execute the contents of a file identified by the
4034 \envvar{PYTHONSTARTUP} environment variable when you start an
4035 interactive interpreter.}
Fred Drake20082d92000-04-03 04:26:58 +00004036\refstmodindex{rlcompleter}\refbimodindex{readline}
Fred Drake72389881998-04-13 01:31:10 +00004037
4038\begin{verbatim}
4039import rlcompleter, readline
4040readline.parse_and_bind('tab: complete')
4041\end{verbatim}
4042
4043This binds the TAB key to the completion function, so hitting the TAB
4044key twice suggests completions; it looks at Python statement names,
4045the current local variables, and the available module names. For
4046dotted expressions such as \code{string.a}, it will evaluate the the
4047expression up to the final \character{.} and then suggest completions
4048from the attributes of the resulting object. Note that this may
4049execute application-defined code if an object with a
4050\method{__getattr__()} method is part of the expression.
4051
4052
Fred Drakeb7833d31998-09-11 16:21:55 +00004053\section{Commentary \label{commentary}}
Guido van Rossum194e57c1995-02-15 15:51:38 +00004054
Fred Drake5443c492000-07-08 05:18:54 +00004055This facility is an enormous step forward compared to earlier versions
4056of the interpreter; however, some wishes are left: It would be nice if
4057the proper indentation were suggested on continuation lines (the
4058parser knows if an indent token is required next). The completion
4059mechanism might use the interpreter's symbol table. A command to
4060check (or even suggest) matching parentheses, quotes, etc., would also
4061be useful.
Guido van Rossum194e57c1995-02-15 15:51:38 +00004062
Guido van Rossum97662c81996-08-23 15:35:47 +00004063
Guido van Rossumd9bf55d1991-01-11 16:35:08 +00004064\end{document}